design-system-patterns

Use it when:: You're creating design tokens, adding theme switching or multi-brand themes, or building a component library.
It does:: Organizes tokens in three layers: primitives (raw values), semantic tokens (what a value means, such as text-primary) and component tokens (button-bg).
You get:: Tokens as CSS custom properties, a theme switcher that follows the system setting, and components with variant and size systems.
Also covers:: A Style Dictionary config that builds CSS, SCSS, iOS and Android files from JSON token files.

TL;DR

A reference for the foundations of a design system. Tokens are named by purpose rather than look (text-primary, not dark-gray): semantic tokens refer to primitives, and component tokens to semantic ones. Its code, mostly in a separate file, shows the three token layers as CSS custom properties, a React theme provider that switches between light, dark and the system's color-scheme setting and remembers the choice, a button with variants and sizes built with class-variance-authority, and the Style Dictionary config. It also lists, without examples, compound, polymorphic, slot-based and headless components, reduced-motion and high-contrast modes, and syncing tokens from Figma in CI. Its rules: document how each token is used, version tokens like an API with semver, test every theme with every component, automate the token pipeline and retire tokens gradually. Common problems it names are token sprawl, mixed naming conventions, tokens that ignore dark mode, hardcoded values, tokens that reference each other in loops, and tokens missing on some platforms.

Summarizes the skill at 4bde316.

npx skills add https://github.com/wshobson/agents --skill design-system-patterns

skills.sh page Source on GitHub All skills from wshobson/agents

Total Downloads: 16,700 on skills.sh, Nov 9, 2026
Repo stars: 42,334 wshobson/agents
First seen: Jan 20, 2026 on skills.sh

Weekly Downloads

262

-11% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	295
Sep 28	358
Oct 5	386
Oct 12	338
Oct 19	287
Oct 26	325
Nov 2	378
Nov 9	262

Category	category:design category:software-engineering Taste for interfaces that don't look generated: direction, motion and accessibility. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:guidelines Knowledge and rules the agent applies while it works: best practices, design principles, API references.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	design-system design
Stack	stack:react stack:style-dictionary

SKILL.md

From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.

Frontmatter

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

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)