design-system-patterns

SKILL.md

Design System Patterns

Master design system architecture to create consistent, maintainable, and scalable UI foundations across web and mobile applications.

When to Use This Skill

Creating design tokens for colors, typography, spacing, and shadows

Implementing light/dark theme switching with CSS custom properties

Building multi-brand theming systems

Architecting component libraries with consistent APIs

Establishing design-to-code workflows with Figma tokens

Creating semantic token hierarchies (primitive, semantic, component)

Setting up design system documentation and guidelines

Core Capabilities

1. Design Tokens

Primitive tokens (raw values: colors, sizes, fonts)

Semantic tokens (contextual meaning: text-primary, surface-elevated)

Component tokens (specific usage: button-bg, card-border)

Token naming conventions and organization

Multi-platform token generation (CSS, iOS, Android)

2. Theming Infrastructure

CSS custom properties architecture

Theme context providers in React

Dynamic theme switching

System preference detection (prefers-color-scheme)

Persistent theme storage

Reduced motion and high contrast modes

3. Component Architecture

Compound component patterns

Polymorphic components (as prop)

Variant and size systems

Slot-based composition

Headless UI patterns

Style props and responsive variants

4. Token Pipeline

Figma to code synchronization

Style Dictionary configuration

Token transformation and formatting

CI/CD integration for token updates

Quick Start

// Design tokens with CSS custom properties
const tokens = {
  colors: {
    // Primitive tokens
    gray: {
      50: "#fafafa",
      100: "#f5f5f5",
      900: "#171717",
    },
    blue: {
      500: "#3b82f6",
      600: "#2563eb",
    },
  },
  // Semantic tokens (reference primitives)
  semantic: {
    light: {
      "text-primary": "var(--color-gray-900)",
      "text-secondary": "var(--color-gray-600)",
      "surface-default": "var(--color-white)",
      "surface-elevated": "var(--color-gray-50)",
      "border-default": "var(--color-gray-200)",
      "interactive-primary": "var(--color-blue-500)",
    },
    dark: {
      "text-primary": "var(--color-gray-50)",
      "text-secondary": "var(--color-gray-400)",
      "surface-default": "var(--color-gray-900)",
      "surface-elevated": "var(--color-gray-800)",
      "border-default": "var(--color-gray-700)",
      "interactive-primary": "var(--color-blue-400)",
    },
  },
};

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

Best Practices

Name Tokens by Purpose: Use semantic names (text-primary) not visual descriptions (dark-gray)

Maintain Token Hierarchy: Primitives > Semantic > Component tokens

Document Token Usage: Include usage guidelines with token definitions

Version Tokens: Treat token changes as API changes with semver

Test Theme Combinations: Verify all themes work with all components

Automate Token Pipeline: CI/CD for Figma-to-code synchronization

Provide Migration Paths: Deprecate tokens gradually with clear alternatives

Common Issues

Token Sprawl: Too many tokens without clear hierarchy

Inconsistent Naming: Mixed conventions (camelCase vs kebab-case)

Missing Dark Mode: Tokens that don't adapt to theme changes

Hardcoded Values: Using raw values instead of tokens

Circular References: Tokens referencing each other in loops

Platform Gaps: Tokens missing for some platforms (web but not mobile)