Build scalable design systems with design tokens

Design system patterns

by wshobson · MIT license · ★ 39,857 on GitHub · updated Sep 21

Build scalable design systems with design tokens, theming infrastructure, and component architecture patterns. Use when creating design tokens, implementing theme switching, building component libraries, or establishing design system…

---
name: design-system-patterns
description: Build scalable design systems with design tokens, theming infrastructure, and component architecture patterns. Use when creating design tokens, implementing theme switching, building component libraries, or establishing design system foundations.
---

# 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

Overview

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

Manual install (npx, ZIP)

Claude Codenpx skills add wshobson/agents --skill design-system-patterns -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/wshobson/agents/tar.gz/4236bb91f839 \
  | tar -xz -C ~/.claude/skills --strip-components=4 agents-4236bb91f839/plugins/ui-design/skills/design-system-patterns

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/4066e08159ca4e4c34e9/design-system-patterns.zip" -OutFile "$env:TEMP\design-system-patterns.zip"; Expand-Archive "$env:TEMP\design-system-patterns.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md3.9 KB
references/4 files · 43.5 KB

Read the files here

wshobson/4236bb95 files

SKILL.md3.9 KB

SKILL.md

Show the full text116 lines

design-system-patterns/SKILL.md116 lines · 3.9 KB

PreviewCode

Outline

RawView on GitHub

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)

1	---
2	name: design-system-patterns
3	description: Build scalable design systems with design tokens, theming infrastructure, and component architecture patterns. Use when creating design tokens, implementing theme switching, building component libraries, or establishing design system foundations.
4	---
5
6	# Design System Patterns
7
8	Master design system architecture to create consistent, maintainable, and scalable UI foundations across web and mobile applications.
9
10	## When to Use This Skill
11
12	- Creating design tokens for colors, typography, spacing, and shadows
13	- Implementing light/dark theme switching with CSS custom properties
14	- Building multi-brand theming systems
15	- Architecting component libraries with consistent APIs
16	- Establishing design-to-code workflows with Figma tokens
17	- Creating semantic token hierarchies (primitive, semantic, component)
18	- Setting up design system documentation and guidelines
19
20	## Core Capabilities
21
22	### 1. Design Tokens
23
24	- Primitive tokens (raw values: colors, sizes, fonts)
25	- Semantic tokens (contextual meaning: text-primary, surface-elevated)
26	- Component tokens (specific usage: button-bg, card-border)
27	- Token naming conventions and organization
28	- Multi-platform token generation (CSS, iOS, Android)
29
30	### 2. Theming Infrastructure
31
32	- CSS custom properties architecture
33	- Theme context providers in React
34	- Dynamic theme switching
35	- System preference detection (prefers-color-scheme)
36	- Persistent theme storage
37	- Reduced motion and high contrast modes
38
39	### 3. Component Architecture
40
41	- Compound component patterns
42	- Polymorphic components (as prop)
43	- Variant and size systems
44	- Slot-based composition
45	- Headless UI patterns
46	- Style props and responsive variants
47
48	### 4. Token Pipeline
49
50	- Figma to code synchronization
51	- Style Dictionary configuration
52	- Token transformation and formatting
53	- CI/CD integration for token updates
54
55	## Quick Start
56
57	```typescript
58	// Design tokens with CSS custom properties
59	const tokens = {
60	colors: {
61	// Primitive tokens
62	gray: {
63	50: "#fafafa",
64	100: "#f5f5f5",
65	900: "#171717",
66	},
67	blue: {
68	500: "#3b82f6",
69	600: "#2563eb",
70	},
71	},
72	// Semantic tokens (reference primitives)
73	semantic: {
74	light: {
75	"text-primary": "var(--color-gray-900)",
76	"text-secondary": "var(--color-gray-600)",
77	"surface-default": "var(--color-white)",
78	"surface-elevated": "var(--color-gray-50)",
79	"border-default": "var(--color-gray-200)",
80	"interactive-primary": "var(--color-blue-500)",
81	},
82	dark: {
83	"text-primary": "var(--color-gray-50)",
84	"text-secondary": "var(--color-gray-400)",
85	"surface-default": "var(--color-gray-900)",
86	"surface-elevated": "var(--color-gray-800)",
87	"border-default": "var(--color-gray-700)",
88	"interactive-primary": "var(--color-blue-400)",
89	},
90	},
91	};
92	```
93
94	## Detailed patterns and worked examples
95
96	Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
97
98	## Best Practices
99
100	1. Name Tokens by Purpose: Use semantic names (text-primary) not visual descriptions (dark-gray)
101	2. Maintain Token Hierarchy: Primitives > Semantic > Component tokens
102	3. Document Token Usage: Include usage guidelines with token definitions
103	4. Version Tokens: Treat token changes as API changes with semver
104	5. Test Theme Combinations: Verify all themes work with all components
105	6. Automate Token Pipeline: CI/CD for Figma-to-code synchronization
106	7. Provide Migration Paths: Deprecate tokens gradually with clear alternatives
107
108	## Common Issues
109
110	- Token Sprawl: Too many tokens without clear hierarchy
111	- Inconsistent Naming: Mixed conventions (camelCase vs kebab-case)
112	- Missing Dark Mode: Tokens that don't adapt to theme changes
113	- Hardcoded Values: Using raw values instead of tokens
114	- Circular References: Tokens referencing each other in loops
115	- Platform Gaps: Tokens missing for some platforms (web but not mobile)
116