Account for every design difference.
design-qa hands design QA to a coding agent. The question I built it around: what evidence should a pass require?
I designed and built it with Claude Code, shipping four tagged releases in under two weeks.
Key results
- State by state — each designed state compared with the build, or listed as unverified with the reason (Qualitative)
- A report and a fix plan — one for the reviewer, one the coding agent acts on, from the same run (Qualitative)
- You pick the fixes — the rest becomes design debt, ticketed only when you ask (Qualitative)
design-qa
Open source
GitHub
Screenshot of the sample report that ships with design-qa. Acme Checkout v3 and every finding in it are fictional.
Rendered live from the walkthrough’s code. Acme Checkout v3 and every finding in it are fictional.
Live from the walkthrough’s code; the score card is an illustration. Acme Checkout v3 and every finding in it are fictional.
The whole walkthrough
Two commands, one check
From a ticket key
Every screen, every state
Six ways to compare
Pinned and traced to tokens
A verdict per designed state
Blockers can’t become debt
Review and send
Fixed, ticketed or dismissed
Undesigned states, back to Figma
It gates the merge
Dismiss, with a reason
Designed 160 ms ease-out, never shipped
Hand checking to the agent
The bet
When engineering moved a ticket to QA, a designer stopped their own work to check the build against Figma, often several times per ticket. They kept finding differences in components Figma already defined. I built design-qa to give that time back.
A screenshot is only one state
Empty, loading, error, hover and focus are rarely compared with the build.
A difference isn’t always a defect
Real data and approved changes also differ from the design.
Manual QA → the bet
A designer stops their own work to find every difference.
A coding agent prepares the comparisons and fixes; people decide what to accept.
For every designed state, the agent shows evidence or explains what stopped it.
Point it at your work
How it works
Give it a Figma link, a prototype, a Jira ticket or the build’s URL.
Figma
Framer
v0
Lovable
Jira
Names and logos belong to their owners and imply no endorsement. Jira is a trademark of Atlassian.
Works in your agent
Install
design-qa is open source on GitHub under the MIT licence; the latest release is 0.2.2.2.
Claude Code
OpenAI Codex
Cursor
And any agent that supports skills
GitHub Copilot
Gemini CLI
Windsurf
View the repository
Release notes
OpenAI Codex
Link it into .agents/skills; run $design-qa.
Cursor
Copy it into .cursor/skills; pick it with /.
What the report checks
The report
One run writes a report a person reads and a fix plan the agent acts on.
Motion counts too
A transition the design specifies and the build skips is a finding.
Decisions go back to the agent
Close the loop
You choose what gets fixed now, what waits and what is dismissed; the agent fixes your picks and logs what waits as design debt.
Dismissals that stick
Each needs a reason, and later runs re-apply it.
What should count as a pass?
The design work
The agent proposes; a person decides.
Make the design the only reference
A pixel diff shows where something changed, not whether it is a defect.
Every difference ends one of four ways: fixed in code, signed off as intentional, dismissed with a reason, or accepted as different data. I removed a fifth, changing Figma to match, so the check can never move its own target.
Make missing evidence part of the verdict
I had a review try to break my own verdict. An empty report scored 100%.
I rebuilt the verdict around evidence. The planned fix is an inventory of expected checks, and the current release ships its core: every difference needs a decision, and a run that compared under half the designed states cannot pass.
The reviewer decides
Automating every fix would automate the agent’s mistakes too.
The agent changes nothing until the reviewer says go. Blockers can’t be put off, and accepting a difference as intentional needs the reviewer’s name and reason. A pass means every difference is accounted for, not that the build is identical.
What is proven so far
Where it stands
That review also found gaps in evidence completeness, capture security and ticket handling. The 0.2.2 changelog records a fix for each; those fixes are not independently verified here.
No measured results yet
No real-project audit is presented here; the clips use a fictional sample. I haven’t measured how many defects it catches, how often it’s wrong or the time it saves.
Fixed widths, partial motion
It checks each state only at the design frame’s width, and doesn’t capture scroll-linked motion yet.
What the review changed
What worked
Findings a reviewer can check
Each finding arrives with its captures and a proposed fix, so the reviewer judges the agent’s reasoning instead of redoing the comparison.
What I’d change
Define the evidence before the verdict
I decided what a pass meant before deciding what evidence it needed. The scripts now confirm every difference got a decision, not that the decision was right.
FAQ
When can I use it?
Now. It is open source under the MIT licence; the repository has install steps for Claude Code, OpenAI Codex and Cursor.
What does it need to run?
A Figma link or coded prototype, and a running build it can open. A Jira ticket can supply both links. If it can’t reach a state, it says so and why.
Why a skill and not a standalone tool?
The coding agent already knows the project’s code, so each finding points at the code that fixes it. The catch: the agent can be wrong, so scripts check its evidence and a person decides.