ui-design-system

UI Design System

Generate design tokens, create color palettes, calculate typography scales, build component systems, and prepare developer handoff documentation.

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
2. Brand primary color (hex format)
3. Style preference: modern | classic | playful

1. Generate tokens using script

``bash python scripts/design_token_generator.py "#0066CC" modern json ``

1. Review generated categories
2. Colors: primary, secondary, neutral, semantic, surface
3. Typography: fontFamily, fontSize, fontWeight, lineHeight
4. Spacing: 8pt grid-based scale (0-64)
5. Borders: radius, width
6. Shadows: none through 2xl
7. Animation: duration, easing
8. Breakpoints: xs through 2xl

1. 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 ```

1. Validate accessibility
2. Check color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)
3. 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
2. Atoms: Button, Input, Icon, Label, Badge
3. Molecules: FormField, SearchBar, Card, ListItem
4. Organisms: Header, Footer, DataTable, Modal
5. Templates: DashboardLayout, AuthLayout

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

1. 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 ``

1. Document component API
2. Props interface with types
3. Variant options
4. State handling (hover, active, focus, disabled)
5. Accessibility requirements

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

1. 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); ``

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

1. 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 ```

1. Prepare framework integration

React + CSS Variables: ```tsx import './design-tokens.css';

<button className="btn btn-primary">Click</button> ```

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']}; ; ```

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

1. Handoff checklist
2. [ ] Token files added to project
3. [ ] Build pipeline configured
4. [ ] Theme/CSS variables imported
5. [ ] Component library aligned
6. [ ] Documentation generated

1. Reference: See references/developer-handoff.md

Tool Reference

design_token_generator.py

Generates complete design token system from brand color.

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

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