design-setup— agent skill

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:

## 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.