Skip to main content
command CX Codex

ux-audit — Claude Code command: UX review and installation

ux-audit is a Claude Code command that reviews an existing page or interface across six UX lenses. It runs on requests to audit a surface, assess its quality, or find what is broken.

MIT ★ 110 updated 2026-11-02

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill
Open on GitHub

What ux-audit does

ux-audit examines how a surface fits its audience and goal, how easily people find actions, how the page reads visually, and how it handles interaction, copy, and errors. Each finding names a principle, gives evidence from the surface, suggests a fix, and receives a severity label. Findings are grouped by lens.

Provide a URL, a file or screenshot path, a code snippet, or a description. When .ux/last-frame.json exists, the command reads it for audience and outcome context. It fetches URLs with WebFetch or a browser MCP if one is available. The surface must already exist; ux-design is for new work, while separate commands cover single-lens reviews. Backend-only tasks and infrastructure are out of scope.

What it helps with

  • spot UX issues on an existing page
  • rank findings by severity
  • check interface choices against UX principles
  • turn observations into suggested fixes

Example prompts for the agent

  • Audit this page for UX issues and group the findings by severity.
  • Review the interface in src/pages/home.tsx across all six UX lenses.
  • Inspect this screenshot and report evidence with suggested fixes.

How to install ux-audit

1Plugin marketplace

/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill

2Manually: put the files in place

.claude/commands/ux-audit.md

Call it with /ux-audit. For all projects use ~/.claude/commands/

Questions about ux-audit

How do I install ux-audit in Claude Code?

Run /plugin marketplace add Laith0003/ux-skill, then /plugin install ux@ux-skill. The command file is .claude/commands/ux-audit.md.

What does ux-audit do?

It reviews an existing interface across six UX lenses and produces grouped findings with severity labels, evidence, and suggested fixes.

What can I give ux-audit to inspect?

It accepts a URL, an absolute path to code or markup, a screenshot path, a code snippet, or a description of the surface.

Source text

ux-audit.md · MIT
---
description: Full 6-lens UX review of a surface. Outputs a structured Polaris-style report with findings, severity, evidence, and fixes. Triggers on "audit", "review the ux", "is this any good", or "what's broken". Use when auditing UX on a page or surface, running a structured UX review, the user asks "is this any good", checking against Norman / Krug / Laws of UX, producing a Polaris-style severity-tagged report. Skip when the surface doesn't exist yet (use ux-design for new builds), the user wants only one lens (use the targeted command — ux-a11y / ux-copy / ux-motion / ux-polish), backend-only work, infrastructure.
allowed-tools: Read, Write, Edit, Bash(ls:*), Bash(cat:*), Bash(find:*), Bash(mkdir:*), Bash(curl:*), Bash(date:*), Glob, Grep, Task, WebFetch
disable-model-invocation: false
---

# /ux-audit

You are running the `/ux-audit` command from the `ux` plugin. The job is a structured, opinionated review of a surface against six lenses, producing findings the user can act on.

## When to use

Triggers: "audit", "review the ux", "is this any good", "what's broken", "audit this page", "ux review", "tear this apart".

Use when the surface already exists (live URL, mockup, code, screenshot) and the user wants a structured, defensible critique with severity-tagged findings. Not for taste calls — that is `/ux-critique`. Not for a single dimension — use `/ux-copy`, `/ux-a11y`, `/ux-motion`, or `/ux-polish` for narrow scopes.

## Input

One of: a URL, an absolute file path to code or a markup file, a screenshot path, a code snippet pasted in chat, or a free description. If multiple, treat them as the same surface.

If `.ux/last-frame.json` exists, read it first — audience and outcome anchor every finding's severity.

## Process

### 1. Anchor to the framing

Read `.ux/last-frame.json` if present. If absent and the surface clearly needs framing context, suggest running `/ux-discover --frame` first, but proceed if the user insists.

### 2. Read the surface

- URL → fetch the page (WebFetch or the browser MCP if available).
- File path → read the file.
- Screenshot → look at the image.
- Code snippet → use as-is.
- Description → ask one clarifying question if too vague to inspect, then proceed.

### 3. Run the six lenses in order

For each lens, identify findings, cite which principle each finding violates, write evidence (what you saw) and a fix (what to do).

#### Lens 1 — FRAME

Reference: `references/process/lean-ux-gothelf.md` and `references/process/lean-ux-klein.md`.

