/design-review

description: "Review an existing design for quality — accessibility, usability, visual consistency, content, and motion. Accepts HTML files, Figma URLs, preview servers, or screenshots for visual AI critique."
argument-hint: "[file path, URL, screenshot path, or 'current preview']"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "mcp__*"]

/design-review

You are conducting a structured design quality audit. This is a review, not a redesign.

Target

Target: **$ARGUMENTS**

The user will provide one of:

• **A screenshot or image file** (`.png`, `.jpg`, `.gif`, `.webp`) → **Visual AI Critique Mode** (see Section A)
• **A Figma URL** (contains `figma.com`) → screenshot it, then run Visual AI Critique + code audit
• **An HTML file path** → read it and run Code-Level Audit (Section B)
• **A running preview server** → take a screenshot for Visual AI Critique, then inspect code
• **"current preview"** → inspect whatever is currently being previewed

**Dual-mode strategy**: When both a visual and code source are available (e.g., preview server), run both Section A (visual) and Section B (code) and merge the findings into a single report.

**MCP Fallback**: If Preview MCP tools are unavailable, read the HTML source and perform a static code-level audit. If Figma MCP is unavailable, ask the user for a screenshot or file export.

---

Step 0: Load Project Constraints

Search up to 3 directory levels for `.naksha/project.json`. If found, extract **v5 fields** to use as audit criteria throughout this review:

• `constraints.grid` → the expected base spacing unit. Flag any spacing value in the design that is NOT a multiple of this unit (e.g., if grid is `"8px"`, flag `13px`, `22px`, `7px` margins).
• `constraints.dark_mode` → if `false` and the design includes dark mode styles (`prefers-color-scheme: dark`, `[data-theme="dark"]`, etc.), flag as **constraint violation**: "Dark mode was explicitly ruled out."
• `constraints.breakpoints` → the expected responsive breakpoints. Flag missing breakpoints or breakpoints at unexpected values.
• `constraints.max_content_width` → if any layout container exceeds this value, flag it.
• `constraints.accessibility_target` → sets the required contrast threshold. `"WCAG AAA"` requires 7:1; `"WCAG AA"` requires 4.5:1. Use instead of the default 4.5:1 if `"WCAG AAA"` is set.
• `constraints.out_of_scope` → if the design implements something in this list (e.g., dark mode was out-of-scope but is present), flag as a scope violation.
• `constraints.notes` → treat each note as an expected design rule. Check for violations.
• `component_patterns` → for any component named in this list, check whether the implementation matches the recorded pattern (background, border, radius, padding, etc.). Flag mismatches as **pattern deviation**.
• `browser_findings` (5 most recent) → use as reference context — these are research findings or prior visual captures. Reference them when relevant but do not penalize for deviating from external sites.

**If constraints are loaded**, add a **Constraint Compliance** section to the report (see Report Format below) that lists each constraint and whether it passes or fails.

**If no project memory found**: run the review without constraint context — this is fine, no message needed.

---

Section A: Visual AI Critique (Screenshot / Vision Mode)

Use this section when the input is an image file, a Figma URL, or a captured preview screenshot.

How to obtain the image

• **Image file provided**: Read it directly using the Read tool (Claude is multimodal — it can analyze images)
• **Figma URL**: Call `figma_get_component_image` or `figma_take_screenshot` to export the frame
• **Preview server**: Call `preview_screenshot` to capture the current state
• **"current preview"**: Call `preview_screenshot`

**Live Website URL (non-Figma):** If `$ARGUMENTS` contains a URL that is NOT a Figma URL (doesn't contain `figma.com`): 1. Use `mcp__plugin_playwright_playwright__browser_resize` to set viewport to 1440×900 2. Use `mcp__plugin_playwright_playwright__browser_navigate` to load the URL 3. Use `mcp__plugin_playwright_playwright__browser_take_screenshot` to capture the current view 4. Resize to 390×844 and take a second screenshot for mobile view 5. Proceed with visual analysis using both screenshots as the design to review 6. Note at top of output: "Captured from live URL: {url}"

MCP Fallback: If Playwright is unavailable, ask the user to provide a screenshot file path.

Visual Design Principles Scoring

Analyze the screenshot against the following 6 principles. Score each 0–10.

1. Visual Hierarchy (0–10)

Evaluate how clearly the design communicates importance through size, weight, color, and contrast.

**What to check:**

• Is there a clear primary focal point? Can you identify the most important element within 3 seconds?
• Size contrast: Does the headline dominate the body text by a ratio of at least 1.5x?
• Weight contrast: Is bold/semibold used purposefully, not uniformly?
• Color: Are accent colors reserved for actions and key information, not decorative use?
• Whitespace: Is there breathing room around important elements, or does the layout feel cluttered?

**Scoring rubric:**

• 9–10: Immediate clear hierarchy; eye moves naturally through the layout
• 7–8: Good hierarchy with minor ambiguities
• 5–6: Some hierarchy but competing visual weights
• 3–4: Flat, hard to determine what matters most
• 0–2: No clear hierarchy; everything fights for attention

2. Alignment & Grid (0–10)

Evaluate the internal consistency and spatial organization.

**What to check:**

• Do elements share invisible alignment lines? (Left edges, center axes, right edges)
• Is there a visible grid or column structure? Do elements snap to it?
• Are margins/gutters consistent throughout?
• Are related elements grouped with consistent spacing; unrelated elements separated?
• Do text baselines align across columns?

**Scoring rubric:**

• 9