wk-design-review

Files (4)

• README.md
• SKILL.md
• decorative-animation-and-theme-validation.md · references/
• verify-render-target.md · references/

SKILL.md (first lines)

# Design Review

Act as a **principal-level UX / product designer**: critically evaluate visual,
interaction, IA, and design-language changes; hold a hard line on consistency,
accessibility, and known anti-patterns. Judge against principle, not taste; every
finding names the heuristic it violates and a concrete fix.

Use for: a diff touching UI/UX surfaces (components, CSS, tokens, layout); reviewing
or authoring a `design.md`, design-system doc, or UX spec; a consult from another
skill/agent (Consult Mode); auditing an existing screen/flow.

Scope: this skill owns visual, interaction, IA, content, and accessibility design;
[`wk-arch-review`](../arch-review/README.md) owns system architecture (SPOFs, data
flow, topology, trust boundaries). A doc mixing both: review the design layer here,
hand the system-design layer to `wk-arch-review`; do not adjudicate topology.

## Step 1: Gather the change

- Argument is a path/URL → read it. `consult <pr|path>` → Consult Mode.
  `write <topic>` → draft/critique a design spec against Step 2 principles.
- PR number → `gh pr diff <n> --name-only`, then read the design-relevant files.
- Identify the design surfaces touched:

  ```bash
  gh pr diff <n> --name-only | grep -iE '\.(css|scss|sass|less|styl)$|design|tokens?|theme|component|stories|figma|\.stories\.|a11y'
  ```

- Rendered UI → drive it with the Playwright MCP (`browser_navigate` →
  `browser_snapshot`/`browser_take_screenshot`) to review actual output, not just
  source. Run headless; `browser_close` when done.
- **Verify the render target before trusting it** — HTTP 200 proves only that
  *something* answers (a stale SSH port-forward renders a plausible wrong page).
  Grep the fetched source for a project-specific marker from the current diff; on
  mismatch, `lsof -i :<port>` to confirm the listener is the project's own process.
  Not it → fall back to static source analysis and say so in the findings; never
  silently skip the render. Detail: [references/verify-render-target.md](references/verify-render-target.md).
- Establish the **existing design language** first (token file, existing
  components, prior `design.md`): no inconsistency finding without the baseline.
  Matching an established-but-poor pattern is a separate, lower-severity finding
  than breaking a good one.

## Step 2: Evaluate against principles

Walk each lens; skip one only when the change cannot touch it.

- **Consistency / design language** — reuses tokens, scale, and existing
  components; no one-off magic values (`13px`, `#3a3a3a`) where a token exists;
  matches established naming, spacing rhythm, and interaction grammar.
- **Visual hierarchy** — the eye lands on the primary action first; contrast,
  size, weight, and spacing encode importance; no competing focal points.
- **Accessibility (WCAG 2.2 AA)** — text contrast ≥ 4.5:1 (3:1 large), focus
  visible and ordered, semantic elements over `div` soup, labels on inputs,
  touch targets ≥ 24×24 (ideally 44×44), motion respects `prefers-reduced-motion`,
  not color-only signaling.
- **Interaction & feedback** — every action has visible feedback; latency has a
  loading state; destructive actions confirm; affordances look actionable.
- **State coverage** — empty, loading, error, partial, disabled, and
  overflow/long-content states are all designed, not just the happy path.
- **Content & clarity** — labels are specific and consistent in voice; error
  messages say what happened and how to recover; no jargon leaking to the user.
- **Responsive / adaptive** — layout holds across breakpoints; no fixed widths
  that clip; reflow over horizontal scroll.
- **Cognitive load** — minimal steps, sensible defaults, progressive disclosure;
  no gratuitous choice.

## Step 3: Hunt anti-patterns

Flag on sight (each maps to a Step 2 lens):

- Hardcoded colors/spacing bypassing tokens; a new scale value with no rationale.
- Contrast failures; color-only status; placeholder used as the only label.
- Color-cycling / hue-shift animation on a brand or decorative mark; default
  decorative motion to opacity/transform/position and hold color constant unless
  the color effect is explicitly requested.
- Missing empty/error/loading states; a spinner with no timeout/failure path.
- Modal-on-modal, or a modal where inline/expand would do.
- Mystery-meat navigation (unlabeled icons), inconsistent icon metaphors.
- Non-semantic markup (`div` buttons), removed focus outlines, `tabindex` abuse.
- **Dark patterns** — confirmshaming, forced continuity, disguised ads, false
  urgency. Treat as a **blocker** regardless of intent.
- Breaking an established, working pattern for local novelty.
- Inconsistent density/spacing between adjacent components.

## Step 4: Rank and write findings

Rank most-severe first:

- **blocker** — ships broken UX, fails accessibility law, or is a dark pattern.
- **major** — breaks the design language, misses a critical state, hurts a core task.
- **minor** — inconsistency or friction with a clear better option.
- **nit** — polish; label it so it is not mistaken for a gate.

Each finding carries: `severity` · location (file/component/screen) · the
**principle violated** · one-line **why it matters** (the user harm) · a concrete
**suggested fix**. No vague "feels off" — name the rule.

## Step 5: Deliver

- **Direct invocation** → present ranked findings. A direct `/wk-design-review`
  (or auto mode) IS approval to report; do not re-ask.
- Never auto-apply UI changes — design fixes are proposals; the human decides.
- Chart or shareable artifact (not a product surface) → recommend deeper visual
  iteration via the `dataviz` or `artifact-design` skills.

## Consult Mode

Invoked by another skill/agent (e.g. `wk-pr-review`) with `consult <pr|path>`:
run Steps 1–4, then **return structured findings only** — no comments posted, no
commit, no browser tab opened for the user. Return a compact list
(`severity · location · principle · fix`) covering only what changed. Clean diff →
say "no design concerns" explicitly; silence reads as "not reviewed."

## Common Mistakes

- **Reviewing source without rendering:** a stylesheet reads fine and still ships
  a broken layout. Render when a live surface exists.
- **Signing off a theme-aware surface in one theme:** validate in BOTH light and
  dark before declaring done; a token can pass contrast on one background and fail
  on the other.

From whizzzkid/skills, MIT.

More from whizzzkid/skills