Design System Documentation

System Info

Design Principles

The following principles guide all design decisions in this system:

1. [Principle 1 Name] - [One sentence description. Example: "Clarity over cleverness - every element should have an obvious purpose."]

2. [Principle 2 Name] - [One sentence description. Example: "Consistency breeds confidence - similar actions should look and behave the same."]

3. [Principle 3 Name] - [One sentence description. Example: "Accessible by default - every component must meet WCAG 2.1 AA standards."]

4. [Principle 4 Name] - [One sentence description. Example: "Progressive disclosure - show only what is needed, reveal complexity on demand."]

Color Palette

Brand Colors

Neutral Colors

Semantic Colors

Accessibility

• All text colors must meet WCAG 2.1 AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
• Test with color blindness simulators
• Never use color as the only indicator of state

Typography Scale

Font Family

• Primary: [Font Name] (headings and body)
• Monospace: [Font Name] (code blocks, technical content)
• Fallback Stack: [System font stack]

Type Scale

Spacing System

Base Unit: 4px

Layout Spacing

• Page margin: space-6 (mobile), space-8 (tablet), space-12 (desktop)
• Card padding: space-5
• Form field gap: space-3
• Section gap: space-10

Component Library

Component Status Legend

• Stable - Production ready, fully documented and tested
• Beta - Functional but may change, use with awareness
• Deprecated - Scheduled for removal, migrate to replacement
• Planned - On roadmap, not yet available

Components

Usage Guidelines

Do

• Use components as documented (do not override internal styles)
• Follow the spacing system for consistent layouts
• Test components across supported browsers and screen sizes
• Use semantic colors for their intended purpose
• Reference design tokens instead of hardcoded values

Do Not

• Modify component internals without contributing changes back
• Create one-off components when an existing component fits
• Use brand colors for semantic purposes (error, success)
• Skip accessibility requirements for "internal" tools
• Mix design system versions across a single application

Contribution Process

Proposing a New Component

1. Check existing components - Verify no existing component solves the need
2. Create proposal - Document use case, behavior, variants, accessibility requirements
3. Design review - Present to design system team for feedback
4. Build - Implement component following system patterns
5. Review - Code review + design review + accessibility audit
6. Document - Add to component library with usage guidelines
7. Release - Publish in next minor version

Updating an Existing Component

1. File issue - Describe the change and justification
2. Impact assessment - Identify all instances of current usage
3. Design + develop - Implement change with backward compatibility
4. Migration guide - Document breaking changes if any
5. Release - Publish with changelog entry

Reporting Issues

• File bug reports with reproduction steps and screenshots
• Tag with component name and severity
• Include browser/OS information for rendering issues

Component Architecture Guide

Reference for design system component organization, naming conventions, and documentation patterns.

Table of Contents

• Component Hierarchy
• Naming Conventions
• Component Documentation
• Variant Patterns
• Token Integration

Component Hierarchy

Atomic Design Structure

┌─────────────────────────────────────────────────────────────┐
│                    COMPONENT HIERARCHY                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  TOKENS (Foundation)                                        │
│    └── Colors, Typography, Spacing, Shadows                 │
│                                                             │
│  ATOMS (Basic Elements)                                     │
│    └── Button, Input, Icon, Label, Badge                    │
│                                                             │
│  MOLECULES (Simple Combinations)                            │
│    └── FormField, SearchBar, Card, ListItem                 │
│                                                             │
│  ORGANISMS (Complex Components)                             │
│    └── Header, Footer, DataTable, Modal                     │
│                                                             │
│  TEMPLATES (Page Layouts)                                   │
│    └── DashboardLayout, AuthLayout, SettingsLayout          │
│                                                             │
│  PAGES (Specific Instances)                                 │
│    └── HomePage, LoginPage, UserProfile                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Component Categories

Naming Conventions

Token Naming

{category}-{property}-{variant}-{state}

Examples:
  color-primary-500
  color-primary-500-hover
  spacing-md
  fontSize-lg
  shadow-md
  radius-lg

Component Naming

{ComponentName}             # PascalCase for components
{componentName}{Variant}    # Variant suffix

Examples:
  Button
  ButtonPrimary
  ButtonOutline
  ButtonGhost

CSS Class Naming (BEM)

.block__element--modifier

Examples:
  .button
  .button__icon
  .button--primary
  .button--lg
  .button__icon--loading

