design-foundation

What this skill does

# Design Foundation

## Overview

A design foundation is the bedrock upon which all great products are built. It's not just a collection of colors and fonts—it's a system of decisions that enables your team to build consistently, quickly, and with intention.

This skill helps you create or formalize your design foundation, whether you're starting from scratch or documenting what already exists. It covers design tokens, component structure, design principles documentation, and the governance model for your system.

## Core Methodology: Token-Based Design Systems

Modern design systems are built on the concept of **design tokens**—named entities that store design decisions. Rather than hardcoding colors or spacing values throughout your codebase, tokens centralize these decisions, making them easy to maintain, theme, and scale.

### The Token Hierarchy

Design tokens are organized in layers, from most abstract to most concrete:

**Layer 1: Global Tokens (The Foundation)**
These are your base design decisions—the raw materials of your system.

```
Global Tokens:
├── Colors
│   ├── Primary: #3B82F6
│   ├── Secondary: #8B5CF6
│   ├── Success: #10B981
│   ├── Warning: #F59E0B
│   ├── Error: #EF4444
│   ├── Neutral-50: #F9FAFB
│   ├── Neutral-100: #F3F4F6
│   └── ... (up to Neutral-950)
├── Typography
│   ├── Font-Family-Base: Inter, system-ui, sans-serif
│   ├── Font-Size-Base: 16px
│   ├── Line-Height-Base: 1.5
│   └── Font-Weight: (300, 400, 500, 600, 700, 800)
├── Spacing
│   ├── Space-0: 0
│   ├── Space-1: 0.25rem (4px)
│   ├── Space-2: 0.5rem (8px)
│   ├── Space-3: 0.75rem (12px)
│   └── ... (up to Space-12+)
├── Shadows
│   ├── Shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05)
│   ├── Shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1)
│   └── ...
└── Border Radius
    ├── Radius-sm: 0.25rem (4px)
    ├── Radius-md: 0.375rem (6px)
    ├── Radius-lg: 0.5rem (8px)
    └── ...
```

**Layer 2: Semantic Tokens (The Meaning)**
These tokens assign meaning to global tokens based on context and usage.

```
Semantic Tokens:
├── Colors
│   ├── Background-Primary: {Global.Neutral-50}
│   ├── Background-Secondary: {Global.Neutral-100}
│   ├── Text-Primary: {Global.Neutral-950}
│   ├── Text-Secondary: {Global.Neutral-600}
│   ├── Border-Primary: {Global.Neutral-200}
│   ├── Interactive-Primary: {Global.Primary}
│   ├── Interactive-Hover: {Global.Primary-600}
│   ├── Interactive-Active: {Global.Primary-700}
│   ├── State-Success: {Global.Success}
│   ├── State-Warning: {Global.Warning}
│   └── State-Error: {Global.Error}
├── Typography
│   ├── Heading-1: (Font-Size: 32px, Line-Height: 1.2, Font-Weight: 700)
│   ├── Heading-2: (Font-Size: 24px, Line-Height: 1.3, Font-Weight: 600)
│   ├── Body-Large: (Font-Size: 18px, Line-Height: 1.5, Font-Weight: 400)
│   ├── Body-Regular: (Font-Size: 16px, Line-Height: 1.5, Font-Weight: 400)
│   ├── Body-Small: (Font-Size: 14px, Line-Height: 1.5, Font-Weight: 400)
│   └── Caption: (Font-Size: 12px, Line-Height: 1.4, Font-Weight: 500)
├── Spacing
│   ├── Padding-Component: {Global.Space-4}
│   ├── Padding-Section: {Global.Space-8}
│   ├── Margin-Component: {Global.Space-3}
│   └── Gap-Component: {Global.Space-4}
└── Shadows
    ├── Elevation-1: {Global.Shadow-sm}
    ├── Elevation-2: {Global.Shadow-md}
    └── Elevation-3: {Global.Shadow-lg}
```

**Layer 3: Component Tokens (The Application)**
These tokens are specific to individual components and use semantic tokens as their values.

