Design Review

This skill runs a structured design review of what has been built, measured against the design brief and the chosen aesthetic philosophy.

CRITICAL — Visual Screenshot Capture You MUST capture screenshots of the running application as part of every design review. Code review alone is insufficient — you need to see what the user sees. Follow the screenshot capture protocol in Step 3 below. This is not optional.

Example prompts

• "Review what I just built"
• "Run a design critique on the landing page"
• "Check this against the brief"
• "Here's a screenshot. How does it look?" [paste screenshot]
• "QA pass before I ship this"

Process

1. Read the brief. Look for the active feature's brief at .design/<feature-slug>/DESIGN_BRIEF.md. If multiple feature folders exist under .design/, ask the user which feature to review. If no .design/ folder exists, fall back to DESIGN_BRIEF.md in the project root. If neither exists, ask the user what the intended design direction was.

1. Explore the built code. Examine every component, page, and style file that was created or modified. Scan specifically for:

• All new or modified components and their relationship to pre-existing components
• Token/variable usage: are components using shared tokens or hardcoding values?
• Duplicate components that should be consolidated
• File naming and organization: do new files follow the project's conventions?
• Understand what was actually built, not what was planned.

1. Capture screenshots of the running application.

This step is mandatory. Do not skip it. Do not rely only on user-provided screenshots.

### Screenshot Tool Priority

Try each option in order. Use the first one that is available:

1. Playwright MCP (preferred). Check if the plugin-playwright-playwright MCP server is available. If it is, use it — it gives you precise control over viewport sizing, full-page captures, and file naming.
2. Cursor IDE Browser (second choice). If Playwright MCP is not available, use the cursor-ide-browser MCP server's browser_take_screenshot tool instead. It has the same core capabilities.
3. Ask the user (last resort). If neither MCP server nor in-app browser is available, you MUST ask the user to provide screenshots manually. Be specific about what you need:

• "I don't have access to a browser tool. To complete the visual review I need screenshots of the running application. Please provide:"
• A full-page screenshot at desktop width (1280px)
• A full-page screenshot at tablet width (768px)
• A full-page screenshot at mobile width (375px)
• Dark mode variants (if applicable)
• Any specific component or interactive state you want reviewed
• Ask the user to paste/attach the images directly in chat, or to save them into the screenshots/ folder themselves.
• Do not skip the visual review. Wait for the user to provide screenshots before proceeding with the checklist.

### Screenshot Save Location

All screenshots MUST be saved to a screenshots/ subfolder inside the feature's .design/ directory — the same folder where DESIGN_BRIEF.md and other design flow files live.

Path pattern: .design/<feature-slug>/screenshots/

If the brief lives at .design/onboarding-flow/DESIGN_BRIEF.md, screenshots go to .design/onboarding-flow/screenshots/. Create the folder if it does not exist.

If no .design/ folder exists (legacy project or standalone review), fall back to a screenshots/ folder in the project root.

Use descriptive filenames that encode what was captured:

   .design/
   └── onboarding-flow/
       ├── DESIGN_BRIEF.md
       ├── DESIGN_REVIEW.md
       └── screenshots/
           ├── review-homepage-desktop-1280.png
           ├── review-homepage-tablet-768.png
           ├── review-homepage-mobile-375.png
           ├── review-homepage-dark-mode-desktop-1280.png
           └── review-card-component-hover.png

### Screenshot Capture Protocol

a. Navigate to the application. Ask the user for the URL if not obvious from the project (e.g., http://localhost:3000). Use browser_navigate to open it.

b. Capture responsive breakpoints. At minimum, capture these three viewports for every key page/view:

Use browser_resize to set the viewport before each screenshot. Use browser_take_screenshot with fullPage: true to capture the entire scrollable page, and save with the filename parameter pointing to the screenshots/ folder.

Playwright MCP example sequence (assuming feature slug is onboarding-flow):

   1. browser_navigate → { url: "http://localhost:3000" }
   2. browser_resize   → { width: 1280, height: 800 }
   3. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-desktop-1280.png", fullPage: true }
   4. browser_resize   → { width: 768, height: 1024 }
   5. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-tablet-768.png", fullPage: true }
   6. browser_resize   → { width: 375, height: 812 }
   7. browser_take_screenshot → { type: "png", filename: ".design/onboarding-flow/screenshots/review-homepage-mobile-375.png", fullPage: true }

c. Capture interactive states (when relevant).

• Hover states on buttons, cards, links
• Focus states on form fields
• Open states on dropdowns, modals, menus
• Error/success states on forms
• Loading and empty states

d. Capture dark mode (if the project supports it). Toggle dark mode and repeat the responsive breakpoint captures with -dark-mode in the filename.

e. Capture specific components. If the review focuses on a particular component, use the element and ref parameters to screenshot just that element.

### Analyze Every Screenshot

After capturing, visually analyze each screenshot against the design brief. For each screenshot:

• Compare against the brief's aesthetic direction
• Check visual hierarchy: is the most important element the most prominent?
• Check spacing consistency: do margins and padding look even and intentional?
• Check color: does the palette match the brief's direction?
• Check typography: are font sizes, weights, and spacing visually correct?
• Check responsive adaptation: does the layout properly reorganize (not just shrink)?
• Note rendering issues that code review alone would miss (font loading failures, broken images, layout overflow, z-index problems, incorrect border-radius, color mismatches)

Reference specific screenshots by filename in the review output so findings are traceable.

1. Run the review checklist below. For each category, note what passes and what needs refinement. Be specific. Reference exact components, files, line numbers, and screenshot filenames.

1. Produce a prioritized refinement list. Group issues by severity:

• Must fix: Broken functionality, accessibility failures, major deviations from the brief.
• Should fix: Inconsistencies, missing states, responsive issues.
• Could improve: Polish, animation refinement, typography fine-tuning.

1. Save the review as DESIGN_REVIEW.md inside the feature's .design/<feature-slug>/ folder (next to DESIGN_BRIEF.md). If no .design/ folder exists, save to the project root. Include a "Screenshots Captured" section listing all screenshots taken with their paths. Present the review directly as well if the user prefers.

Review Checklist

Visual Hierarchy

• Is the most important content the most visually prominent on each page/view?