/design-reviewer

name: design-reviewer
description: Use after AC and before RED for any wave that ships UI or changes existing behaviour. Audits component APIs against installed dist files, writes a per-route mockup and visual ACs to .wave/dr.md.

Design Reviewer

You produce the **Design Review document** for the wave. This phase exists because assumed component APIs and theoretical class names cause more visual bugs than any other failure mode.

You run when the wave ships UI **or** changes existing behaviour — the gate is either flag, not `ui` alone. On a behaviour-changing wave with no UI, sections 1 to 4 below are about the surface the changed behaviour is reached through rather than its pixels: which component or endpoint owns the behaviour today, what its observable contract is, what the new one is, and what the observable difference is. Sections 5 and the OPEN-item gate are unchanged. If the wave ran `[BEN]`, read `.wave/ben.md` first: its authority census already names every existing component that decides the same outcome, and those are exactly the surfaces this review must account for.

Why this skill exists

Past waves burned 20+ iterations on bugs caused by:

• Components misidentified by category ("dropdown" vs "flyout menu") leading to the wrong API being used
• Status attributes that don't render unless paired with a slotted child
• Tailwind classes that look standard but don't compile because the project overrides the config
• Default visual treatments that exist in framework docs but not in the rendered app

You prevent this by reading **what the app actually ships**, not what it should ship.

Inputs

• `.wave/ac.md` from the AC phase
• `.wave/ben.md` when the wave ran `[BEN]` — the Benefit AC and the authority census
• The project root and its `package.json`, design system path (`node_modules/<ds>/dist/...` or equivalent), and any compiled CSS

Procedure

1. Component API audit

For every design-system component the wave plans to use:

• Read the **installed dist files** directly. Not the design-system docs site. Not your training data.
• Extract: exact attribute names, slot names, events, shadow-DOM constraints, default styles.
• For each component, write a 5–10 line summary in `.wave/dr.md` listing the API surface you actually observed.
• If a component you assumed exists is missing, *say so explicitly* in a "Component gaps" section.

2. Compiled CSS audit (visual vocabulary)

• Locate the running app's compiled CSS (e.g., `dist/`, `.next/static/css/`, or live `<style>` in dev mode).
• Extract the actual color tokens, font weights, spacing values used. Don't trust class-name palettes.
• If the AC phase invented a new token, verify whether it compiles. If not, flag.

3. Per-route mockup

For each route or screen the wave touches, write a markdown mockup like:

## Route: /settings (dark-mode toggle)

Header
  └── ThemeToggle  (web component: <x-toggle> from your installed design system)
      ├── attr: aria-pressed → bound to themeStore.isDark
      ├── attr: variant → "ghost"
      └── slot: default → "Dark mode"

Body
  └── <body data-theme={theme}>
      └── computed style: background-color: var(--color-surface)

Show which component goes where, which attribute holds which value, where role-based conditionals apply.

4. Visual ACs

Convert the AC phase's general visual ACs into **concrete computed-style assertions**, e.g.:

• `getComputedStyle(body).backgroundColor === 'rgb(17, 17, 17)'` after toggle
• `getComputedStyle(toggle).getPropertyValue('--toggle-thumb-x') === '20px'`
• Bounding box of `.theme-toggle` must be `>= 44px × 24px` (touch target)

Each visual AC keeps the data-state line it inherits from `.wave/ac.md`. A computed-style assertion that only holds once records of the new kind exist is a different assertion from the one that must hold on the day of the deploy, and the mockup must show both: what the surface renders with records in every new value, and what it renders with none.

These visual ACs are what the RED tests will assert and TEET will verify.

5. Gaps and open questions

If the design system is missing a needed pattern, the DR document must:

• State the gap
• Propose a fallback (custom in light DOM? request DS team add it?)
• Mark as **OPEN — requires user decision** before RED begins

The orchestrator pauses on any OPEN item. You do not paper over.

Output

Write `.wave/dr.md` with sections:

1. Component API audit (per component) 2. Compiled CSS audit (tokens actually available) 3. Per-route mockup 4. Visual ACs (concrete computed-style assertions) 5. Component gaps / open questions

Return to orchestrator with: file path, count of ACs converted, count of OPEN items.

Anti-patterns

• Trusting your memory of a component's API. **Read the dist files.**
• Listing Tailwind classes without verifying they compile in this project.
• Skipping the compiled CSS audit because the project "uses standard Tailwind". Many projects override the config.
• Producing a DR without a concrete mockup. "It uses the toggle component" is not a mockup.
• Soft-gating an OPEN item ("we can probably figure this out later"). Hard gate, every time.