Design System

Design System

Establish the foundational design language: tokens, color, typography, spacing, and motion philosophy.

Core principle: One coherent system, applied consistently. Design decisions made once, expressed everywhere.

When to Use

• Starting a new product or major redesign
• Choosing color palette, typography, or spacing system
• Creating design tokens for a codebase
• Writing DESIGN.md to codify design decisions
• Evaluating whether UI is consistent with its design system

When NOT to Use

• Building specific UI components (use ui-components skill)
• Reviewing visual quality of existing UI (use ui-components skill)
• Performance optimization of UI (use frontend-performance skill)

Phase 1: Product Context Assessment

Before proposing a design system, answer:

1. What is the product? — Productivity tool, consumer app, developer tool, marketing site
2. Who is the user? — Enterprise knowledge worker, consumer, developer, creative professional
3. What industry? — Finance (trust, precision), Health (clarity, calm), Creative (expression, energy)
4. What density? — Information-dense dashboard vs. content-first editorial vs. e-commerce

Phase 2: Visual Theme Axes

Rate on three axes to anchor all design decisions:

Design Preset Archetypes

When clients ask for a direction ("make it modern", "premium", "bold"), anchor to one of these named presets:

Phase 3: Color Palette

60-30-10 Color Rule

Every palette must allocate by visual weight:

• 60% dominant neutral — backgrounds, surfaces, containers
• 30% secondary — body text, borders, inactive states, supporting UI
• 10% accent — CTAs, interactive focus, highlights, brand moments

Mandatory Constraints

• Maximum 1 accent color — saturation below 80%
• Absolute neutral bases — Zinc/Slate/Stone (no warm/cool gray fluctuation)
• One palette for the entire product — no per-section themes
• Never pure black (#000000) — use Zinc-950, Off-Black, or Charcoal
• No neon AI aesthetic — purple/indigo gradients, oversaturated accents banned

WCAG 2.1 AA Minimum Contrast

Palette Structure

Neutral scale:   50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
Accent scale:    50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
Semantic roles:  background, foreground, muted, border, primary, error, warning, success

Phase 4: Typography

Font Selection

Prefer distinctive fonts over generic defaults for premium contexts:

• Display/Editorial: Geist, Cabinet Grotesk, Satoshi, Outfit
• UI/Product: Inter, Geist, Plus Jakarta Sans
• Monospace: Geist Mono, JetBrains Mono, Fira Code

Generic fonts (Arial, Helvetica, system-ui` alone) are acceptable only for developer tools or ultra-minimal contexts.

Type Scale

Use consistent increments:

12px — caption, label, badge
14px — body small, helper text
16px — body default (minimum on mobile)
18px — body large, lead text
24px — heading small (h3)
32px — heading medium (h2)
48px — heading large (h1)
64px — display

Use clamp() for responsive scaling:

font-size: clamp(1.5rem, 3vw, 2rem);  /* scales between 24px and 32px */

Typography Rules

Phase 5: Spacing System

• 8pt grid — canonical scale: 0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64px
• Use the 8pt grid as default; 4pt for fine-tuning within components
• Proximity principle: related elements 8-16px apart; section breaks 32-48px; page-level sections 64px+
• CSS Grid over Flexbox calc hacks
• Max-width containment: 1400px centered for content
• Touch targets minimum 44px on mobile

Phase 6: Motion Philosophy

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Phase 7: Design Token Architecture

Three layers — never use raw values in components:

Primitive (raw values):   --color-blue-600: #2563EB
Semantic (purpose):       --color-action-primary: var(--color-blue-600)
Component (specific):     --button-bg: var(--color-action-primary)

Name tokens by role, not color value:

❌  --color-blue-500        (describes the color — breaks when brand changes)
✅  --color-action-primary  (Primary Action color — survives brand pivots)
✅  --color-feedback-error  (Error state — meaningful without knowing it's red)
✅  --color-surface-raised  (Elevated surface — not "white" or "gray-50")

@layer base {
  :root {
    /* Primitives */
    --color-zinc-950: #09090b;
    --color-zinc-50: #fafafa;
    --color-blue-600: #2563eb;

    /* Semantic */
    --background: var(--color-zinc-50);
    --foreground: var(--color-zinc-950);
    --primary: var(--color-blue-600);
    --muted: 210 40% 96.1%;  /* HSL for Tailwind compatibility */
  }

  .dark {
    --background: var(--color-zinc-950);
    --foreground: var(--color-zinc-50);
  }
}

DESIGN.md Output

# Design System: [Project Title]

## 1. Visual Theme & Atmosphere
- Density: X/10 — [description]
- Variance: X/10 — [description]
- Motion: X/10 — [description]

## 2. Color Palette & Roles
- Neutral base: Zinc/Slate/Stone [chosen scale]
- Accent: [color name, hex, usage]
- Semantic roles: background, foreground, primary, muted, error, success, warning

## 3. Typography
- Display: [font name], track-tight
- Body: [font name], 1.6 leading, max 65ch
- Scale: 12/14/16/18/24/32/48px

## 4. Spacing
- System: 4pt base (4/8/12/16/24/32/48/64px)
- Max content width: 1400px

## 5. Motion
- Physics: spring(100, 20)
- Duration: 150-300ms
- Properties: transform + opacity only

## 6. Anti-Patterns (Banned)
- [Specific things that are never allowed in this product]

Verification Checklist

• Max 1 accent color, saturation <80%
• No pure black (#000000) anywhere
• Neutral base consistent (no warm/cool gray mixing)
• WCAG 2.1 AA contrast verified (4.5:1 text, 3:1 UI)
• Type scale uses consistent increments
• Mobile body text ≥16px
• Spacing system documented (4pt grid)
• Motion only uses transform + opacity
• prefers-reduced-motion respected
• Design tokens follow primitive → semantic → component hierarchy
• No raw hex values in component code
• DESIGN.md written and covers all 6 sections