File Structure

components/
├── Button/
│   ├── Button.tsx           # Main component
│   ├── Button.styles.ts     # Styles/tokens
│   ├── Button.test.tsx      # Tests
│   ├── Button.stories.tsx   # Storybook
│   ├── Button.types.ts      # TypeScript types
│   └── index.ts             # Export
├── Input/
│   └── ...
└── index.ts                 # Barrel export

Component Documentation

Documentation Template

# ComponentName

Brief description of what this component does.

## Usage

\`\`\`tsx
import { Button } from '@design-system/components'

<Button variant="primary" size="md">
  Click me
</Button>
\`\`\`

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Component size |
| disabled | boolean | false | Disabled state |
| onClick | () => void | - | Click handler |

## Variants

### Primary
Use for main actions.

### Secondary
Use for secondary actions.

### Ghost
Use for tertiary or inline actions.

## Accessibility

- Uses `button` role by default
- Supports `aria-disabled` for disabled state
- Focus ring visible for keyboard navigation

## Design Tokens Used

- `color-primary-*` for primary variant
- `spacing-*` for padding
- `radius-md` for border radius
- `shadow-sm` for elevation

Props Interface Pattern

interface ButtonProps {
  /** Visual variant of the button */
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';

  /** Size of the button */
  size?: 'sm' | 'md' | 'lg';

  /** Whether button is disabled */
  disabled?: boolean;

  /** Whether button shows loading state */
  loading?: boolean;

  /** Left icon element */
  leftIcon?: React.ReactNode;

  /** Right icon element */
  rightIcon?: React.ReactNode;

  /** Click handler */
  onClick?: () => void;

  /** Button content */
  children: React.ReactNode;
}

Variant Patterns

Size Variants

const sizeTokens = {
  sm: {
    height: 'sizing-button-sm-height',    // 32px
    paddingX: 'sizing-button-sm-paddingX', // 12px
    fontSize: 'fontSize-sm',               // 14px
    iconSize: 'sizing-icon-sm'             // 16px
  },
  md: {
    height: 'sizing-button-md-height',    // 40px
    paddingX: 'sizing-button-md-paddingX', // 16px
    fontSize: 'fontSize-base',             // 16px
    iconSize: 'sizing-icon-md'             // 20px
  },
  lg: {
    height: 'sizing-button-lg-height',    // 48px
    paddingX: 'sizing-button-lg-paddingX', // 20px
    fontSize: 'fontSize-lg',               // 18px
    iconSize: 'sizing-icon-lg'             // 24px
  }
};

Color Variants

const variantTokens = {
  primary: {
    background: 'color-primary-500',
    backgroundHover: 'color-primary-600',
    backgroundActive: 'color-primary-700',
    text: 'color-white',
    border: 'transparent'
  },
  secondary: {
    background: 'color-neutral-100',
    backgroundHover: 'color-neutral-200',
    backgroundActive: 'color-neutral-300',
    text: 'color-neutral-900',
    border: 'transparent'
  },
  outline: {
    background: 'transparent',
    backgroundHover: 'color-primary-50',
    backgroundActive: 'color-primary-100',
    text: 'color-primary-500',
    border: 'color-primary-500'
  },
  ghost: {
    background: 'transparent',
    backgroundHover: 'color-neutral-100',
    backgroundActive: 'color-neutral-200',
    text: 'color-neutral-700',
    border: 'transparent'
  }
};

State Variants

const stateStyles = {
  default: {
    cursor: 'pointer',
    opacity: 1
  },
  hover: {
    // Uses variantTokens backgroundHover
  },
  active: {
    // Uses variantTokens backgroundActive
    transform: 'scale(0.98)'
  },
  focus: {
    outline: 'none',
    boxShadow: '0 0 0 2px color-primary-200'
  },
  disabled: {
    cursor: 'not-allowed',
    opacity: 0.5,
    pointerEvents: 'none'
  },
  loading: {
    cursor: 'wait',
    pointerEvents: 'none'
  }
};

Token Integration

Consuming Tokens in Components

CSS Custom Properties:

.button {
  height: var(--sizing-button-md-height);
  padding-left: var(--sizing-button-md-paddingX);
  padding-right: var(--sizing-button-md-paddingX);
  font-size: var(--typography-fontSize-base);
  border-radius: var(--borders-radius-md);
}

.button--primary {
  background-color: var(--colors-primary-500);
  color: var(--colors-surface-background);
}

.button--primary:hover {
  background-color: var(--colors-primary-600);
}

JavaScript/TypeScript:

import tokens from './design-tokens.json';

const buttonStyles = {
  height: tokens.sizing.components.button.md.height,
  paddingLeft: tokens.sizing.components.button.md.paddingX,
  backgroundColor: tokens.colors.primary['500'],
  borderRadius: tokens.borders.radius.md
};

Styled Components:

import styled from 'styled-components';

const Button = styled.button`
  height: ${({ theme }) => theme.sizing.components.button.md.height};
  padding: 0 ${({ theme }) => theme.sizing.components.button.md.paddingX};
  background: ${({ theme }) => theme.colors.primary['500']};
  border-radius: ${({ theme }) => theme.borders.radius.md};

  &:hover {
    background: ${({ theme }) => theme.colors.primary['600']};
  }
