design-qa

Judged from the render, not the code

The design-qa skill is a checklist the coding agent follows over rendered pixels. Code review can confirm the tokens are right; this pass decides whether the result looks right. It also runs as the quality gate inside new-component. Below are the steps, then one pass over Button traced from its stories to the report. The full skill file is on Skills.

The steps

Pick the target
A component, a page, or a sweep across several. With no target named, it takes what the session just built or changed.
Makes the capturesRender it in both themes
A component renders every story in Storybook. A page renders on the dev site at desktop and mobile widths. Each is captured in light and dark, with the theme checked on the root element first.
Look closely
Zoom into every corner, join, divider, icon seat and focus ring. Drive hover, keyboard focus, active, disabled and loading for real, then try the longest label and a narrow container.
Line up the siblings
Capture the same crops of the two or three nearest relatives by role. Then read the spec in design.md and the source, to name the cause of what the pixels showed.
Judge each finding
Name the principle or craft check it breaks, then class it: a defect, polish, or a direction call.
Makes the fixesFix and look again
Fix defects and polish at the source, re-capture the same crops, and look over the changed area. Repeat until a full pass finds nothing new.
Makes the reportReport
The verdict first, then what was fixed, the open decisions with one recommendation each, and what was checked and found clean.

Button, one pass

Button’s stories live in src/components/Button/Button.stories.ts and its showcase page is /components/button. The pass renders both in light and dark, then compares the same crops with the nearest buttons in the registry’s actions category, picked at the time of the run. Only defects and polish enter the loop; a direction call goes to the report for the owner.

1 · Renderthe real thing, never a memory

2 · Look closelyevery variant and state

3 · Judgeagainst what is rendered now

4 · Outcomeevery finding gets one class

Button storiessrc/components/Button/Button.stories.ts

Storybookstorybook in .claude/launch.json

Both themesdata-theme light, then dark

Showcase page/components/button

Driven stateshover · focus by keyboard · disabled · loading

Stressed contentlongest label · narrow container

Magnified cropscorners · icon seat · focus ring

Re-capturethe same crops, before and after

Specdesign.md · Button · Composition

Rubricdesign principles · craft checks

Rendered siblingsSplitButton · ButtonGroup · CircularButton

SourceButton.css · Button.tsx, read last

Directionrecommend one option, apply none

Reportverdict · fixed · open · clean

Defect or polishone right answer, or small and safe

Fix at the sourceButton.css · Button.tsx

same crops of eachbefore and afteruntil nothing new

Rendered now, compared with siblings rendered in the same run, looped until a pass finds nothing new.

Three outcomes

Every finding names what it breaks and takes one class. A pass with no findings is a valid result.

What happens to each kind of finding
Outcome	Means	Result
Defect	Wrong against the rubric, the spec or the siblings. One right answer.	Fixed
Polish	A clearly better version exists, and the change is small and safe.	Fixed
Direction	More than one defensible answer, or it changes the design. One option is recommended, none applied.	Owner decides
Clean	A full pass finds nothing. The report says what was covered.	Reported