diff --git a/product-team/ui-design-system/SKILL.md b/product-team/ui-design-system/SKILL.md
index 35be86b..2f08dc4 100644
--- a/product-team/ui-design-system/SKILL.md
+++ b/product-team/ui-design-system/SKILL.md
@@ -5,28 +5,375 @@ description: UI design system toolkit for Senior UI Designer including design to
# UI Design System
-Professional toolkit for creating and maintaining scalable design systems.
+Generate design tokens, create color palettes, calculate typography scales, build component systems, and prepare developer handoff documentation.
-## Core Capabilities
-- Design token generation (colors, typography, spacing)
-- Component system architecture
-- Responsive design calculations
-- Accessibility compliance
-- Developer handoff documentation
+---
-## Key Scripts
+## Table of Contents
+
+- [Trigger Terms](#trigger-terms)
+- [Workflows](#workflows)
+ - [Workflow 1: Generate Design Tokens](#workflow-1-generate-design-tokens)
+ - [Workflow 2: Create Component System](#workflow-2-create-component-system)
+ - [Workflow 3: Responsive Design](#workflow-3-responsive-design)
+ - [Workflow 4: Developer Handoff](#workflow-4-developer-handoff)
+- [Tool Reference](#tool-reference)
+- [Quick Reference Tables](#quick-reference-tables)
+- [Knowledge Base](#knowledge-base)
+
+---
+
+## Trigger Terms
+
+Use this skill when you need to:
+
+- "generate design tokens"
+- "create color palette"
+- "build typography scale"
+- "calculate spacing system"
+- "create design system"
+- "generate CSS variables"
+- "export SCSS tokens"
+- "set up component architecture"
+- "document component library"
+- "calculate responsive breakpoints"
+- "prepare developer handoff"
+- "convert brand color to palette"
+- "check WCAG contrast"
+- "build 8pt grid system"
+
+---
+
+## Workflows
+
+### Workflow 1: Generate Design Tokens
+
+**Situation:** You have a brand color and need a complete design token system.
+
+**Steps:**
+
+1. **Identify brand color and style**
+ - Brand primary color (hex format)
+ - Style preference: `modern` | `classic` | `playful`
+
+2. **Generate tokens using script**
+ ```bash
+ python scripts/design_token_generator.py "#0066CC" modern json
+ ```
+
+3. **Review generated categories**
+ - Colors: primary, secondary, neutral, semantic, surface
+ - Typography: fontFamily, fontSize, fontWeight, lineHeight
+ - Spacing: 8pt grid-based scale (0-64)
+ - Borders: radius, width
+ - Shadows: none through 2xl
+ - Animation: duration, easing
+ - Breakpoints: xs through 2xl
+
+4. **Export in target format**
+ ```bash
+ # CSS custom properties
+ python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css
+
+ # SCSS variables
+ python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss
+
+ # JSON for Figma/tooling
+ python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json
+ ```
+
+5. **Validate accessibility**
+ - Check color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)
+ - Verify semantic colors have contrast colors defined
+
+---
+
+### Workflow 2: Create Component System
+
+**Situation:** You need to structure a component library using design tokens.
+
+**Steps:**
+
+1. **Define component hierarchy**
+ - Atoms: Button, Input, Icon, Label, Badge
+ - Molecules: FormField, SearchBar, Card, ListItem
+ - Organisms: Header, Footer, DataTable, Modal
+ - Templates: DashboardLayout, AuthLayout
+
+2. **Map tokens to components**
+
+ | Component | Tokens Used |
+ |-----------|-------------|
+ | Button | colors, sizing, borders, shadows, typography |
+ | Input | colors, sizing, borders, spacing |
+ | Card | colors, borders, shadows, spacing |
+ | Modal | colors, shadows, spacing, z-index, animation |
+
+3. **Define variant patterns**
+
+ Size variants:
+ ```
+ sm: height 32px, paddingX 12px, fontSize 14px
+ md: height 40px, paddingX 16px, fontSize 16px
+ lg: height 48px, paddingX 20px, fontSize 18px
+ ```
+
+ Color variants:
+ ```
+ primary: background primary-500, text white
+ secondary: background neutral-100, text neutral-900
+ ghost: background transparent, text neutral-700
+ ```
+
+4. **Document component API**
+ - Props interface with types
+ - Variant options
+ - State handling (hover, active, focus, disabled)
+ - Accessibility requirements
+
+5. **Reference:** See `references/component-architecture.md`
+
+---
+
+### Workflow 3: Responsive Design
+
+**Situation:** You need breakpoints, fluid typography, or responsive spacing.
+
+**Steps:**
+
+1. **Define breakpoints**
+
+ | Name | Width | Target |
+ |------|-------|--------|
+ | xs | 0 | Small phones |
+ | sm | 480px | Large phones |
+ | md | 640px | Tablets |
+ | lg | 768px | Small laptops |
+ | xl | 1024px | Desktops |
+ | 2xl | 1280px | Large screens |
+
+2. **Calculate fluid typography**
+
+ Formula: `clamp(min, preferred, max)`
+
+ ```css
+ /* 16px to 24px between 320px and 1200px viewport */
+ font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
+ ```
+
+ Pre-calculated scales:
+ ```css
+ --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);
+ ```
+
+3. **Set up responsive spacing**
+
+ | Token | Mobile | Tablet | Desktop |
+ |-------|--------|--------|---------|
+ | --space-md | 12px | 16px | 16px |
+ | --space-lg | 16px | 24px | 32px |
+ | --space-xl | 24px | 32px | 48px |
+ | --space-section | 48px | 80px | 120px |
+
+4. **Reference:** See `references/responsive-calculations.md`
+
+---
+
+### Workflow 4: Developer Handoff
+
+**Situation:** You need to hand off design tokens to development team.
+
+**Steps:**
+
+1. **Export tokens in required formats**
+ ```bash
+ # For CSS projects
+ python scripts/design_token_generator.py "#0066CC" modern css
+
+ # For SCSS projects
+ python scripts/design_token_generator.py "#0066CC" modern scss
+
+ # For JavaScript/TypeScript
+ python scripts/design_token_generator.py "#0066CC" modern json
+ ```
+
+2. **Prepare framework integration**
+
+ **React + CSS Variables:**
+ ```tsx
+ import './design-tokens.css';
+
+
+ ```
+
+ **Tailwind Config:**
+ ```javascript
+ const tokens = require('./design-tokens.json');
+
+ module.exports = {
+ theme: {
+ colors: tokens.colors,
+ fontFamily: tokens.typography.fontFamily
+ }
+ };
+ ```
+
+ **styled-components:**
+ ```typescript
+ import tokens from './design-tokens.json';
+
+ const Button = styled.button`
+ background: ${tokens.colors.primary['500']};
+ padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
+ `;
+ ```
+
+3. **Sync with Figma**
+ - Install Tokens Studio plugin
+ - Import design-tokens.json
+ - Tokens sync automatically with Figma styles
+
+4. **Handoff checklist**
+ - [ ] Token files added to project
+ - [ ] Build pipeline configured
+ - [ ] Theme/CSS variables imported
+ - [ ] Component library aligned
+ - [ ] Documentation generated
+
+5. **Reference:** See `references/developer-handoff.md`
+
+---
+
+## Tool Reference
### design_token_generator.py
-Generates complete design system tokens from brand colors.
-**Usage**: `python scripts/design_token_generator.py [brand_color] [style] [format]`
-- Styles: modern, classic, playful
-- Formats: json, css, scss
+Generates complete design token system from brand color.
-**Features**:
-- Complete color palette generation
-- Modular typography scale
-- 8pt spacing grid system
-- Shadow and animation tokens
-- Responsive breakpoints
-- Multiple export formats
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| brand_color | Hex color | #0066CC | Primary brand color |
+| style | modern, classic, playful | modern | Design style preset |
+| format | json, css, scss, summary | json | Output format |
+
+**Examples:**
+
+```bash
+# Generate JSON tokens (default)
+python scripts/design_token_generator.py "#0066CC"
+
+# Classic style with CSS output
+python scripts/design_token_generator.py "#8B4513" classic css
+
+# Playful style summary view
+python scripts/design_token_generator.py "#FF6B6B" playful summary
+```
+
+**Output Categories:**
+
+| Category | Description | Key Values |
+|----------|-------------|------------|
+| colors | Color palettes | primary, secondary, neutral, semantic, surface |
+| typography | Font system | fontFamily, fontSize, fontWeight, lineHeight |
+| spacing | 8pt grid | 0-64 scale, semantic (xs-3xl) |
+| sizing | Component sizes | container, button, input, icon |
+| borders | Border values | radius (per style), width |
+| shadows | Shadow styles | none through 2xl, inner |
+| animation | Motion tokens | duration, easing, keyframes |
+| breakpoints | Responsive | xs, sm, md, lg, xl, 2xl |
+| z-index | Layer system | base through notification |
+
+---
+
+## Quick Reference Tables
+
+### Color Scale Generation
+
+| Step | Brightness | Saturation | Use Case |
+|------|------------|------------|----------|
+| 50 | 95% fixed | 30% | Subtle backgrounds |
+| 100 | 95% fixed | 38% | Light backgrounds |
+| 200 | 95% fixed | 46% | Hover states |
+| 300 | 95% fixed | 54% | Borders |
+| 400 | 95% fixed | 62% | Disabled states |
+| 500 | Original | 70% | Base/default color |
+| 600 | Original × 0.8 | 78% | Hover (dark) |
+| 700 | Original × 0.6 | 86% | Active states |
+| 800 | Original × 0.4 | 94% | Text |
+| 900 | Original × 0.2 | 100% | Headings |
+
+### Typography Scale (1.25x Ratio)
+
+| Size | Value | Calculation |
+|------|-------|-------------|
+| xs | 10px | 16 ÷ 1.25² |
+| sm | 13px | 16 ÷ 1.25¹ |
+| base | 16px | Base |
+| 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⁶ |
+
+### WCAG Contrast Requirements
+
+| Level | Normal Text | Large Text |
+|-------|-------------|------------|
+| AA | 4.5:1 | 3:1 |
+| AAA | 7:1 | 4.5:1 |
+
+Large text: ≥18pt regular or ≥14pt bold
+
+### Style Presets
+
+| Aspect | Modern | Classic | Playful |
+|--------|--------|---------|---------|
+| Font Sans | Inter | Helvetica | Poppins |
+| Font Mono | Fira Code | Courier | Source Code Pro |
+| Radius Default | 8px | 4px | 16px |
+| Shadows | Layered, subtle | Single layer | Soft, pronounced |
+
+---
+
+## Knowledge Base
+
+Detailed reference guides in `references/`:
+
+| File | Content |
+|------|---------|
+| `token-generation.md` | Color algorithms, HSV space, WCAG contrast, type scales |
+| `component-architecture.md` | Atomic design, naming conventions, props patterns |
+| `responsive-calculations.md` | Breakpoints, fluid typography, grid systems |
+| `developer-handoff.md` | Export formats, framework setup, Figma sync |
+
+---
+
+## Validation Checklist
+
+### Token Generation
+- [ ] Brand color provided in hex format
+- [ ] Style matches project requirements
+- [ ] All token categories generated
+- [ ] Semantic colors include contrast values
+
+### Component System
+- [ ] All sizes implemented (sm, md, lg)
+- [ ] All variants implemented (primary, secondary, ghost)
+- [ ] All states working (hover, active, focus, disabled)
+- [ ] Uses only design tokens (no hardcoded values)
+
+### Accessibility
+- [ ] Color contrast meets WCAG AA
+- [ ] Focus indicators visible
+- [ ] Touch targets ≥ 44×44px
+- [ ] Semantic HTML elements used
+
+### Developer Handoff
+- [ ] Tokens exported in required format
+- [ ] Framework integration documented
+- [ ] Design tool synced
+- [ ] Component documentation complete
diff --git a/product-team/ui-design-system/references/component-architecture.md b/product-team/ui-design-system/references/component-architecture.md
new file mode 100644
index 0000000..a50a1e2
--- /dev/null
+++ b/product-team/ui-design-system/references/component-architecture.md
@@ -0,0 +1,396 @@
+# Component Architecture Guide
+
+Reference for design system component organization, naming conventions, and documentation patterns.
+
+---
+
+## Table of Contents
+
+- [Component Hierarchy](#component-hierarchy)
+- [Naming Conventions](#naming-conventions)
+- [Component Documentation](#component-documentation)
+- [Variant Patterns](#variant-patterns)
+- [Token Integration](#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
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| **Primitives** | Base HTML wrapper | Box, Text, Flex, Grid |
+| **Inputs** | User interaction | Button, Input, Select, Checkbox |
+| **Display** | Content presentation | Card, Badge, Avatar, Icon |
+| **Feedback** | User feedback | Alert, Toast, Progress, Skeleton |
+| **Navigation** | Route management | Link, Menu, Tabs, Breadcrumb |
+| **Overlay** | Layer above content | Modal, Drawer, Popover, Tooltip |
+| **Layout** | Structure | Stack, Container, Divider |
+
+---
+
+## 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
+
+```markdown
+# ComponentName
+
+Brief description of what this component does.
+
+## Usage
+
+\`\`\`tsx
+import { Button } from '@design-system/components'
+
+
+\`\`\`
+
+## 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:**
+
+```css
+.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:**
+
+```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:**
+
+```typescript
+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 | Token Categories Used |
+|-----------|----------------------|
+| Button | colors, sizing, borders, shadows, typography |
+| Input | colors, sizing, borders, spacing |
+| Card | colors, borders, shadows, spacing |
+| Typography | typography (all), colors |
+| Icon | sizing, colors |
+| Modal | colors, shadows, spacing, z-index, animation |
+
+---
+
+## 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*
diff --git a/product-team/ui-design-system/references/developer-handoff.md b/product-team/ui-design-system/references/developer-handoff.md
new file mode 100644
index 0000000..ee0d60a
--- /dev/null
+++ b/product-team/ui-design-system/references/developer-handoff.md
@@ -0,0 +1,509 @@
+# Developer Handoff Guide
+
+Reference for integrating design tokens into development workflows and design tool collaboration.
+
+---
+
+## Table of Contents
+
+- [Export Formats](#export-formats)
+- [Integration Patterns](#integration-patterns)
+- [Framework Setup](#framework-setup)
+- [Design Tool Integration](#design-tool-integration)
+- [Handoff Checklist](#handoff-checklist)
+
+---
+
+## Export Formats
+
+### JSON (Recommended for Most Projects)
+
+**File:** `design-tokens.json`
+
+```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`
+
+```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`
+
+```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.
+
+```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.)
+
+```typescript
+// 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;
+```
+
+```typescript
+// 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
+
+```javascript
+// 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
+
+```tsx
+// App.tsx
+import './design-tokens.css';
+import './styles.css';
+
+function App() {
+ return (
+
+ );
+}
+```
+
+```css
+/* 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
+
+```tsx
+// ThemeProvider.tsx
+import { ThemeProvider } from 'styled-components';
+import { theme } from './theme';
+
+export function AppThemeProvider({ children }) {
+ return (
+
+ {children}
+
+ );
+}
+```
+
+```tsx
+// 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
+
+```vue
+
+
+
+
+
+
+```
+
+### Next.js + Tailwind
+
+```javascript
+// 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(', ')
+ }
+ }
+ }
+};
+```
+
+```tsx
+// page.tsx
+export default function Page() {
+ return (
+
+ );
+}
+```
+
+---
+
+## 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
+
+```javascript
+// .storybook/preview.js
+import '../design-tokens.css';
+
+export const parameters = {
+ backgrounds: {
+ default: 'light',
+ values: [
+ { name: 'light', value: '#FFFFFF' },
+ { name: 'dark', value: '#111827' }
+ ]
+ }
+};
+```
+
+```javascript
+// 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
+
+| Tool | Token Format | Sync Method |
+|------|--------------|-------------|
+| Figma | JSON | Tokens Studio plugin / Variables |
+| Sketch | JSON | Craft / Shared Styles |
+| Adobe XD | JSON | Design Tokens plugin |
+| InVision DSM | JSON | Native import |
+| Zeroheight | JSON/CSS | Direct import |
+
+---
+
+## 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
+
+| Document | Contents |
+|----------|----------|
+| `design-tokens.json` | All tokens in JSON |
+| `design-tokens.css` | CSS custom properties |
+| `_design-tokens.scss` | SCSS variables |
+| `README.md` | Usage instructions |
+| `CHANGELOG.md` | Token version history |
+
+---
+
+## Version Control
+
+### Token Versioning
+
+```json
+{
+ "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
+
+| Change Type | Version Bump | Migration |
+|-------------|--------------|-----------|
+| Add new token | Patch (1.0.x) | None |
+| Change token value | Minor (1.x.0) | Optional |
+| Rename/remove token | Major (x.0.0) | Required |
+
+---
+
+*See also: `token-generation.md` for generation options*
diff --git a/product-team/ui-design-system/references/responsive-calculations.md b/product-team/ui-design-system/references/responsive-calculations.md
new file mode 100644
index 0000000..f6468e3
--- /dev/null
+++ b/product-team/ui-design-system/references/responsive-calculations.md
@@ -0,0 +1,390 @@
+# Responsive Design Calculations
+
+Reference for breakpoint math, fluid typography, and responsive layout patterns.
+
+---
+
+## Table of Contents
+
+- [Breakpoint System](#breakpoint-system)
+- [Fluid Typography](#fluid-typography)
+- [Responsive Spacing](#responsive-spacing)
+- [Container Queries](#container-queries)
+- [Grid Systems](#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
+
+| Name | Min Width | Target Devices |
+|------|-----------|----------------|
+| xs | 0 | Small phones |
+| sm | 480px | Large phones |
+| md | 640px | Small tablets |
+| lg | 768px | Tablets, small laptops |
+| xl | 1024px | Laptops, desktops |
+| 2xl | 1280px | Large desktops |
+| 3xl | 1536px | Extra large displays |
+
+### Mobile-First Media Queries
+
+```css
+/* 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
+
+```javascript
+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
+
+```css
+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
+
+| Style | Mobile (320px) | Desktop (1200px) | Clamp Value |
+|-------|----------------|------------------|-------------|
+| h1 | 32px | 64px | `clamp(2rem, 1rem + 3.6vw, 4rem)` |
+| h2 | 28px | 48px | `clamp(1.75rem, 1rem + 2.3vw, 3rem)` |
+| h3 | 24px | 36px | `clamp(1.5rem, 1rem + 1.4vw, 2.25rem)` |
+| h4 | 20px | 28px | `clamp(1.25rem, 1rem + 0.9vw, 1.75rem)` |
+| body | 16px | 18px | `clamp(1rem, 0.95rem + 0.2vw, 1.125rem)` |
+| small | 14px | 14px | `0.875rem` (fixed) |
+
+### Implementation
+
+```css
+: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
+
+```css
+/* 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
+
+| Token | Mobile | Tablet | Desktop |
+|-------|--------|--------|---------|
+| --space-xs | 4px | 4px | 4px |
+| --space-sm | 8px | 8px | 8px |
+| --space-md | 12px | 16px | 16px |
+| --space-lg | 16px | 24px | 32px |
+| --space-xl | 24px | 32px | 48px |
+| --space-2xl | 32px | 48px | 64px |
+| --space-section | 48px | 80px | 120px |
+
+### Implementation
+
+```css
+: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 | Max Width | Use Case |
+|-----------|-----------|----------|
+| sm | 640px | Narrow content |
+| md | 768px | Blog posts |
+| lg | 1024px | Standard pages |
+| xl | 1280px | Wide layouts |
+| 2xl | 1536px | Full-width dashboards |
+
+### Container CSS
+
+```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
+
+```css
+/* 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
+
+```css
+.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
+
+```css
+/* 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:**
+```css
+.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:**
+```css
+.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
+
+| Unit | Description |
+|------|-------------|
+| vw | 1% of viewport width |
+| vh | 1% of viewport height |
+| vmin | 1% of smaller dimension |
+| vmax | 1% of larger dimension |
+| dvh | Dynamic viewport height (accounts for mobile chrome) |
+| svh | Small viewport height |
+| lvh | Large viewport height |
+
+### 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
+
+| Device | Width | Breakpoint |
+|--------|-------|------------|
+| iPhone SE | 375px | xs-sm |
+| iPhone 14 | 390px | sm |
+| iPhone 14 Pro Max | 430px | sm |
+| iPad Mini | 768px | lg |
+| iPad Pro 11" | 834px | lg |
+| MacBook Air 13" | 1280px | xl |
+| iMac 24" | 1920px | 2xl+ |
+
+---
+
+*See also: `token-generation.md` for breakpoint token details*
diff --git a/product-team/ui-design-system/references/token-generation.md b/product-team/ui-design-system/references/token-generation.md
new file mode 100644
index 0000000..0d50ac5
--- /dev/null
+++ b/product-team/ui-design-system/references/token-generation.md
@@ -0,0 +1,324 @@
+# Design Token Generation Guide
+
+Reference for color palette algorithms, typography scales, and WCAG accessibility checking.
+
+---
+
+## Table of Contents
+
+- [Color Palette Generation](#color-palette-generation)
+- [Typography Scale System](#typography-scale-system)
+- [Spacing Grid System](#spacing-grid-system)
+- [Accessibility Contrast](#accessibility-contrast)
+- [Export Formats](#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
+
+```python
+# 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
+
+```python
+# 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
+
+| Step | Use Case | Brightness | Saturation |
+|------|----------|------------|------------|
+| 50 | Subtle backgrounds | 95% (fixed) | 30% |
+| 100 | Light backgrounds | 95% (fixed) | 38% |
+| 200 | Hover states | 95% (fixed) | 46% |
+| 300 | Borders | 95% (fixed) | 54% |
+| 400 | Disabled states | 95% (fixed) | 62% |
+| 500 | Base color | Original | 70% |
+| 600 | Hover (dark) | Original × 0.8 | 78% |
+| 700 | Active states | Original × 0.6 | 86% |
+| 800 | Text | Original × 0.4 | 94% |
+| 900 | Headings | Original × 0.2 | 100% |
+
+---
+
+## 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
+
+| Ratio | Name | Multiplier | Character |
+|-------|------|------------|-----------|
+| 1.067 | Minor Second | Tight | Compact UIs |
+| 1.125 | Major Second | Subtle | App interfaces |
+| 1.200 | Minor Third | Moderate | General use |
+| **1.250** | **Major Third** | **Balanced** | **Default** |
+| 1.333 | Perfect Fourth | Pronounced | Marketing |
+| 1.414 | Augmented Fourth | Bold | Editorial |
+| 1.618 | Golden Ratio | Dramatic | Headlines |
+
+### Pre-composed Text Styles
+
+| Style | Size | Weight | Line Height | Letter Spacing |
+|-------|------|--------|-------------|----------------|
+| h1 | 48px | 700 | 1.2 | -0.02em |
+| h2 | 36px | 700 | 1.3 | -0.01em |
+| h3 | 28px | 600 | 1.4 | 0 |
+| h4 | 24px | 600 | 1.4 | 0 |
+| h5 | 20px | 600 | 1.5 | 0 |
+| h6 | 16px | 600 | 1.5 | 0.01em |
+| body | 16px | 400 | 1.5 | 0 |
+| small | 14px | 400 | 1.5 | 0 |
+| caption | 12px | 400 | 1.5 | 0.01em |
+
+---
+
+## 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
+
+| Token | Numeric | Value | Use Case |
+|-------|---------|-------|----------|
+| xs | 1 | 4px | Inline icon margins |
+| sm | 2 | 8px | Button padding |
+| md | 4 | 16px | Card padding |
+| lg | 6 | 24px | Section spacing |
+| xl | 8 | 32px | Component gaps |
+| 2xl | 12 | 48px | Section margins |
+| 3xl | 16 | 64px | Page sections |
+
+### 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
+
+| Level | Normal Text | Large Text | Definition |
+|-------|-------------|------------|------------|
+| AA | 4.5:1 | 3:1 | Minimum requirement |
+| AAA | 7:1 | 4.5:1 | Enhanced accessibility |
+
+**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
+
+| Background | Minimum Text Step | For AA |
+|------------|-------------------|--------|
+| 50 | 700+ | Large text at 600 |
+| 100 | 700+ | Large text at 600 |
+| 200 | 800+ | Large text at 700 |
+| 300 | 900 | - |
+| 500 (base) | White or 50 | - |
+| 700+ | White or 50-100 | - |
+
+### Semantic Colors Accessibility
+
+Generated semantic colors include contrast colors:
+
+```json
+{
+ "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
+
+```json
+{
+ "colors": {
+ "primary": {
+ "50": "#E6F2FF",
+ "500": "#0066CC",
+ "900": "#002855"
+ }
+ },
+ "typography": {
+ "fontSize": {
+ "base": "16px",
+ "lg": "20px"
+ }
+ }
+}
+```
+
+### CSS Custom Properties
+
+Best for: Web applications, CSS frameworks
+
+```css
+: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
+
+```scss
+$colors-primary-50: #E6F2FF;
+$colors-primary-500: #0066CC;
+$colors-primary-900: #002855;
+$typography-fontSize-base: 16px;
+$typography-fontSize-lg: 20px;
+```
+
+### Format Selection Guide
+
+| Format | When to Use |
+|--------|-------------|
+| JSON | Figma plugins, Storybook, JS/TS, design tool APIs |
+| CSS | Plain CSS projects, CSS-in-JS (some), web apps |
+| SCSS | SASS pipelines, component libraries, theming |
+| Summary | Quick verification, debugging |
+
+---
+
+## Quick Reference
+
+### Generation Command
+
+```bash
+# 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
+
+| Aspect | Modern | Classic | Playful |
+|--------|--------|---------|---------|
+| Fonts | Inter, Fira Code | Helvetica, Courier | Poppins, Source Code Pro |
+| Border Radius | 8px default | 4px default | 16px default |
+| Shadows | Layered, subtle | Single layer | Soft, pronounced |
+
+---
+
+*See also: `component-architecture.md` for component design patterns*
diff --git a/product-team/ui-design-system/scripts/design_token_generator.py b/product-team/ui-design-system/scripts/design_token_generator.py
index b671e86..119508c 100644
--- a/product-team/ui-design-system/scripts/design_token_generator.py
+++ b/product-team/ui-design-system/scripts/design_token_generator.py
@@ -1,7 +1,59 @@
#!/usr/bin/env python3
"""
Design Token Generator
-Creates consistent design system tokens for colors, typography, spacing, and more
+Creates consistent design system tokens for colors, typography, spacing, and more.
+
+Usage:
+ python design_token_generator.py [brand_color] [style] [format]
+
+ brand_color: Hex color (default: #0066CC)
+ style: modern | classic | playful (default: modern)
+ format: json | css | scss | summary (default: json)
+
+Examples:
+ python design_token_generator.py "#0066CC" modern json
+ python design_token_generator.py "#8B4513" classic css
+ python design_token_generator.py "#FF6B6B" playful summary
+
+Table of Contents:
+==================
+
+CLASS: DesignTokenGenerator
+ __init__() - Initialize base unit (8pt), type scale (1.25x)
+ generate_complete_system() - Main entry: generates all token categories
+ generate_color_palette() - Primary, secondary, neutral, semantic colors
+ generate_typography_system() - Font families, sizes, weights, line heights
+ generate_spacing_system() - 8pt grid-based spacing scale
+ generate_sizing_tokens() - Container and component sizing
+ generate_border_tokens() - Border radius and width values
+ generate_shadow_tokens() - Shadow definitions per style
+ generate_animation_tokens() - Durations, easing, keyframes
+ generate_breakpoints() - Responsive breakpoints (xs-2xl)
+ generate_z_index_scale() - Z-index layering system
+ export_tokens() - Export to JSON/CSS/SCSS
+
+PRIVATE METHODS:
+ _generate_color_scale() - Generate 10-step color scale (50-900)
+ _generate_neutral_scale() - Fixed neutral gray palette
+ _generate_type_scale() - Modular type scale using ratio
+ _generate_text_styles() - Pre-composed h1-h6, body, caption
+ _export_as_css() - CSS custom properties exporter
+ _hex_to_rgb() - Hex to RGB conversion
+ _rgb_to_hex() - RGB to Hex conversion
+ _adjust_hue() - HSV hue rotation utility
+
+FUNCTION: main() - CLI entry point with argument parsing
+
+Token Categories Generated:
+ - colors: primary, secondary, neutral, semantic, surface
+ - typography: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing
+ - spacing: 0-64 scale based on 8pt grid
+ - sizing: containers, buttons, inputs, icons
+ - borders: radius (per style), width
+ - shadows: none through 2xl, inner
+ - animation: duration, easing, keyframes
+ - breakpoints: xs, sm, md, lg, xl, 2xl
+ - z-index: hide through notification
"""
import json
@@ -61,9 +113,7 @@ class DesignTokenGenerator:
},
'warning': {
'base': '#F59E0B',
- 'light': '#FBB
-
-D24',
+ 'light': '#FBBD24',
'dark': '#D97706',
'contrast': '#FFFFFF'
},