`;

Token-to-Component Mapping

Component Checklist

Before Release

• All sizes implemented (sm, md, lg)
• All variants implemented (primary, secondary, etc.)
• All states working (hover, active, focus, disabled)
• Keyboard accessible
• Screen reader tested
• Uses only design tokens (no hardcoded values)
• TypeScript types complete
• Storybook stories for all variants
• Unit tests passing
• Documentation complete

Accessibility Checklist

• Correct semantic HTML element
• ARIA attributes where needed
• Visible focus indicator
• Color contrast meets AA
• Works with keyboard only
• Screen reader announces correctly
• Touch target ≥ 44×44px

See also: token-generation.md for token creation

Developer Handoff Guide

Reference for integrating design tokens into development workflows and design tool collaboration.

Table of Contents

• Export Formats
• Integration Patterns
• Framework Setup
• Design Tool Integration
• Handoff Checklist

Export Formats

JSON (Recommended for Most Projects)

File: design-tokens.json

{
  "meta": {
    "version": "1.0.0",
    "style": "modern",
    "generated": "2024-01-15"
  },
  "colors": {
    "primary": {
      "50": "#E6F2FF",
      "100": "#CCE5FF",
      "500": "#0066CC",
      "900": "#002855"
    }
  },
  "typography": {
    "fontFamily": {
      "sans": "Inter, system-ui, sans-serif",
      "mono": "Fira Code, monospace"
    },
    "fontSize": {
      "xs": "10px",
      "sm": "13px",
      "base": "16px",
      "lg": "20px"
    }
  },
  "spacing": {
    "0": "0px",
    "1": "4px",
    "2": "8px",
    "4": "16px"
  }
}

Use Case: JavaScript/TypeScript projects, build tools, Figma plugins

CSS Custom Properties

File: design-tokens.css

:root {
  /* Colors */
  --color-primary-50: #E6F2FF;
  --color-primary-100: #CCE5FF;
  --color-primary-500: #0066CC;
  --color-primary-900: #002855;

  /* Typography */
  --font-family-sans: Inter, system-ui, sans-serif;
  --font-family-mono: Fira Code, monospace;
  --font-size-xs: 10px;
  --font-size-sm: 13px;
  --font-size-base: 16px;
  --font-size-lg: 20px;

  /* Spacing */
  --spacing-0: 0px;
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-4: 16px;
}

Use Case: Plain CSS, CSS-in-JS, any web project

SCSS Variables

File: _design-tokens.scss

// Colors
$color-primary-50: #E6F2FF;
$color-primary-100: #CCE5FF;
$color-primary-500: #0066CC;
$color-primary-900: #002855;

// Typography
$font-family-sans: Inter, system-ui, sans-serif;
$font-family-mono: Fira Code, monospace;
$font-size-xs: 10px;
$font-size-sm: 13px;
$font-size-base: 16px;
$font-size-lg: 20px;

// Spacing
$spacing-0: 0px;
$spacing-1: 4px;
$spacing-2: 8px;
$spacing-4: 16px;

// Maps for programmatic access
$colors-primary: (
  '50': $color-primary-50,
  '100': $color-primary-100,
  '500': $color-primary-500,
  '900': $color-primary-900
);

Use Case: SASS/SCSS pipelines, component libraries

Integration Patterns

Pattern 1: CSS Variables (Universal)

Works with any framework or vanilla CSS.

/* Import tokens */
@import 'design-tokens.css';

/* Use in styles */
.button {
  background-color: var(--color-primary-500);
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  border-radius: var(--radius-md);
}

.button:hover {
  background-color: var(--color-primary-600);
}

Pattern 2: JavaScript Theme Object

For CSS-in-JS libraries (styled-components, Emotion, etc.)

// theme.ts
import tokens from './design-tokens.json';

export const theme = {
  colors: {
    primary: tokens.colors.primary,
    secondary: tokens.colors.secondary,
    neutral: tokens.colors.neutral,
    semantic: tokens.colors.semantic
  },
  typography: {
    fontFamily: tokens.typography.fontFamily,
    fontSize: tokens.typography.fontSize,
    fontWeight: tokens.typography.fontWeight
  },
  spacing: tokens.spacing,
  shadows: tokens.shadows,
  radii: tokens.borders.radius
};

export type Theme = typeof theme;

// styled-components usage
import styled from 'styled-components';

const Button = styled.button`
  background: ${({ theme }) => theme.colors.primary['500']};
  padding: ${({ theme }) => theme.spacing['2']} ${({ theme }) => theme.spacing['4']};
  font-size: ${({ theme }) => theme.typography.fontSize.base};
