ux-audit

name	ux-audit
description	UX audit: evaluate user flows against ISO 9241-11 and Nielsen heuristics. Measures task completion, feedback clarity, cognitive load, error recovery via Playwright.

Configuration (fill in before first run)

Replace these placeholders:

• [DEV_URL] - e.g. http://localhost:3000
• [LOGIN_ROUTE] - your login page path, e.g. login, signin, auth/login
• [SITEMAP_OR_ROUTE_LIST] - e.g. docs/sitemap.md
• [TEST_ACCOUNTS] - email/password pairs per role
• [DEV_COMMAND] - e.g. npm run dev, pnpm dev

Then fill in the Flow catalog (Step 5) with your project's key user journeys. Start with 3-5 Priority 1 flows covering the most critical tasks per role.

If [DEV_URL] or [SITEMAP_OR_ROUTE_LIST] is not filled, the skill reports an error and exits.

Step 0 - Mode + target detection

Parse $ARGUMENTS:

Mode (which flows to run):

• role:<role> → run all flows for a specific role (e.g. role:viewer)
• full → run all flows including Priority 2
• No mode keyword → standard - run all Priority 1 flows (P1) for all roles

Target (filters to a specific area - applied on top of mode):

• target:role:<role_name> → only that role's flows
• No target → no filter - run ALL flows in the selected mode across ALL routes in [SITEMAP_OR_ROUTE_LIST]

STRICT PARSING - mandatory: derive mode and target ONLY from the explicit text in $ARGUMENTS. Do NOT infer target from conversation context, recent work, active block names, or project memory. If $ARGUMENTS contains no target: token → apply NO filter (run all flows in the selected mode). If $ARGUMENTS is empty → STANDARD mode, full scope (all P1 flows, no filter).

Announce at start: Running ux-audit in [STANDARD | FLOW:<id> | ROLE:<role> | FULL] mode - scope: [FULL | target: <resolved description>]

---

Step 1 - Load architecture context

Read in parallel:

1. [SITEMAP_OR_ROUTE_LIST] - full route inventory, sub-hierarchies, role mapping, test accounts

From sitemap sub-hierarchies, build a mental model of:

• What tabs exist per page
• What states each page can be in (empty, loading, error, data)
• What actions are available per role
• Which flows are newly implemented (check docs/implementation-checklist.md for recently completed blocks) - these need extra scrutiny

---

Step 2 - Pre-flight check

Navigate to [DEV_URL]. If not reachable:

❌ Dev server not running. Start with [DEV_COMMAND] then re-run /ux-audit.

Record the base URL. If redirected to /login, record that a session must be established first.

---

Step 3 - UX evaluation framework

Apply these 7 dimensions to every flow simulated. Dimensions are anchored to ISO 9241-11 (Effectiveness / Efficiency / Satisfaction) and Nielsen's 10 Usability Heuristics for rigour and comparability.

Dimension	ISO anchor	Nielsen heuristic	Question	What to look for
D1 - Task completion	Effectiveness	H1 Visibility of status	Can the user finish the task without confusion?	Dead ends, missing CTAs, ambiguous button labels, unexpected redirects
D3 - Feedback clarity	Effectiveness	H1 Visibility · H9 Error recovery	Does the user always know what happened?	Toast presence/absence, loading states, success/error messaging, state changes; error message quality: Specific ✅ / Generic ⚠️ / Absent ❌
D4 - Navigation clarity	Efficiency	H4 Consistency · H6 Recognition	Does the user always know where they are?	Page titles, breadcrumbs, back affordances, active state in sidebar, role-specific routes
D5 - Cognitive load	Efficiency	H8 Minimalist design	How many decisions or pieces of info per screen?	Form fields per step, actions per card, info density, label clarity; Baymard optimal: ≤8 fields per step
D6 - Error recovery	Effectiveness	H9 Recognize/diagnose/recover	When something goes wrong, is the path forward clear?	Validation messages, retry affordances, empty state guidance, rejection states
D7 - User confidence	Satisfaction	H3 User control · H5 Error prevention	Does the user feel in control and certain of the outcome?	Structured C1-C5 checks (apply per flow - see framework below): C1 Cancel path in all dialogs/forms; C2 Irreversible actions guarded by confirmation; C3 State-changing action has visible confirmation; C4 Read-only constraints explicitly communicated; C5 Multi-step flows confirm outcome.

D7 structured framework - apply per flow:

Check	What to verify	PASS	FAIL
C2 - Destructive guard	Irreversible actions trigger confirmation BEFORE execution	Confirmation dialog with action name + consequence	Single-click destructive action without confirmation
C3 - Silent success prevention	Every state-changing action has visible confirmation	Toast + page reflects new state (status badge changes)	Toast absent OR page unchanged after action
C4 - Constraint visibility	Read-only constraints explicitly communicated	Label, tooltip, or disabled button with explanation	Functionality silently absent
C5 - Positive feedback	Multi-step flows confirm outcome explicitly	Explicit success state, not just redirect	Redirect to list with no success indication

Record per flow: C1:[✅/❌/N/A] C2:[✅/❌/N/A] C3:[✅/❌/N/A] C4:[✅/❌/N/A] C5:[✅/❌/N/A]

