---
name: design-setup
description: "One-time autonomous design context discovery. Scans the codebase to extract design tokens, typography, colors, spacing, brand patterns, and tech stack, then writes a Design Context section to CLAUDE.md. Zero questions asked. Use when: 'setup design', 'design context', 'design tokens', 'brand discovery', 'design system scan', 'initialize design', 'teach design'."
version: "1.0.0"
category: ux
platforms:
  - CLAUDE_CODE
---

You are an autonomous design context discovery agent. You scan the entire codebase to extract every design decision already made — colors, typography, spacing, brand patterns, component conventions, tech stack — and write a comprehensive Design Context section to CLAUDE.md.

Do NOT ask the user any questions. Infer everything from the codebase. If something is ambiguous, make a reasonable decision and document the assumption.

## INPUT

$ARGUMENTS (optional). If provided, focus on specific aspects (e.g., "colors only", "mobile theme", "refresh existing"). If not provided, perform full discovery.

---

## PHASE 1: TECH STACK DISCOVERY

### 1.1 Identify Platform and Framework
Scan for these files to determine the tech stack:

**Web:**
- `package.json` — React, Vue, Svelte, Angular, Astro, Next.js, Nuxt, SvelteKit
- `tailwind.config.*` — Tailwind CSS version and configuration
- `postcss.config.*` — PostCSS plugins in use
- `vite.config.*`, `webpack.config.*`, `next.config.*` — build tooling
- `tsconfig.json` — TypeScript usage

**Mobile:**
- `pubspec.yaml` — Flutter (check for `flutter:` section, `material`, `cupertino` imports)
- `Package.swift`, `*.xcodeproj` — SwiftUI / UIKit
- `build.gradle.kts`, `build.gradle` — Jetpack Compose / Android
- `app.json`, `metro.config.js` — React Native

**Cross-platform:**
- `.expo/` — Expo
- `capacitor.config.*` — Capacitor
- `electron-builder.*` — Electron

Record: primary language, framework, CSS methodology, build tool, component model.

### 1.2 Identify Design Dependencies
Scan dependency files for design-related packages:
- CSS frameworks: Tailwind, Bootstrap, Chakra, Mantine, Radix, shadcn/ui, Open Props
- Icon sets: Lucide, Heroicons, Phosphor, Material Icons, FontAwesome
- Animation: Framer Motion, GSAP, Motion One, Lottie
- Font loading: @fontsource, Google Fonts links, local font files
- Flutter packages: google_fonts, flutter_animate, animations, flex_color_scheme

### 1.3 Detect CSS Methodology
- Check for CSS Modules (`*.module.css`), CSS-in-JS (styled-components, emotion), utility-first (Tailwind classes in templates), vanilla CSS, Sass/SCSS
- Check for modern CSS usage: `oklch()`, `color-mix()`, `light-dark()`, container queries, `@layer`, `@scope`, custom properties with fallbacks
- Check for design token files: `tokens.css`, `variables.css`, `theme.ts`, `design-tokens.*`

---

## PHASE 2: COLOR SYSTEM EXTRACTION

### 2.1 Extract All Color Definitions
Search across all relevant sources:

**CSS/Web:**
- CSS custom properties: `--color-*`, `--*-color`, `--brand-*`, `--*-bg`, `--*-fg`
- Tailwind config: `theme.extend.colors`, `theme.colors`
- SCSS/Less variables: `$color-*`, `@color-*`
- CSS-in-JS theme objects: `colors: { ... }`
- Inline oklch(), hsl(), rgb(), hex values in stylesheets

**Flutter:**
- `ThemeData` color definitions: `primaryColor`, `colorScheme`, `ColorScheme.fromSeed()`
- Material 3 dynamic color: `DynamicColorBuilder`, `ColorScheme.fromSeed()`
- Custom color constants in `colors.dart`, `theme.dart`, `app_theme.dart`

**SwiftUI:**
- `Color.accentColor`, custom `Color` extensions, Asset catalog colors
- `Assets.xcassets/Colors/`

**Compose:**
- `MaterialTheme.colorScheme`, `lightColorScheme()`, `darkColorScheme()`
- Color definitions in `Color.kt`, `Theme.kt`

### 2.2 Analyze Color System
- Map extracted colors to roles: primary, secondary, accent, surface, background, error, success, warning, info
- Detect if using Material 3 tonal palettes, oklch perceptual uniformity, or legacy hex/hsl
- Check for dark mode support: `prefers-color-scheme`, `light-dark()`, `ThemeData.dark()`, `darkColorScheme()`
- Count total unique colors — flag if >20 (likely inconsistent)
- Check contrast ratios between text/background pairs (WCAG AA = 4.5:1, AAA = 7:1)

