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**
   - 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';

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

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

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

{
  "format": "aiskill/v1",
  "skill": {
    "name": "ui-design-system",
    "slug": "ui-design-system",
    "version": "1.0.0",
    "description": "UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use when creating design systems, generating design tokens, maintaining visual consistency, or facilitating design-dev collaboration and developer handoff.",
    "category": "Design",
    "tags": [
      "design-creative",
      "design"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# UI Design System\r\n\r\nGenerate design tokens, create color palettes, calculate typography scales, build component systems, and prepare developer handoff documentation.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [Trigger Terms](#trigger-terms)\r\n- [Workflows](#workflows)\r\n  - [Workflow 1: Generate Design Tokens](#workflow-1-generate-design-tokens)\r\n  - [Workflow 2: Create Component System](#workflow-2-create-component-system)\r\n  - [Workflow 3: Responsive Design](#workflow-3-responsive-design)\r\n  - [Workflow 4: Developer Handoff](#workflow-4-developer-handoff)\r\n- [Tool Reference](#tool-reference)\r\n- [Quick Reference Tables](#quick-reference-tables)\r\n- [Knowledge Base](#knowledge-base)\r\n\r\n---\r\n\r\n## Trigger Terms\r\n\r\nUse this skill when you need to:\r\n\r\n- \"generate design tokens\"\r\n- \"create color palette\"\r\n- \"build typography scale\"\r\n- \"calculate spacing system\"\r\n- \"create design system\"\r\n- \"generate CSS variables\"\r\n- \"export SCSS tokens\"\r\n- \"set up component architecture\"\r\n- \"document component library\"\r\n- \"calculate responsive breakpoints\"\r\n- \"prepare developer handoff\"\r\n- \"convert brand color to palette\"\r\n- \"check WCAG contrast\"\r\n- \"build 8pt grid system\"\r\n\r\n---\r\n\r\n## Workflows\r\n\r\n### Workflow 1: Generate Design Tokens\r\n\r\n**Situation:** You have a brand color and need a complete design token system.\r\n\r\n**Steps:**\r\n\r\n1. **Identify brand color and style**\r\n   - Brand primary color (hex format)\r\n   - Style preference: `modern` | `classic` | `playful`\r\n\r\n2. **Generate tokens using script**\r\n   ```bash\r\n   python scripts/design_token_generator.py \"#0066CC\" modern json\r\n   ```\r\n\r\n3. **Review generated categories**\r\n   - Colors: primary, secondary, neutral, semantic, surface\r\n   - Typography: fontFamily, fontSize, fontWeight, lineHeight\r\n   - Spacing: 8pt grid-based scale (0-64)\r\n   - Borders: radius, width\r\n   - Shadows: none through 2xl\r\n   - Animation: duration, easing\r\n   - Breakpoints: xs through 2xl\r\n\r\n4. **Export in target format**\r\n   ```bash\r\n   # CSS custom properties\r\n   python scripts/design_token_generator.py \"#0066CC\" modern css > design-tokens.css\r\n\r\n   # SCSS variables\r\n   python scripts/design_token_generator.py \"#0066CC\" modern scss > _design-tokens.scss\r\n\r\n   # JSON for Figma/tooling\r\n   python scripts/design_token_generator.py \"#0066CC\" modern json > design-tokens.json\r\n   ```\r\n\r\n5. **Validate accessibility**\r\n   - Check color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)\r\n   - Verify semantic colors have contrast colors defined\r\n\r\n---\r\n\r\n### Workflow 2: Create Component System\r\n\r\n**Situation:** You need to structure a component library using design tokens.\r\n\r\n**Steps:**\r\n\r\n1. **Define component hierarchy**\r\n   - Atoms: Button, Input, Icon, Label, Badge\r\n   - Molecules: FormField, SearchBar, Card, ListItem\r\n   - Organisms: Header, Footer, DataTable, Modal\r\n   - Templates: DashboardLayout, AuthLayout\r\n\r\n2. **Map tokens to components**\r\n\r\n   | Component | Tokens Used |\r\n   |-----------|-------------|\r\n   | Button | colors, sizing, borders, shadows, typography |\r\n   | Input | colors, sizing, borders, spacing |\r\n   | Card | colors, borders, shadows, spacing |\r\n   | Modal | colors, shadows, spacing, z-index, animation |\r\n\r\n3. **Define variant patterns**\r\n\r\n   Size variants:\r\n   ```\r\n   sm: height 32px, paddingX 12px, fontSize 14px\r\n   md: height 40px, paddingX 16px, fontSize 16px\r\n   lg: height 48px, paddingX 20px, fontSize 18px\r\n   ```\r\n\r\n   Color variants:\r\n   ```\r\n   primary: background primary-500, text white\r\n   secondary: background neutral-100, text neutral-900\r\n   ghost: background transparent, text neutral-700\r\n   ```\r\n\r\n4. **Document component API**\r\n   - Props interface with types\r\n   - Variant options\r\n   - State handling (hover, active, focus, disabled)\r\n   - Accessibility requirements\r\n\r\n5. **Reference:** See `references/component-architecture.md`\r\n\r\n---\r\n\r\n### Workflow 3: Responsive Design\r\n\r\n**Situation:** You need breakpoints, fluid typography, or responsive spacing.\r\n\r\n**Steps:**\r\n\r\n1. **Define breakpoints**\r\n\r\n   | Name | Width | Target |\r\n   |------|-------|--------|\r\n   | xs | 0 | Small phones |\r\n   | sm | 480px | Large phones |\r\n   | md | 640px | Tablets |\r\n   | lg | 768px | Small laptops |\r\n   | xl | 1024px | Desktops |\r\n   | 2xl | 1280px | Large screens |\r\n\r\n2. **Calculate fluid typography**\r\n\r\n   Formula: `clamp(min, preferred, max)`\r\n\r\n   ```css\r\n   /* 16px to 24px between 320px and 1200px viewport */\r\n   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);\r\n   ```\r\n\r\n   Pre-calculated scales:\r\n   ```css\r\n   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);\r\n   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);\r\n   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);\r\n   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);\r\n   ```\r\n\r\n3. **Set up responsive spacing**\r\n\r\n   | Token | Mobile | Tablet | Desktop |\r\n   |-------|--------|--------|---------|\r\n   | --space-md | 12px | 16px | 16px |\r\n   | --space-lg | 16px | 24px | 32px |\r\n   | --space-xl | 24px | 32px | 48px |\r\n   | --space-section | 48px | 80px | 120px |\r\n\r\n4. **Reference:** See `references/responsive-calculations.md`\r\n\r\n---\r\n\r\n### Workflow 4: Developer Handoff\r\n\r\n**Situation:** You need to hand off design tokens to development team.\r\n\r\n**Steps:**\r\n\r\n1. **Export tokens in required formats**\r\n   ```bash\r\n   # For CSS projects\r\n   python scripts/design_token_generator.py \"#0066CC\" modern css\r\n\r\n   # For SCSS projects\r\n   python scripts/design_token_generator.py \"#0066CC\" modern scss\r\n\r\n   # For JavaScript/TypeScript\r\n   python scripts/design_token_generator.py \"#0066CC\" modern json\r\n   ```\r\n\r\n2. **Prepare framework integration**\r\n\r\n   **React + CSS Variables:**\r\n   ```tsx\r\n   import './design-tokens.css';\r\n\r\n   <button className=\"btn btn-primary\">Click</button>\r\n   ```\r\n\r\n   **Tailwind Config:**\r\n   ```javascript\r\n   const tokens = require('./design-tokens.json');\r\n\r\n   module.exports = {\r\n     theme: {\r\n       colors: tokens.colors,\r\n       fontFamily: tokens.typography.fontFamily\r\n     }\r\n   };\r\n   ```\r\n\r\n   **styled-components:**\r\n   ```typescript\r\n   import tokens from './design-tokens.json';\r\n\r\n   const Button = styled.button`\r\n     background: ${tokens.colors.primary['500']};\r\n     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};\r\n   `;\r\n   ```\r\n\r\n3. **Sync with Figma**\r\n   - Install Tokens Studio plugin\r\n   - Import design-tokens.json\r\n   - Tokens sync automatically with Figma styles\r\n\r\n4. **Handoff checklist**\r\n   - [ ] Token files added to project\r\n   - [ ] Build pipeline configured\r\n   - [ ] Theme/CSS variables imported\r\n   - [ ] Component library aligned\r\n   - [ ] Documentation generated\r\n\r\n5. **Reference:** See `references/developer-handoff.md`\r\n\r\n---\r\n\r\n## Tool Reference\r\n\r\n### design_token_generator.py\r\n\r\nGenerates complete design token system from brand color.\r\n\r\n| Argument | Values | Default | Description |\r\n|----------|--------|---------|-------------|\r\n| brand_color | Hex color | #0066CC | Primary brand color |\r\n| style | modern, classic, playful | modern | Design style preset |\r\n| format | json, css, scss, summary | json | Output format |\r\n\r\n**Examples:**\r\n\r\n```bash\r\n# Generate JSON tokens (default)\r\npython scripts/design_token_generator.py \"#0066CC\"\r\n\r\n# Classic style with CSS output\r\npython scripts/design_token_generator.py \"#8B4513\" classic css\r\n\r\n# Playful style summary view\r\npython scripts/design_token_generator.py \"#FF6B6B\" playful summary\r\n```\r\n\r\n**Output Categories:**\r\n\r\n| Category | Description | Key Values |\r\n|----------|-------------|------------|\r\n| colors | Color palettes | primary, secondary, neutral, semantic, surface |\r\n| typography | Font system | fontFamily, fontSize, fontWeight, lineHeight |\r\n| spacing | 8pt grid | 0-64 scale, semantic (xs-3xl) |\r\n| sizing | Component sizes | container, button, input, icon |\r\n| borders | Border values | radius (per style), width |\r\n| shadows | Shadow styles | none through 2xl, inner |\r\n| animation | Motion tokens | duration, easing, keyframes |\r\n| breakpoints | Responsive | xs, sm, md, lg, xl, 2xl |\r\n| z-index | Layer system | base through notification |\r\n\r\n---\r\n\r\n## Quick Reference Tables\r\n\r\n### Color Scale Generation\r\n\r\n| Step | Brightness | Saturation | Use Case |\r\n|------|------------|------------|----------|\r\n| 50 | 95% fixed | 30% | Subtle backgrounds |\r\n| 100 | 95% fixed | 38% | Light backgrounds |\r\n| 200 | 95% fixed | 46% | Hover states |\r\n| 300 | 95% fixed | 54% | Borders |\r\n| 400 | 95% fixed | 62% | Disabled states |\r\n| 500 | Original | 70% | Base/default color |\r\n| 600 | Original × 0.8 | 78% | Hover (dark) |\r\n| 700 | Original × 0.6 | 86% | Active states |\r\n| 800 | Original × 0.4 | 94% | Text |\r\n| 900 | Original × 0.2 | 100% | Headings |\r\n\r\n### Typography Scale (1.25x Ratio)\r\n\r\n| Size | Value | Calculation |\r\n|------|-------|-------------|\r\n| xs | 10px | 16 ÷ 1.25² |\r\n| sm | 13px | 16 ÷ 1.25¹ |\r\n| base | 16px | Base |\r\n| lg | 20px | 16 × 1.25¹ |\r\n| xl | 25px | 16 × 1.25² |\r\n| 2xl | 31px | 16 × 1.25³ |\r\n| 3xl | 39px | 16 × 1.25⁴ |\r\n| 4xl | 49px | 16 × 1.25⁵ |\r\n| 5xl | 61px | 16 × 1.25⁶ |\r\n\r\n### WCAG Contrast Requirements\r\n\r\n| Level | Normal Text | Large Text |\r\n|-------|-------------|------------|\r\n| AA | 4.5:1 | 3:1 |\r\n| AAA | 7:1 | 4.5:1 |\r\n\r\nLarge text: ≥18pt regular or ≥14pt bold\r\n\r\n### Style Presets\r\n\r\n| Aspect | Modern | Classic | Playful |\r\n|--------|--------|---------|---------|\r\n| Font Sans | Inter | Helvetica | Poppins |\r\n| Font Mono | Fira Code | Courier | Source Code Pro |\r\n| Radius Default | 8px | 4px | 16px |\r\n| Shadows | Layered, subtle | Single layer | Soft, pronounced |\r\n\r\n---\r\n\r\n## Knowledge Base\r\n\r\nDetailed reference guides in `references/`:\r\n\r\n| File | Content |\r\n|------|---------|\r\n| `token-generation.md` | Color algorithms, HSV space, WCAG contrast, type scales |\r\n| `component-architecture.md` | Atomic design, naming conventions, props patterns |\r\n| `responsive-calculations.md` | Breakpoints, fluid typography, grid systems |\r\n| `developer-handoff.md` | Export formats, framework setup, Figma sync |\r\n\r\n---\r\n\r\n## Validation Checklist\r\n\r\n### Token Generation\r\n- [ ] Brand color provided in hex format\r\n- [ ] Style matches project requirements\r\n- [ ] All token categories generated\r\n- [ ] Semantic colors include contrast values\r\n\r\n### Component System\r\n- [ ] All sizes implemented (sm, md, lg)\r\n- [ ] All variants implemented (primary, secondary, ghost)\r\n- [ ] All states working (hover, active, focus, disabled)\r\n- [ ] Uses only design tokens (no hardcoded values)\r\n\r\n### Accessibility\r\n- [ ] Color contrast meets WCAG AA\r\n- [ ] Focus indicators visible\r\n- [ ] Touch targets ≥ 44×44px\r\n- [ ] Semantic HTML elements used\r\n\r\n### Developer Handoff\r\n- [ ] Tokens exported in required format\r\n- [ ] Framework integration documented\r\n- [ ] Design tool synced\r\n- [ ] Component documentation complete",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The ui-design-system/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/ui-design-system",
    "exported_at": "2026-11-03T07:42:11.308Z"
  }
}

format: aiskill/v1
skill:
  name: ui-design-system
  slug: ui-design-system
  version: 1.0.0
  description: >-
    UI design system toolkit for Senior UI Designer including design token generation, component
    documentation, responsive design calculations, and developer handoff tools. Use when creating
    design systems, generating design tokens, maintaining visual consistency, or facilitating
    design-dev collaboration and developer handoff.
  category: Design
  tags:
    - design-creative
    - design
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# UI Design System\r\n\r\nGenerate design tokens, create color palettes, calculate typography scales, build component systems, and prepare developer handoff documentation.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [Trigger Terms](#trigger-terms)\r\n- [Workflows](#workflows)\r\n  - [Workflow 1: Generate Design Tokens](#workflow-1-generate-design-tokens)\r\n  - [Workflow 2: Create Component System](#workflow-2-create-component-system)\r\n  - [Workflow 3: Responsive Design](#workflow-3-responsive-design)\r\n  - [Workflow 4: Developer Handoff](#workflow-4-developer-handoff)\r\n- [Tool Reference](#tool-reference)\r\n- [Quick Reference Tables](#quick-reference-tables)\r\n- [Knowledge Base](#knowledge-base)\r\n\r\n---\r\n\r\n## Trigger Terms\r\n\r\nUse this skill when you need to:\r\n\r\n- \"generate design tokens\"\r\n- \"create color palette\"\r\n- \"build typography scale\"\r\n- \"calculate spacing system\"\r\n- \"create design system\"\r\n- \"generate CSS variables\"\r\n- \"export SCSS tokens\"\r\n- \"set up component architecture\"\r\n- \"document component library\"\r\n- \"calculate responsive breakpoints\"\r\n- \"prepare developer handoff\"\r\n- \"convert brand color to palette\"\r\n- \"check WCAG contrast\"\r\n- \"build 8pt grid system\"\r\n\r\n---\r\n\r\n## Workflows\r\n\r\n### Workflow 1: Generate Design Tokens\r\n\r\n**Situation:** You have a brand color and need a complete design token system.\r\n\r\n**Steps:**\r\n\r\n1. **Identify brand color and style**\r\n   - Brand primary color (hex format)\r\n   - Style preference: `modern` | `classic` | `playful`\r\n\r\n2. **Generate tokens using script**\r\n   ```bash\r\n   python scripts/design_token_generator.py \"#0066CC\" modern json\r\n   ```\r\n\r\n3. **Review generated categories**\r\n   - Colors: primary, secondary, neutral, semantic, surface\r\n   - Typography: fontFamily, fontSize, fontWeight, lineHeight\r\n   - Spacing: 8pt grid-based scale (0-64)\r\n   - Borders: radius, width\r\n   - Shadows: none through 2xl\r\n   - Animation: duration, easing\r\n   - Breakpoints: xs through 2xl\r\n\r\n4. **Export in target format**\r\n   ```bash\r\n   # CSS custom properties\r\n   python scripts/design_token_generator.py \"#0066CC\" modern css > design-tokens.css\r\n\r\n   # SCSS variables\r\n   python scripts/design_token_generator.py \"#0066CC\" modern scss > _design-tokens.scss\r\n\r\n   # JSON for Figma/tooling\r\n   python scripts/design_token_generator.py \"#0066CC\" modern json > design-tokens.json\r\n   ```\r\n\r\n5. **Validate accessibility**\r\n   - Check color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)\r\n   - Verify semantic colors have contrast colors defined\r\n\r\n---\r\n\r\n### Workflow 2: Create Component System\r\n\r\n**Situation:** You need to structure a component library using design tokens.\r\n\r\n**Steps:**\r\n\r\n1. **Define component hierarchy**\r\n   - Atoms: Button, Input, Icon, Label, Badge\r\n   - Molecules: FormField, SearchBar, Card, ListItem\r\n   - Organisms: Header, Footer, DataTable, Modal\r\n   - Templates: DashboardLayout, AuthLayout\r\n\r\n2. **Map tokens to components**\r\n\r\n   | Component | Tokens Used |\r\n   |-----------|-------------|\r\n   | Button | colors, sizing, borders, shadows, typography |\r\n   | Input | colors, sizing, borders, spacing |\r\n   | Card | colors, borders, shadows, spacing |\r\n   | Modal | colors, shadows, spacing, z-index, animation |\r\n\r\n3. **Define variant patterns**\r\n\r\n   Size variants:\r\n   ```\r\n   sm: height 32px, paddingX 12px, fontSize 14px\r\n   md: height 40px, paddingX 16px, fontSize 16px\r\n   lg: height 48px, paddingX 20px, fontSize 18px\r\n   ```\r\n\r\n   Color variants:\r\n   ```\r\n   primary: background primary-500, text white\r\n   secondary: background neutral-100, text neutral-900\r\n   ghost: background transparent, text neutral-700\r\n   ```\r\n\r\n4. **Document component API**\r\n   - Props interface with types\r\n   - Variant options\r\n   - State handling (hover, active, focus, disabled)\r\n   - Accessibility requirements\r\n\r\n5. **Reference:** See `references/component-architecture.md`\r\n\r\n---\r\n\r\n### Workflow 3: Responsive Design\r\n\r\n**Situation:** You need breakpoints, fluid typography, or responsive spacing.\r\n\r\n**Steps:**\r\n\r\n1. **Define breakpoints**\r\n\r\n   | Name | Width | Target |\r\n   |------|-------|--------|\r\n   | xs | 0 | Small phones |\r\n   | sm | 480px | Large phones |\r\n   | md | 640px | Tablets |\r\n   | lg | 768px | Small laptops |\r\n   | xl | 1024px | Desktops |\r\n   | 2xl | 1280px | Large screens |\r\n\r\n2. **Calculate fluid typography**\r\n\r\n   Formula: `clamp(min, preferred, max)`\r\n\r\n   ```css\r\n   /* 16px to 24px between 320px and 1200px viewport */\r\n   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);\r\n   ```\r\n\r\n   Pre-calculated scales:\r\n   ```css\r\n   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);\r\n   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);\r\n   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);\r\n   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);\r\n   ```\r\n\r\n3. **Set up responsive spacing**\r\n\r\n   | Token | Mobile | Tablet | Desktop |\r\n   |-------|--------|--------|---------|\r\n   | --space-md | 12px | 16px | 16px |\r\n   | --space-lg | 16px | 24px | 32px |\r\n   | --space-xl | 24px | 32px | 48px |\r\n   | --space-section | 48px | 80px | 120px |\r\n\r\n4. **Reference:** See `references/responsive-calculations.md`\r\n\r\n---\r\n\r\n### Workflow 4: Developer Handoff\r\n\r\n**Situation:** You need to hand off design tokens to development team.\r\n\r\n**Steps:**\r\n\r\n1. **Export tokens in required formats**\r\n   ```bash\r\n   # For CSS projects\r\n   python scripts/design_token_generator.py \"#0066CC\" modern css\r\n\r\n   # For SCSS projects\r\n   python scripts/design_token_generator.py \"#0066CC\" modern scss\r\n\r\n   # For JavaScript/TypeScript\r\n   python scripts/design_token_generator.py \"#0066CC\" modern json\r\n   ```\r\n\r\n2. **Prepare framework integration**\r\n\r\n   **React + CSS Variables:**\r\n   ```tsx\r\n   import './design-tokens.css';\r\n\r\n   <button className=\"btn btn-primary\">Click</button>\r\n   ```\r\n\r\n   **Tailwind Config:**\r\n   ```javascript\r\n   const tokens = require('./design-tokens.json');\r\n\r\n   module.exports = {\r\n     theme: {\r\n       colors: tokens.colors,\r\n       fontFamily: tokens.typography.fontFamily\r\n     }\r\n   };\r\n   ```\r\n\r\n   **styled-components:**\r\n   ```typescript\r\n   import tokens from './design-tokens.json';\r\n\r\n   const Button = styled.button`\r\n     background: ${tokens.colors.primary['500']};\r\n     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};\r\n   `;\r\n   ```\r\n\r\n3. **Sync with Figma**\r\n   - Install Tokens Studio plugin\r\n   - Import design-tokens.json\r\n   - Tokens sync automatically with Figma styles\r\n\r\n4. **Handoff checklist**\r\n   - [ ] Token files added to project\r\n   - [ ] Build pipeline configured\r\n   - [ ] Theme/CSS variables imported\r\n   - [ ] Component library aligned\r\n   - [ ] Documentation generated\r\n\r\n5. **Reference:** See `references/developer-handoff.md`\r\n\r\n---\r\n\r\n## Tool Reference\r\n\r\n### design_token_generator.py\r\n\r\nGenerates complete design token system from brand color.\r\n\r\n| Argument | Values | Default | Description |\r\n|----------|--------|---------|-------------|\r\n| brand_color | Hex color | #0066CC | Primary brand color |\r\n| style | modern, classic, playful | modern | Design style preset |\r\n| format | json, css, scss, summary | json | Output format |\r\n\r\n**Examples:**\r\n\r\n```bash\r\n# Generate JSON tokens (default)\r\npython scripts/design_token_generator.py \"#0066CC\"\r\n\r\n# Classic style with CSS output\r\npython scripts/design_token_generator.py \"#8B4513\" classic css\r\n\r\n# Playful style summary view\r\npython scripts/design_token_generator.py \"#FF6B6B\" playful summary\r\n```\r\n\r\n**Output Categories:**\r\n\r\n| Category | Description | Key Values |\r\n|----------|-------------|------------|\r\n| colors | Color palettes | primary, secondary, neutral, semantic, surface |\r\n| typography | Font system | fontFamily, fontSize, fontWeight, lineHeight |\r\n| spacing | 8pt grid | 0-64 scale, semantic (xs-3xl) |\r\n| sizing | Component sizes | container, button, input, icon |\r\n| borders | Border values | radius (per style), width |\r\n| shadows | Shadow styles | none through 2xl, inner |\r\n| animation | Motion tokens | duration, easing, keyframes |\r\n| breakpoints | Responsive | xs, sm, md, lg, xl, 2xl |\r\n| z-index | Layer system | base through notification |\r\n\r\n---\r\n\r\n## Quick Reference Tables\r\n\r\n### Color Scale Generation\r\n\r\n| Step | Brightness | Saturation | Use Case |\r\n|------|------------|------------|----------|\r\n| 50 | 95% fixed | 30% | Subtle backgrounds |\r\n| 100 | 95% fixed | 38% | Light backgrounds |\r\n| 200 | 95% fixed | 46% | Hover states |\r\n| 300 | 95% fixed | 54% | Borders |\r\n| 400 | 95% fixed | 62% | Disabled states |\r\n| 500 | Original | 70% | Base/default color |\r\n| 600 | Original × 0.8 | 78% | Hover (dark) |\r\n| 700 | Original × 0.6 | 86% | Active states |\r\n| 800 | Original × 0.4 | 94% | Text |\r\n| 900 | Original × 0.2 | 100% | Headings |\r\n\r\n### Typography Scale (1.25x Ratio)\r\n\r\n| Size | Value | Calculation |\r\n|------|-------|-------------|\r\n| xs | 10px | 16 ÷ 1.25² |\r\n| sm | 13px | 16 ÷ 1.25¹ |\r\n| base | 16px | Base |\r\n| lg | 20px | 16 × 1.25¹ |\r\n| xl | 25px | 16 × 1.25² |\r\n| 2xl | 31px | 16 × 1.25³ |\r\n| 3xl | 39px | 16 × 1.25⁴ |\r\n| 4xl | 49px | 16 × 1.25⁵ |\r\n| 5xl | 61px | 16 × 1.25⁶ |\r\n\r\n### WCAG Contrast Requirements\r\n\r\n| Level | Normal Text | Large Text |\r\n|-------|-------------|------------|\r\n| AA | 4.5:1 | 3:1 |\r\n| AAA | 7:1 | 4.5:1 |\r\n\r\nLarge text: ≥18pt regular or ≥14pt bold\r\n\r\n### Style Presets\r\n\r\n| Aspect | Modern | Classic | Playful |\r\n|--------|--------|---------|---------|\r\n| Font Sans | Inter | Helvetica | Poppins |\r\n| Font Mono | Fira Code | Courier | Source Code Pro |\r\n| Radius Default | 8px | 4px | 16px |\r\n| Shadows | Layered, subtle | Single layer | Soft, pronounced |\r\n\r\n---\r\n\r\n## Knowledge Base\r\n\r\nDetailed reference guides in `references/`:\r\n\r\n| File | Content |\r\n|------|---------|\r\n| `token-generation.md` | Color algorithms, HSV space, WCAG contrast, type scales |\r\n| `component-architecture.md` | Atomic design, naming conventions, props patterns |\r\n| `responsive-calculations.md` | Breakpoints, fluid typography, grid systems |\r\n| `developer-handoff.md` | Export formats, framework setup, Figma sync |\r\n\r\n---\r\n\r\n## Validation Checklist\r\n\r\n### Token Generation\r\n- [ ] Brand color provided in hex format\r\n- [ ] Style matches project requirements\r\n- [ ] All token categories generated\r\n- [ ] Semantic colors include contrast values\r\n\r\n### Component System\r\n- [ ] All sizes implemented (sm, md, lg)\r\n- [ ] All variants implemented (primary, secondary, ghost)\r\n- [ ] All states working (hover, active, focus, disabled)\r\n- [ ] Uses only design tokens (no hardcoded values)\r\n\r\n### Accessibility\r\n- [ ] Color contrast meets WCAG AA\r\n- [ ] Focus indicators visible\r\n- [ ] Touch targets ≥ 44×44px\r\n- [ ] Semantic HTML elements used\r\n\r\n### Developer Handoff\r\n- [ ] Tokens exported in required format\r\n- [ ] Framework integration documented\r\n- [ ] Design tool synced\r\n- [ ] Component documentation complete"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The ui-design-system/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/ui-design-system
  exported_at: "2026-11-03T07:42:11.308Z"