design-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# Design Review

The **empirical** front-end reviewer for the user's Workspace. It opens the real page in a real browser, exercises it across viewports and input modalities, checks it against WCAG 2.2 and design-quality standards, and returns a triaged, evidence-backed report.

Synthesized from three sources: the live-environment 7-phase methodology (OneRedOak `claude-code-workflows`), the quality-pillar lens + review modes (Microsoft `frontend-design-review`), and the WCAG 2.2 / POUR rigor (Addy Osmani `web-quality-skills/accessibility`).

## Where this fits (don't duplicate other skills)

| Need | Use | Why |
|---|---|---|
| **Review a running UI empirically** (this skill) | `design-review` | Drives the browser, observes real behavior |
| Generate / build new UI | `frontend-design`, `ui-ux-pro-max` | Generative design intelligence |
| Critique design from principles (no running page) | `impeccable` | Static expert critique + live iteration |
| Just launch/screenshot the app | `run`, `verify` | Plumbing to get a preview URL up |

**Handoff rule:** this skill *finds and describes* problems. It does **not** rewrite the UI. When fixes are wanted, route them to `impeccable` / `ui-ux-pro-max` / `frontend-design`. Report first; edit only if explicitly asked.

## Core principles

1. **Live Environment First.** Assess the interactive experience before reading code. Reality over theory.
2. **Problems Over Prescriptions.** Describe the problem and its *impact on the user*, not the CSS fix. Say "the spacing reads as inconsistent and creates visual clutter," not "change margin to 16px."
3. **Evidence-based.** Every visual finding gets a screenshot. Every a11y finding cites the WCAG criterion.
4. **Assume good intent. Start with what works.** Then triage by severity.

## Prerequisites & setup (Windows / PowerShell / OneDrive)

- **Playwright MCP** must be connected (tools appear as `mcp__plugin_playwright_playwright__browser_*`). If the browser isn't installed, the first `browser_navigate` will say so — install per Playwright MCP docs, then retry.
- **A live preview URL.** Ask for it, or start the project's dev server first (use the `run` skill). For `su-kb-site` (GitHub Pages / static), serve the built site locally (e.g. a local static server) and use that URL — don't review the raw markdown.
- **OneDrive note:** serve from the project dir is fine; don't point Playwright at file-handle-contended paths mid-sync if avoidable.

## Review modes — pick scope before starting

Ask which mode, or infer from the request. Default = **Standard**.

| Mode | Trigger | What it runs |
|---|---|---|
| **Quick** | "quick look", small change | Phases 1–3 at desktop + mobile only; console check |
| **Standard** (default) | "review this page/PR" | All 7 phases, 3 viewports |
| **Accessibility-deep** | "a11y audit", "WCAG", "screen reader" | Phase 4 expanded to full WCAG 2.2 POUR sweep + automated axe/Lighthouse pass |
| **Design-system** | "matches our design system / tokens" — *only if a design system exists* | Adds token/component-compliance check; **skip if no Figma/Storybook/token system** |

## The 7-phase live methodology