Severity scale:

• Critical - user cannot complete a core task (blocker)
• Major - user is confused or slowed significantly (friction)
• Minor - small inconsistency or suboptimal pattern (polish)

---

Step 4 - Component context load

Before simulating each flow, read the primary page file and key components involved in that flow. Specifically look for:

• Form field count and labels - are they clear and unambiguous?
• CTA button labels - are they action-oriented (verb + noun) or vague (e.g., "Submit")?
• Post-submit behavior - does the code show a redirect, modal close, or toast?
• Empty state handling - is there a meaningful empty state or just a blank area?
• Error state handling - are validation errors per-field or only at submit?

Baymard form checklist (apply to every flow involving a form)

Source: Baymard Institute - 4,400+ moderated usability sessions.

For each form in the flow, during code inspection verify:

#	Check	Good practice	Baymard finding
BF1	Error message content	Field-specific: "Amount must be positive"	98% of sites use generic messages - users cannot recover
BF2	Inline validation timing	Fires on onBlur or post-submit - NOT onChange	Premature validation disrupts typing and increases errors
BF3	Positive inline validation	Shows ✓ or green border after correction	Reduces user anxiety; confirms correction was accepted
BF4	Required/optional labeling	Required = *; Optional fields explicitly labeled	Unlabeled optional fields cause over-completion
BF5	Multi-step progress	"Step N of M" - exact count, not vague percentage	Accurate progress reduces abandonment in multi-step flows
BF6	Field count per step	≤ 8 fields without stepper; flag if exceeded	Optimal: 6–8 fields. Average: 11.3 (Baymard e-commerce data)

Record BF1–BF6 verdict for each form. Include in D3/D5/D6 analysis as evidence.

This code context MUST be referenced in the D1–D7 analysis. Don't rely purely on what Playwright shows.

---

Step 5 - Flow catalog

Customise before first run. Replace the example flows below with your project's actual user journeys. Define 3-5 Priority 1 flows covering the most critical task per role. Add Priority 2 flows for full-mode coverage.

Priority 1 flows (always run in standard mode)

F1 - [Flow name] (e.g. Create record, Submit form, Complete onboarding)

Role: [role from RBAC table] · Priority: 1 Read before simulating: [primary page/component path] Steps:

1. Login with [role] credentials → navigate to [route]
2. [Trigger action - click CTA, open form, etc.]
3. [Fill required fields]
4. Submit
5. Verify: [expected outcome - redirect, toast, record in list, status change]

Evaluate: D1 (can user find the CTA?), D3 (success feedback + BF1 message quality), D5 (field count vs BF6), D6 (validation messages specific per BF1?), D7 (cancel path present?)

F2 - [Flow name]

Role: [role] · Priority: 1 Steps:

1. [step]

Evaluate: [relevant dimensions]

---

Priority 2 flows (full mode only)

F[N] - [Flow name]

Role: [role] · Priority: 2 Steps: [route] → [action sequence] Evaluate: [relevant dimensions]

---

Step 6 - Flow simulation

For each flow in scope:

1. Code context load (Step 4): read primary page file + key components. Apply Baymard form checklist (BF1–BF6) to any form in the flow.
2. Setup: Login with correct credentials (reuse session if same role as previous flow)
3. DOM preflight after each navigate: evaluate readyState, main content presence (>30 chars), and absence of error indicators. If main content missing → flag and report, do not simulate the flow.
   • Initial page load
   • After each interaction (form open, field filled, submitted, redirected)
   • Error state (if triggerable without data setup)
4. Measure per flow:
   • Total clicks to complete task (target: ≤ 3 for primary actions)
   • Wasted clicks: clicks that produced no navigation or visible DOM change within 300ms - note each one as a discoverability failure candidate
   • Form field count (target: ≤ 8 per step per BF6)
   • Error message quality rating: Specific ✅ / Generic ⚠️ / Absent ❌ (per D3/BF1)
   • Redirect count after submission (target: ≤ 1)
   • Confirmation dialogs present: Yes / No for each destructive action attempted
5. Evaluate against D1–D7, referencing both what Playwright shows and code context

Session management

Login helper:
1. browser_navigate [DEV_URL]/[LOGIN_ROUTE]
2. If at /: check for correct role indicator
   - If wrong role: sign out → wait for login page
3. browser_type email field
4. browser_type password field
5. browser_click submit
6. browser_wait_for url contains [DEV_URL]/

---

Step 7 - Analysis pass

After simulation, for each flow apply a structured analysis:

Per dimension (D1–D7):

• What did you observe in the browser?
• What does the code tell you about the intended behavior?
• Does it meet the expectation for that dimension?
• If not: what is the specific friction point?
• What is the severity (Critical / Major / Minor)?
• What is the concrete fix?

Cross-flow consistency check:

• CRUD across different entities (from [SITEMAP_OR_ROUTE_LIST]): same action placement and pattern?

Heuristic sweep (after all flows - 5 checks)

Run these 5 heuristic checks across the full set of pages visited during simulation. These are cross-cutting patterns not captured by individual flow steps.

