← All craftbooks

UX & Visual Design Review

Review and QAevalv1.0.0released 2026-06-05workflow: build-loop

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the design reviewreviewerentry

   enumerate screens + lock UX/visual heuristics

   Show working prompt

   Step 1: Identify the screens/components and the primary user task the design serves. Step 2: Write a design acceptance-criteria checklist covering UX and visual heuristics: clear visual hierarchy (the most important element reads first), consistent spacing rhythm and alignment to a grid, a coherent typographic scale (limited sizes/weights), sufficient color contrast and a disciplined palette, consistency of components/patterns across screens, obvious affordances and immediate feedback on actions, presence and quality of empty/loading/error/success states, and low friction on the primary task (minimal steps, no dead-ends). Step 3: For each heuristic state the pass condition for THIS UI (e.g. 'spacing uses a 4/8px scale, no arbitrary gaps', 'one accent color used only for primary actions'). Step 4: Note how you will evaluate (screenshots via the existing automation if available, else reading the markup/CSS and reasoning about the rendered result). Write the screen list + heuristic checklist to `write_task_note` AND `notes/scope.md`. No critique yet.

2. Review the designvisual-designer

   critique each screen against the heuristics

   Show working prompt

   Step 1: View each screen (capture/screenshot via the existing Playwright specs or browser if available; otherwise render the CSS in your head from the source and reason precisely). Step 2: For EACH heuristic, assess the screen and note specific issues: where the hierarchy is flat or competing, where spacing/alignment is inconsistent (cite the elements and the px values), where type or color breaks the system, where an affordance is missing or feedback is absent, and which states are unhandled. Step 3: For every finding capture: the screen/element, the heuristic violated, the user/visual impact, severity (high = hurts the task or looks broken / medium / low polish), and a CONCRETE fix with values ('increase the card padding from 8px to 16px', 'demote the secondary button to a text link', 'add a skeleton loading state'). Step 4: Note what works well too — a good review reinforces the strong patterns. Good looks like: specific, valued-anchored fixes, never 'make it cleaner'. Stage findings to `write_task_note`. Do not write the report yet.

3. Write the design reportreviewer

   prioritized findings with concrete fixes

   Show working prompt

   Step 1: Open `design-review.md` and write a 2-3 sentence overall impression: what works, and the single biggest opportunity. Step 2: Add a '## High impact' section (issues that hurt usability or look broken), '## Medium', and '## Polish' — each finding as `screen/element — problem — concrete fix (with values)`. Step 3: Add a '## What's working' section reinforcing the strong patterns to keep. Step 4: If screenshots were captured, reference them per finding. Every fix must be specific and actionable (values, not adjectives). On a loop-back, fix only the named gaps without dropping valid findings. `write_task_note` the report path and the count of findings by impact.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Open `design-review.md` and grade it against the scope heuristic checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) every heuristic in the checklist was assessed; (2) findings are prioritized by impact (high/medium/polish); (3) each finding names the screen/element and gives a concrete fix with values, not adjectives; (4) empty/loading/error states were evaluated; (5) the primary task's friction was assessed; (6) a What's-working section exists; (7) no vague 'make it pop' filler. If any criterion fails, name the exact gap and loop back.
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• design review
• ux critique
• review the design
• give design feedback
• visual QA
• does this look right

Source

View this craftbook on GitHub · MIT license