ui-design-system

---
name: ui-design-system
description: Use when creating a design system, generating design tokens or color palettes, calculating typography/spacing scales, or preparing design-to-dev handoff documentation.
category: Product
version: 1.0.0
tools: []
---

# UI Design System

Generate design tokens, build color palettes, calculate typography scales, structure component systems, and prepare developer handoff documentation — all delivered as markdown/code in chat, since there is no filesystem to write token files to.

## Workflow 1: Generate Design Tokens

**Situation:** A brand color needs a complete design token system.

**Steps:**
1. Get the brand primary color (hex) and a style preference: `modern` | `classic` | `playful`.
2. Compute each token category using the formulas and presets below (Color Scale Generation, Typography Scale, Style Presets).
3. Present the full set: colors (primary, secondary, neutral, semantic, surface), typography (fontFamily, fontSize, fontWeight, lineHeight), spacing (8pt grid, 0-64 scale), borders (radius, width), shadows (none through 2xl), animation (duration, easing), breakpoints (xs-2xl), z-index (base through notification).
4. Output in whichever format the user needs — CSS custom properties, SCSS variables, or a JSON block — by translating the same token values into that syntax.
5. Validate accessibility: check color contrast meets WCAG AA (4.5:1 normal text, 3:1 large text) and confirm semantic colors have contrast colors defined.

## Workflow 2: Create Component System

**Situation:** Structuring a component library on top of the tokens.

**Steps:**
1. Define the 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: Button uses colors/sizing/borders/shadows/typography; Input uses colors/sizing/borders/spacing; Card uses colors/borders/shadows/spacing; Modal uses colors/shadows/spacing/z-index/animation.
3. Define variants — sizes (`sm`: height 32px/paddingX 12px/fontSize 14px; `md`: 40px/16px/16px; `lg`: 48px/20px/18px) and colors (`primary`: background primary-500, text white; `secondary`: background neutral-100, text neutral-900; `ghost`: background transparent, text neutral-700).
4. Document each component's API: props interface with types, variant options, state handling (hover, active, focus, disabled), accessibility requirements.

## Workflow 3: Responsive Design

**Situation:** Breakpoints, fluid typography, or responsive spacing are needed.

**Steps:**
1. Use these breakpoints: 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 with `clamp(min, preferred, max)` — e.g. `font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem)` scales 16px to 24px between 320px and 1200px viewports. Pre-calculated 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)`.
3. Set responsive spacing tokens: `--space-md` 12px mobile / 16px tablet / 16px desktop; `--space-lg` 16/24/32px; `--space-xl` 24/32/48px; `--space-section` 48/80/120px.

## Workflow 4: Developer Handoff

**Situation:** Handing tokens to a dev team in their framework.

**Steps:**
1. Produce the token set in the format the project needs (CSS variables, SCSS, or JSON/TS).
2. Show framework integration: React imports the CSS file and applies classes (`<button className="btn btn-primary">`); Tailwind config pulls `theme.colors`/`theme.fontFamily` from the token JSON; styled-components interpolates token values directly into template literals (`background: ${tokens.colors.primary['500']}`).
3. For Figma sync, note that a Tokens Studio-style plugin can import the JSON token file so tokens stay aligned with Figma styles.
4. Handoff checklist: token values delivered, build pipeline/theme import documented, component library aligned to the same tokens, documentation included.

## Token Categories Reference

| 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 (HSV-based, per step)

| 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, base 16px)

| 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 |

## Validation Checklist

- **Tokens:** brand color in hex, style matches project, all categories generated, semantic colors include contrast values.
- **Components:** all sizes (sm/md/lg) and variants (primary/secondary/ghost) implemented, all states (hover/active/focus/disabled) working, no hardcoded values outside tokens.
- **Accessibility:** WCAG AA contrast met, focus indicators visible, touch targets ≥44×44px, semantic HTML used.
- **Handoff:** tokens exported in the needed format, framework integration documented, design tool synced, component docs complete.