`;

Pattern 3: Tailwind Config

// tailwind.config.js
const tokens = require('./design-tokens.json');

module.exports = {
  theme: {
    colors: {
      primary: tokens.colors.primary,
      secondary: tokens.colors.secondary,
      neutral: tokens.colors.neutral,
      success: tokens.colors.semantic.success,
      warning: tokens.colors.semantic.warning,
      error: tokens.colors.semantic.error
    },
    fontFamily: {
      sans: [tokens.typography.fontFamily.sans],
      serif: [tokens.typography.fontFamily.serif],
      mono: [tokens.typography.fontFamily.mono]
    },
    spacing: {
      0: tokens.spacing['0'],
      1: tokens.spacing['1'],
      2: tokens.spacing['2'],
      // ... etc
    },
    borderRadius: tokens.borders.radius,
    boxShadow: tokens.shadows
  }
};

Framework Setup

React + CSS Variables

// App.tsx
import './design-tokens.css';
import './styles.css';

function App() {
  return (
    <button className="btn btn-primary">
      Click me
    </button>
  );
}

/* styles.css */
.btn {
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  font-weight: var(--font-weight-medium);
  border-radius: var(--radius-md);
  transition: background-color var(--animation-duration-fast);
}

.btn-primary {
  background: var(--color-primary-500);
  color: var(--color-surface-background);
}

.btn-primary:hover {
  background: var(--color-primary-600);
}

React + styled-components

// ThemeProvider.tsx
import { ThemeProvider } from 'styled-components';
import { theme } from './theme';

export function AppThemeProvider({ children }) {
  return (
    <ThemeProvider theme={theme}>
      {children}
    </ThemeProvider>
  );
}

// Button.tsx
import styled from 'styled-components';

export const Button = styled.button<{ variant?: 'primary' | 'secondary' }>`
  padding: ${({ theme }) => `${theme.spacing['2']} ${theme.spacing['4']}`};
  font-size: ${({ theme }) => theme.typography.fontSize.base};
  border-radius: ${({ theme }) => theme.radii.md};

  ${({ variant = 'primary', theme }) => variant === 'primary' && `
    background: ${theme.colors.primary['500']};
    color: ${theme.colors.surface.background};

    &:hover {
      background: ${theme.colors.primary['600']};
    }
  `}
