---
id: sm-design-system-patterns
name: "design-system-patterns"
url: https://skills.yangsir.net/skill/sm-design-system-patterns
author: wshobson
domain: design
tags: ["design-systems", "ui/ux-patterns", "component-libraries", "brand-guidelines", "figma/sketch"]
install_count: 9700
rating: 4.50 (35 reviews)
github: https://github.com/wshobson/agents
---

# design-system-patterns

> 专注于设计系统模式，结合智能自动化和多智能体编排，统一设计规范，提升产品一致性和开发效率。

**Stats**: 9,700 installs · 4.5/5 (35 reviews)

## Before / After 对比

### 设计系统一致性与开发效率

| Metric | Before | After | Change |
|---|---|---|---|
| - | - | - | - |
| - | - | - | - |

## Readme

# 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 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)",
    },
  },
};

```

## Key Patterns

### Pattern 1: Token Hierarchy

```
/* Layer 1: Primitive tokens (raw values) */
:root {
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-gray-50: #fafafa;
  --color-gray-900: #171717;

  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;

  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;

  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 1rem;
}

/* Layer 2: Semantic tokens (meaning) */
:root {
  --text-primary: var(--color-gray-900);
  --text-secondary: var(--color-gray-600);
  --surface-default: white;
  --interactive-primary: var(--color-blue-500);
  --interactive-primary-hover: var(--color-blue-600);
}

/* Layer 3: Component tokens (specific usage) */
:root {
  --button-bg: var(--interactive-primary);
  --button-bg-hover: var(--interactive-primary-hover);
  --button-text: white;
  --button-radius: var(--radius-md);
  --button-padding-x: var(--space-4);
  --button-padding-y: var(--space-2);
}

```

### Pattern 2: Theme Switching with React

```
import { createContext, useContext, useEffect, useState } from "react";

type Theme = "light" | "dark" | "system";

interface ThemeContextValue {
  theme: Theme;
  resolvedTheme: "light" | "dark";
  setTheme: (theme: Theme) => void;
}

const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>(() => {
    if (typeof window !== "undefined") {
      return (localStorage.getItem("theme") as Theme) || "system";
    }
    return "system";
  });

  const [resolvedTheme, setResolvedTheme] = useState<"light" | "dark">("light");

  useEffect(() => {
    const root = document.documentElement;

    const applyTheme = (isDark: boolean) => {
      root.classList.remove("light", "dark");
      root.classList.add(isDark ? "dark" : "light");
      setResolvedTheme(isDark ? "dark" : "light");
    };

    if (theme === "system") {
      const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
      applyTheme(mediaQuery.matches);

      const handler = (e: MediaQueryListEvent) => applyTheme(e.matches);
      mediaQuery.addEventListener("change", handler);
      return () => mediaQuery.removeEventListener("change", handler);
    } else {
      applyTheme(theme === "dark");
    }
  }, [theme]);

  useEffect(() => {
    localStorage.setItem("theme", theme);
  }, [theme]);

  return (
    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => {
  const context = useContext(ThemeContext);
  if (!context) throw new Error("useTheme must be used within ThemeProvider");
  return context;
};

```

### Pattern 3: Variant System with CVA

```
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const buttonVariants = cva(
  // Base styles
  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive:
          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline:
          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        secondary:
          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        sm: "h-9 px-3 text-sm",
        md: "h-10 px-4 text-sm",
        lg: "h-11 px-8 text-base",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "md",
    },
  },
);

interface ButtonProps
  extends
    React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

export function Button({ className, variant, size, ...props }: ButtonProps) {
  return (
    <button
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  );
}

```

### Pattern 4: Style Dictionary Configuration

```
// style-dictionary.config.js
module.exports = {
  source: ["tokens/**/*.json"],
  platforms: {
    css: {
      transformGroup: "css",
      buildPath: "dist/css/",
      files: [
        {
          destination: "variables.css",
          format: "css/variables",
          options: {
            outputReferences: true, // Preserve token references
          },
        },
      ],
    },
    scss: {
      transformGroup: "scss",
      buildPath: "dist/scss/",
      files: [
        {
          destination: "_variables.scss",
          format: "scss/variables",
        },
      ],
    },
    ios: {
      transformGroup: "ios-swift",
      buildPath: "dist/ios/",
      files: [
        {
          destination: "DesignTokens.swift",
          format: "ios-swift/class.swift",
          className: "DesignTokens",
        },
      ],
    },
    android: {
      transformGroup: "android",
      buildPath: "dist/android/",
      files: [
        {
          destination: "colors.xml",
          format: "android/colors",
          filter: { attributes: { category: "color" } },
        },
      ],
    },
  },
};

```

## 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)

Weekly Installs4.9KRepository[wshobson/agents](https://github.com/wshobson/agents)GitHub Stars31.5KFirst SeenJan 20, 2026Security Audits[Gen Agent Trust HubPass](/wshobson/agents/design-system-patterns/security/agent-trust-hub)[SocketPass](/wshobson/agents/design-system-patterns/security/socket)[SnykPass](/wshobson/agents/design-system-patterns/security/snyk)Installed onopencode3.7Kgemini-cli3.7Kclaude-code3.5Kcodex3.5Kcursor3.4Kgithub-copilot3.1K

---
*Source: https://skills.yangsir.net/skill/sm-design-system-patterns*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-design-system-patterns/markdown*