Check: does the surface match the audience and outcome from the framing? Is the hypothesis observable in the surface? Is the success signal supported by what the user can do here?

If the framing is missing, this lens checks: does the surface have a clear "who is this for and what changes for them?" signal — or is it generic?

Every page gets two named checks. The **stranger test**: show someone new only the first screen and ask them to name the product and its reader; a page that needs the scroll to answer fails. The **swap test**: put a rival's name into the headline; a headline that stays true says nothing about this product. Write findings as counts, never adjectives: "four filled buttons above the fold", not "cluttered".

#### Lens 2 — DISCOVER

Reference: `references/laws/norman.md`.

Check: signifiers (does the user see what they can do?), discoverability (are key actions findable in under three seconds?), mental models (does it match what the audience expects from this category of product?), gulf of execution (can the user form an intention here?).

#### Lens 3 — SCAN

Reference: `references/laws/krug.md`.

Check: information hierarchy (does the eye know where to land?), self-evidence (can the user grok the page without reading?), noise reduction (what can be cut?), the squint test (does the layout survive blurred vision?).

#### Lens 4 — ACT

Reference: `references/laws/laws-of-ux.md` and `references/laws/norman.md`.

Check: Fitts's law (are tap targets sized and placed for the gesture?), Hick's law (too many choices at decision points?), feedback (does every action have a visible response within 100ms?), affordances (do controls look like the kind of control they are?).

#### Lens 5 — READ

Reference: `references/foundations/copy.md`.

Check: are CTAs verb + outcome? Are errors specific with the fix included? Are empty states helpful, not decorative? Is the voice consistent? Is the copy doing work or filling space?

#### Lens 6 — RECOVER

Reference: `references/laws/norman.md` and `references/foundations/accessibility.md`.

Check: error prevention (can the user undo or be warned before mistakes?), error recovery (when something goes wrong, can the user fix it without leaving?), accessibility floor (contrast, focus, keyboard, screen reader basics — full audit lives in `/ux-a11y`).

### 4. Score and group findings

For each finding, assign severity:

- **Critical** — blocks the success signal. Audience cannot complete the outcome.
- **High** — degrades the success signal significantly. Outcome possible but friction is severe.
- **Medium** — friction the audience will tolerate but should not have to.
- **Cosmetic** — polish issue. Audience may not notice, but a discerning reviewer would.

Group findings by lens. Within each lens, sort Critical → Cosmetic.

**What each finding rests on.** Tag every finding with its `evidence_kind`: `measured` (a tool read it), `counted` (the arithmetic is shown), `quoted` (a user's or the client's words, with where they come from), `observed` (seen on the surface), `heuristic` (a named, published principle), `assumed`, `hypothesis`, `unknown`, or `out-of-scope`. An assumption sits in the finding it weakens, not in a closing disclaimer. A threshold is either cited to its source for what the source says, or labelled a house default; never present one as the other. `unknown` is a valid answer. Never predict a lift in conversion or in any other number.

**Brand fidelity (when a client brand is on file).** If `.ux/brand.json` exists, also judge BRAND FIDELITY: run `evaluate(html, brand_profile=...)` (or read it from a prior `uxskill evolve --brand-file` run) for `brand_fidelity` + `imagery` + `brand_passed`. Treat off-brand drift — wrong or absent brand primary, missing logo, house-style colors (clay `#cc785c` / blurple `#5e6ad2`), or a text-wall with no real imagery — as a **Critical** finding under DISCOVER: a surface that ignores the client's brand fails no matter how polished. See `references/process/brand-extraction.md`.

### 5. Format the output

Use the Polaris-style report template per `references/output/polaris-style.md`. Skeleton:

```
─── audit ───
Surface:          <URL / path / brief description>
Framing anchor:   <audience + outcome, or "no framing on file">
Severity counts:  Critical <n> | High <n> | Medium <n> | Cosmetic <n>

─── findings ───

FRAME
  [<severity>] <finding title>
    Principle: <which principle>
    Evidence:  <what you saw>
    Rests on:  <evidence_kind, with its source or its arithmetic>
    Fix:       <what to do>

DISCOVER
  ...

SCAN
  ...

ACT
  ...

READ
  ...

RECOVER
  ...

─── strategic moves ───
1. <highest-impact move based on finding cluster>
2. <second move>
3. <third move>
```

Keep each finding to four lines. No prose paragraphs in the findings section.

### 6. Persist state

Write `.ux/last-audit.json`:

