# Complete Design System Guide

Bangstack provides a comprehensive design system with full color palettes, typography scales, and per-component styling - similar to Tailwind/Radix/Shadcn.

## Philosophy

**Start with a complete design system**, not minimal colors. This gives you:
- Full color palette (all colors with shades 50-950)
- Complete typography scale (h1-h6, body, small)
- Per-component styling (radius, padding, shadows)
- Icon library integration
- Maximum flexibility from day one

---

## Color System

### Semantic Colors

Map semantic meanings to your color palette:

```yaml
design:
  theme:
    colors:
      # Brand/Identity
      brand: "blue-600"       # Your brand color
      primary: "blue-600"     # Primary actions (buttons, links)
      secondary: "purple-600" # Secondary elements
      accent: "pink-500"      # Accents and highlights

      # Status colors
      success: "green-600"
      warning: "amber-600"
      error: "red-600"
      info: "sky-600"

      # Neutral/Layout
      background: "gray-50"         # Page background
      foreground: "gray-950"        # Primary text
      muted: "gray-100"             # Muted backgrounds
      muted_foreground: "gray-500"  # Muted text
```

### Full Color Palette

Include complete color scales (Tailwind/Radix style):

```yaml
design:
  theme:
    colors:
      # ... semantic colors above

      palette:
        # Gray scale (essential)
        gray:
          50: "#F9FAFB"
          100: "#F3F4F6"
          200: "#E5E7EB"
          300: "#D1D5DB"
          400: "#9CA3AF"
          500: "#6B7280"   # Base
          600: "#4B5563"
          700: "#374151"
          800: "#1F2937"
          900: "#111827"
          950: "#030712"

        # Blue scale
        blue:
          50: "#EFF6FF"
          100: "#DBEAFE"
          200: "#BFDBFE"
          300: "#93C5FD"
          400: "#60A5FA"
          500: "#3B82F6"   # Base
          600: "#2563EB"
          700: "#1D4ED8"
          800: "#1E40AF"
          900: "#1E3A8A"
          950: "#172554"

        # Green scale
        green:
          50: "#F0FDF4"
          100: "#DCFCE7"
          200: "#BBF7D0"
          300: "#86EFAC"
          400: "#4ADE80"
          500: "#22C55E"   # Base
          600: "#16A34A"
          700: "#15803D"
          800: "#166534"
          900: "#14532D"
          950: "#052E16"

        # Red scale
        red:
          50: "#FEF2F2"
          100: "#FEE2E2"
          200: "#FECACA"
          300: "#FCA5A5"
          400: "#F87171"
          500: "#EF4444"   # Base
          600: "#DC2626"
          700: "#B91C1C"
          800: "#991B1B"
          900: "#7F1D1D"
          950: "#450A0A"

        # Amber scale (warning)
        amber:
          50: "#FFFBEB"
          100: "#FEF3C7"
          200: "#FDE68A"
          300: "#FCD34D"
          400: "#FBBF24"
          500: "#F59E0B"   # Base
          600: "#D97706"
          700: "#B45309"
          800: "#92400E"
          900: "#78350F"
          950: "#451A03"

        # ... all other colors (orange, yellow, lime, emerald, teal,
        #     cyan, sky, indigo, violet, purple, fuchsia, pink, rose)
```

### Usage in Components

```tsx
// Generated CSS variables
:root {
  --color-brand: #2563EB;
  --color-primary: #2563EB;
  --color-success: #16A34A;
  --color-error: #DC2626;

  --color-gray-50: #F9FAFB;
  --color-gray-100: #F3F4F6;
  // ... all shades

  --color-blue-50: #EFF6FF;
  // ... all shades
}

// Use in components
<button className="bg-primary text-white hover:bg-blue-700">
  Click me
</button>

<div className="bg-gray-100 text-gray-900">
  Muted background
</div>

<span className="text-success">Success message</span>
```

---

## Typography System

### Complete Type Scale

