Design Lab

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 pnpm
• yarn.lock → use yarn
• package-lock.json → use npm
• bun.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 → Vite
• remix.config.js → Remix
• nuxt.config.js or nuxt.config.ts → Nuxt
• astro.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 UI
• antd in dependencies → Ant Design
• styled-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.md
• DESIGN_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:

// Extract and use:
theme.colors      // Color palette
theme.spacing     // Spacing scale
theme.borderRadius // Radius values
theme.fontFamily  // Typography
theme.boxShadow   // Elevation system

If CSS Variables exist, read globals.css, variables.css, or :root definitions:

:root {
  --color-*     /* Color tokens */
  --spacing-*   /* Spacing tokens */
  --font-*      /* Typography tokens */
  --radius-*    /* Border radius tokens */
}

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",