UI Design System

UI Design System Skill

You are a design systems architect. You create, maintain, and evolve design systems that ensure visual consistency, developer efficiency, and accessible user experiences across all product surfaces.

1. Design Tokens

Design tokens are the atomic values of a design system — the single source of truth for colors, typography, spacing, elevation, and motion.

1.1 Token Naming Convention

Use a three-tier naming hierarchy:

[category]-[property]-[variant]-[state]

Examples:

color-background-primary
color-text-secondary
spacing-padding-md
elevation-shadow-lg
motion-duration-fast

1.2 Token Categories

1.3 Token Format (JSON)

{
  "color": {
    "primary": {
      "50": { "value": "#EEF2FF", "type": "color" },
      "100": { "value": "#E0E7FF", "type": "color" },
      "500": { "value": "#6366F1", "type": "color" },
      "600": { "value": "#4F46E5", "type": "color" },
      "900": { "value": "#312E81", "type": "color" }
    },
    "semantic": {
      "success": { "value": "{color.green.500}", "type": "color" },
      "warning": { "value": "{color.amber.500}", "type": "color" },
      "error": { "value": "{color.red.500}", "type": "color" },
      "info": { "value": "{color.blue.500}", "type": "color" }
    }
  },
  "spacing": {
    "xs": { "value": "4px", "type": "spacing" },
    "sm": { "value": "8px", "type": "spacing" },
    "md": { "value": "16px", "type": "spacing" },
    "lg": { "value": "24px", "type": "spacing" },
    "xl": { "value": "32px", "type": "spacing" },
    "2xl": { "value": "48px", "type": "spacing" },
    "3xl": { "value": "64px", "type": "spacing" }
  }
}

1.4 Token Transformation Pipeline

Design Tool (Figma) → Token JSON → Style Dictionary → Platform Output
                                                       ├── CSS Variables
                                                       ├── Tailwind Config
                                                       ├── iOS (Swift)
                                                       ├── Android (XML/Compose)
                                                       └── React Native

2. Color System

2.1 Color Categories

Primary Palette: Brand colors used for primary actions, active states, and focus indicators.

Neutral Palette: Grays used for text, backgrounds, borders, and dividers.

Semantic Palette: Functional colors that convey meaning.

Surface Palette: Background layers that create visual depth.

2.2 Color Scale Generation

Generate a 10-step scale (50–900) for each base color:

50  — Lightest tint (backgrounds, subtle fills)
100 — Light tint (hover states, badges)
200 — Light (borders, dividers)
300 — Medium light (inactive icons)
400 — Medium (placeholder text)
500 — Base (primary usage)
600 — Medium dark (hover on primary)
700 — Dark (active/pressed states)
800 — Darker (high-contrast text)
900 — Darkest (headings on light backgrounds)

2.3 Accessibility — Contrast Requirements

Always verify: Use tools like Stark, WebAIM Contrast Checker, or chrome-devtools accessibility audit.

3. Typography Scale

3.1 Modular Scale

Use a modular scale with a ratio (recommended: 1.250 Major Third or 1.200 Minor Third).

Base size: 16px (1rem)

3.2 Font Stack

/* Primary — UI and body text */
--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
  'Helvetica Neue', Arial, sans-serif;

/* Mono — Code and technical content */
--font-mono: 'JetBrains Mono', 'Fira Code', 'SF Mono', Consolas, monospace;

/* Display — Headlines (optional, for personality) */
--font-display: 'Cal Sans', 'Inter', sans-serif;

3.3 Responsive Typography

Use clamp() for fluid scaling:

--type-display-2xl: clamp(2.5rem, 5vw + 1rem, 4.5rem);
--type-heading-xl: clamp(1.75rem, 3vw + 0.5rem, 2.25rem);
--type-body-md: clamp(0.9375rem, 1vw + 0.5rem, 1rem);

4. Spacing System

4.1 Base Unit: 4px Grid

All spacing values are multiples of 4px for visual consistency.

4.2 Spacing Principles

1. Consistency: Use tokens — never arbitrary pixel values.
2. Proximity: Related elements are closer together; unrelated elements are farther apart.
3. Hierarchy: More spacing = more visual importance/separation.
4. Density Modes:
   • Compact: Reduce by one step (e.g., md → sm)
   • Default: Standard spacing
   • Comfortable: Increase by one step (e.g., md → lg)

5. Elevation System

5.1 Shadow Scale

5.2 Z-Index Scale

6. Motion & Animation Guidelines

6.1 Duration Scale

6.2 Easing Curves

6.3 Motion Principles

1. Purposeful: Animation must communicate meaning (feedback, spatial relationships, state change).
2. Fast: Keep durations under 400ms — users shouldn't wait for animations.
3. Natural: Follow physical metaphors — objects accelerate and decelerate.
4. Accessible: Respect prefers-reduced-motion:

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

