# Ui Audit

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-mblode-agent-skills-ui-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mblode](https://agentstack.voostack.com/s/mblode)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mblode](https://github.com/mblode)
- **Source:** https://github.com/mblode/agent-skills/tree/main/skills/ui-audit
- **Website:** https://www.skills.sh/mblode/agent-skills

## Install

```sh
agentstack add skill-mblode-agent-skills-ui-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# UI Audit

Audits the **built frontend** at the **feature level** (checkout, onboarding, a dashboard) for a dev with a PR open: "**which of these hurt users in production, and which are nice-to-haves?**" Reasons about code behavior (React/Next source) and rendered quality (accessibility, layout, performance, type, motion).

- **IS:** a diff-aware reviewer that detects which feature each changed file implements, runs that feature's playbook across behavior, rendered-quality, and Laws of UX rules, and emits a 3-tier ship verdict with `file:line` evidence and fixes.
- **IS NOT:** the product decision of what *should* exist (right interaction, action naming, reachable states → `product-design`), an agentic-app review (tool parity, trust cues, approval gates → `ax-audit`), a deep typography or motion pass (→ `typography-audit` or `ui-animation`), or a re-implementation of Lighthouse/axe/Chromatic (→ see "Defer to other tools").

## product-design or ui-audit?

The dispatch signal is the artifact, not the topic. Both care about states and interaction, but act at different moments.

| You have... | The question is | Use |
|---|---|---|
| A brief, spec, mockup, intent, or a UI you decide *about* | What should exist: the right interaction, the action's name, which states *should* be reachable | `product-design` |
| Code, a diff, or a running UI you decide *on* | Is the built result right: states covered, accessible, renders and behaves correctly, ready to ship | `ui-audit` |

Often both in sequence: `product-design` decides the states that must exist, `ui-audit` verifies the built code implements them.

## Contents

- [Audit workflow](#audit-workflow)
- [Rule layers and dispatch](#rule-layers-and-dispatch)
- [Scope: diff-aware by default](#scope-diff-aware-by-default)
- [Ship-readiness verdict](#ship-readiness-verdict)
- [Output adapters](#output-adapters)
- [Suppressions](#suppressions)
- [Defer to other tools](#defer-to-other-tools)
- [Reference files](#reference-files)
- [Related skills](#related-skills)
- [Gotchas](#gotchas)
- [Audit self-check](#audit-self-check)

## Audit workflow

Copy and track this checklist:

```text
UI Audit progress:
- [ ] Step 1: Determine scope (PR diff via `git diff --name-only main` OR explicit file/folder)
- [ ] Step 2: Detect features in scope (sign-in / checkout / form / modal / list / dashboard / ...)
- [ ] Step 3: For each feature, run its playbook from references/feature-playbooks.md in order
- [ ] Step 4: For each check, load the named rule file (rules-modern/, rules-surface/, or rules/) and run its detection
- [ ] Step 5: Assign each finding a ship tier per references/ship-readiness.md (surface can bump tiers)
- [ ] Step 6: Build the JSON document, then render with the chosen output adapter
- [ ] Step 7: Run the audit-self-check; report INCOMPLETE if it fails
```

Step notes:

1. **Scope.** Diff by default; never the whole codebase (see [Scope](#scope-diff-aware-by-default)).
2. **Detect features.** Match semantics + filenames + routes: `` with email + password is sign-in; `role="dialog"` is a modal; `/checkout` is checkout. Table: `references/feature-playbooks.md`.
3. **Run playbooks.** Each feature has 5-7 ordered checks. Run every one even when you expect a pass; passes feed the self-check's `rulesRun` count.
4. **Load rules.** Only the rule files the playbook names, never a whole folder (see [dispatch](#rule-layers-and-dispatch)).
5. **Tier.** Every finding gets `release-blocker | fix-this-sprint | backlog`; surface context bumps the default tier (sign-in/checkout up; marketing/internal-admin down).
6. **Render.** JSON first, then the adapter: the JSON keeps findings comparable across runs.
7. **Self-check.** Terminal evidence step; criteria below.

## Rule layers and dispatch

Four layers, each with its own loading condition. Load rule files individually, on demand:

| Layer | Location | Load when | Size |
|---|---|---|---|
| 1: Feature playbooks | `references/feature-playbooks.md` | Always, at Step 2, since it is the entry point that names which Layer 2/3/4 rules to run | 12 playbooks |
| 2: Modern failure modes (behavior) | `rules-modern/-.md` | A playbook check names the rule, or a changed file matches the rule's category (forms, states, async, focus, mobile, dark-i18n, microcopy) | 31 rules |
| 3: Rendered quality (surface) | `rules-surface/-.md` | A playbook check names the rule, or a surface needs a rendered-quality check (a11y, interaction, forms, type, nav, layout, perf, motion, copy) | 34 rules |
| 4: Laws of UX | `rules/-.md` | A playbook explicitly names a Laws rule, or a finding needs cognitive/perceptual reasoning no Layer 2/3 rule covers | 30 rules (20 programmatic, 10 rubric) |

Layer-specific notes:

- **Layer 2 (behavior) reasons from React/Next source:** state coverage, form data loss, async races, focus management, optimistic-rollback, dark-mode/i18n. Index: `rules-modern/_sections.md`; summaries + default tiers: `references/modern-failure-modes.md`. Each rule file: detection greps, false-positive guards, surface-tier overrides, before/after fix.
- **Layer 3 (rendered quality) reasons from rendered output:** accessibility markup, keyboard operability, layout resilience, performance, motion, surface typography, copy specificity. Index + per-rule impact: `rules-surface/_sections.md`. A rule's frontmatter impact wins over its category default (e.g. `perf-image-dimensions-and-priority` is CRITICAL inside the HIGH `perf-` category).
- **Layers 2 and 3 are complementary, not redundant:** for a form, Layer 2 catches data loss on validation, Layer 3 catches a missing label or 14px mobile input. Run both when a feature has both in scope.
- **Layer 4 is reserve.** Expect 1-2 Laws findings per audit, not 30. Index: `rules/_sections.md`. The 10 rubric-kind rules score 1-5 against anchor tables in `references/observational-rubrics.md`: emit the score plus the verbatim anchor text.
- **When multiple layers fire on one issue, keep the most concrete framing.** "Missing error state" (Layer 2) beats "Postel's Law violation" (Layer 4): concrete fix, specific surface match.

## Scope: diff-aware by default

```bash
git diff --name-only main -- '*.tsx' '*.jsx' '*.ts' '*.js' '*.css' '*.module.css'
```

Audit only those files; surface the base in output: `Auditing: 8 files changed vs main`.

- Single component: `git diff --name-only HEAD -- src/Component.tsx`
- Full sweep: only on explicit request (`--full src/`), e.g. introducing the skill to a codebase. A default full sweep buries the 3 findings that matter under 60 that don't.

## Ship-readiness verdict

Every audit opens with a verdict block before per-finding detail:

```text
═══════════════════════════════════════════════════════════
SHIP VERDICT: ❌ NOT READY (1 release-blocker)

Surface count:           3 (CheckoutForm, PaymentStep, ConfirmStep)
Findings:                7
  Release blockers:      1   ⛔  Form data loss on validation (PaymentStep.tsx:42)
  Fix this sprint:       3   ⚠️
  Backlog:               3   📋

Defer-to (not audited here):
  Measured CWV (lab):    Run Lighthouse
  Bundle size:           Run size-limit
  Full WCAG conformance: Run axe-core
═══════════════════════════════════════════════════════════
```

Verdict computation: ✅ READY (0 blockers, ≤3 sprint) · ⚠️ READY WITH FOLLOW-UP (0 blockers, ≥4 sprint) · ❌ NOT READY (≥1 blocker) · 🚫 INCOMPLETE (self-check failed). Tier definitions, surface bump rules, and worked examples: `references/ship-readiness.md`.

## Output adapters

All three formats render from the same JSON document. Templates and field mappings: `references/output-adapters.md`; strict schema: `references/output-schema.md`.

| Adapter | When | Format |
|---|---|---|
| Terminal table | Local dev, agent chat | Tight table grouped by surface, tier-sorted |
| PR comment | GitHub / Vercel review | Markdown summary + inline comments with `suggestion` blocks |
| CI JSON | Pipelines, merge gates | Strict JSON; gate with `jq -e '.summary.releaseBlockers == 0'` |

## Suppressions

A finding is suppressed with an inline comment whose slug matches the rule:

```tsx
{/* ui-audit-ignore:focus-not-restored, intentional: parent owns focus */}

```

Suppressed findings still appear in the summary (`summary.suppressed`) so reviewers can verify intent.

## Defer to other tools

ui-audit reasons statically; it does not measure runtime metrics or replace conformance scanners. It does surface-level a11y and performance checks (alt text, labels, contrast cues, image dimensions, font loading) but defers comprehensive measurement. When a finding belongs to another tool, link out, don't restate:

| Concern | Use instead |
|---|---|
| Measured Core Web Vitals (LCP, CLS, INP) | Lighthouse + web-vitals |
| Full WCAG conformance scan | axe-core / eslint-plugin-jsx-a11y |
| Visual regression | Chromatic / Percy |
| Bundle size budgets | size-limit / bundle-analyzer |
| Generic correctness bugs | CodeRabbit / Vercel Agent / `pr-reviewer` |

Full coverage map plus the gaps only ui-audit catches: `references/defer-to-other-tools.md`.

## Reference files

| File | Read when |
|------|-----------|
| `references/feature-playbooks.md` | Steps 2-3: feature detection table + per-feature ordered checks |
| `references/modern-failure-modes.md` | Browsing Layer 2: all 31 rules with categories and default tiers |
| `references/states-coverage.md` | Validating loading/empty/error/disabled coverage; state-pair grep recipes |
| `references/ship-readiness.md` | Step 5: tier definitions, surface bump table, verdict logic |
| `references/output-adapters.md` | Step 6: verbatim terminal / PR-comment / JSON templates |
| `references/output-schema.md` | Step 6: strict JSON schema and validation rules |
| `references/observational-rubrics.md` | Scoring any of the 10 Layer 4 rubric-kind rules (1-5 anchors) |
| `references/defer-to-other-tools.md` | Deciding whether a concern is another tool's job |
| `references/craft-checklist.md` | Optional polish sweep (hit targets, hover states, chrome hierarchy, optical alignment, concentric radii) when polish or pre-release sign-off is in scope |
| `references/typography-checklist.md` | Optional typography sweep (punctuation, measure, leading, OpenType basics, link styling, table numerals) when typography is named |
| `rules-modern/_sections.md` | Layer 2 category index (behavior failure modes) |
| `rules-modern/-.md` | Step 4: running a named Layer 2 behavior check |
| `rules-surface/_sections.md` | Layer 3 category index (rendered-quality, 9 prefixes) |
| `rules-surface/-.md` | Step 4: running a named Layer 3 rendered-quality check |
| `rules/_sections.md` | Layer 4 category index (Laws of UX, 5 prefixes) |
| `rules/-.md` | Step 4: running a named Layer 4 Laws check |

## Related skills

- `product-design`: the product decision, not the build. Route there when the question is "is this the right interaction or set of states", on a brief, spec, mockup, or intent.
- `ax-audit`: agentic-feature PRs (agent dashboards, tool-use UIs, trust patterns). Run both on an agentic feature: ax-audit for the agent layer, ui-audit for the surfaces around it.
- `pr-reviewer`: correctness bugs and code quality in the same diff; ui-audit covers only user-facing quality and behavior.
- `typography-audit`: deep typography (pairing, OpenType systems, brand and display type); ui-audit's `type-` rules and typography sweep are the shallower check.
- `ui-animation`: motion implementation and review (springs, easing, gestures); ui-audit's `motion-` findings route here for the fix.

## Gotchas

- **Don't audit the whole codebase by default.** Full sweeps need an explicit request; otherwise the noise floor hides release-blockers.
- **Don't skip feature detection and run every rule on every file.** 95 rules × N files is a wall of backlog nits; per-feature playbook checks produce signal. Load only the `rules-modern/`, `rules-surface/`, `rules/` files the playbook names.
- **Don't assign `release-blocker` liberally.** Reserve it for data loss, broken critical paths, and dark patterns. If everything is a blocker, the verdict stops gating merges.
- **Don't prescribe fixes without the matching React 19 API.** "Add a loading state" is unactionable; "wrap in `}>`" gets applied.
- **Don't render markdown before the JSON document is complete.** Adapters project the JSON; skipping it loses `defaultTier`/`assignedTier`/`tierReason` and makes runs incomparable.
- **Don't double-report one issue across layers.** When Layers 2, 3, and 4 all touch one issue, keep only the most concrete framing; emitting all inflates the count and splits the fix. Layers 2 and 3 catching *different* issues on one feature (data loss vs missing label) is expected, not a duplicate.
- **Don't report a rendered-quality rule at its category default when the frontmatter overrides it.** `perf-image-dimensions-and-priority` is CRITICAL (CLS) even though `perf-` is a HIGH category.
- **Don't quote lawsofux.com verbatim.** It is CC BY-NC-SA; every Layer 4 rule paraphrases. Quoting contaminates the output's license.
- **Don't fabricate detections.** No grep/Read evidence → `result: "unknown"` with a `reason`, never a `fail`. The self-check flags audits with >30% unknowns.

## Audit self-check

Self-flag the audit `INCOMPLETE` if any are true:

- Fewer rules ran than planned (`rulesRun < rulesPlanned`)
- Over 30% of executed rules returned `unknown`
- Any fail/warn finding lacks a `file:line` citation
- Any fail/warn finding lacks a `fix` (and, where mechanical, a `fixSnippet`)
- No Read or Grep tool calls between findings (audit was guessed, not run)
- Every finding landed in the same tier (suspect blanket assignment)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mblode](https://github.com/mblode)
- **Source:** [mblode/agent-skills](https://github.com/mblode/agent-skills)
- **License:** MIT
- **Homepage:** https://www.skills.sh/mblode/agent-skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mblode-agent-skills-ui-audit
- Seller: https://agentstack.voostack.com/s/mblode
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.