### Phase 0 — Preparation
- Read the PR/change description (or the user's description) to understand intent and testing notes.
- Skim the diff to scope what changed (which routes/components).
- `browser_navigate` to the preview URL. Set desktop viewport: `browser_resize` 1440×900.

### Phase 1 — Interaction & user flow
- Walk the primary user flow (`browser_click`, `browser_type`, `browser_fill_form`, `browser_select_option`).
- Test interactive states: hover, active, disabled, focus.
- Verify destructive actions have confirmation.
- **Quality-pillar lens — Frictionless:** is the core task completable in ≤3 interactions? Is there exactly **one** obvious primary action per view? Red flags: competing primary buttons, buried actions, dead ends.

### Phase 2 — Responsiveness
- Desktop 1440px → `browser_take_screenshot`.
- Tablet 768px (`browser_resize`) → verify layout adapts.
- Mobile 375px → verify touch targets and no horizontal scroll / overlap → screenshot.
- Confirm no element overlap, clipping, or reflow breakage at any width.

### Phase 3 — Visual polish (Quality Craft pillar)
- Alignment & spacing consistency; typographic hierarchy & legibility; color cohesion; image quality.
- Does visual hierarchy guide attention to the primary action?
- Red flags: generic/"AI-slop" aesthetic, magic-number spacing, hierarchy that competes with itself.

### Phase 4 — Accessibility (WCAG 2.2 — POUR)
Use `browser_snapshot` (DOM/a11y tree) + keyboard simulation (`browser_press_key` Tab/Enter/Space) + `browser_evaluate` for computed styles/contrast.

- **Perceivable:** images have meaningful `alt` (or `alt=""` if decorative); icon-only buttons have accessible names; **color contrast** meets thresholds (table below); information isn't conveyed by color alone.
- **Operable:** full keyboard operability; visible `:focus-visible` indicators (≥3:1 against background); **no keyboard traps**; focus order matches visual order; focused element **not obscured** by sticky headers/footers (2.4.11); **target size ≥ 24×24px** (2.5.8); `prefers-reduced-motion` respected; dragging has a single-pointer alternative.
- **Understandable:** `<html lang>` set; consistent navigation; form inputs have programmatically-associated labels; errors announced (`role="alert"`/`aria-live`, `aria-invalid`).
- **Robust:** native elements preferred over ARIA-on-div; correct ARIA roles/states where used; live regions for dynamic updates.

**Contrast thresholds (WCAG 2.2):**

| Element | AA | AAA |
|---|---|---|
| Normal text (<18px / <14px bold) | 4.5:1 | 7:1 |
| Large text (≥18px / ≥14px bold) | 3:1 | 4.5:1 |
| UI components & graphics, focus indicators | 3:1 | 3:1 |

**Accessibility-deep mode** also runs an automated pass (report results, don't auto-fix):
```powershell
npx lighthouse <url> --only-categories=accessibility --quiet
# or
npx @axe-core/cli <url>
```

### Phase 5 — Robustness
- Form validation with invalid input; content-overflow / long-string stress; loading, empty, and error states; edge cases.

### Phase 6 — Code health
- Component reuse over duplication; design tokens vs magic numbers; adherence to established patterns. *(Design-system mode: verify tokens/components match the system; flag deviations.)*

### Phase 7 — Content & console
- Grammar/clarity of visible copy.
- `browser_console_messages` → flag errors/warnings. `browser_network_requests` → flag failed/slow requests if relevant.
- **Trustworthy pillar:** AI-generated content carries a disclaimer where appropriate; error messages are actionable, not opaque.

## Playwright MCP tools (the user's namespace — use these exact names)

`mcp__plugin_playwright_playwright__browser_navigate` · `browser_resize` · `browser_snapshot` · `browser_take_screenshot` · `browser_click` · `browser_type` · `browser_fill_form` · `browser_select_option` · `browser_hover` · `browser_drag` · `browser_press_key` · `browser_wait_for` · `browser_evaluate` · `browser_console_messages` · `browser_network_requests` · `browser_tabs` · `browser_navigate_back` · `browser_close`

(There is no `browser_install` / `browser_navigate_forward` / `browser_tab_*` in this harness — don't call them.)

## Triage matrix

Categorize every issue:
- **[Blocker]** — critical failure; must fix before merge (broken flow, WCAG-A violation, security/data exposure in UI).
- **[High-Priority]** — significant; fix before merge (WCAG-AA gap, broken mobile layout, failed primary action).
- **[Medium-Priority]** — follow-up improvement.
- **[Nit]** — minor aesthetic detail; prefix "Nit:".

## Output format

```markdown
## Design Review: [Page/Feature/PR]

**Verdict:** Pass / Needs work / Blocked — [one line]

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness