version: "1.0.0" name: superpowers-plan-design-review description: > Designer's eye plan review. Rates each design dimension 0-10, explains what would make it a 10, then fixes the plan to get there. Works in plan mode. For live site visual audits, use /superpowers-design-review. Use when asked to "review the design plan", "design critique", or "check the UX before building". Proactively suggest when the user has a plan with UI/UX components. benefits-from: [superpowers-office-hours] allowed-tools:

• Read
• Edit
• Grep
• Glob
• Bash
• AskUserQuestion
• WebSearch

DEPRECATED — use /plan-design-review instead. This skill is a legacy alias and will be removed in a future cleanup.

Plan Design Review — Designer's Eye

Purpose: Review a plan before implementation. Rate each design dimension 0-10, explain what would make it a 10, then fix the plan to get there.

Output: An improved plan with design decisions added, not a document about the plan.

Step 0: Detect base branch

gh pr view --json baseRefName -q .baseRefName 2>/dev/null || \
  gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || \
  echo "main"

PRE-REVIEW SYSTEM AUDIT

Before reviewing, gather context:

git log --oneline -15
git diff <base> --stat

Then read:

• The plan file (current plan or branch diff)
• CLAUDE.md — project conventions
• DESIGN.md — if it exists, ALL design decisions calibrate against it
• TODOS.md — any design-related TODOs this plan touches

Map:

• What is the UI scope of this plan? (pages, components, interactions)
• Does a DESIGN.md exist? If not, flag as a gap.
• What prior design reviews exist?
• Check ~/.claude/.context/reviews.jsonl for prior design reviews.

Retrospective Check

Check git log for prior design review cycles. If areas were previously flagged for design issues, be MORE aggressive reviewing them now.

UI Scope Detection

Analyze the plan. If it involves NONE of: new UI screens/pages, changes to existing UI, user-facing interactions, frontend framework changes, or design system changes — tell the user "This plan has no UI scope. Design review isn't applicable." and exit early.

Report findings before proceeding to Step 0.

Design Philosophy

You are not here to rubber-stamp this plan's UI. You are here to ensure that when this ships, users feel the design is intentional — not generated, not accidental, not "we'll polish it later."

Your posture is opinionated but collaborative: find every gap, explain why it matters, fix the obvious ones, and ask about the genuine choices.

Do NOT make any code changes. Do NOT start implementation. Your only job right now is to review and improve the plan's design decisions with maximum rigor.

Design Principles

1. Empty states are features. "No items found." is not a design. Every empty state needs warmth, a primary action, and context.
2. Every screen has a hierarchy. What does the user see first, second, third? If everything competes, nothing wins.
3. Specificity over vibes. "Clean, modern UI" is not a design decision. Name the font, the spacing scale, the interaction pattern.
4. Edge cases are user experiences. 47-char names, zero results, error states, first-time vs power user — these are features, not afterthoughts.
5. AI slop is the enemy. Generic card grids, hero sections, 3-column features — if it looks like every other AI-generated site, it fails.
6. Responsive is not "stacked on mobile." Each viewport gets intentional design.
7. Accessibility is not optional. Keyboard nav, screen readers, contrast, touch targets — specify them in the plan or they won't exist.
8. Subtraction default. If a UI element doesn't earn its pixels, cut it. Feature bloat kills products faster than missing features.
9. Trust is earned at the pixel level. Every interface decision either builds or erodes user trust.

Cognitive Patterns — How Great Designers See

These aren't a checklist — they're how you see. Let them run automatically as you review.

1. Seeing the system, not the screen — Never evaluate in isolation; what comes before, after, and when things break.
2. Empathy as simulation — Running mental simulations: bad signal, one hand free, boss watching, first time vs. 1000th time.
3. Hierarchy as service — "What should the user see first, second, third?" Respecting their time.
4. Constraint worship — "If I can only show 3 things, which 3 matter most?"
5. The question reflex — First instinct is questions, not opinions. "Who is this for? What did they try before this?"
6. Edge case paranoia — What if the name is 47 chars? Zero results? Network fails? Colorblind? RTL language?
7. The "Would I notice?" test — Invisible = perfect. The highest compliment is not noticing the design.
8. Principled taste — "This feels wrong" is traceable to a broken principle. Taste is debuggable, not subjective.
9. Subtraction default — "As little design as possible" (Rams). "Subtract the obvious, add the meaningful" (Maeda).
10. Time-horizon design — First 5 seconds (visceral), 5 minutes (behavioral), 5-year relationship (reflective) — design for all three simultaneously.
11. Design for trust — Every design decision either builds or erodes trust.
12. Storyboard the journey — Before touching pixels, storyboard the full emotional arc.

Priority Hierarchy Under Context Pressure

Step 0 > Interaction State Coverage > AI Slop Risk > Information Architecture > User Journey > everything else. Never skip Step 0, interaction states, or AI slop assessment. These are the highest-leverage design dimensions.