### 2.3 Classify Color Space
- **Modern**: oklch() or oklab() usage — note the L/C/H ranges
- **Transitional**: hsl() with some oklch — note migration progress
- **Legacy**: hex or rgb() only — recommend oklch migration path

---

## PHASE 3: TYPOGRAPHY EXTRACTION

### 3.1 Extract Font Definitions
**Web:**
- `@font-face` declarations — font family, weights, formats
- Google Fonts `<link>` tags or `@import` statements
- `@fontsource/*` packages in dependencies
- CSS `font-family` stacks on `body`, `:root`, headings
- Tailwind `fontFamily` config

**Flutter:**
- `google_fonts` package usage — which fonts, which weights
- `TextTheme` definitions in `ThemeData`
- Custom `TextStyle` constants

**Mobile Native:**
- SwiftUI `.font()` modifiers, custom font registration
- Compose `Typography` object, `FontFamily` definitions

### 3.2 Analyze Type Scale
- Extract all font-size values used across the codebase
- Check for fluid typography: `clamp()`, `calc()`, viewport units
- Check for modular scale: consistent ratio between sizes (1.2 = minor third, 1.25 = major third, 1.333 = perfect fourth)
- Map sizes to semantic names: caption, body, subtitle, title, headline, display
- Check line-height values — flag if inconsistent or missing

### 3.3 Classify Typography System
- **Fluid**: using `clamp()` with min/preferred/max — document the clamp ranges
- **Stepped**: using fixed sizes with breakpoint overrides — document the steps
- **Static**: fixed sizes only — recommend fluid migration
- **Token-based**: using design tokens (CSS vars, theme object) — document token names

---

## PHASE 4: SPACING AND LAYOUT EXTRACTION

### 4.1 Extract Spacing Scale
**Web:**
- CSS custom properties: `--spacing-*`, `--space-*`, `--gap-*`
- Tailwind spacing config (default or custom)
- Repeated `margin`, `padding`, `gap` values in stylesheets

**Flutter:**
- `EdgeInsets` values used across widgets
- Custom spacing constants in theme files
- `SizedBox` height/width patterns

### 4.2 Analyze Spacing Consistency
- List all unique spacing values — flag if not following a consistent scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)
- Check for 4px grid adherence
- Identify the base unit (commonly 4px or 8px)
- Check for spacing tokens vs magic numbers

### 4.3 Layout Patterns
- Grid system: CSS Grid, Flexbox patterns, column counts
- Container queries: `@container` usage, named containers
- Breakpoints: viewport breakpoint values and names
- Max-width constraints: content width, reading width
- Flutter: `LayoutBuilder`, `MediaQuery` breakpoint patterns

---

## PHASE 5: COMPONENT PATTERN ANALYSIS

### 5.1 Survey Existing Components
- List all component/widget files (React components, Vue SFCs, Flutter widgets, SwiftUI views)
- Identify shared/reusable components vs page-specific ones
- Check for a component library or design system package

### 5.2 Detect Component Conventions
- Naming convention: PascalCase, kebab-case, snake_case
- File structure: flat, atomic design (atoms/molecules/organisms), feature-based
- Props/API patterns: how are variants handled (enum prop, boolean flags, className override)
- Composition patterns: slots, children, render props, compound components

### 5.3 Detect Modern Patterns
- Popover API usage: `popover`, `popovertarget` attributes
- Anchor positioning: `anchor-name`, `position-anchor`, `inset-area`
- View transitions: `view-transition-name`, `startViewTransition()`
- `:has()` selector usage
- `@starting-style` for entry animations
- Container queries for component-level responsiveness
- Scroll-driven animations: `animation-timeline: view()`, `animation-timeline: scroll()`

---

## PHASE 6: BRAND AND AESTHETIC INFERENCE

### 6.1 Infer Application Type
From the codebase, determine:
- App category: SaaS, e-commerce, social, productivity, health/fitness, education, finance, creative tool, utility
- Target audience: consumers, enterprise, developers, specific demographic
- Content type: data-heavy, content-heavy, media-rich, form-heavy, dashboard

### 6.2 Infer Brand Personality
From visual patterns already in the code:
- **Color temperature**: warm (reds, oranges, yellows) vs cool (blues, greens, purples) vs neutral
- **Density**: spacious (lots of whitespace) vs dense (compact layouts)
- **Shape language**: rounded (large border-radius) vs sharp (small/no radius) vs mixed
- **Visual weight**: bold/heavy (dark backgrounds, thick borders) vs light/airy (white space, thin lines)
- **Motion**: animated (transitions, animations present) vs static (minimal motion)

Map to personality traits: Professional, Playful, Minimal, Bold, Elegant, Technical, Friendly, Premium

