variant-ux git:20260927.f9d8d40A

Immutable. This exact content never changes and is served at /api/v1/blob/cb81eaf111026d57.

---
name: variant-ux
description: UX Review mode — heuristic evaluation (Nielsen's 10), cognitive load analysis, mental model diagnosis, affordance audit, dark pattern detection — grounded in NNG research. Load references/ux-heuristics.md and references/ux-psychology.md. Triggers on: ux review, heuristic evaluation, usability audit, cognitive load, mental models, affordances, dark patterns, review this design, check usability, is this good UX
---

## UX Review Mode

When the user wants to evaluate usability rather than generate visuals, switch to UX Review mode. Load `references/ux-heuristics.md` and `references/ux-psychology.md`. Load additional references as the review scope demands (see "When to Load Which Reference" below).

### Triggers

| User says | Action | Load |
|---|---|---|
| "ux review" / "heuristic review" / "usability audit" | Full heuristic evaluation against Nielsen's 10 | `ux-heuristics.md` + `ux-psychology.md` |
| "review this design" / "what's wrong with this UI" | Heuristic scan → findings list with severity | `ux-heuristics.md` |
| "check usability" / "is this good UX" | Walk through flow, flag violations | `ux-heuristics.md` + `ux-psychology.md` |
| "cognitive load" / "too complex?" | Cognitive load analysis → reduction suggestions | `ux-psychology.md` |
| "why do users get confused here" | Mental model analysis → mismatch diagnosis | `ux-psychology.md` |
| "affordances" / "does this look clickable" | Affordance/signifier audit | `ux-psychology.md` |
| "dark patterns" / "is this ethical" | Dark pattern scan | `ux-psychology.md` |
| "navigation" / "can't find" / "information architecture" / "IA" | IA audit — labels, hierarchy, findability | `ux-information-architecture.md` |
| "site structure" / "how to organize" / "card sort" / "tree test" | IA design or validation | `ux-information-architecture.md` |
| "accessibility" / "a11y" / "screen reader" / "keyboard navigation" | Accessibility audit against WCAG 2.1 AA | `ux-accessibility.md` |
| "WCAG" / "alt text" / "aria" / "focus" | Specific accessibility check | `ux-accessibility.md` |
| "user testing" / "how to test this" / "usability test" | Research method recommendation + test plan | `ux-research-methods.md` |
| "what do users think" / "how do I get feedback" | Research method selection | `ux-research-methods.md` |
| "NPS" / "SUS" / "survey" / "interview users" | Measurement framework or interview guidance | `ux-research-methods.md` |
| "transition feels wrong" / "animation timing" / "state choreography" / "loading feels laggy" | Component transition audit | `ux-interaction-transitions.md` |
| "touch target" / "thumb zone" / "mobile gesture" / "iOS vs Android" | Mobile interaction audit | `ux-mobile-patterns.md` |
| "onboarding" / "empty state" / "first use" / "aha moment" / "activation" | Onboarding flow review | `ux-onboarding.md` |
| "chart" / "dashboard" / "data viz" / "KPI card" / "which chart" | Data visualization audit or recommendation | `ux-data-visualization.md` |
| "content model" / "taxonomy" / "multilingual" / "RTL" / "localization" | Content structure review | `ux-content-strategy.md` |
| "design tokens" / "token naming" / "theming" / "dark mode architecture" | Token architecture review | `ux-design-tokens.md` |
| "component spec" / "button states" / "modal behavior" / "ARIA" | Component spec review | `ux-component-specs.md` |
| "design critique" / "feedback on design" / "design review meeting" | Critique framework guidance | `ux-design-critique.md` |
| "conversion" / "landing page" / "trust signals" / "CTA copy" / "pricing page" | Conversion UX audit | `ux-conversion-patterns.md` |
| "error message" / "error state" / "form error" / "validation" / "recovery path" / "prevent errors" | Error design audit — classification, messaging, prevention | `ux-error-design.md` |
| "empty state" / "no data" / "blank state" / "nothing here" / "zero state" | Empty state design — all 4 types | `ux-empty-states.md` |
| "notification" / "toast" / "banner" / "badge" / "push notification" / "alert priority" | Notification system design and priority rules | `ux-notifications.md` |
| "table" / "data table" / "sorting" / "filtering" / "pagination" / "bulk select" / "row actions" | Table and list interaction design | `ux-tables-lists.md` |
| "search" / "autocomplete" / "search results" / "search bar" / "faceted search" / "command palette" | Search pattern design — input, suggestions, results | `ux-search-patterns.md` |

### UX Review Workflow

Two paths depending on what's available:
- **Code in cwd** → run Code Scan (Steps 1a–1b) first, then layer conceptual analysis
- **No code / screenshots / description only** → skip to Step 2

**Step 1a: Auto-detect project files**

```bash
# Find component files in cwd (skip node_modules, .git, dist)
find . \( -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.html" \) \
  -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" | head -30
```

If files found, proceed to Step 1b. Otherwise skip to Step 2.

**Step 1b: Code-level heuristic scan**

First run the shared deterministic scanner, then use the targeted greps below for heuristics that require human confirmation:

```bash
node <skill-root>/scripts/quality-gate.mjs <file-or-directory> --json
```

The scanner covers English and Chinese generic errors, missing image alt attributes, removed focus indicators, missing reduced-motion handling, placeholder content, and common resilience issues. Run these additional greps against the found files:

```bash
# H9 — Generic error messages (critical pattern)
grep -rn "error occurred\|something went wrong\|invalid input\|please try again\|An error\|Unknown error\|出错了\|发生错误\|未知错误\|输入有误\|请重试\|操作失败" \
  --include="*.tsx" --include="*.jsx" --include="*.vue" --include="*.html" \
  --exclude-dir=node_modules --exclude-dir=dist . 2>/dev/null

# H1 — Missing loading states: async handlers without loading flag
grep -rn "onClick\|onSubmit\|handleSubmit" \
  --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules . 2>/dev/null | head -20
# (then read those files to check if loading/disabled state is managed)

# H3 — Destructive actions: delete/remove calls without confirmation guard
grep -rn "delete\|remove\|destroy\|clearAll\|reset" \
  --include="*.tsx" --include="*.jsx" -i --exclude-dir=node_modules . 2>/dev/null | \
  grep -iv "confirm\|modal\|dialog\|undo\|trash\|soft" | head -20

# H4 — Terminology inconsistency: mixed action words for same concept
grep -rn '"Delete"\|"Remove"\|"Erase"\|"Discard"\|"Clear"' \
  --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules . 2>/dev/null
# Flag if multiple terms coexist in same codebase

# H6 — Icon-only buttons missing accessible label
grep -rn "<button\|<Button\|<IconButton" \
  --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules . 2>/dev/null | \
  grep -v "aria-label\|title=\|children\|tooltip" | head -20

# H5 — Forms missing inline validation
grep -rn "<form\|<Form\|onSubmit" \
  --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules . 2>/dev/null | head -10
# (then read those files to check for inline validation vs. submit-only)

# H10 — Empty states: no empty state handling
grep -rn "\.length === 0\|\.length == 0\|items\.length\|data\.length" \
  --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules . 2>/dev/null | \
  grep -v "EmptyState\|empty\|nothing\|no items\|no results" | head -15

# A11y — Images missing alt text
grep -rn "<img " \
  --include="*.tsx" --include="*.jsx" --include="*.html" \
  --exclude-dir=node_modules . 2>/dev/null | grep -v "alt=" | head -10

# A11y — Buttons missing accessible name (icon-only)
grep -rn "<button\|<Button\|<IconButton" \
  --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules . 2>/dev/null | \
  grep -v "aria-label\|aria-labelledby\|title=" | head -15

# A11y — onClick on non-interactive elements (no keyboard access)
grep -rn "onClick" \
  --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules . 2>/dev/null | \
  grep -E "<div|<span|<p" | head -15

# A11y — outline:none removing focus indicators
grep -rn "outline:\s*none\|outline:\s*0" \
  --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" \
  --exclude-dir=node_modules . 2>/dev/null | head -10

# A11y — Inputs missing associated label
grep -rn "<input" \
  --include="*.tsx" --include="*.jsx" --include="*.html" \
  --exclude-dir=node_modules . 2>/dev/null | \
  grep -v "type=\"hidden\"\|aria-label\|aria-labelledby\|id=" | head -10
```

For each scanner or grep result: read the flagged files at the relevant lines to confirm whether it is a real violation or a false positive. Report only confirmed violations.

**Step 2: Define scope** — What task(s) is the user trying to complete? What screens/flows are in scope?

**Step 3: Walk the flow** — Step through each screen as a first-time user would. For each screen, check:
- What is the user trying to do here? (H1: visibility of goal)
- Can they figure out how to do it? (affordances, signifiers)
- Will they know when it worked? (feedback, system status)
- What could go wrong? (error prevention)
- Is anything adding unnecessary mental work? (cognitive load)

**Step 4: Log violations** — For each violation found (from code scan or conceptual walk):
```
File: [path:line] or Screen: [name]
Heuristic: [H1–H10, or cognitive load / mental model / affordance]
Violation: [specific description — quote actual code or UI text where possible]
Severity: [1=cosmetic / 2=minor / 3=major / 4=critical]
Fix: [concrete recommendation with code example if applicable]
```

**Step 5: Report** — Present as a prioritized list, critical issues first. Group by heuristic to surface systemic problems.

**Step 6: Offer next step** — After the report, offer:
- `fix [H9]` → Generate corrected error messages as a code snippet or new component
- `generate fix` → Generate redesigned version of worst-offending screen as HTML/TSX
- `compare` → Side-by-side: current vs. fixed version opened in browser
- `checklist` → Generate a dev-ready fix checklist (markdown, copy-pasteable to GitHub Issues)

### UX Review Output Format

```
✦ UX Review: [screen/flow name]
  Scanned: 23 components · 4 violations found

  Critical (fix before launch)
  ────────────────────────────
  [H9] src/components/LoginForm.tsx:47
       catch(e) { setError("An error occurred") }
       Fix: setError(`Login failed: ${e.message}. Check your email and password.`)

  [H1] src/components/UploadButton.tsx:23
       onClick={handleUpload} — no loading/disabled state managed
       Fix: setLoading(true) on click; disabled={loading}; show <Spinner /> inside button

  Major (high priority)
  ─────────────────────
  [H3] src/pages/ProjectList.tsx:89
       onClick={() => deleteProject(id)} — no confirmation, immediate delete
       Fix: Move to trash: softDelete(id) + undo toast for 5s, or confirm dialog

  Minor (low priority)
  ────────────────────
  [H4] "Remove" (src/components/MemberList.tsx:34) vs "Delete" (src/pages/Settings.tsx:102)
       Same destructive action, two different words
       Fix: Standardize to "Remove" for members, "Delete" for owned resources

  Summary: 2 critical · 1 major · 1 minor
  Next: fix H9 · fix H1 · generate fix · checklist
```

### Quick Triggers for UX Review

| User types | Action |
|---|---|
| `ux scan` | Code scan only — run all heuristic greps, report file:line violations, no conceptual walk |
| `ux review` | Full review — code scan + conceptual walk + report |
| `ux review src/components/` | Scope scan to specific directory |
| `fix H9` | Generate corrected error message patterns as a code snippet |
| `fix H1` | Generate loading state pattern for flagged component |
| `fix H3` | Generate soft-delete / confirmation dialog pattern |
| `generate fix` | Generate redesigned screen that resolves all critical violations |
| `checklist` | Output dev-ready markdown checklist of all violations (copy to GitHub Issues) |
| `compare ux` | Side-by-side: current vs. UX-fixed version in browser |

### Cross-Mode Bridges

**From Site Analysis → UX Review:**
After `audit` extracts tokens and consistency issues, you can continue with `ux scan` — the two modes complement each other. Style audit catches visual/token issues; UX scan catches behavioral/interaction issues.

**From UX Review → Generate:**
After flagging violations, offer to generate a fixed version:
- `generate fix` → generate corrected screen as HTML/TSX, written to `variant-output/ux-fix-[screen].html`, opened in browser
- `compare ux` → write both current (screenshot or recreation) and fixed version, open side-by-side in `variant-output/_ux-compare.html`

**From Generate → UX Review:**
Every generated design runs `<skill-root>/scripts/quality-gate.mjs` plus the relevant heuristic checks before presentation. Fix confirmed critical violations before presenting the variation.

### When to Load Which Reference

| Question | Load |
|---|---|
| Nielsen heuristics evaluation | `references/ux-heuristics.md` |
| Mental models, cognitive load, Gestalt, affordances | `references/ux-psychology.md` |
| Navigation, findability, IA structure, labeling, search | `references/ux-information-architecture.md` |
| Accessibility, WCAG, keyboard nav, screen readers, a11y | `references/ux-accessibility.md` |
| User research methods, usability testing, interviews, surveys | `references/ux-research-methods.md` |
| Component state transitions, timing, easing, choreography | `references/ux-interaction-transitions.md` |
| Mobile gestures, thumb zones, iOS/Android conventions, touch targets | `references/ux-mobile-patterns.md` |
| Onboarding, empty states, Aha moment, first-use experience | `references/ux-onboarding.md` |
| Charts, dashboards, data visualization, chart selection | `references/ux-data-visualization.md` |
| Content models, taxonomy, multilingual UX, content lifecycle | `references/ux-content-strategy.md` |
| Design tokens, token architecture, theming, dark mode | `references/ux-design-tokens.md` |
| Component specs, button/form/modal states, ARIA patterns | `references/ux-component-specs.md` |
| Design critique, feedback frameworks, design review | `references/ux-design-critique.md` |
| Conversion, landing pages, trust signals, pricing UX, CTAs | `references/ux-conversion-patterns.md` |
| Error messages, validation, recovery paths, prevention layers | `references/ux-error-design.md` |
| Empty states (first use / cleared / no results / error) | `references/ux-empty-states.md` |
| Notifications — Toast, Banner, Badge, Push, priority management | `references/ux-notifications.md` |
| Tables, lists, sorting, filtering, pagination, bulk selection | `references/ux-tables-lists.md` |
| Search patterns — autocomplete, facets, results page, command palette | `references/ux-search-patterns.md` |
| Full UX review | Load all relevant references above |

**For generation tasks:** Load `ux-heuristics.md` and `ux-psychology.md` as silent quality constraints. Every generated design should pass the relevant mechanical and heuristic checks before being presented.