Define all heading and text styles:

```yaml
design:
  theme:
    typography:
      font_family: "Inter, system-ui, sans-serif"
      heading_font: "Inter"  # Can use different font for headings
      mono_font: "JetBrains Mono, monospace"  # For code

      scale:
        h1:
          size: "3.75rem"    # 60px
          weight: "800"
          line_height: "1"
          letter_spacing: "-0.025em"

        h2:
          size: "3rem"       # 48px
          weight: "700"
          line_height: "1.1"
          letter_spacing: "-0.025em"

        h3:
          size: "2.25rem"    # 36px
          weight: "600"
          line_height: "1.2"

        h4:
          size: "1.875rem"   # 30px
          weight: "600"
          line_height: "1.3"

        h5:
          size: "1.5rem"     # 24px
          weight: "600"
          line_height: "1.4"

        h6:
          size: "1.25rem"    # 20px
          weight: "600"
          line_height: "1.4"

        body:
          size: "1rem"       # 16px
          weight: "400"
          line_height: "1.5"

        body_bold:
          size: "1rem"
          weight: "600"
          line_height: "1.5"

        small:
          size: "0.875rem"   # 14px
          weight: "400"
          line_height: "1.4"

        # Custom variants
        custom:
          caption:
            size: "0.75rem"  # 12px
            weight: "500"
            line_height: "1.3"

          lead:
            size: "1.25rem"  # 20px
            weight: "400"
            line_height: "1.6"

          code:
            size: "0.875rem"
            weight: "500"
            line_height: "1.5"
```

### Generated CSS

```css
h1 {
  font-family: Inter, system-ui, sans-serif;
  font-size: 3.75rem;
  font-weight: 800;
  line-height: 1;
  letter-spacing: -0.025em;
}

.body-text {
  font-family: Inter, system-ui, sans-serif;
  font-size: 1rem;
  font-weight: 400;
  line-height: 1.5;
}

.caption {
  font-size: 0.75rem;
  font-weight: 500;
  line-height: 1.3;
}
```

---

## Spacing, Radius, and Shadows

### Spacing Scale

```yaml
design:
  theme:
    spacing:
      xs: "4px"
      sm: "8px"
      md: "16px"
      lg: "24px"
      xl: "32px"
      custom:
        xxl: "48px"
        jumbo: "96px"
```

### Border Radius Scale

```yaml
design:
  theme:
    radius:
      none: "0"
      sm: "4px"
      md: "8px"
      lg: "12px"
      xl: "16px"
      full: "9999px"
```

### Shadow Scale

```yaml
design:
  theme:
    shadows:
      sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)"
      md: "0 4px 6px -1px rgb(0 0 0 / 0.1)"
      lg: "0 10px 15px -3px rgb(0 0 0 / 0.1)"
      xl: "0 20px 25px -5px rgb(0 0 0 / 0.1)"
      custom:
        inner: "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)"
```

---

## Per-Component Styling

Override styles for specific components:

```yaml
design:
  theme:
    # Global defaults
    radius:
      md: "8px"

    # Per-component overrides
    components:
      button:
        radius: "full"       # Fully rounded buttons
        padding: "12px 24px"
        shadow: "md"

      card:
        radius: "lg"         # More rounded cards
        padding: "24px"
        shadow: "lg"
        border: "1px solid"
        custom:
          border_color: "gray-200"

      input:
        radius: "md"
        padding: "8px 12px"
        border: "1px solid"
        custom:
          border_color: "gray-300"
          focus_border_color: "blue-500"

      badge:
        radius: "full"
        padding: "4px 12px"
        custom:
          font_size: "0.75rem"
          font_weight: "600"
```

### Generated Component Styles

```tsx
// Button component
<button className="rounded-full px-6 py-3 shadow-md">
  Click me
</button>

// Card component
<div className="rounded-lg p-6 shadow-lg border border-gray-200">
  Card content
</div>

// Input component
<input className="rounded-md px-3 py-2 border border-gray-300 focus:border-blue-500" />
```

