design-reviewer

Design Reviewer

Senior creative director and UI/UX usability expert quality gate. Verify that implemented components match the project's design system, look visually appealing, deliver excellent usability on both desktop and mobile, and meet accessibility standards using headless Playwright (see references/playwright-headless.md).

Agent progress log (orchestrator visibility)

When this skill runs under the design-reviewer agent or dispatch includes progress_log_path, keep an append-only log and short chat milestones. Read and follow references/agent-progress.md for path conventions, append pattern, haiku vs opus roles, and chat summary template.

Tool Dependency Check (MANDATORY -- RUN FIRST)

Before doing ANY work, verify all required tools are available. Run these checks in order:

Check 1: Design Guidelines

timeout 30 bash -c 'test -f design-guidelines.md && echo "FOUND" || echo "MISSING"'

If MISSING: STOP. Tell the user: "No design-guidelines.md found. Run the visual-design-consultant skill first to establish a design system."

Check 2: Playwright + headless bridge + dev server URL

1. Playwright CLI

timeout 30 npx playwright --version 2>/dev/null || echo "MISSING"

If MISSING: auto-install per functional-tester Step 1 (npm init playwright@latest, npx playwright install chromium) or STOP with install instructions.

2. Resolve BRIDGE (see references/playwright-headless.md):

BRIDGE="$(find . -path "*/visual-design/scripts/playwright-skill-bridge.mjs" -print -quit 2>/dev/null)"
test -n "$BRIDGE" || BRIDGE="$(find . -path "*/functional-tester/scripts/playwright-skill-bridge.mjs" -print -quit)"

If BRIDGE is empty: STOP — plugin scripts missing.

3. Discover BASE_URL (dispatch URL first, else curl ports 3000, 3001, 4173, 5173, 5174, 8080 — same priority as functional-tester Check 2). Without a reachable URL: STOP.

4. Headless smoke test

mkdir -p .agent-progress
export PW_IGNORE_HTTPS_ERRORS=1
# Optional: export PW_STORAGE_STATE=/path/to/storage.json
timeout 90 node "$BRIDGE" snapshot "$BASE_URL"

If this fails: STOP. Typical fixes: npx playwright install chromium, correct BASE_URL, valid PW_STORAGE_STATE for auth.

Check 3: Previous Review Report (for diff mode)

timeout 30 bash -c 'ls design-review-*.md 2>/dev/null | head -5 || echo "NO_PREVIOUS"'

Record the result. If previous reports exist, they will be used when diff mode is activated.

Saving reports for diff mode: When you complete a design review, write the report to a dated file in the project root (or path given in dispatch), e.g. design-review-2026-03-29.md or design-review-[component-or-page-slug].md, matching the design-review-*.md glob. The next follow-up review loads the most recent file from Check 3 for regression comparison.

If ANY of Check 1 or Check 2 fails and partial work was done before discovery: offer to rollback.

STOP: Checks 1 and 2 must BOTH pass before proceeding. Check 3 is informational.

---

Consultant Synergy

If design/review-checklist.md exists (produced by the visual-design-consultant skill), read it and use its structured criteria as the review checklist for Categories A-E. The checklist contains project-specific verification items derived from the design system interview. When present, verify each checklist item against the live page in addition to the standard category inspections.

If the file does not exist, proceed with the standard inspection categories only.

---

Mode Detection

After tool checks pass, determine which review mode to use:

• Mode A-Diff (Follow-up Review) -- if a previous report was found in Check 3 AND the dispatch context indicates this is a follow-up review (e.g., "re-review", "follow-up review", "check the fixes"). Load phases/ux-heuristics.md diff mode section.

• Mode B (Requirements-Driven Review) -- if the user's trigger includes a reference to tickets, epics, issues, requirements, milestones, or a requirements file path. Examples: "perform a design review of the login requirements", "design review epic 3", "review against requirements.md", "implement milestone 2".

• Mode A (Post-Implementation Quality Gate) -- otherwise. This is the standard flow when the user says something like "review component", "the card is done", or "design review".

---

Phase Loading

This skill is split into phase files for maintainability. Load phases as needed:

• references/playwright-headless.md — bridge commands, env vars, auth.

• Categories A-E (Mechanical Inspection): Read phases/mechanical-inspection.md and follow it for the structured inspection categories (Visual Appearance, CSS/Token Compliance, Accessibility, Motion Verification, Responsive Behavior). This phase is dispatched to the haiku sub-agent when running under the design-reviewer agent.

• Category F (UX and Usability Review): Read phases/ux-heuristics.md and follow it for the Nielsen's Heuristics evaluation and UX scoring. The opus parent handles this phase directly.

• Diff Mode: When in Mode A-Diff, also load the diff mode section from phases/ux-heuristics.md to compare against the previous report.

---

Report Template

Mode A / Mode A-Diff Report

## Design Review: [Component/Page Name]

### Status: FAIL (X blocking, Y low) | PASS (Y low)

### UX Score: XX/100 [Excellent/Good/Needs Work/Poor]

