UX Audit

Dogfood web apps by browsing them as a real user would — with their goals, their patience, and their context. Goes beyond "does it work?" to "is it good?" by tracking emotional friction (trust, anxiety, confusion), counting click efficiency, testing resilience, and asking the ultimate question: "would I come back?" Uses Chrome MCP (for authenticated apps with your session) or Playwright for browser automation. Produces structured audit reports with findings ranked by impact.

Browser Tool Detection

Before starting any mode, detect available browser tools:

1. Chrome MCP (mcp__claude-in-chrome__*) — preferred for authenticated apps. Uses the user's logged-in Chrome session, so OAuth/cookies just work.
2. Playwright MCP (mcp__plugin_playwright_playwright__*) — for public apps or parallel sessions.
3. playwright-cli — for scripted flows and sub-agent browser tasks.

If none are available, inform the user and suggest installing Chrome MCP or Playwright.

See references/browser-tools.md for tool-specific commands.

URL Resolution

If the user didn't provide a URL, find one automatically. Prefer the deployed/live version — that's what real users see.

1. Check wrangler.jsonc for custom domains or routes:

   grep -E '"pattern"|"custom_domain"' wrangler.jsonc 2>/dev/null
   

   If found, use the production URL (e.g. https://app.example.com).

2. Check for deployed URL in CLAUDE.md, README, or package.json homepage field.

3. Fall back to local dev server — check if one is already running:

   lsof -i :5173 -i :3000 -i :8787 -t 2>/dev/null
   

   If running, use http://localhost:{port}.

4. Ask the user as a last resort.

Why live over local: The live site has real data, real auth, real network latency, real CDN behaviour, and real CORS/CSP policies. Testing locally misses deployment-specific issues (missing env vars, broken asset paths, CORS errors, slow API responses). The UX audit should test what the user actually experiences.

When local is better: The user explicitly says "test localhost", or the feature isn't deployed yet.

Depth Levels

Control how thorough the audit is. Pass as an argument: /ux-audit quick, /ux-audit thorough, or default to standard.

Exhaustive Mode

The exhaustive mode goes beyond thorough. Thorough tests workflows and pages. Exhaustive tests every single interactive element in the application.

For each page discovered:

1. Inventory all interactive elements — buttons, links, inputs, selects, checkboxes, toggles, tabs, accordions, modals triggers, dropdowns, context menus, drag handles, sliders
2. Click/interact with every one — open every dialog, expand every accordion, select every tab, toggle every switch, trigger every dropdown
3. Screenshot each state — default, hover, active, open, closed, expanded, collapsed, selected, error
4. Test every form — fill with valid data, submit. Fill with invalid data, submit. Leave empty, submit. Test every field individually.
5. Test every combination — if there are filters, test each filter value. If there are tabs, test each tab. If there are sort options, test each sort.
6. Dark mode + light mode — every page, every dialog, every state in both modes
7. Three viewport widths — 1280px, 768px, 375px for every page and dialog
8. Keyboard navigation — tab through every page, verify focus order, test Enter/Space/Escape on every interactive element
9. Right-click/context menus — if the app has custom context menus, test every option in every context
10. Edge states — what happens with 0 items, 1 item, 100 items, 1000 items? What happens with very long text in every field?
11. Concurrent tabs — open the same page in two tabs, interact in both, check for conflicts
12. Every error path — trigger every validation error, every 404, every permission denied, every timeout

Progress tracking: This mode generates a LOT of findings. Write findings to the report incrementally — don't hold everything in memory. Update docs/ux-audit-exhaustive-YYYY-MM-DD.md after each page is complete.

Element inventory format (per page):

/clients — 47 interactive elements
  [x] "Add Client" button — opens modal ✓, form submits ✓, validation ✓
  [x] Search input — filters correctly ✓, clear button works ✓, empty search ✓
  [x] Sort dropdown — all 4 options work ✓, persists on navigation ✗ (BUG)
  [x] Client row click — navigates to detail ✓
  [x] Star button — toggles ✓, persists on refresh ✓
  [ ] Pagination — next ✓, prev ✓, page numbers ✓, items per page ✗ (not tested - no data)
  ...

Thorough Mode: Overnight Workflow

The thorough mode is designed to run unattended. Kick it off at end of day, review the report in the morning. The user should NOT need to find issues themselves — this mode catches everything.

Mindset: Don't run through a checklist. Think about the real person who will use this app every day. What are the threads of their workday? How will they move through the system? Will they understand what they're looking at? Will the app teach them how to use it through its design, or will they be guessing? Read references/workflow-comprehension.md before starting.

1. Discover all routes — read router config, crawl navigation, build complete page inventory
2. Identify workflow threads — what are the 3-5 real tasks a user does in a day? Map them before testing individual pages. See references/workflow-comprehension.md.
3. Create a task list — track progress across the audit
4. Visual & layout sweep (every page):
   • Screenshot at 1280px, 1024px, 768px, 375px widths
   • Screenshot in light mode and dark mode
   • Run JS overflow detection on each page (see below)
   • Check for clipped text, overlapping elements, broken grids
   • Compare sidebar + content alignment across all pages
5. Workflow thread testing — follow each identified thread end to end:
   • Does the next step suggest itself at every point?
   • Can the user leave and come back without losing their place?
   • Do transitions between pages preserve context (filters, selections)?
   • Do nav labels match how a user would describe their work?
   • After creating/saving/deleting, does the app take them somewhere logical?
6. UX Walkthrough x3 personas:
   • First-time user (non-technical, time-poor, first visit)
   • Power user (daily user, knows the app, looking for efficiency)
   • Mobile user (phone, touch targets, small viewport)
7. Full QA sweep — every page, all CRUD, all states (empty, error, loading, populated)
8. Resilience testing — every form: bad data, mid-navigation, back button, refresh, double-submit
9. Accessibility basics — heading hierarchy, alt text, focus order, colour contrast
10. Console error sweep — check browser console on every page for JS errors, failed network requests, deprecation warnings
11. Wayfinding & comprehension check — on each page: do I know where I am? Can I get back? Does the heading tell me what I can do here? Are visual cues guiding me to the right action?
12. Scenario tests — run all six from references/scenario-tests.md:
    • New hire onboarding (can you figure out the app with zero guidance?)
    • Interrupted workflow (start a task, close the tab, come back — what survived?)
    • Wrong turn recovery (go to the wrong page, how many clicks to get back on track?)
    • Day two (repeat the same tasks — is it faster? are there shortcuts?)
    • Explain it to a colleague (write a 2-min guide for each workflow — gaps = UX failures)
    • What changed? (log in after creating data — can you tell what needs attention?)
13. Screenshot everything — save to .jez/screenshots/ux-audit/ (numbered chronologically)
14. Comprehensive report — docs/ux-audit-thorough-YYYY-MM-DD.md with issue counts by severity
15. Summary — top 5 critical issues, workflow gaps, scenario test results, "one thing to fix first"

Automated Layout Detection (JS Injection)

On each page, inject JavaScript via the browser tool to programmatically detect layout issues:

// Detect elements overflowing their parent
document.querySelectorAll('*').forEach(el => {
  const r = el.getBoundingClientRect();
  const p = el.parentElement?.getBoundingClientRect();
  if (p && (r.left < p.left - 1 || r.right > p.right + 1)) {
    console.warn('OVERFLOW:', el.tagName, el.className, 'extends beyond parent');
  }
});

// Detect text clipped by containers
document.querySelectorAll('h1,h2,h3,h4,p,span,a,button,label').forEach(el => {
  if (el.scrollWidth > el.clientWidth + 2 || el.scrollHeight > el.clientHeight + 2) {
    console.warn('CLIPPED:', el.tagName, el.textContent?.slice(0,50));
  }
});

// Detect elements with zero or negative visibility
document.querySelectorAll('*').forEach(el => {
  const s = getComputedStyle(el);
  const r = el.getBoundingClientRect();
  if (r.width > 0 && r.height > 0 && r.left + r.width < 0) {
    console.warn('OFF-SCREEN LEFT:', el.tagName, el.className);
  }
});

// Detect low contrast text (rough check)
document.querySelectorAll('h1,h2,h3,p,span,a,li,td,th,label,button').forEach(el => {
  const s = getComputedStyle(el);
  if (s.color === s.backgroundColor || s.opacity === '0') {
    console.warn('INVISIBLE TEXT:', el.tagName, el.textContent?.slice(0,30));