`;

Vue + CSS Variables

<!-- App.vue -->
<template>
  <button class="btn btn-primary">Click me</button>
</template>

<style>
@import './design-tokens.css';

.btn {
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  border-radius: var(--radius-md);
}

.btn-primary {
  background: var(--color-primary-500);
  color: var(--color-surface-background);
}
</style>

Next.js + Tailwind

// tailwind.config.js
const tokens = require('./design-tokens.json');

module.exports = {
  content: ['./app/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: tokens.colors,
      fontFamily: {
        sans: tokens.typography.fontFamily.sans.split(', ')
      }
    }
  }
};

// page.tsx
export default function Page() {
  return (
    <button className="bg-primary-500 hover:bg-primary-600 px-4 py-2 rounded-md text-white">
      Click me
    </button>
  );
}

Design Tool Integration

Figma

Option 1: Tokens Studio Plugin

1. Install "Tokens Studio for Figma" plugin
2. Import design-tokens.json
3. Tokens sync automatically with Figma styles

Option 2: Figma Variables (Native)

1. Open Variables panel
2. Create collections matching token structure
3. Import JSON via plugin or API

Sync Workflow:

design_token_generator.py
        ↓
design-tokens.json
        ↓
Tokens Studio Plugin
        ↓
Figma Styles & Variables

Storybook

// .storybook/preview.js
import '../design-tokens.css';

export const parameters = {
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#FFFFFF' },
      { name: 'dark', value: '#111827' }
    ]
  }
};

// Button.stories.tsx
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost']
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg']
    }
  }
};

export const Primary = {
  args: {
    variant: 'primary',
    children: 'Button'
  }
};

Design Tool Comparison

Handoff Checklist

Token Generation

• Brand color defined
• Style selected (modern/classic/playful)
• Tokens generated: python scripts/design_token_generator.py "#0066CC" modern
• All formats exported (JSON, CSS, SCSS)

Developer Setup

• Token files added to project
• Build pipeline configured
• Theme/CSS variables imported
• Hot reload working for token changes

Design Sync

• Figma/design tool updated with tokens
• Component library aligned
• Documentation generated
• Storybook stories created

Validation

• Colors render correctly
• Typography scales properly
• Spacing matches design
• Responsive breakpoints work
• Dark mode tokens (if applicable)

Documentation Deliverables

Version Control

Token Versioning

{
  "meta": {
    "version": "1.2.0",
    "style": "modern",
    "generated": "2024-01-15",
    "changelog": [
      "1.2.0 - Added animation tokens",
      "1.1.0 - Updated primary color",
      "1.0.0 - Initial release"
    ]
  }
}

Breaking Change Policy

See also: token-generation.md for generation options

Responsive Design Calculations

Reference for breakpoint math, fluid typography, and responsive layout patterns.

Table of Contents

• Breakpoint System
• Fluid Typography
• Responsive Spacing
• Container Queries
• Grid Systems

Breakpoint System

Standard Breakpoints

┌─────────────────────────────────────────────────────────────┐
│                    BREAKPOINT RANGES                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  xs        sm         md         lg         xl        2xl   │
│  │─────────│──────────│──────────│──────────│─────────│     │
│  0      480px      640px      768px     1024px    1280px    │
│                                                      1536px │
│                                                             │
│  Mobile   Mobile+    Tablet    Laptop    Desktop   Large    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Breakpoint Values

Mobile-First Media Queries

/* Base styles (mobile) */
.component {
  padding: var(--spacing-sm);
  font-size: var(--fontSize-sm);
}

/* Small devices and up */
@media (min-width: 480px) {
  .component {
    padding: var(--spacing-md);
  }
}

/* Medium devices and up */
@media (min-width: 768px) {
  .component {
    padding: var(--spacing-lg);
    font-size: var(--fontSize-base);
  }
}

/* Large devices and up */
@media (min-width: 1024px) {
  .component {
    padding: var(--spacing-xl);
  }
}

Breakpoint Utility Function

const breakpoints = {
  xs: 480,
  sm: 640,
  md: 768,
  lg: 1024,
  xl: 1280,
  '2xl': 1536
};

function mediaQuery(breakpoint, type = 'min') {
  const value = breakpoints[breakpoint];
  if (type === 'min') {
    return `@media (min-width: ${value}px)`;
  }
  return `@media (max-width: ${value - 1}px)`;
}

// Usage
const styles = `
  ${mediaQuery('md')} {
    display: flex;
  }
