UI Design System Skill | Agent Skills

UI Design System

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

Trigger Terms
Workflows
Tool Reference
Quick Reference Tables
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"

Clarify First

Before generating the tokens or system, confirm these inputs. If any is unknown or vague, ASK — do not assume:

[ ] Brand primary color (hex) — the seed for the full palette (drives the color scale and WCAG contrast checks)
[ ] Style preset — modern, classic, or playful (sets fonts, border radius, and shadow style)
[ ] Output format and framework — CSS, SCSS, or JSON for Tailwind/styled-components/Figma (drives export and developer handoff)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1: Generate Design Tokens

Situation: You have a brand color and need a complete design token system.

Steps:

Identify brand color and style
- Brand primary color (hex format)
- Style preference: modern | classic | playful

Generate tokens using script

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

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

Export in target format

# 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

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:

Define component hierarchy
- Atoms: Button, Input, Icon, Label, Badge
- Molecules: FormField, SearchBar, Card, ListItem
- Organisms: Header, Footer, DataTable, Modal
- Templates: DashboardLayout, AuthLayout
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 |

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

Document component API
- Props interface with types
- Variant options
- State handling (hover, active, focus, disabled)
- Accessibility requirements
Reference: See references/component-architecture.md

Workflow 3: Responsive Design

Situation: You need breakpoints, fluid typography, or responsive spacing.

Steps:

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 |

Calculate fluid typography

Formula: clamp(min, preferred, max)

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

Pre-calculated scales:

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

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 |
Reference: See references/responsive-calculations.md

Workflow 4: Developer Handoff

Situation: You need to hand off design tokens to development team.

Steps:

Export tokens in required formats

# 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

Prepare framework integration

React + CSS Variables:

import './design-tokens.css';

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

Tailwind Config:

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

module.exports = {
  theme: {
    colors: tokens.colors,
    fontFamily: tokens.typography.fontFamily
  }
};

styled-components:

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

const Button = styled.button`
  background: ${tokens.colors.primary['500']};
  padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
`;

Sync with Figma
- Install Tokens Studio plugin
- Import design-tokens.json
- Tokens sync automatically with Figma styles
Handoff checklist
- [ ] Token files added to project
- [ ] Build pipeline configured
- [ ] Theme/CSS variables imported
- [ ] Component library aligned
- [ ] Documentation generated
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% | 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

Troubleshooting

| Problem | Cause | Solution | |---------|-------|----------| | Generated colors fail WCAG contrast | Brand color too light or too saturated | Use darker shades (600+) for text on light backgrounds; check with contrast tool | | Token export has incorrect values | Wrong format argument or color syntax | Ensure hex color is quoted (e.g. "#0066CC"); verify format is json, css, or scss | | Typography scale too large/small | Default 1.25x ratio doesn't fit design | Modify type_scale_ratio in DesignTokenGenerator class (1.125 for tighter, 1.333 for looser) | | SCSS variables conflict with existing | Token naming collision | Prefix all tokens with project namespace (edit export function) | | Design tools show different colors | Hex rounding in color scale generation | Use JSON export as source of truth; sync with Tokens Studio plugin | | Spacing values don't align with grid | Custom spacing mixed with 8pt grid | Use only values from the generated spacing system; avoid arbitrary pixel values | | Shadow tokens look wrong in dark mode | Shadows designed for light backgrounds | Create separate dark-mode shadow tokens with lighter opacity values |

Success Criteria

| Criterion | Target | How to Measure | |-----------|--------|----------------| | Token consistency | Zero hardcoded color/spacing values in codebase | Lint rule violations count | | WCAG AA compliance | All text colors meet 4.5:1 contrast ratio | Automated contrast checker or manual audit | | Export format coverage | CSS, SCSS, and JSON all generate correctly | Run generator with each format; validate output | | Design-dev sync | <24h between token update and code deployment | Time from Figma change to production | | Component token coverage | 100% of components use design tokens | Audit component styles for hardcoded values | | Typography consistency | All text uses design system type scale | Visual audit across all pages | | Responsive behavior | Fluid typography works across all breakpoints | Test at xs, sm, md, lg, xl, 2xl widths |

Scope & Limitations

In scope:

Complete design token generation from brand color
Color palette generation (primary, secondary, neutral, semantic)
Typography system with modular scale
8pt grid-based spacing system
Component sizing, border, shadow, animation tokens
Export to CSS custom properties, SCSS variables, and JSON
Responsive breakpoint definitions
WCAG contrast reference tables

Out of scope:

Dark mode token generation (requires separate palette mapping)
Animation/motion design library
Icon system generation
Runtime theme switching implementation
Figma plugin or API integration (use Tokens Studio)
Visual regression testing
Design-to-code conversion (use Figma Dev Mode or Locofy)

Integration Points

| Tool / Platform | Integration Method | Use Case | |-----------------|-------------------|----------| | Figma / Tokens Studio | Import JSON output as token source | Sync design tool with code tokens | | Tailwind CSS | JSON tokens as tailwind.config.js theme | Configure Tailwind from design system | | styled-components / Emotion | Import JSON tokens in theme provider | CSS-in-JS theming | | Style Dictionary | Use JSON output as source tokens | Multi-platform token build (iOS, Android, web) | | Storybook | Pair tokens with component stories | Document component visual variations | | CI/CD | Token generation in build pipeline | Automated token updates on brand change |

Agent Skills: UI Design System

Install this agent skill to your local

Skill Files

UI Design System

Table of Contents

Trigger Terms

Clarify First

Workflows

Workflow 1: Generate Design Tokens

Workflow 2: Create Component System

Workflow 3: Responsive Design

Workflow 4: Developer Handoff

Tool Reference

design_token_generator.py

Quick Reference Tables

Color Scale Generation

Typography Scale (1.25x Ratio)

WCAG Contrast Requirements

Style Presets

Knowledge Base

Validation Checklist

Token Generation

Component System

Accessibility

Developer Handoff

Troubleshooting

Success Criteria

Scope & Limitations

Integration Points