---

## Icon Library

Choose from popular icon libraries or use custom:

```yaml
design:
  theme:
    icons:
      library: lucide  # lucide, heroicons, feather, phosphor, tabler, custom
```

### Supported Libraries

**Lucide** (recommended)
```tsx
import { Check, X, ChevronRight } from 'lucide-react';

<Check className="w-4 h-4 text-success" />
```

**Heroicons**
```tsx
import { CheckIcon, XMarkIcon } from '@heroicons/react/24/outline';
```

**Custom Icons**
```yaml
icons:
  library: custom
  custom_path: "./src/icons"  # Path to your icon components
```

---

## Complete Example

```yaml
design:
  theme:
    colors:
      # Semantic colors
      brand: "blue-600"
      primary: "blue-600"
      success: "green-600"
      warning: "amber-600"
      error: "red-600"
      background: "gray-50"
      foreground: "gray-950"

      # Full palette (Tailwind colors)
      palette:
        gray: { 50: "#F9FAFB", 100: "#F3F4F6", ... }
        blue: { 50: "#EFF6FF", 100: "#DBEAFE", ... }
        green: { 50: "#F0FDF4", 100: "#DCFCE7", ... }
        red: { 50: "#FEF2F2", 100: "#FEE2E2", ... }
        amber: { 50: "#FFFBEB", 100: "#FEF3C7", ... }
        # ... all other colors

    typography:
      font_family: "Inter, system-ui, sans-serif"
      heading_font: "Inter"
      mono_font: "JetBrains Mono, monospace"
      scale:
        h1: { size: "3.75rem", weight: "800", line_height: "1" }
        h2: { size: "3rem", weight: "700", line_height: "1.1" }
        h3: { size: "2.25rem", weight: "600", line_height: "1.2" }
        h4: { size: "1.875rem", weight: "600", line_height: "1.3" }
        h5: { size: "1.5rem", weight: "600", line_height: "1.4" }
        h6: { size: "1.25rem", weight: "600", line_height: "1.4" }
        body: { size: "1rem", weight: "400", line_height: "1.5" }
        small: { size: "0.875rem", weight: "400", line_height: "1.4" }

    spacing:
      xs: "4px"
      sm: "8px"
      md: "16px"
      lg: "24px"
      xl: "32px"

    radius:
      sm: "4px"
      md: "8px"
      lg: "12px"
      xl: "16px"
      full: "9999px"

    shadows:
      sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)"
      md: "0 4px 6px -1px rgb(0 0 0 / 0.1)"
      lg: "0 10px 15px -3px rgb(0 0 0 / 0.1)"

    components:
      button:
        radius: "full"
        padding: "12px 24px"
        shadow: "md"

      card:
        radius: "lg"
        padding: "24px"
        shadow: "lg"

      input:
        radius: "md"
        padding: "8px 12px"
        custom:
          border_color: "gray-300"

    icons:
      library: lucide

  component_library: "shadcn/ui"  # Optional: Use existing component library
```

---

## Default Color Palette

If palette is not specified, Bangstack uses Tailwind's default color system:

**All colors with shades 50-950**:
- gray, slate, zinc, neutral, stone
- red, orange, amber, yellow, lime, green, emerald, teal, cyan
- sky, blue, indigo, violet, purple, fuchsia, pink, rose

This ensures you **always have a complete color palette** to work with.

---

## Summary

**Complete Design System Features**:
- ✅ Full color palette (all colors, all shades 50-950)
- ✅ Semantic color mapping (brand, primary, success, error)
- ✅ Complete typography scale (h1-h6, body, small, custom)
- ✅ Spacing, radius, and shadow scales
- ✅ Per-component styling overrides
- ✅ Icon library integration
- ✅ Default Tailwind palette if not specified

**No missing colors. Maximum flexibility. Production-ready from day one.**