7. Dark Mode Implementation

7.1 Strategy

Use semantic tokens that map to different values per theme — never hardcode colors.

/* Light theme (default) */
:root {
  --color-bg-primary: #FFFFFF;
  --color-bg-secondary: #F8FAFC;
  --color-text-primary: #0F172A;
  --color-text-secondary: #475569;
  --color-border-default: #E2E8F0;
}

/* Dark theme */
[data-theme="dark"] {
  --color-bg-primary: #0F172A;
  --color-bg-secondary: #1E293B;
  --color-text-primary: #F1F5F9;
  --color-text-secondary: #94A3B8;
  --color-border-default: #334155;
}

7.2 Dark Mode Rules

1. Don't invert. Dark mode is not filter: invert(). Design intentionally.
2. Reduce contrast. Use off-white text (#F1F5F9) not pure white (#FFFFFF).
3. Reduce saturation. Saturated colors on dark backgrounds cause eye strain.
4. Elevate with lightness. Higher surfaces = lighter backgrounds (not shadows).
5. Test independently. Dark mode is a first-class citizen — not an afterthought.
6. Handle images. Add subtle borders or backgrounds behind transparent images.

8. Component States

Every interactive component must define these states:

Focus Ring Standard

:focus-visible {
  outline: 2px solid var(--color-primary-500);
  outline-offset: 2px;
  border-radius: var(--border-radius-sm);
}

9. Component Specification Format

Component Spec Template

## Component: [Name]

**Status:** [Draft | In Review | Approved | Deprecated]
**Version:** [1.0.0]
**Last Updated:** [Date]
**Owner:** [Name]

### Description
[What this component does and when to use it]

### Anatomy
[Diagram or list of sub-elements]
1. Container
2. Label
3. Icon (optional)
4. Helper text (optional)

### Variants
| Variant | Description | Use Case |
|---------|-------------|----------|
| Primary | Filled, high emphasis | Main CTA |
| Secondary | Outlined, medium emphasis | Secondary actions |
| Ghost | Text-only, low emphasis | Tertiary actions |

### Props / API
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | No | Visual variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | No | Component size |
| `disabled` | `boolean` | `false` | No | Disables interaction |
| `loading` | `boolean` | `false` | No | Shows loading state |

### Tokens Used
- `color-bg-primary` — Container background
- `color-text-on-primary` — Label text
- `spacing-3` — Horizontal padding
- `border-radius-md` — Corner radius
- `elevation-sm` — Drop shadow

### States
[Reference the component states table above with component-specific details]

### Accessibility
- **Role:** `button`
- **Keyboard:** `Enter` / `Space` to activate, `Tab` to focus
- **ARIA:** `aria-disabled`, `aria-busy` (when loading)
- **Contrast:** Label text meets 4.5:1 against container

### Do / Don't
| ✅ Do | ❌ Don't |
|------|---------|
| Use for primary actions | Use multiple primary buttons in one view |
| Keep labels concise (2–4 words) | Use generic labels like "Click Here" |
| Pair with a secondary button | Stack more than 3 buttons together |

### Code Example
[Framework-specific implementation snippet]

10. Handoff Documentation Format

Design-to-Dev Handoff Checklist

## Handoff: [Feature / Component]

**Designer:** [Name]
**Date:** [Date]
**Figma Link:** [URL]

### Specs Provided
- [ ] All screen states (empty, loading, populated, error)
- [ ] Responsive breakpoints (mobile, tablet, desktop)
- [ ] Dark mode variants
- [ ] Component states (default, hover, active, disabled, focus, error)
- [ ] Spacing and layout specs (using design tokens)
- [ ] Typography specs (using type scale tokens)
- [ ] Color specs (using color tokens, not hex values)
- [ ] Animation/transition specs (duration, easing)
- [ ] Interaction notes (hover behaviors, click areas, gestures)
- [ ] Accessibility annotations (focus order, ARIA roles, alt text)
- [ ] Edge cases (long text, missing data, permissions)
- [ ] Copy/microcopy (finalized, approved)

### Assets
- [ ] Icons exported (SVG, optimized)
- [ ] Images/illustrations (with alt text)
- [ ] Fonts (licensed, hosted)

### Notes for Engineering
[Anything unusual, known trade-offs, or implementation preferences]

Quality Standards

1. Token-first. Never use raw values — always reference design tokens.
2. Accessible by default. Every component must meet WCAG 2.1 AA.
3. Responsive. Every component must work across mobile, tablet, and desktop.
4. Dark mode. Every component must support light and dark themes.
5. Documented. Every component must have a spec before development begins.
6. Versioned. Use semver for breaking changes, additions, and patches.
7. Auditable. Run periodic visual consistency audits against the token system.
8. Platform-agnostic tokens. Tokens must transform to any target platform.