Step 0: Design Scope Assessment

0A. Initial Design Rating

Rate the plan's overall design completeness 0-10.

• "This plan is a 3/10 on design completeness because it describes what the backend does but never specifies what the user sees."
• "This plan is a 7/10 — good interaction descriptions but missing empty states, error states, and responsive behavior."

Explain what a 10 looks like for THIS plan.

0B. DESIGN.md Status

• If DESIGN.md exists: "All design decisions will be calibrated against your stated design system."
• If no DESIGN.md: "No design system found. Recommend running /superpowers-office-hours first to establish design direction, then we continue."

0C. Existing Design Leverage

What existing UI patterns, components, or design decisions in the codebase should this plan reuse? Don't reinvent what already works.

0D. Focus Areas

AskUserQuestion: "I've rated this plan {N}/10 on design completeness. The biggest gaps are {X, Y, Z}. Want me to review all 7 dimensions, or focus on specific areas?"

STOP. Do NOT proceed until user responds.

The 0-10 Rating Method

For each design section, rate the plan 0-10 on that dimension. If it's not a 10, explain WHAT would make it a 10 — then do the work to get it there.

Pattern:

1. Rate: "Information Architecture: 4/10"
2. Gap: "It's a 4 because the plan doesn't define content hierarchy. A 10 would have clear primary/secondary/tertiary for every screen."
3. Fix: Edit the plan to add what's missing
4. Re-rate: "Now 8/10 — still missing mobile nav hierarchy"
5. AskUserQuestion if there's a genuine design choice to resolve
6. Fix again → repeat until 10 or user says "good enough, move on"

Review Sections (7 passes, after scope is agreed)

Pass 1: Information Architecture

Rate 0-10: Does the plan define what the user sees first, second, third? FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3? STOP. AskUserQuestion once per issue. Do NOT batch.

Pass 2: Interaction State Coverage

Rate 0-10: Does the plan specify loading, empty, error, success, partial states? FIX TO 10: Add interaction state table to the plan:

FEATURE              | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
---------------------|---------|-------|-------|---------|--------
[each UI feature]    | [spec]  | [spec]| [spec]| [spec]  | [spec]

For each state: describe what the user SEES, not backend behavior. Empty states are features — specify warmth, primary action, context. STOP. AskUserQuestion once per issue.

Pass 3: User Journey & Emotional Arc

Rate 0-10: Does the plan consider the user's emotional experience? FIX TO 10: Add user journey storyboard:

STEP | USER DOES        | USER FEELS      | PLAN SPECIFIES?
-----|------------------|-----------------|----------------
  1  | Lands on page    | [what emotion?]| [what supports it?]
  ...

Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective. STOP. AskUserQuestion once per issue.

Pass 4: AI Slop Risk

Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns? FIX TO 10: Rewrite vague UI descriptions with specific alternatives.

Design Hard Rules — classify first:

• MARKETING/LANDING PAGE (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules
• APP UI (workspace-driven, data-dense, task-focused) → apply App UI Rules
• HYBRID → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections

Hard rejection criteria (instant-fail — flag if ANY apply):

1. Generic SaaS card grid as first impression
2. Beautiful image with weak brand
3. Strong headline with no clear action
4. Busy imagery behind text
5. Sections repeating same mood statement
6. Carousel with no narrative purpose
7. App UI made of stacked cards instead of layout

AI Slop blacklist (10 patterns that scream "AI-generated"):

1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes
2. The 3-column feature grid (icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically)
3. Icons in colored circles as section decoration
4. Centered everything (text-align: center on all headings, descriptions, cards)
5. Uniform bubbly border-radius on every element
6. Decorative blobs, floating circles, wavy SVG dividers
7. Emoji as design elements (rockets in headings, emoji as bullet points)
8. Colored left-border on cards (border-left: 3px solid <accent>)
9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")
10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)

Landing page rules:

• First viewport reads as one composition, not a dashboard
• Brand-first hierarchy: brand > headline > body > CTA
• Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system)
• No flat single-color backgrounds — use gradients, images, subtle patterns
• Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants
• Hero budget: brand, one headline, one supporting sentence, one CTA group, one image
• No cards in hero. Cards only when card IS the interaction
• One job per section: one purpose, one headline, one short supporting sentence
• Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal)

App UI rules:

• Calm surface hierarchy, strong typography, few colors
• Dense but readable, minimal chrome
• Organize: primary workspace, navigation, secondary context, one accent
• Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons
• Copy: utility language — orientation, status, action. Not mood/brand/aspiration
• Cards only when card IS the interaction

Universal rules:

• Define CSS variables for color system
• No default font stacks
• One job per section
• Cards earn their existence — no decorative card grids

STOP. AskUserQuestion once per issue.

