/design-system-setup

description: "Initialize a design system with tokens"
argument-hint: "[--preset minimal|standard|comprehensive]"

Design System Setup

Initialize a design system with design tokens, component patterns, and documentation. Creates a foundation for consistent UI development.

Pre-flight Checks

1. Check if `.ui-design/` directory exists:

• If exists with `design-system.json`: Ask to update or reinitialize
• If not: Create `.ui-design/` directory

2. Detect existing design system indicators:

• Check for `tailwind.config.js` with custom theme
• Check for CSS custom properties in global styles
• Check for existing token files (tokens.json, theme.ts, etc.)
• Check for design system packages (chakra, radix, shadcn, etc.)

3. Load project context:

• Read `conductor/tech-stack.md` if exists
• Detect styling approach (CSS, Tailwind, styled-components, etc.)
• Detect TypeScript usage

4. If existing design system detected:

   I detected an existing design system configuration:

   - {detected_system}

   Would you like to:
   1. Integrate with existing system (add missing tokens)
   2. Replace with new design system
   3. View current configuration
   4. Cancel

   Enter number:

Interactive Configuration

**CRITICAL RULES:**

• Ask ONE question per turn
• Wait for user response before proceeding
• Build complete specification before generating files

Q1: Design System Preset (if not provided)

What level of design system do you need?

1. Minimal   - Colors, typography, spacing only
               Best for: Small projects, rapid prototyping

2. Standard  - Colors, typography, spacing, shadows, borders, breakpoints
               Best for: Most projects, good balance of flexibility

3. Comprehensive - Full token system with semantic naming, component tokens,
                   animation, and documentation
               Best for: Large projects, design teams, long-term maintenance

Enter number:

Q2: Brand Colors

Let's define your brand colors.

Enter your primary brand color (hex code, e.g., #3B82F6):

After receiving primary:

Primary color: {color}

Now enter your secondary/accent color (or press enter to auto-generate):

Q3: Color Mode Support

What color modes should the design system support?

1. Light mode only
2. Dark mode only
3. Light and dark modes
4. Light, dark, and system preference

Enter number:

Q4: Typography

What font family should be used?

1. System fonts (fastest loading, native feel)
   font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', ...

2. Inter (modern, highly readable)
3. Open Sans (friendly, versatile)
4. Roboto (clean, Google standard)
5. Custom (provide name)

Enter number or font name:

Q5: Spacing Scale

What spacing scale philosophy?

1. Linear (4px base)
   4, 8, 12, 16, 20, 24, 32, 40, 48, 64

2. Geometric (4px base, 1.5x multiplier)
   4, 6, 9, 14, 21, 32, 48, 72

3. Tailwind-compatible
   0, 1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64

4. Custom (provide values)

Enter number:

Q6: Border Radius

What corner radius style?

1. Sharp    - 0px (no rounding)
2. Subtle   - 4px (slight rounding)
3. Moderate - 8px (noticeable rounding)
4. Rounded  - 12px (significant rounding)
5. Pill     - 9999px for buttons, 16px for cards

Enter number:

Q7: Output Format

How should the design tokens be output?

1. CSS Custom Properties (works everywhere)
2. Tailwind config (tailwind.config.js extension)
3. JavaScript/TypeScript module
4. JSON tokens (Design Token Community Group format)
5. Multiple formats (all of the above)

Enter number:

Q8: Component Guidelines (Comprehensive only)

If comprehensive preset selected:

Should I generate component design guidelines?

These include:
- Button variants and states
- Form input patterns
- Card/container patterns
- Typography hierarchy
- Icon usage guidelines

1. Yes, generate all guidelines
2. Yes, but let me select which ones
3. No, tokens only

Enter number:

State Management

Create `.ui-design/setup_state.json`:

{
  "status": "in_progress",
  "preset": "standard",
  "colors": {
    "primary": "#3B82F6",
    "secondary": "#8B5CF6"
  },
  "color_modes": ["light", "dark"],
  "typography": {
    "family": "Inter",
    "scale": "1.25"
  },
  "spacing": "linear",
  "radius": "moderate",
  "output_formats": ["css", "tailwind"],
  "current_step": 1,
  "started_at": "ISO_TIMESTAMP"
}

Token Generation

1. Generate Color Palette

From primary and secondary colors, generate:

{
  "colors": {
    "primary": {
      "50": "#EFF6FF",
      "100": "#DBEAFE",
      "200": "#BFDBFE",
      "300": "#93C5FD",
      "400": "#60A5FA",
      "500": "#3B82F6",
      "600": "#2563EB",
      "700": "#1D4ED8",
      "800": "#1E40AF",
      "900": "#1E3A8A",
      "950": "#172554"
    },
    "secondary": { ... },
    "neutral": {
      "50": "#F9FAFB",
      "100": "#F3F4F6",
      "200": "#E5E7EB",
      "300": "#D1D5DB",
      "400": "#9CA3AF",
      "500": "#6B7280",
      "600": "#4B5563",
      "700": "#374151",
      "800": "#1F2937",
      "900": "#111827",
      "950": "#030712"
    },
    "semantic": {
      "success": "#22C55E",
      "warning": "#F59E0B",
      "error": "#EF4444",
      "info": "#3B82F6"
    }
  }
}

2. Generate Typography Scale

{
  "typography": {
    "fontFamily": {
      "sans": "Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
      "mono": "ui-monospace, 'Fira Code', monospace"
    },
    "fontSize": {
      "xs": "0.75rem",
      "sm": "0.875rem",
      "base": "1rem",
      "lg": "1.125rem",
      "xl": "1.25rem",
      "2xl": "1.5rem",
      "3xl": "1.875rem",
      "4xl": "2.25rem",
      "5xl": "3rem"
    },
    "fontWeight": {
      "normal": "400",
      "medium": "500",
      "semibold": "600",
      "bold": "700"
    },
    "lineHeight": {
      "tight": "1.25",
      "normal":