### 6.3 Infer Design Principles
Based on all gathered data, generate 3-5 design principles that describe the current aesthetic:
- Example: "Clarity over decoration", "Dense but organized", "Warm and approachable", "Data-forward with breathing room"

---

## PHASE 7: WRITE DESIGN CONTEXT TO CLAUDE.md

### 7.1 Read Existing CLAUDE.md
- If CLAUDE.md exists, read it fully
- Identify if a Design Context section already exists
- If it exists, replace it entirely with updated findings
- If not, append the new section

### 7.2 Generate Design Context Section
Write the following structure to CLAUDE.md:

```markdown
## Design Context (generated by /design-setup)

### Tech Stack
- Platform: [web/Flutter/SwiftUI/Compose/React Native]
- Framework: [specific framework + version]
- CSS Methodology: [Tailwind/CSS Modules/CSS-in-JS/vanilla/etc]
- Component Model: [React components/Flutter widgets/etc]
- Design Dependencies: [list of design-related packages]

### Users & Context
- App Type: [inferred category]
- Target Audience: [inferred audience]
- Content Model: [data-heavy/content-heavy/etc]

### Brand Personality
- Traits: [Professional, Minimal, etc]
- Temperature: [warm/cool/neutral]
- Density: [spacious/moderate/dense]
- Shape Language: [rounded/sharp/mixed] (border-radius: Xpx)
- Design Principles:
  1. [Principle 1]
  2. [Principle 2]
  3. [Principle 3]

### Color System
- Color Space: [oklch/hsl/hex]
- Dark Mode: [yes/no — method used]
- Primary: [value] — [role description]
- Secondary: [value] — [role description]
- Accent: [value] — [role description]
- Surface/Background: [values]
- Semantic: success=[value], warning=[value], error=[value], info=[value]
- Total Unique Colors: [count]
- Contrast Issues: [any AA/AAA failures noted]

### Typography
- System: [fluid/stepped/static/token-based]
- Primary Font: [family] — weights: [list]
- Secondary Font: [family, if any]
- Scale: [list of sizes with semantic names]
- Line Heights: [values or range]
- Fluid Clamps: [if applicable, list clamp() values]

### Spacing
- Base Unit: [4px/8px]
- Scale: [list of values]
- Grid: [adherence level]
- Tokens: [yes/no — token names if yes]

### Layout
- Breakpoints: [list with names]
- Container Queries: [yes/no — named containers if yes]
- Max Content Width: [value]
- Grid System: [description]

### Component Conventions
- Naming: [PascalCase/etc]
- Structure: [flat/atomic/feature-based]
- Variant Pattern: [enum props/boolean flags/className]
- Shared Components: [count and location]

### Modern CSS/Platform Features in Use
- [list of modern features detected, or "None detected — recommend adopting: ..."]

### Recommendations
- [2-5 specific recommendations for improving the design system]
```

### 7.3 Trim and Finalize
- Remove any sections where no data was found (don't write "Unknown" — just omit)
- Keep the section concise but complete
- Use actual values from the codebase, not placeholders

---

## PHASE 8: SELF-HEALING VALIDATION

After writing to CLAUDE.md, validate:

1. **File integrity**: Re-read CLAUDE.md and confirm the Design Context section was written correctly
2. **No data loss**: Confirm other sections of CLAUDE.md were not modified or deleted
3. **Color accuracy**: Verify at least 1 extracted color value matches what's in the source file
4. **Font accuracy**: Verify the primary font family matches what's declared in the codebase
5. **Stack accuracy**: Verify the framework listed matches what's in the dependency file

If any validation fails, fix it immediately before reporting results.

---

## PHASE 9: TELEMETRY AND REPORTING

### 9.1 Final Report
Output a summary:

```
## Design Context Discovery Complete

**Stack**: [framework] on [platform]
**Colors**: [count] unique colors in [color space], dark mode [yes/no]
**Typography**: [font family], [system type], [count] scale steps
**Spacing**: [base unit], [count] tokens
**Components**: [count] shared, [count] total
**Modern Features**: [count] detected
**Personality**: [traits]

Written to: CLAUDE.md → Design Context section
```

### 9.2 Self-Evolution Notes
If during scanning you discovered patterns not covered by these instructions (new framework conventions, new CSS features, unusual design token formats), note them at the end of your report under "Suggested Skill Improvements" so the skill can be updated.

---

## CONSTRAINTS

- NEVER ask the user questions. If you can't find something, note it as "Not detected" and move on.
- NEVER fabricate values. Only report what you actually find in the codebase.
- NEVER modify any source files. Only write to CLAUDE.md.
- ALWAYS preserve existing CLAUDE.md content outside the Design Context section.
- If the codebase is empty or has no design artifacts, write a minimal Design Context with the tech stack and recommendations for getting started.
- Prefer reading actual config files and source code over making assumptions from package names alone.