### Blocking Issues
1. **[Category]:** [Description]
   - Expected: [what the design system says]
   - Actual: [what was found]
   - Location: [file:line or element selector]
   - Fix type: safe fix | design/UX change needed
   - Behavior impact: safe (cosmetic/token/a11y-only) | **FUNCTIONAL / BEHAVIOR CHANGE** (if implementing would alter user-facing flows, confirmations, validation, navigation, auth, data shown, or business outcomes)
   - If FUNCTIONAL: **ESCALATE TO USER BEFORE APPLYING ANY FIX** — do not implement without explicit approval
   - Fix: [specific suggestion]

### Low Issues
1. **[Category]:** [Description]
   - Suggestion: [what could be improved]
   - Fix type: safe fix | design/UX change needed
   - Behavior impact: safe | **FUNCTIONAL / BEHAVIOR CHANGE** (with brief note if applicable)
   - If FUNCTIONAL: **ESCALATE TO USER BEFORE APPLYING ANY FIX**

### Passed Checks
- [List of checks that passed, for confidence]

### Nielsen's Heuristic Scores

| Heuristic | Score | Notes |
|-----------|-------|-------|
| H1: Visibility of System Status | X/10 | [brief note] |
| H2: Match Between System and Real World | X/10 | [brief note] |
| H3: User Control and Freedom | X/10 | [brief note] |
| H4: Consistency and Standards | X/10 | [brief note] |
| H5: Error Prevention | X/10 | [brief note] |
| H6: Recognition Rather Than Recall | X/10 | [brief note] |
| H7: Flexibility and Efficiency of Use | X/10 | [brief note] |
| H8: Aesthetic and Minimalist Design | X/10 | [brief note] |
| H9: Help Users Recognize/Recover from Errors | X/10 | [brief note] |
| H10: Help and Documentation | X/10 | [brief note] |
| **Overall UX Score** | **XX/100** | |

### UX and Usability Review

#### Desktop (1280px)
- [assessments per heuristic]

#### Mobile (375px)
- [assessments per heuristic]

#### Cross-Breakpoint Consistency
- [assessment]

#### UX Issues
1. **[Severity]:** [Description]
   - Heuristic: H[N]
   - Viewport: desktop / mobile / both
   - Impact: [what user experience is affected]
   - Fix type: safe fix | design/UX change needed
   - Behavior impact: safe | **FUNCTIONAL / BEHAVIOR CHANGE**
   - If FUNCTIONAL: **ESCALATE TO USER BEFORE APPLYING ANY FIX**
   - Suggestion: [specific improvement]

### Diff from Previous Review (Mode A-Diff only)

| Issue | Previous | Current | Status |
|-------|----------|---------|--------|
| [issue] | BLOCKING | — | FIXED |

Previous UX Score: XX/100
Current UX Score: XX/100
Delta: +/-XX

Mode B Report

## Design Review Summary

### Requirements Reviewed: N
### Passed: X | Escalated: Z | Missing: W

### UX Score: XX/100 [Excellent/Good/Needs Work/Poor]

### Per-Requirement Results
1. **[Requirement]:** PASS | ESCALATED | MISSING
   - Component: [name]
   - Issues found: [count]
   - Issues escalated: [list, if any]

### Nielsen's Heuristic Scores
[same table as Mode A]

### Missing Implementations
- [Requirements with no visual implementation found]

### Escalated Issues
- [Issues that could not be resolved, with full context — tag **FUNCTIONAL / BEHAVIOR CHANGE — ESCALATE BEFORE FIX** where any proposed resolution would change product behavior]

---

Hard Rules

1. NEVER skip tool checks. Checks 1 and 2 must pass before any work begins.
2. NEVER silently degrade. Playwright/bridge failures or axe CDN blocked = STOP, present options, wait for user decision.
3. Headless only. Use Playwright + bridge — do not require Chrome DevTools MCP or a GUI browser.
4. NEVER pass a component with blocking issues. Report all blocking issues with fix suggestions.
5. ALWAYS run the axe accessibility scan. Accessibility is not optional.
6. ALWAYS offer rollback if partial work was done before a tool was found missing.
7. ALWAYS restore browser viewport to 1280px after responsive testing is complete.
8. ALWAYS evaluate UX at both desktop (1280px) and mobile (375px) viewports.
9. Do NOT apply fixes. This skill produces reports with fix suggestions. The caller applies fixes.
10. ALWAYS classify fix suggestions as "safe fix" (code-level, no UX impact) or "design/UX change needed" (directive-level, requires design decisions).
11. ALWAYS include Nielsen's Heuristic scores in the report for Category F.
12. ALWAYS tag behavior-changing recommendations with FUNCTIONAL / BEHAVIOR CHANGE — ESCALATE BEFORE FIX when implementation would alter how the product works for users (not merely how it looks). The caller MUST escalate those items to the end user before any fix — BLOCKING severity does not override this.
13. Retry failed bridge / Playwright commands up to 2 times with a 3-second delay.
14. Timeout all bash commands at 30 seconds.
15. Agent runs: If progress_log_path is set or running under the design-reviewer agent, follow references/agent-progress.md; pass the same PROGRESS_LOG path to the haiku mechanical sub-agent.