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

typescript
1// Design tokens with CSS custom properties
2const tokens = {
3  colors: {
4    // Primitive tokens
5    gray: {
6      50: "#fafafa",
7      100: "#f5f5f5",
8      900: "#171717",
9    },
10    blue: {
11      500: "#3b82f6",
12      600: "#2563eb",
13    },
14  },
15  // Semantic tokens (reference primitives)
16  semantic: {
17    light: {
18      "text-primary": "var(--color-gray-900)",
19      "text-secondary": "var(--color-gray-600)",
20      "surface-default": "var(--color-white)",
21      "surface-elevated": "var(--color-gray-50)",
22      "border-default": "var(--color-gray-200)",
23      "interactive-primary": "var(--color-blue-500)",
24    },
25    dark: {
26      "text-primary": "var(--color-gray-50)",
27      "text-secondary": "var(--color-gray-400)",
28      "surface-default": "var(--color-gray-900)",
29      "surface-elevated": "var(--color-gray-800)",
30      "border-default": "var(--color-gray-700)",
31      "interactive-primary": "var(--color-blue-400)",
32    },
33  },
34};

Key Patterns

Pattern 1: Token Hierarchy

css
1/* Layer 1: Primitive tokens (raw values) */
2:root {
3  --color-blue-500: #3b82f6;
4  --color-blue-600: #2563eb;
5  --color-gray-50: #fafafa;
6  --color-gray-900: #171717;
7
8  --space-1: 0.25rem;
9  --space-2: 0.5rem;
10  --space-4: 1rem;
11
12  --font-size-sm: 0.875rem;
13  --font-size-base: 1rem;
14  --font-size-lg: 1.125rem;
15
16  --radius-sm: 0.25rem;
17  --radius-md: 0.5rem;
18  --radius-lg: 1rem;
19}
20
21/* Layer 2: Semantic tokens (meaning) */
22:root {
23  --text-primary: var(--color-gray-900);
24  --text-secondary: var(--color-gray-600);
25  --surface-default: white;
26  --interactive-primary: var(--color-blue-500);
27  --interactive-primary-hover: var(--color-blue-600);
28}
29
30/* Layer 3: Component tokens (specific usage) */
31:root {
32  --button-bg: var(--interactive-primary);
33  --button-bg-hover: var(--interactive-primary-hover);
34  --button-text: white;
35  --button-radius: var(--radius-md);
36  --button-padding-x: var(--space-4);
37  --button-padding-y: var(--space-2);
38}

Pattern 2: Theme Switching with React

tsx
1import { createContext, useContext, useEffect, useState } from "react";
2
3type Theme = "light" | "dark" | "system";
4
5interface ThemeContextValue {
6  theme: Theme;
7  resolvedTheme: "light" | "dark";
8  setTheme: (theme: Theme) => void;
9}
10
11const ThemeContext = createContext<ThemeContextValue | null>(null);
12
13export function ThemeProvider({ children }: { children: React.ReactNode }) {
14  const [theme, setTheme] = useState<Theme>(() => {
15    if (typeof window !== "undefined") {
16      return (localStorage.getItem("theme") as Theme) || "system";
17    }
18    return "system";
19  });
20
21  const [resolvedTheme, setResolvedTheme] = useState<"light" | "dark">("light");
22
23  useEffect(() => {
24    const root = document.documentElement;
25
26    const applyTheme = (isDark: boolean) => {
27      root.classList.remove("light", "dark");
28      root.classList.add(isDark ? "dark" : "light");
29      setResolvedTheme(isDark ? "dark" : "light");
30    };
31
32    if (theme === "system") {
33      const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
34      applyTheme(mediaQuery.matches);
35
36      const handler = (e: MediaQueryListEvent) => applyTheme(e.matches);
37      mediaQuery.addEventListener("change", handler);
38      return () => mediaQuery.removeEventListener("change", handler);
39    } else {
40      applyTheme(theme === "dark");
41    }
42  }, [theme]);
43
44  useEffect(() => {
45    localStorage.setItem("theme", theme);
46  }, [theme]);
47
48  return (
49    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
50      {children}
51    </ThemeContext.Provider>
52  );
53}
54
55export const useTheme = () => {
56  const context = useContext(ThemeContext);
57  if (!context) throw new Error("useTheme must be used within ThemeProvider");
58  return context;
59};

Pattern 3: Variant System with CVA

tsx
1import { cva, type VariantProps } from "class-variance-authority";
2import { cn } from "@/lib/utils";
3
4const buttonVariants = cva(
5  // Base styles
6  "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",
7  {
8    variants: {
9      variant: {
10        default: "bg-primary text-primary-foreground hover:bg-primary/90",
11        destructive:
12          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
13        outline:
14          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
15        secondary:
16          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
17        ghost: "hover:bg-accent hover:text-accent-foreground",
18        link: "text-primary underline-offset-4 hover:underline",
19      },
20      size: {
21        sm: "h-9 px-3 text-sm",
22        md: "h-10 px-4 text-sm",
23        lg: "h-11 px-8 text-base",
24        icon: "h-10 w-10",
25      },
26    },
27    defaultVariants: {
28      variant: "default",
29      size: "md",
30    },
31  },
32);
33
34interface ButtonProps
35  extends
36    React.ButtonHTMLAttributes<HTMLButtonElement>,
37    VariantProps<typeof buttonVariants> {
38  asChild?: boolean;
39}
40
41export function Button({ className, variant, size, ...props }: ButtonProps) {
42  return (
43    <button
44      className={cn(buttonVariants({ variant, size, className }))}
45      {...props}
46    />
47  );
48}

Pattern 4: Style Dictionary Configuration

javascript
1// style-dictionary.config.js
2module.exports = {
3  source: ["tokens/**/*.json"],
4  platforms: {
5    css: {
6      transformGroup: "css",
7      buildPath: "dist/css/",
8      files: [
9        {
10          destination: "variables.css",
11          format: "css/variables",
12          options: {
13            outputReferences: true, // Preserve token references
14          },
15        },
16      ],
17    },
18    scss: {
19      transformGroup: "scss",
20      buildPath: "dist/scss/",
21      files: [
22        {
23          destination: "_variables.scss",
24          format: "scss/variables",
25        },
26      ],
27    },
28    ios: {
29      transformGroup: "ios-swift",
30      buildPath: "dist/ios/",
31      files: [
32        {
33          destination: "DesignTokens.swift",
34          format: "ios-swift/class.swift",
35          className: "DesignTokens",
36        },
37      ],
38    },
39    android: {
40      transformGroup: "android",
41      buildPath: "dist/android/",
42      files: [
43        {
44          destination: "colors.xml",
45          format: "android/colors",
46          filter: { attributes: { category: "color" } },
47        },
48      ],
49    },
50  },
51};

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)

Resources

• Style Dictionary Documentation
• Tokens Studio for Figma
• Design Tokens W3C Spec
• Radix UI Themes
• shadcn/ui Theming