Design System Patterns

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

1. Name Tokens by Purpose: Use semantic names (text-primary) not visual descriptions (dark-gray)
2. Maintain Token Hierarchy: Primitives > Semantic > Component tokens
3. Document Token Usage: Include usage guidelines with token definitions
4. Version Tokens: Treat token changes as API changes with semver
5. Test Theme Combinations: Verify all themes work with all components
6. Automate Token Pipeline: CI/CD for Figma-to-code synchronization
7. 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)