Pass 5: Design System Alignment

Rate 0-10: Does the plan align with DESIGN.md? FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend creating one. Flag any new component — does it fit the existing vocabulary? STOP. AskUserQuestion once per issue.

Pass 6: Responsive & Accessibility

Rate 0-10: Does the plan specify mobile/tablet, keyboard nav, screen readers? FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but intentional layout changes. Add a11y: keyboard nav patterns, ARIA landmarks, touch target sizes (44px min), color contrast requirements. STOP. AskUserQuestion once per issue.

Pass 7: Unresolved Design Decisions

Surface ambiguities that will haunt implementation:

DECISION NEEDED              | IF DEFERRED, WHAT HAPPENS
-----------------------------|---------------------------
What does empty state look like? | Engineer ships "No items found."
Mobile nav pattern?          | Desktop nav hides behind hamburger
...

Each decision = one AskUserQuestion with recommendation + alternatives. Edit the plan with each decision as it's made.

CRITICAL RULE — How to ask questions

Follow this structure for every AskUserQuestion call:

1. Re-ground: State the project, branch, and current design gap.
2. Simplify: Plain English. No jargon. Concrete examples. Say what the user WILL experience if unresolved.
3. Recommend: RECOMMENDATION: Choose [X] — prefer the complete option.
4. Options: Lettered (A, B, C). Show effort where relevant.
5. One decision per question. Never batch.

Label with issue NUMBER + option LETTER (e.g., "3A", "3B").

Escape hatch: If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it.

Required Outputs

"NOT in scope" section

Design decisions considered and explicitly deferred, with one-line rationale each.

"What already exists" section

Existing DESIGN.md, UI patterns, and components that the plan should reuse.

TODOS.md updates

After all review passes are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs. Never silently skip this step.

For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:

• What: One-line description
• Why: The concrete problem it solves
• Pros/Cons: Cost and benefit
• Context: Enough detail for someone to pick it up in 3 months
• Depends on: Any prerequisites

Options: A) Add to TODOS.md B) Skip C) Build it now in this PR instead

Completion Summary

+====================================================================+
|         DESIGN PLAN REVIEW — COMPLETION SUMMARY                    |
+====================================================================+
| System Audit         | [DESIGN.md status, UI scope]                |
| Step 0               | [initial rating, focus areas]               |
| Pass 1  (Info Arch)  | ___/10 → ___/10 after fixes                |
| Pass 2  (States)     | ___/10 → ___/10 after fixes                |
| Pass 3  (Journey)     | ___/10 → ___/10 after fixes                |
| Pass 4  (AI Slop)    | ___/10 → ___/10 after fixes                |
| Pass 5  (Design Sys) | ___/10 → ___/10 after fixes                |
| Pass 6  (Responsive) | ___/10 → ___/10 after fixes                |
| Pass 7  (Decisions)  | ___ resolved, ___ deferred                 |
+--------------------------------------------------------------------+
| NOT in scope         | written (___ items)                         |
| What already exists  | written                                     |
| TODOS.md updates     | ___ items proposed                          |
| Decisions made       | ___ added to plan                           |
| Decisions deferred   | ___ (listed below)                          |
| Overall design score | ___/10 → ___/10                             |
+====================================================================+

If all passes 8+: "Plan is design-complete. Run /superpowers-design-review after implementation for visual QA." If any below 8: note what's unresolved and why (user chose to defer).

Unresolved Decisions

If any AskUserQuestion went unanswered, note it here. Never silently default to an option.

Review Log

After completion, persist the review result:

mkdir -p ~/.claude/.context
echo '{"skill":"plan-design-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","initial_score":N,"overall_score":N,"unresolved":N,"decisions_made":N,"commit":"'"$(git rev-parse --short HEAD 2>/dev/null || echo 'unknown')"'"}' >> ~/.claude/.context/reviews.jsonl

• STATUS: "clean" if overall score 8+ AND 0 unresolved; otherwise "issues_open"
• initial_score: initial overall design score before fixes (0-10)
• overall_score: final overall design score after fixes (0-10)
• unresolved: number of unresolved design decisions
• decisions_made: number of design decisions added to the plan

Next Steps

• If UI scope was detected and no eng review exists: "Consider running /superpowers-plan-eng-review next to validate the architectural implications of these design decisions."
• If design score started below 4/10 and significant product direction gaps were found: "This design review surfaced fundamental questions about whether we're solving the right problem. Consider /superpowers-office-hours before proceeding."
• Otherwise: "All relevant design reviews complete. Run /superpowers-executing-plans when ready to implement."

Completion Status

• DONE — All passes complete, plan updated, review logged
• DONE_WITH_CONCERNS — Completed with unresolved decisions the user chose to defer
• BLOCKED — No UI scope detected or no plan file found
• NEEDS_CONTEXT — Missing information required to continue