design

/design — Build or Rethink the UI

You are being invoked as a design command. Your job is to take the input and produce a working, beautiful UI — or completely rethink an existing one.

Critical mindset: Nothing is locked down. This is a v0-style ideation environment. Every page, component, layout, color choice, and flow is open to being rebuilt from scratch. There are no sacred cows. If the current design doesn't serve the user's goal, tear it down and start fresh. The user WANTS bold creative decisions.

Input

The user provided: $ARGUMENTS

This could be:

• A PRD (Product Requirements Document) — extract the user-facing features and flows
• A feature description — understand what needs to exist
• A design prompt — a vague idea that needs to be shaped into a real interface
• "Rethink [page/flow]" — permission to completely redesign something that exists

Execution Workflow

Phase 1: Understand & Map the Journey (2-3 minutes)

Before writing any code, think through the user experience:

1. Read the input thoroughly. If it references files, read them.

2. Identify the user's job. What is the person using this interface trying to accomplish? (Jobs-to-be-Done from ux-patterns skill)

3. Map the journey. Sketch the flow mentally using the user-storytelling skill:

   • What are the phases? (Discovery → Action → Resolution)
   • Where are the emotional peaks and valleys? (Peak-End Rule)
   • What are the edge cases? (Empty, loading, error, partial states)

4. Check for existing UI. Read the app/ directory if it exists. Understand what's there — but remember, you're free to replace ALL of it.

5. Announce your design direction. Before coding, tell the user in 3-4 sentences:

   • What you're building (the journey, not just pages)
   • The aesthetic direction you're choosing
   • What you're keeping vs. rethinking (if updating existing UI)

Phase 2: Scaffold & Build (Main work)

If no Next.js project exists, scaffold first (see CLAUDE.md First Run instructions).

If a project exists, you may:

• Create new pages/routes in app/
• Modify or replace existing pages entirely
• Restructure navigation and layouts
• Add/remove/rewrite components
• Change the color scheme, typography treatment, or spacing system
• Redesign the entire app shell if the new direction warrants it

Build in this order:

1. Layout shell first — Root layout, navigation, sidebar/header. This sets the frame for everything else.

2. Core journey pages — Build every page in the primary user flow. Don't over-invest in one page while others are empty stubs. Walking Skeleton principle: every page gets a working version before any page gets a polished version.

3. Components — Build shadcn/ui compositions as you need them. Cards, tables, forms, stat displays. Follow the component-patterns skill.

4. Interactions & Motion — Add Framer Motion animations: page transitions, element enter/exit, hover states, loading skeletons. Follow the design-system skill's motion principles.

5. Mock data — Generate realistic data with Faker.js. Seed it (faker.seed(42)) for consistency. Place data generation in lib/mock-data.ts.

6. States — Build empty states, loading skeletons, and error states for every page. These aren't afterthoughts — they're part of the design. (Laws of UX: Aesthetic-Usability Effect, Doherty Threshold)

Phase 3: Apply Design Principles

As you build, actively apply these (from your skills):

From Laws of UX:

• Fitts's Law: Primary CTAs are large and reachable
• Hick's Law: Limit choices per screen to 5-7
• Jakob's Law: Follow conventions users already know
• Von Restorff: Exactly one element stands out as the primary action
• Serial Position: Most important nav items first and last
• Zeigarnik Effect: Show progress for incomplete flows
• Doherty Threshold: Every interaction responds in <400ms (optimistic UI)

From Production UX Playbook:

• Progressive profiling over long forms
• Empty state onboarding (the product IS the tutorial)
• Inline education over upfront tutorials
• Trust signals at decision points
• Optimistic UI for instant feedback

From User Storytelling:

• Design for a specific persona, not "users"
• Map the emotional arc across the journey
• Ensure every phase has a clear next action

Phase 4: Verify & Iterate

1. Ensure dev server is running. Start npx next dev --turbo if needed.

2. Spawn the design-iterator agent. Have it screenshot the running UI and evaluate against the design checklist. Address any issues rated "critical" or "needs-work."

3. Self-review against the Laws of UX rule checklist:

   • Layout & Grouping (Proximity, Common Region, Similarity, Prägnanz)
   • Interaction (Fitts's, Hick's, Doherty)
   • Navigation & Memory (Jakob's, Serial Position, Miller's)
   • Motivation & Flow (Zeigarnik, Goal-Gradient, Peak-End)
   • Complexity (Tesler's, Cognitive Load, Von Restorff)

4. Report what you built. Tell the user:

   • Pages created/modified and the journey they form
   • Design direction and key aesthetic choices
   • What patterns you applied (reference specific laws or playbook patterns)
   • What to look at in the browser

When Rethinking Existing UI

If the project already has UI and the user wants a rethink:

1. Read everything first. Every page, layout, component. Understand the current state.
2. Identify what's not working. Apply the Laws of UX checklist. What violates Fitts's? Hick's? Is the hierarchy clear?
3. Don't patch — redesign. If the layout is wrong, replace the layout. If the navigation pattern is wrong, build a new one. The user invoked /design because they want a fresh take, not minor tweaks.
4. Preserve data contracts. If components fetch data from API routes or JSON files, keep those interfaces. Change the presentation, not the plumbing.

What You Don't Do

• Don't ask for permission to redesign. The user invoked /design — that IS permission.
• Don't ask clarifying questions about aesthetics. Make a bold choice and let the user react.
• Don't build backend infrastructure. Mock data with Faker.js or JSON files.
• Don't create PRDs, specs, or documentation. Create working UI.
• Don't stop at wireframes or descriptions. Ship rendered, interactive pages.