| name | product-design-design-qa |
| description | Internal prototype QA helper. Use only after a Product Design prototype, URL-to-code build, or image-to-code build has a source visual target and a rendered implementation to compare before handoff. Do not use for broad UX critique, design critique, product audits, or flow reviews; route those user-facing requests to audit. |
Design QA
Use this internal helper to compare a prototype's source design against the rendered implementation before handoff.
Do not use this skill for broad UX critique, design critique, product audits, or flow reviews. Use audit for those user-facing requests.
Use this skill before every Product Design build handoff.
A passing QA run requires both:
- a source visual target: Figma node, image, screenshot, mockup, or source capture
- a rendered implementation: local URL, deployed URL, app screen, component, or screenshot
If either artifact cannot be opened, captured, or compared, write design-qa.md with final result: blocked and name the blocker. Do not let the build skill hand off as done.
Critical Overrides
Follow critical-overrides.
Workflow
Compare the intended design to the implementation as a product-quality reviewer, not as a generic aesthetic critic. The output must be a prioritized fix list grounded in evidence from both artifacts.
Do not write the QA review from memory, code, or file paths alone. Open or capture both the source design and the implementation first, then compare what is actually visible.
Do not pretend separate image views are side-by-side comparison. Put the source image and the implementation screenshot together in the same comparison input, then judge the visible differences from that combined input.
Design QA is an iteration loop. The first comparison may pass only when it finds no actionable P0/P1/P2 differences and no visual fixes are made in response.
When a comparison finds any P0/P1/P2 issue:
- Record the finding and keep the current result blocked.
- Apply the fix.
- Capture the revised implementation at the same viewport and state.
- Compare the revised capture against the source again.
A later pass must identify the earlier findings, the fixes made, and the post-fix visual evidence. Build, dependency, lint, deployment, and preview troubleshooting do not count as design-QA iterations.
-
Identify the comparison target.
- Determine the source design: Figma node, image, design board, screenshot, spec, or mockup.
- Determine the implementation: local URL, deployed URL, app screen, component, screenshot, or code-rendered view.
- Match the same viewport, state, theme, device density, route, content, auth state, and interaction state before judging.
- If artifacts do not represent the same state, call that out first and avoid false precision.
-
Capture evidence.
- For Figma, use design context and screenshot tools when available.
- For Product Design
mobile-app template implementations, capture the app viewport itself, not the whole browser page, desktop canvas, or surrounding phone stage. Use data-testid="device-screen" / [data-phone-screen] for content-only comparisons; use data-testid="phone-frame" only when the source visual includes the device bezel.
- Before capturing a
mobile-app template, run npm run check:runtime. Treat a failure as blocking. Do not bypass the check or accept a rasterized or duplicated status bar, device bezel, or home indicator as app content.
- For web/app implementations, follow the Browser Choice rule in index. In ChatGPT Work Mode, follow the active build skill's "Previewing prototypes in ChatGPT Work Mode" section before opening a local implementation. Then capture screenshots at the intended viewport.
- Capture additional states when relevant: mobile/desktop, hover/focus/active, empty/loading/error, dark/light, and key responsive breakpoints.
- Save paths or URLs for screenshots when available so findings can cite evidence.
- Capturing screenshots is not enough. Put the source image and the implementation screenshot together in the same comparison input before judging.
-
Normalize before comparing.
- Align crop, viewport size, scale, and device frame. Do not compare a framed mockup to an unframed page without noting the mismatch.
- Prefer comparing content regions over full browser chrome or surrounding canvas.
- For the
mobile-app template, force or verify a 1:1 phone-screen capture before judging fidelity. The template scales the device down to fit small browser viewports; use a large enough Playwright viewport for scale 1 and verify [data-phone-screen] measures 393 x 852 CSS px before capture. If the screen measures smaller, the screenshot is scaled and is not valid for 1:1 comparison.
Required Fidelity Surfaces
Every QA report must explicitly evaluate these surfaces:
- Fonts and typography: family, fallback, weight, size, line height, letter spacing, antialiasing, hierarchy, wrapping, truncation, and whether display text and small UI text use appropriate optical weights. It is incredibly important to check fonts carefully for fidelity, including looking up similar typefaces or using image analysis to find the font differences.
- Spacing and layout rhythm: frame size, crop, alignment, margins, padding, grid tracks, section gaps, component spacing, radii, shadows/elevation, and vertical rhythm.
- Colors and visual tokens: sampled or inferred palette, gradients, opacity, contrast, semantic state colors, foreground/background balance, and whether CSS tokens map to the source design.
- Image quality and asset fidelity: subject correctness, crop, scale, sharpness, compression, transparency halos, masking, background treatment, raster-vs-vector appropriateness, and whether generated assets match the source art direction. Fail QA if logos, illustrations, decorative marks, product imagery, non-standard icons, or other visible image assets from the visual target were replaced with custom inline SVG, handcrafted SVG, HTML elements, div/span shapes, CSS drawings, gradients, emoji, text glyphs, placeholder shapes, or code-native approximations.
- Copy and content of app-specific text
Severity
P0: Blocks core use, severe accessibility failure, broken layout, or impossible task.P1: Major design mismatch or usability regression likely to be noticed by users.P2: Moderate visual drift, inconsistent state, responsive issue, or fixable polish gap.P3: Minor refinement that improves fidelity but does not block acceptance.
Treat viewport overflow that hides persistent app controls, and mismatches that materially change above-the-fold content, major-region proportions, text wrapping, or interface density, as P2 or higher.
Output Format
Use this structure unless the user asks otherwise:
**Findings**
- [P1] Short issue title
Location: screen/component/selector/file if known.
Evidence: design does X, implementation does Y.
Impact: why this matters.
Fix: concrete change.
**Open Questions**
- Any ambiguity about intentional deviations, unavailable states, or missing artifacts.
**Implementation Checklist**
- Ordered fixes that can be executed directly.
**Follow-up Polish**
- P3 refinements that can improve fidelity after handoff.
If there are no substantive mismatches, say that clearly and list any residual test gaps.
When this skill is used before handoff, save the latest QA report as project-root design-qa.md.
design-qa.md must include:
- source visual truth path
- implementation screenshot path
- viewport
- source and implementation pixel dimensions, CSS size, and density normalization used
- state
- full-view comparison evidence
- focused region comparison evidence, or why it was not needed
- findings
- comparison history for every P0/P1/P2 iteration: earlier findings, fixes made, and post-fix visual evidence
- final result
For ChatGPT Work Mode builds, design-qa.md must include the browser-rendered implementation screenshot, viewport, primary interactions tested, console errors checked, and final result. If browser-rendered evidence is missing, final result is blocked.
final result must be exactly passed or blocked.
Use passed when there are no actionable P0/P1/P2 findings. P3 findings may remain as follow-up polish.
Use blocked when actionable P0/P1/P2 findings remain and name the blocker.
Return the file path with the QA report.