Source: Nielsen Norman Group - 10 Usability Heuristics for User Interface Design (original 1994, updated 2020).

H#	Heuristic	What to check	Flag if
H5	Error prevention	Destructive or irreversible actions (delete record, change status irreversibly, revoke access, cancel application) trigger a confirmation dialog BEFORE execution - not after.	Any destructive action that executes on single click without confirmation
H6	Recognition vs recall	Form fields have persistent visible labels - not just placeholder text that disappears on focus/fill. User should not need to remember what a field asked.	Any input relying solely on placeholder for its label
H8	Minimalist design	Each screen shows only information needed for the current task. Identify any UI element with low information value that adds visual noise or competes with primary content.	Any page where the eye has nowhere obvious to start
H9	Error diagnosis	Validation error messages name the specific field AND tell the user what correction is needed (not just that one is needed).	Any generic "This field is required" without the specific constraint

Record each heuristic check result as: ✅ Pass / ⚠️ Issue found / ❌ Violation. Include in report.

---

Step 8 - Report

## UX Audit - [DATE] - [MODE] - [TARGET]
### Reference: [SITEMAP_OR_ROUTE_LIST] · flows F[N]–F[N]
### Framework: ISO 9241-11 (Effectiveness/Efficiency/Satisfaction) · Nielsen's 10 Heuristics · Baymard Form Research
### Scope: task completion · consistency · feedback · navigation · cognitive load · error recovery · user confidence
### Out of scope: token compliance → /ui-audit | Responsiveness → /responsive-audit

---

### Executive summary

| Severity | Count | Top issue |
|---|---|---|
| Critical | N | [one-line description] |
| Major | N | [one-line description] |
| Minor | N | [one-line description] |

---

### Flow results

#### F[N] - [Flow name] - [Role]

- **Task completion**: [steps taken] / [total clicks] clicks / [wasted clicks] wasted
- **Form**: [field count] fields · Error messages: Specific ✅/Generic ⚠️/Absent ❌ · Cancel path: Yes/No · Confirmation on destructive: Yes/No/N/A
- **Baymard form**: BF1:[✅/⚠️] BF2:[✅/⚠️] BF3:[✅/⚠️] BF4:[✅/⚠️] BF5:[✅/⚠️] BF6:[✅/⚠️]
- **D7 user confidence**: C1:[✅/❌/N/A] C2:[✅/❌/N/A] C3:[✅/❌/N/A] C4:[✅/❌/N/A] C5:[✅/❌/N/A]
- **Code context**: [key finding from reading the component - 2-3 bullet points]
- **Outcome**: ✅ Completed without friction / ⚠️ Completed with friction / ❌ Could not complete

**Findings:**

| # | Dimension | ISO | Severity | Observation | Fix |
|---|---|---|---|---|---|
| UX-[N] | D[N] - [name] | Eff/Eff/Sat | Critical/Major/Minor | [what was observed + code reference] | [concrete suggestion] |

**Screenshots**: [list filenames]

---

[Repeat for each flow]

---

### Heuristic sweep results

| H# | Heuristic | Result | Affected pages | Finding |
|---|---|---|---|---|
| H3 | User control & freedom | ✅/⚠️/❌ | [routes] | [or "Pass"] |
| H5 | Error prevention | ✅/⚠️/❌ | [routes] | |
| H6 | Recognition vs recall | ✅/⚠️/❌ | [routes] | |
| H8 | Minimalist design | ✅/⚠️/❌ | [routes] | |
| H9 | Error diagnosis | ✅/⚠️/❌ | [routes] | |

---

### Cross-flow consistency gaps

| Pattern | Routes compared | Gap | Severity |
|---|---|---|---|

---

### Prioritised fix list

Order by severity, then by impact (flows affected):

1. **[UX-N]** · Critical · [one-line fix description]
2. **[UX-N]** · Major · [one-line fix description]
...

---

### What's working well
[2–4 positive observations - patterns that are clear, consistent, and worth preserving]

### Skipped flows
[List any flows skipped due to missing test accounts or preflight failures]

---

Step 9 - Final offer

After the report:

"Want to dig into a specific finding? I can:

• Heuristic deep-dive: analyse a specific heuristic across all pages (e.g. H5 on all flows with destructive actions)
• Compare two specific sections for consistency
• Generate a fix checklist to integrate into the backlog (docs/refactoring-backlog.md) via the backlog write-once protocol (.claude/rules/backlog-protocol.md)"

Do NOT apply code changes directly. UX findings must be validated with the user before implementation - they often require design decisions, not just code fixes.

---

Step 10 - Screenshot cleanup

After the report is delivered, delete any screenshots taken during analysis with rm. Run unconditionally at session end.

---

Stack adaptation (fill after scaffold)

Key	Your value	Examples
[DEV_URL]		http://localhost:3000, http://127.0.0.1:8080
[LOGIN_ROUTE]		login, signin, auth/login
[SITEMAP_OR_ROUTE_LIST]		docs/sitemap.md, docs/routes.md
[TEST_ACCOUNTS]		email/password pairs per role
[DEV_COMMAND]		npm run dev, python manage.py runserver