Design Lab Skill
This skill implements a complete design exploration workflow: interview, generate variations, collect feedback, refine, preview, and finalize.
CRITICAL: Cleanup Behavior
All temporary files MUST be deleted when the process ends, whether by:
- User confirms final design → cleanup, then generate plan
- User aborts/cancels → cleanup immediately, no plan generated
Never leave .claude-design/ or __design_lab routes behind. If the user says "cancel", "abort", "stop", or "nevermind" at any point, confirm and then delete all temporary artifacts.
Phase 0: Preflight Detection
Before starting the interview, automatically detect:
Package Manager
Check for lock files in the project root:
pnpm-lock.yaml → use pnpmyarn.lock → use yarnpackage-lock.json → use npmbun.lockb → use bun
Framework Detection
Check for config files:
next.config.js or next.config.mjs or next.config.ts → Next.js
- Check for
app/ directory → App Router
- Check for
pages/ directory → Pages Router
vite.config.js or vite.config.ts → Viteremix.config.js → Remixnuxt.config.js or nuxt.config.ts → Nuxtastro.config.mjs → Astro
Styling System Detection
Check package.json dependencies and config files:
tailwind.config.js or tailwind.config.ts → Tailwind CSS@mui/material in dependencies → Material UI@chakra-ui/react in dependencies → Chakra UIantd in dependencies → Ant Designstyled-components in dependencies → styled-components@emotion/react in dependencies → Emotion.css or .module.css files → CSS Modules
Design Memory Check
Look for existing Design Memory file:
docs/design-memory.mdDESIGN_MEMORY.md.claude-design/design-memory.md
If found, read it and use to prefill defaults and skip redundant questions.
Visual Style Inference (CRITICAL)
DO NOT use generic/predefined styles. Extract visual language from the project:
If Tailwind detected, read tailwind.config.js or tailwind.config.ts:
theme.colors
theme.spacing
theme.borderRadius
theme.fontFamily
theme.boxShadow
If CSS Variables exist, read globals.css, variables.css, or :root definitions:
:root {
--color-*
--spacing-*
--font-*
--radius-*
}
If UI library detected (MUI, Chakra, Ant), read the theme configuration:
- MUI:
theme.ts or createTheme() call
- Chakra:
theme/index.ts or extendTheme() call
- Ant:
ConfigProvider theme prop
Always scan existing components to understand patterns:
- Find 2-3 existing buttons → note their styling patterns
- Find 2-3 existing cards → note padding, borders, shadows
- Find existing forms → note input styles, label placement
- Find existing typography → note heading sizes, body text
Store inferred styles in the Design Brief for consistent use across all variants.
Phase 1: Interview
Use the AskUserQuestion tool for all interview steps. Adapt questions based on Design Memory if it exists.
Step 1.1: Scope & Target
Ask these questions (can combine into single AskUserQuestion with multiple questions):
Question 1: Scope
- Header: "Scope"
- Question: "Are we designing a single component or a full page?"
- Options:
- "Component" - A reusable UI element (button, card, form, modal, etc.)
- "Page" - A complete page or screen layout
Question 2: New or Redesign
- Header: "Type"
- Question: "Is this a new design or a redesign of something existing?"
- Options:
- "New" - Creating something from scratch
- "Redesign" - Improving an existing component/page
If "Redesign" selected, ask:
Question 3: Existing Path
- Header: "Location"
- Question: "What is the file path or route of the existing UI?"
- Options: (let user provide via "Other")
If target is unclear, propose a name based on repo patterns and confirm.
Step 1.2: Pain Points & Inspiration
Question 1: Pain Points
- Header: "Problems"
- Question: "What are the top pain points with the current design (or what should this new design avoid)?"
- Options:
- "Too cluttered/dense" - Information overload, hard to scan
- "Unclear hierarchy" - Primary actions aren't obvious
- "Poor mobile experience" - Doesn't work well on small screens
- "Outdated look" - Feels old or inconsistent with brand
- multiSelect: true
Question 2: Visual Inspiration
- Header: "Visual style"
- Question: "What products or brands should I reference for visual inspiration?"
- Options:
- "Stripe" - Clean, minimal, trustworthy
- "Linear" - Dense, keyboard-first, developer-focused
- "Notion" - Flexible, content-focused, playful
- "Apple" - Premium, spacious, refined
- multiSelect: true
Question 3: Functional Inspiration
- Header: "Interactions"
- Question: "What interaction patterns should I emulate?"
- Options:
- "Inline editing" - Edit in place without modals
- "Progressive disclosure" - Show more as needed
- "Optimistic updates" - Instant feedback, sync in background
- "Keyboard shortcuts" - Power user efficiency
Step 1.3: Brand & Style Direction
Question 1: Brand Adjectives
- Header: "Brand tone"
- Question: "What 3-5 adjectives describe the desired brand feel?"
- Options:
- "Minimal" - Clean, simple, uncluttered
- "Premium" - High-end, polished, refined
- "Playful" - Fun, friendly, approachable
- "Utilitarian" - Functional, efficient, no-nonsense
- multiSelect: true
Question 2: Density
- Header: "Density"
- Question: "What information density do you prefer?"
- Options:
- "Compact" - More information visible, tighter spacing
- "Comfortable" - Balanced spacing, easy scanning
- "Spacious" - Generous whitespace, focused attention
Question 3: Dark Mode
- Header: "Dark mode"
- Question: "Is dark mode required?"
- Options:
- "Yes" - Must support dark mode
- "No" - Light mode only
- "Nice to have" - Support if easy, not required
Step 1.4: Persona & Jobs-to-be-Done
Question 1: Primary User
- Header: "User"
- Question: "Who is the primary end user?"
- Options:
- "Developer" - Technical, keyboard-oriented
- "Designer" - Visual, detail-oriented
- "Business user" - Efficiency-focused, less technical
- "End consumer" - General public, varied technical ability
Question 2: Context
- Header: "Context"
- Question: "What's the primary usage context?"
- Options:
- "Desktop-first" - Primarily used on larger screens
- "Mobile-first" - Primarily used on phones
- "Both equally" - Must work well on all devices
Question 3: Key Tasks
- Header: "Key tasks"
- Question: "What are the top 3 tasks users must complete?"
- (Let user provide via "Other" - this is open-ended)
Step 1.5: Constraints
Question 1: Must-Keep Elements
- Header: "Keep"
- Question: "Are there elements that must be preserved?"
- Options:
- "Existing copy/labels" - Keep current text
- "Current fields/inputs" - Keep form structure
- "Navigation structure" - Keep current nav
- "None" - Free to change everything
Question 2: Technical Constraints
- Header: "Constraints"
- Question: "Any technical constraints?"
- Options:
- "No new dependencies" - Use existing libraries only
- "Use existing components" - Build on current design system
- "Must be accessible (WCAG)" - Strict accessibility requirements
- "None" - No special constraints
- multiSelect: true
Phase 2: Generate Design Brief
After the interview, create a structured Design Brief as JSON and save to .claude-design/design-brief.json:
{
"scope": "component|page",
"isRedesign": true|false,
"targetPath": "src/components/Example.tsx",
"targetName": "Example",
"painPoints": ["Too dense", "Primary action unclear"],
"inspiration": {
"visual": ["Stripe", "Linear"],
"functional": ["Inline validation"]
},
"brand": {
"adjectives": ["minimal", "trustworthy"],
"density": "comfortable",
"darkMode": true
},
"persona": {
"primary": "Developer",
"context": "desktop-first",
"keyTasks": ["Complete checkout", "Review order", "Apply discount"]
},
"constraints": {
"mustKeep": ["existing fields"],
"technical": ["no new dependencies", "WCAG accessible"]
},
"framework": "nextjs-app",
"packageManager": "pnpm",
"stylingSystem": "tailwind"
}
Display a summary to the user before proceeding.
Phase 3: Generate Design Lab
Directory Structure
Create all files under .claude-design/:
.claude-design/
├── lab/
│ ├── page.tsx # Main lab page (framework-specific)
│ ├── variants/
│ │ ├── VariantA.tsx
│ │ ├── VariantB.tsx
│ │ ├── VariantC.tsx
│ │ ├── VariantD.tsx
│ │ └── VariantE.tsx
│ ├── components/
│ │ └── LabShell.tsx # Lab layout wrapper
│ ├── feedback/ # Interactive feedback system
│ │ ├── types.ts # TypeScript interfaces
│ │ ├── selector-utils.ts # Element identification
│ │ ├── format-utils.ts # Feedback formatting
│ │ ├── FeedbackOverlay.tsx # Main overlay component
│ │ └── index.ts # Module exports
│ └── data/
│ └── fixtures.ts # Shared mock data
├── design-brief.json
└── run-log.md
Feedback System Setup (CRITICAL - NEVER SKIP)
The FeedbackOverlay is the PRIMARY feature of the Design Lab. Without it, users cannot provide interactive feedback. NEVER generate a Design Lab without the FeedbackOverlay.
Reliability Strategy: To avoid import path issues across different project configurations, create the FeedbackOverlay directly in the route directory (e.g., app/design-lab/FeedbackOverlay.tsx), NOT in .claude-design/. This ensures a simple relative import (./FeedbackOverlay) always works.
Required Files in Route Directory:
app/design-lab/ # or app/__design_lab/ if underscores work
├── page.tsx # Main lab page with variants
└── FeedbackOverlay.tsx # Self-contained overlay component (copy from templates)
Template Source: design-and-refine/templates/feedback/FeedbackOverlay.tsx
Why this approach:
.claude-design/ paths can fail due to bundler configurations- Relative imports from the same directory always work
- The route directory gets deleted during cleanup anyway
Route Integration
Next.js App Router:
Create app/__design_lab/page.tsx that imports from .claude-design/lab/
Next.js Pages Router:
Create pages/__design_lab.tsx that imports from .claude-design/lab/
Vite React:
- If React Router exists: add route to
/__design_lab
- If no router: create a conditional render in
App.tsx based on ?design_lab=true query param
Other frameworks:
Create the most appropriate temporary route for the detected framework.
Variant Generation Guidelines
IMPORTANT: Read DESIGN_PRINCIPLES.md for UX, interaction, and motion best practices. But DO NOT use predefined visual styles—infer them from the project.
Apply universal principles (from DESIGN_PRINCIPLES.md):
- UX: Nielsen's heuristics, cognitive load reduction, progressive disclosure
- Component behavior: Button states, form anatomy, card structure
- Interaction: Feedback patterns, state handling, optimistic updates
- Motion: Timing (150-300ms), easing (ease-out entrances, ease-in exits)
- Accessibility: Focus states, ARIA patterns, touch targets (44px min)
Infer visual styles from the project:
- Colors → from Tailwind config, CSS variables, or existing components
- Typography → from existing headings, body text in the codebase
- Spacing → from the project's spacing scale or existing patterns
- Border radius → from existing cards, buttons, inputs
- Shadows → from existing elevated components
Each variant MUST explore a different design axis. Do not create minor variations—make them meaningfully distinct. Use the project's existing visual language for all variants.
Variant A: Information Hierarchy Focus
- Restructure content hierarchy (what's most important?)
- Apply Gestalt proximity—group related items closer
- One primary action per view
- Use existing typography scale to create clear levels
Variant B: Layout Model Exploration
- Try a different layout approach (card vs list vs table vs split-pane)
- Apply card anatomy or table behavior patterns from DESIGN_PRINCIPLES
- Consider responsive behavior at each breakpoint
- Use the project's existing grid/layout system
Variant C: Density Variation
- If brief says "comfortable", try a more compact version
- If brief says "compact", try a more spacious version
- Use the project's existing spacing tokens—just apply them differently
- Show the tradeoffs: more visible data vs easier scanning
Variant D: Interaction Model