```
Component Tokens:
├── Button
│   ├── Button-Primary-Background: {Semantic.Interactive-Primary}
│   ├── Button-Primary-Background-Hover: {Semantic.Interactive-Hover}
│   ├── Button-Primary-Text: {Semantic.Text-Inverse}
│   ├── Button-Padding: {Semantic.Padding-Component}
│   └── Button-Border-Radius: {Global.Radius-md}
├── Card
│   ├── Card-Background: {Semantic.Background-Primary}
│   ├── Card-Border: {Semantic.Border-Primary}
│   ├── Card-Padding: {Semantic.Padding-Component}
│   ├── Card-Border-Radius: {Global.Radius-lg}
│   └── Card-Shadow: {Semantic.Elevation-1}
└── Input
    ├── Input-Background: {Semantic.Background-Primary}
    ├── Input-Border: {Semantic.Border-Primary}
    ├── Input-Border-Hover: {Semantic.Border-Secondary}
    ├── Input-Text: {Semantic.Text-Primary}
    ├── Input-Padding: {Semantic.Padding-Component}
    └── Input-Border-Radius: {Global.Radius-md}
```

### Implementing Tokens with Tailwind CSS

Tailwind CSS is designed around the concept of tokens. Your `tailwind.config.js` file is essentially your token system:

```javascript
module.exports = {
  theme: {
    // Global Tokens
    colors: {
      primary: {
        50: '#EFF6FF',
        100: '#DBEAFE',
        500: '#3B82F6',
        600: '#2563EB',
        700: '#1D4ED8',
        950: '#0C2340',
      },
      secondary: {
        50: '#F3E8FF',
        500: '#8B5CF6',
        600: '#7C3AED',
        950: '#2E1065',
      },
      success: '#10B981',
      warning: '#F59E0B',
      error: '#EF4444',
      neutral: {
        50: '#F9FAFB',
        100: '#F3F4F6',
        600: '#4B5563',
        950: '#030712',
      },
    },
    // Semantic Tokens (via CSS variables or custom utilities)
    extend: {
      backgroundColor: {
        'bg-primary': 'var(--color-bg-primary)',
        'bg-secondary': 'var(--color-bg-secondary)',
      },
      textColor: {
        'text-primary': 'var(--color-text-primary)',
        'text-secondary': 'var(--color-text-secondary)',
      },
      spacing: {
        'component': 'var(--space-component)',
        'section': 'var(--space-section)',
      },
    },
  },
};
```

## Design System Audit: What to Document

When formalizing your design foundation, audit and document these elements:

### 1. Design Principles
These are the "why" behind your design decisions. They guide all future work.

**Example Design Principles:**
- **Clarity First** — Every element should communicate its purpose clearly. Remove ambiguity.
- **Consistency Builds Trust** — Patterns should be predictable. Users should recognize patterns across the product.
- **Accessibility is Foundational** — Design for all users, including those with disabilities. Accessibility is not a feature; it's a requirement.
- **Simplicity Through Reduction** — Remove everything that doesn't serve the user's goal. Simplicity is the result of careful reduction.
- **Intentionality Matters** — Every decision should have a reason. Avoid arbitrary choices.
- **Performance is Part of Design** — A beautiful interface that's slow is not good design. Speed matters.

### 2. Color System
Document your color palette, including:
- Primary, secondary, and accent colors
- Neutral/grayscale colors (for text, backgrounds, borders)
- Semantic colors (success, warning, error, info)
- Color usage guidelines (when to use which color)
- Contrast ratios for accessibility (WCAG AA or AAA)
- Dark mode variants (if applicable)

**Audit Questions:**
- How many colors are actually used in your product?
- Are colors used consistently?
- Do all color combinations meet WCAG AA contrast requirements?
- Do you have a dark mode? If so, are tokens defined for it?

### 3. Typography System
Document your typography, including:
- Font families (primary, secondary, monospace)
- Font sizes (and the logic behind them—e.g., modular scale)
- Font weights and their usage
- Line heights and letter spacing
- Type scales for different contexts (headings, body, captions)

**Audit Questions:**
- How many different font sizes are used?
- Is there a logical progression (e.g., 12px, 14px, 16px, 18px, 20px, 24px, 32px)?
- Are font weights used consistently?
- Is line height appropriate for readability?

### 4. Spacing System
Document your spacing, including:
- Base unit (e.g., 4px, 8px)
- Spacing scale (e.g., 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)
- Padding conventions (inside components)
- Margin conventions (between components)
- Gap conventions (between grid items, flex items)

**Audit Questions:**
- How many different spacing values are used?