`;

Fluid Typography

Clamp Formula

font-size: clamp(min, preferred, max);

/* Example: 16px to 24px between 320px and 1200px viewport */
font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);

Fluid Scale Calculation

preferred = min + (max - min) * ((100vw - minVW) / (maxVW - minVW))

Simplified:
preferred = base + (scaling-factor * vw)

Where:
  scaling-factor = (max - min) / (maxVW - minVW) * 100

Fluid Typography Scale

Implementation

:root {
  /* Fluid type scale */
  --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
  --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
  --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
  --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
}

h1 { font-size: var(--fluid-h1); }
h2 { font-size: var(--fluid-h2); }
h3 { font-size: var(--fluid-h3); }
body { font-size: var(--fluid-body); }

Responsive Spacing

Fluid Spacing Formula

/* Spacing that scales with viewport */
spacing: clamp(minSpace, preferredSpace, maxSpace);

/* Example: 16px to 48px */
--spacing-responsive: clamp(1rem, 0.5rem + 2vw, 3rem);

Responsive Spacing Scale

Implementation

:root {
  --space-section: clamp(3rem, 2rem + 4vw, 7.5rem);
  --space-component: clamp(1rem, 0.5rem + 1vw, 2rem);
  --space-content: clamp(1.5rem, 1rem + 2vw, 3rem);
}

.section {
  padding-top: var(--space-section);
  padding-bottom: var(--space-section);
}

.card {
  padding: var(--space-component);
  gap: var(--space-content);
}

Container Queries

Container Width Tokens

Container CSS

.container {
  width: 100%;
  margin-left: auto;
  margin-right: auto;
  padding-left: var(--spacing-md);
  padding-right: var(--spacing-md);
}

.container--sm { max-width: 640px; }
.container--md { max-width: 768px; }
.container--lg { max-width: 1024px; }
.container--xl { max-width: 1280px; }
.container--2xl { max-width: 1536px; }

CSS Container Queries

/* Define container */
.card-container {
  container-type: inline-size;
  container-name: card;
}

/* Query container width */
@container card (min-width: 400px) {
  .card {
    display: flex;
    flex-direction: row;
  }
}

@container card (min-width: 600px) {
  .card {
    gap: var(--spacing-lg);
  }
}

Grid Systems

12-Column Grid

.grid {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
  gap: var(--spacing-md);
}

/* Column spans */
.col-1 { grid-column: span 1; }
.col-2 { grid-column: span 2; }
.col-3 { grid-column: span 3; }
.col-4 { grid-column: span 4; }
.col-6 { grid-column: span 6; }
.col-12 { grid-column: span 12; }

/* Responsive columns */
@media (min-width: 768px) {
  .col-md-4 { grid-column: span 4; }
  .col-md-6 { grid-column: span 6; }
  .col-md-8 { grid-column: span 8; }
}

Auto-Fit Grid

/* Cards that automatically wrap */
.auto-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: var(--spacing-lg);
}

/* With explicit min/max columns */
.auto-grid--constrained {
  grid-template-columns: repeat(
    auto-fit,
    minmax(min(100%, 280px), 1fr)
  );
}

Common Layout Patterns

Sidebar + Content:

.layout-sidebar {
  display: grid;
  grid-template-columns: 1fr;
  gap: var(--spacing-lg);
}

@media (min-width: 768px) {
  .layout-sidebar {
    grid-template-columns: 280px 1fr;
  }
}

Holy Grail:

.layout-holy-grail {
  display: grid;
  grid-template-columns: 1fr;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
}

@media (min-width: 1024px) {
  .layout-holy-grail {
    grid-template-columns: 200px 1fr 200px;
    grid-template-rows: auto 1fr auto;
  }

  .layout-holy-grail header,
  .layout-holy-grail footer {
    grid-column: 1 / -1;
  }
}

Quick Reference

Viewport Units

Responsive Testing Checklist

• 320px (small mobile)
• 375px (iPhone SE/8)
• 414px (iPhone Plus/Max)
• 768px (iPad portrait)
• 1024px (iPad landscape/laptop)
• 1280px (desktop)
• 1920px (large desktop)

Common Device Widths

See also: token-generation.md for breakpoint token details

Design Token Generation Guide

Reference for color palette algorithms, typography scales, and WCAG accessibility checking.

Table of Contents

• Color Palette Generation
• Typography Scale System
• Spacing Grid System
• Accessibility Contrast
• Export Formats

Color Palette Generation

HSV Color Space Algorithm

The token generator uses HSV (Hue, Saturation, Value) color space for precise control.

┌─────────────────────────────────────────────────────────────┐
│                    COLOR SCALE GENERATION                   │
├─────────────────────────────────────────────────────────────┤
│  Input: Brand Color (#0066CC)                               │
│  ↓                                                          │
│  Convert: Hex → RGB → HSV                                   │
│  ↓                                                          │
│  For each step (50, 100, 200... 900):                      │
│    • Adjust Value (brightness)                              │
│    • Adjust Saturation                                      │
│    • Keep Hue constant                                      │
│  ↓                                                          │
│  Output: 10-step color scale                                │
└─────────────────────────────────────────────────────────────┘

Brightness Algorithm

# For light shades (50-400): High fixed brightness
if step < 500:
    new_value = 0.95  # 95% brightness

# For dark shades (500-900): Exponential decrease
else:
    new_value = base_value * (1 - (step - 500) / 500)
    # At step 900: brightness ≈ base_value * 0.2

Saturation Scaling

# Saturation increases with step number
# 50 = 30% of base saturation
# 900 = 100% of base saturation
new_saturation = base_saturation * (0.3 + 0.7 * (step / 900))

Complementary Color Generation

Brand Color: #0066CC (H=210°, S=100%, V=80%)
                    ↓
           Add 180° to Hue
                    ↓
Secondary: #CC6600 (H=30°, S=100%, V=80%)

Color Scale Output

Typography Scale System

Modular Scale (Major Third)

The generator uses a 1.25x ratio (major third) to create harmonious font sizes.

Base: 16px

Scale calculation:
  Smaller sizes: 16px ÷ 1.25^n
  Larger sizes: 16px × 1.25^n

Result:
  xs:   10px (16 ÷ 1.25²)
  sm:   13px (16 ÷ 1.25¹)
  base: 16px
  lg:   20px (16 × 1.25¹)
  xl:   25px (16 × 1.25²)
  2xl:  31px (16 × 1.25³)
  3xl:  39px (16 × 1.25⁴)
  4xl:  49px (16 × 1.25⁵)
  5xl:  61px (16 × 1.25⁶)

Type Scale Ratios

Pre-composed Text Styles

Spacing Grid System

8pt Grid Foundation

All spacing values are multiples of 8px for visual consistency.

Base Unit: 8px

Multipliers: 0, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8...

Results:
  0:  0px
  1:  4px  (0.5 × 8)
  2:  8px  (1 × 8)
  3:  12px (1.5 × 8)
  4:  16px (2 × 8)
  5:  20px (2.5 × 8)
  6:  24px (3 × 8)
  ...

Semantic Spacing Mapping

Why 8pt Grid?

1. Divisibility: 8 divides evenly into common screen widths
2. Consistency: Creates predictable vertical rhythm
3. Accessibility: Touch targets naturally align to 48px (8 × 6)
4. Integration: Most design tools default to 8px grids

Accessibility Contrast

WCAG Contrast Requirements

Large text: ≥18pt regular or ≥14pt bold

Contrast Ratio Formula

Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)

Where:
  L1 = Relative luminance of lighter color
  L2 = Relative luminance of darker color

Relative Luminance:
  L = 0.2126 × R + 0.7152 × G + 0.0722 × B
  (Values linearized from sRGB)

Color Step Contrast Guide

Semantic Colors Accessibility

Generated semantic colors include contrast colors:

{
  "success": {
    "base": "#10B981",
    "light": "#34D399",
    "dark": "#059669",
    "contrast": "#FFFFFF"  // For text on base
  }
}

Export Formats

JSON Format

Best for: Design tool plugins, JavaScript/TypeScript projects, APIs

{
  "colors": {
    "primary": {
      "50": "#E6F2FF",
      "500": "#0066CC",
      "900": "#002855"
    }
  },
  "typography": {
    "fontSize": {
      "base": "16px",
      "lg": "20px"
    }
  }
}

CSS Custom Properties

Best for: Web applications, CSS frameworks

:root {
  --colors-primary-50: #E6F2FF;
  --colors-primary-500: #0066CC;
  --colors-primary-900: #002855;
  --typography-fontSize-base: 16px;
  --typography-fontSize-lg: 20px;
}

SCSS Variables

Best for: SCSS/SASS projects, component libraries

$colors-primary-50: #E6F2FF;
$colors-primary-500: #0066CC;
$colors-primary-900: #002855;
$typography-fontSize-base: 16px;
$typography-fontSize-lg: 20px;

Format Selection Guide

Quick Reference

Generation Command

# Default (modern style, JSON output)
python scripts/design_token_generator.py "#0066CC"

# Classic style, CSS output
python scripts/design_token_generator.py "#8B4513" classic css

# Playful style, summary view
python scripts/design_token_generator.py "#FF6B6B" playful summary

Style Differences

See also: component-architecture.md for component design patterns