```json
{
  "command": "ux-audit",
  "timestamp": "<ISO8601>",
  "surface": "<URL / path / description>",
  "findings": [
    {
      "lens": "FRAME | DISCOVER | SCAN | ACT | READ | RECOVER",
      "severity": "Critical | High | Medium | Cosmetic",
      "title": "<short>",
      "principle": "<which principle>",
      "evidence_kind": "measured | counted | quoted | observed | heuristic | assumed | hypothesis | unknown | out-of-scope",
      "evidence": "<what you saw>",
      "fix": "<what to do>"
    }
  ],
  "severity_counts": { "critical": <n>, "high": <n>, "medium": <n>, "cosmetic": <n> },
  "dominant_lens": "<lens with highest-severity cluster>",
  "strategic_moves": ["<m1>", "<m2>", "<m3>"]
}
```

### 7. Optional fix loop

If the user passed `--fix`, after writing the report enter the fix loop:

1. Validate clean working tree.
2. For each finding sorted Critical → Cosmetic (skip Cosmetic unless `--include-cosmetic`):
   - If it is a code/layout finding → dispatch `frontend-engineer` sub-agent via Task tool.
   - If it is a copy finding → dispatch `copy-writer` sub-agent.
   - If it is a motion finding → dispatch `motion-engineer` sub-agent.
   - Where findings are independent, dispatch the agents in parallel in a single message.
3. Each agent commits atomically with a message linking the finding title.
4. After fixes, re-run the audit and report deltas.

If no `--fix`, end with the next-prompt block.

## Output

The audit report from step 5, followed by either fix-loop results (if `--fix`) or the next-prompt block.

## State persisted

- `.ux/last-audit.json` keys: `command`, `timestamp`, `surface`, `findings` (array of `{lens, severity, title, principle, evidence_kind, evidence, fix}`), `severity_counts`, `dominant_lens`, `strategic_moves`.

## Next prompt

Based on `dominant_lens` (the lens with the highest-severity cluster), recommend the narrower follow-up:

- FRAME → `/ux-discover --frame` (the brief is the problem)
- DISCOVER → `/ux-audit --fix` (structural fixes)
- SCAN → `/ux-polish` (hierarchy and rhythm)
- ACT → `/ux-audit --fix` (interaction-level fixes)
- READ → `/ux-copy --fix` (copy pass)
- RECOVER → `/ux-a11y` (accessibility deep-dive)

Print:

```
─── next ───
Recommended: <command keyed off dominant lens>
Other moves: /ux-audit --fix    (apply all findings)
             /ux-critique        (taste call instead of structured)
             /ux-next            (let me decide)
```

## Hard rules

- Never produce a finding without a citation to the relevant reference principle.
- Never write a finding longer than four lines (Principle, Evidence, Rests on, Fix). Push detail into the fix loop or a follow-up command.
- Never skip a lens because the surface "doesn't need it." Run all six — "no findings" is itself a finding.
- Never use vague severity ("kinda bad"). Critical / High / Medium / Cosmetic only.
- Never start a fix loop without a clean working tree confirmation.
- Never dispatch the wrong agent — code findings to `frontend-engineer`, copy to `copy-writer`, motion to `motion-engineer`.

## Failure modes

- **Tour-guide audits**: describing what the surface does instead of what is wrong. Every finding must name a problem and a fix.
- **Severity inflation**: marking everything Critical. If severity counts are skewed, force triage — only outcome-blockers are Critical.
- **Lens skip**: running 4 lenses because the others "seem fine." Run all 6.
- **Fix without verify**: applying fixes in `--fix` mode but not re-running the audit. The user needs to see the delta.
- **Parallel-dispatch confusion**: dispatching dependent agents in parallel. If two findings touch the same file, queue them sequential.

## Error Handling

| Error condition | Recovery |
|---|---|
| Surface URL returns 4xx / 5xx / timeout | Fall back to a file path, screenshot, or pasted code; surface the fetch error to the user |
| File path does not exist | List nearby paths with `ls` of the parent directory; ask which one matches |
| Screenshot too low-resolution or scope too broad to inspect | Ask for higher resolution or scope narrowed to one section |
| `.ux/last-frame.json` absent and surface clearly needs framing | Suggest running `/ux-discover --frame` first; proceed if the user insists, with "no framing on file" stamped on the report |
| Description-only input with no inspectable artifact | Ask one clarifying question to either obtain an artifact or narrow scope; then proceed |
| `--fix` requested on a dirty working tree | Stop; prompt for commit / stash / abort before any dispatch |

