Use free rendered measurements while building, reserve the full visual review for a clean quick pass, and interpret scoped facet/element coverage honestly.
Where: Designer assistant after building or materially restyling a page → review_page.
Key ideas
- Quick is measurement; full is the visual look: review_page depth quick (default) renders desktop and phone and measures readability, layout, overflow, placeholders, and direction without a vision-model round. depth full captures both widths (or deck slides) and asks for visual judgment; reserve it until quick findings are clean.
- Seven explicit QA facets: focus/focuses can request structure, content, visual, responsive, basic-interactions, advanced-motion, and controls. Each facet reports verified, failed, partial, unsupported, or unavailable evidence. element_ids scopes the check to existing roots and the returned coverage says what was actually inspected.
- The build ledger is optional: design_workflow tracks structure, content, visual, responsive, basic interactions, advanced motion, controls, and final evidence. It can show status or scope a concern, but authoring does not require starting and checking each layer in order; the host checks applicable facets together at completion.
Steps
- Build a complete usable page in cohesive batches; do not spend a visual review on an empty scaffold.
- Run review_page with depth quick and include the user brief, acceptance checks, and any relevant focuses.
- Resolve failed and partial findings; if an element-scoped check was requested, confirm its id appears in returned coverage.
- When quick checks are clean, request one depth full review for visual judgment and address its concrete findings.
- Use design_workflow status/check only when you need the optional progress ledger or a focused check; do not advance phases ceremonially.
- At handoff, state verified facets and anything still partial, unavailable, or requiring real playback/public-link testing.
review_page controls
- depth: quick (default) or full.
- focus: one facet; focuses: several facets in one render.
- element_ids: requested roots, with coverage reported for each.
- checks: extra acceptance requirements such as connected design system or full-bleed hero.
- auto_fix: deterministic contrast repair is optional and defaults off.
Workflow ledger
- design_workflow action status reads the ledger.
- start scopes a layer and may include element_ids.
- check runs a targeted concern; the normal host completion gate checks applicable facets together.
- The full visual review is reserved separately from quick checks; failed/unreadable evidence must be reported honestly.
Current write and review guardrails
Designer now preserves useful partial work while refusing destructive corruption. A non-user transaction that empties a page is reversed and named; invalid exposed fields or interactions are dropped while valid siblings still write; stylesheet parse faults fail, while unsafe system-token/kit declarations are removed and the remainder is applied.
- Primitive controls receive design-system classes during writes and a post-write sweep.
- Contrast is measured per element and, for text over imagery, against sampled raster tiles.
- Deck review checks each slide’s final frame so hidden or exited copy is not mistaken for visible content.
- Reviews stay grounded in the user brief, exact slots, current direction, system knobs, sticky overlays, gallery travel, and pinned/scrub runtime behavior.
- Targeted edits preserve authored motion and transforms outside the requested scope.
Tips
- Include the actual audience, brand, and desired feeling in the brief. The reviewer cannot judge brand specificity from “make it nice.”
- Fix composition before polish: hierarchy and layout variety usually matter more than a tiny shadow or border adjustment.
Limitations and important notes
- Quick review is measurement, not a vision-model opinion; full review is the visual pass.
- Facet evidence may be partial, unsupported, or unavailable and those states are not passes.
- A screenshot does not validate playback, accessibility, content accuracy, CMS data, or a public export.
Troubleshooting
The review did not inspect the requested layer.
Check coverage for the exact element id and facet. Use a valid existing id and rerun the relevant scoped check.
I received measurements but wanted visual judgment.
After quick findings are clean, run review_page with depth full; it uses the reserved visual review.