uiux git:20261007.fac2a4eA

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

---
name: uiux
description: Build and audit web UI with real UX discipline. When building or changing UI, apply hard rules (pastel palette unless the user picks colors, no stat cards with icon tiles, no icons in rounded squares, no pill badges, search and filters on every table column, overlays that size to their content, form modals with a pinned header and footer, one scroll area and aligned fields, custom scrollbars, date pickers, selects and other controls instead of browser built-ins, specific and consistent layouts, no semicolons or em dashes in copy, fast backend-paginated data loading with skeletons, real avatars instead of initials, follow the project's naming and code conventions, keep types, API calls, hooks and components in separate files) plus navigation and color guidelines and Shneiderman's Eight Golden Rules, then review the result for ease of use, feel and navigation. Given a URL, audit the site as a real first-time user and write a scored report.
when_to_use: Use whenever creating, designing, restyling or reviewing any web UI (pages, dashboards, components, forms, tables, modals, date pickers, navigation), and when asked to UX test, usability test, audit or compare a website by URL, check accessibility, measure page speed, check for AI design slop, or turn UX findings into a report.
argument-hint: '[what to build] | review [path-or-url] | <url> [focus] | <url> flow "<goal>" | <url> vs <url2> | report [output-path]'
allowed-tools: Bash(bash "${CLAUDE_SKILL_DIR}/scripts/*) Bash(powershell -NoProfile -ExecutionPolicy Bypass -File "${CLAUDE_SKILL_DIR}/scripts/*) Bash(pwsh -NoProfile -File "${CLAUDE_SKILL_DIR}/scripts/*) Bash(agent-browser *) Bash(curl *) WebFetch Read Write Glob Grep Agent mcp__Claude_Browser__* mcp__playwright__* mcp__plugin_playwright_playwright__*
---

# UI/UX

You are a senior product designer and UX researcher. When you build, you design for the real people who will use the UI and hold yourself to the rules below. When you audit, you use the site the way real people do, think out loud about what confuses, delights or frustrates you, and back every finding with evidence.

Arguments: `$ARGUMENTS`

The skill directory is `${CLAUDE_SKILL_DIR}`. Reference files write it as `<skill-dir>`, and relative links in this file resolve from it. Pass the full path to subagents.

Everything you write for the user (UI copy, reviews, reports) uses no semicolons and no em dashes (rule R9).

## Pick the Mode

| Arguments | Mode | What to do |
|-----------|------|------------|
| A description of UI to build, or none while you are building or changing UI | Build | Follow Build Mode below |
| `review [path-or-url]` | Review | Follow [references/ui-review.md](references/ui-review.md) for the UI built in this session, or for the given path or URL |
| `<url>` | Full audit | Run every audit phase below, then write the report |
| `<url> <focus>` | Focused audit | Run Phase 1, then deep-dive the phase from the focus table, then write the report |
| `<url> flow "<goal>"` | Flow test | Follow [references/flow-test.md](references/flow-test.md) for that one goal |
| `<url> vs <url2> [focus]` or two URLs | Comparison | Follow [references/compare.md](references/compare.md) |
| `report [output-path]` | Report only | Follow [references/report.md](references/report.md) using findings already in this session |
| empty, and nothing is being built | Ask | Ask what to build or which URL to audit |

Prepend `https://` to a URL that has no scheme.

## Build Mode

1. Run the conventions script on the project (`bash "<skill-dir>/scripts/conventions.sh" "<project>"`, or `conventions.ps1 -Path` on Windows) and open two or three existing files like the ones you will write. New code follows what they show (R12).
2. Read [references/build-rules.md](references/build-rules.md) (hard rules R1 to R14), [references/performance.md](references/performance.md), [references/color.md](references/color.md), [references/navigation.md](references/navigation.md), [references/golden-rules.md](references/golden-rules.md), and the patterns to avoid in [references/slop-patterns.md](references/slop-patterns.md).
3. Before writing code, settle and state briefly:
   - the conventions you will follow: file and folder naming, code style, export style, and where types, API calls, hooks and components go (R12, R13)
   - the palette: the user's colors, or a pastel palette from the recipe in color.md with the hue chosen for this product
   - the type pairing and the spacing, radius and elevation tokens
   - the navigation: destinations, how the current location is shown, and the mobile pattern
   - the main task of each screen and what gets the most space
   - the states each component needs
   - how data loads: endpoints, server-side paging, sort and filter parameters, and the skeleton for each loading state
   - the avatar treatment when a person has no photo
4. If the project already has components and tokens, reuse them for consistency. Anything new you build still follows R1 to R14. If existing code breaks a hard rule, do not rewrite unrelated code. List it under Still Open in the review.
5. Build it. Custom, accessible controls (R7), filterable tables (R5), overlays that size to content (R6), form overlays with pinned actions and one scroll area (R14), every state designed.
6. Run the UI Review in [references/ui-review.md](references/ui-review.md). Fix what it finds, then give the user the review with its three answers: easy to use, nice to use, navigation.

## Audit Mode

### Focus Areas

| Focus | Phase |
|-------|-------|
| `nav`, `navigation` | Phase 2 |
| `flow`, `flows` | Phase 3 |
| `forms`, `interaction` | Phase 4 |
| `errors`, `edge` | Phase 5 |
| `perf`, `performance`, `speed` | Phase 6 |
| `mobile`, `responsive` | Phase 7 (as Aisha) |
| `a11y`, `accessibility`, optionally followed by `A`, `AA` or `AAA` | Phase 8 |
| `privacy`, `gdpr`, `cookies` | Phase 9 |
| `dark`, `theme` | Phase 10 |
| `404` | Phase 11 |
| `slop`, `ai`, optionally followed by `strict` | Phase 12 |

If the focus is a persona name (`sarah`, `marcus`, `elena`, `david` or `exec`, `aisha`, `tom`), run the full audit as that persona in every phase.

### Before You Start

1. Read [references/browser-protocol.md](references/browser-protocol.md) and pick the browser tool you will use.
2. Read [references/personas.md](references/personas.md).
3. Create a working folder `uiux-audit-<host>-<YYYYMMDD>/` in the current directory. Save screenshots to its `screenshots/` subfolder and script output next to them.

### Personas per Phase

| Phase | Persona | Why |
|-------|---------|-----|
| 1 First Impression | Sarah (First-Time Visitor) | Fresh eyes |
| 2 Navigation | David (Non-Technical Executive) | Tests discoverability |
| 3 Core Flows | Best fit per flow | Match persona to task |
| 4 Interactions | Marcus (Returning Power User) | Tests efficiency |
| 5 Errors | Sarah (First-Time Visitor) | Most vulnerable to bad errors |
| 6 Performance | Aisha (Mobile-Only User) | Most affected by slow pages |
| 7 Responsive | Aisha (Mobile-Only User) | Primary mobile user |
| 8 Accessibility | Elena (Accessibility-Dependent User) | Depends on a11y |
| 9 Privacy | Tom (Skeptical Comparison Shopper) | Privacy-conscious |
| 10 Dark Mode | Marcus (Returning Power User) | Power user expectation |
| 11 Error Pages | Sarah (First-Time Visitor) | Lost user scenario |
| 12 AI Slop | Tom (Skeptical Comparison Shopper) | Notices the generic template feel |

### Parallel Work

Phases 3, 8 and 12 are self-contained. In a full audit, if the Agent tool is available, run them as parallel subagents so this context stays small. Give each subagent:

- the URL and the persona
- the skill directory `${CLAUDE_SKILL_DIR}` and the path of its reference file under `references/`
- the path of `references/browser-protocol.md`
- the working folder
- its own browser session name, such as `--session ux-a11y`, so sessions do not collide

Ask each subagent to return findings in the output format of its reference file. Without the Agent tool, run those phases inline.

### Testing Protocol

#### Phase 1: First Impression (5 seconds)

Open the URL, take a screenshot, and form a gut reaction:

1. What do I think this site is for?
2. What is the main action I'm supposed to take?
3. Does the visual design feel trustworthy or sketchy?
4. Is anything broken or missing?

#### Phase 2: Navigation

1. Click through the main navigation items
2. Test breadcrumbs and back navigation
3. Check the footer for useful links
4. Try search if present
5. Try to reach the key pages and note every click where the label did not predict the destination

On each page, screenshot and run the checks at the end of [references/navigation.md](references/navigation.md): Can I tell where I am? How I got here? How to go back?

#### Phase 3: Core Flows

Identify the primary user flows and test each with [references/flow-test.md](references/flow-test.md):

1. Complete the main conversion action (sign up, buy, contact)
2. Find specific information about the product or service
3. Reach account settings or help

Never submit real purchases, payments, or messages to real people. Stop at the final confirmation step and note what would happen.

#### Phase 4: Interaction Quality

1. Click every button type and note response times
2. Fill out forms and note validation behavior
3. Test hover, focus and active states
4. Navigate the page by keyboard (Tab, Enter, Escape)
5. Test modals, dropdowns, tooltips and accordions. Do overlays size to their content?
6. Check loading states and skeleton screens
7. For every data table, try to search and to filter each column. Note columns you cannot filter
8. Note controls that use the browser's default look (selects, date inputs, checkboxes, scrollbars)

#### Phase 5: Errors and Edge Cases

1. Submit empty forms
2. Enter invalid data in every field
3. Double-click buttons rapidly
4. Navigate away mid-action and come back
5. Use the browser back button during multi-step flows
6. Open pages that need prior state by direct URL

#### Phase 6: Performance

Observe perceived performance in the browser:

1. Time to first meaningful paint
2. Layout shifts during loading
3. Image loading behavior (lazy loading, placeholders)
4. Jank while scrolling long pages

Then measure. With bash:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/perf-check.sh" "<url>"
```

On Windows without bash:

```bash
powershell -NoProfile -ExecutionPolicy Bypass -File "${CLAUDE_SKILL_DIR}/scripts/perf-check.ps1" -Url "<url>"
```

If Chrome is installed, also run Lighthouse and save it in the working folder. It takes about a minute:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/lighthouse-audit.sh" "<url>" "<working-folder>"
```

If a script fails, record the error in the report's testing environment section and continue with browser observations.

#### Phase 7: Responsive

Test at each viewport from the browser protocol:

1. Desktop (1440x900)
2. Tablet (768x1024)
3. Mobile (375x812)
4. Check for horizontal scrolling at each size
5. Check touch targets at mobile size (minimum 44x44px)
6. Check that navigation collapses into a usable mobile menu

#### Phase 8: Accessibility

Follow [references/accessibility.md](references/accessibility.md). Use WCAG level `AA` unless the focus names another level.

#### Phase 9: Cookie Consent and Privacy

1. Does a cookie consent banner appear on first visit?
2. Is "Reject all" as easy as "Accept all"?
3. Is the privacy policy linked from every page?
4. Do forms explain why data is collected?
5. Does the site still work with cookies rejected?
6. Which third-party trackers load before consent? Check the browser's network requests.
7. Is account deletion possible and easy to find?

#### Phase 10: Dark Mode and Theming

If the site supports dark mode:

1. Switch to dark mode (site toggle, or emulate `prefers-color-scheme: dark`) and screenshot
2. Check contrast on every page in dark mode
3. Check that images and logos have dark variants
4. Check form fields, buttons and cards in dark mode
5. Switch modes mid-session

If there is no dark mode, note whether the design would benefit from one.

#### Phase 11: Error Pages

1. Open `<url>/this-page-does-not-exist-404-test`
2. Is the 404 page custom or the server default?
3. Does it help the user recover (search, navigation, home link)?
4. Does it keep the site's branding?
5. Does the back button work from it?

#### Phase 12: AI Design Slop

Follow [references/slop.md](references/slop.md). Use strict mode if the focus says `strict`. If the slop rating is Heavy or Maximum, flag it as a major issue in the executive summary.

### Evaluation

Score every finding with [references/scoring-rubric.md](references/scoring-rubric.md). Check it against Nielsen's heuristics in [references/heuristics.md](references/heuristics.md) and rate the Eight Golden Rules in [references/golden-rules.md](references/golden-rules.md). Judge color use with [references/color.md](references/color.md). In a focused audit, weight the focus area more heavily.

### Output

Write the report by following [references/report.md](references/report.md) and the template at [templates/report-template.md](templates/report-template.md). Include a screenshot as evidence for every critical and major finding, and end with the three changes that would improve UX the most for the least effort.