For path issues: see references/process/discovery-protocol.md for state file location (.ux/ in project root). Report bugs at https://github.com/Laith0003/ux-skill/issues.

---

## v2 Python integration — required preamble

Before producing any judgment, the LLM running this command MUST shell to the v2 Python engine to ground its work in deterministic rules. The mechanical pass runs first; the taste pass runs second.

### Step 1 — Run the deterministic linter

```bash
python3 -m engine.cli.main --no-pretty lint <user-supplied-path> --threshold high > /tmp/ux-lint-report.json 2>/dev/null \
  || bash bin/ux-lint.sh <user-supplied-path>
```

The Python linter reads rules from `data/anti-patterns.json` (35 regex rules across 8 categories). It returns structured JSON with findings keyed by file:line:column.

### Step 2 — Inspect findings

```bash
cat /tmp/ux-lint-report.json | python3 -c "
import json, sys
r = json.load(sys.stdin)
s = r['summary']
print(f\"scanned: {r['files_scanned']} files, {r['rules_loaded']} rules\")
print(f\"  critical: {s.get('critical', 0)}\")
print(f\"  high:     {s.get('high', 0)}\")
print(f\"  medium:   {s.get('medium', 0)}\")
print(f\"  low:      {s.get('low', 0)}\")
print(f\"  total:    {s.get('total', 0)}\")
for f in r['findings'][:20]:
    print(f\"  [{f['severity']}] {f['file']}:{f['line']} {f['rule_name']} ({f['rule_id']})\")
"
```

### Step 3 — Command-specific Python action

Pull the picked style guidelines from `data/styles.json` and the relevant industry rules from `data/industries.json` via:

```bash
test -f .ux/last-discovery.json && python3 -c "
import json
disc = json.load(open('.ux/last-discovery.json'))['answers']
industry = disc.get('industry') or disc.get('audience', '')
print(f'Industry hint: {industry}')
print(f'Forbidden patterns: {disc.get(\"forbidden\", \"\")}')
print(f'Must-have constraints: {disc.get(\"must_have\", \"\")}')
"
```

Use those constraints as the audit's frame.

### Step 4 — Hand back to the LLM

Take the structured findings from Step 1 and any data the engine returned in Step 3, and use those AS YOUR INPUT to the LLM-side reasoning. Do NOT re-derive what the linter already proved — the regex pass is the truth on those rules. Your job is the taste-level judgment the linter cannot make.

### Fallback

If `python3 -m engine.cli.main` is not on PATH, fall back to `bash bin/ux-lint.sh` for the linter pass and v1 prose-only behavior for everything else.

© Laith Aljunaidy · MIT · Laith0003/ux-skill

Similar slash commands

All slash commands for Design →

From the same set31

The whole set →
ux-case-study ux-case-study generates a strict monochrome project case study with fixed (A)–(G) sections. Useful for documenting shipped deliverables after a milestone or launch. CX Codex +1 ★ 110repo stars ux-dashboard ux-dashboard forwards its arguments to /ux-design --dashboard and runs dashboard mode. It is a legacy alias scheduled for removal in version 4.1. CX Codex +1 ★ 110repo stars ux-copy ux-copy — a Claude Code command that audits every visible interface string against a voice rubric and returns a before/after table with per-string severity. CX Codex +1 ★ 110repo stars ux-critique ux-critique provides a designer's opinion on a UI surface, returning three wins, three misses, and one strategic move. Reviews mockups, screenshots, and front-end files. CX Codex +1 ★ 110repo stars ux-a11y ux-a11y audits a page or component against WCAG 2.1 AA and flags issues automated scanners miss. Run it before shipping or right after a redesign to catch accessibility regressions. CX Codex +1 ★ 110repo stars ux-fix ux-fix executes an opt-in fix loop from UX reports, routing fixes to specialized sub-agents with atomic Git commits. CX Codex +1 ★ 110repo stars ux-motion ux-motion audits interface animations for timing, easing, purpose, reduced-motion support, and performance. Use it when transitions feel off or need a focused review. CX Codex +1 ★ 110repo stars design-system-architect design-system-architect assembles a full design system: tokens, foundation docs, and component contracts. It's dispatched by /ux-system and /ux-design --component when no system exists yet. CX Codex ★ 110repo stars

Project sponsors

Companies that keep this analytics open