ux-audit-02c29d— agent skill

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.

D7 structured framework - apply per flow:

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:

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)

<!-- Copy this template for each P1 flow. Number sequentially: F1, F2, F3... -->

#### 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]

<!-- Add F3, F4, F5 as needed. Aim for 3-5 P1 flows covering each primary role. -->

Priority 2 flows (full mode only)

<!-- Add P2 flows for secondary tasks, edge-case roles, or less critical journeys. -->

#### 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)

1. 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

1. 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).

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)