name: design-system-manager description: Create and manage design systems with Tailwind CSS 4, design tokens, theming, and component documentation allowed-tools:

Read
Write
Edit
Bash
Glob
Grep
Task

Design System Manager

Expert skill for creating and maintaining scalable design systems. Specializes in Tailwind CSS 4, design tokens, theming systems, color palettes, and typography scales.

Technology Stack (2025)

Styling

Tailwind CSS 4.0 - CSS-first config, cascade layers, @theme
CSS Variables - Runtime theming
oklch() - Perceptually uniform colors
@property - Registered custom properties

Tools

Style Dictionary 4 - Token transformation
Radix Colors - Accessible color system
colord - Color manipulation
Figma Tokens - Design-to-code sync

Tailwind CSS 4.0 Configuration

CSS-First Configuration

/* app.css */
@import "tailwindcss";

@theme {
  /* Colors using oklch for better interpolation */
  --color-primary: oklch(0.7 0.15 250);
  --color-primary-hover: oklch(0.6 0.15 250);
  --color-secondary: oklch(0.65 0.12 280);

  --color-background: oklch(0.99 0.005 250);
  --color-foreground: oklch(0.15 0.01 250);

  --color-muted: oklch(0.95 0.01 250);
  --color-muted-foreground: oklch(0.45 0.02 250);

  --color-accent: oklch(0.92 0.02 250);
  --color-accent-foreground: oklch(0.15 0.01 250);

  --color-destructive: oklch(0.55 0.2 25);
  --color-destructive-foreground: oklch(0.98 0.01 250);

  --color-success: oklch(0.6 0.18 145);
  --color-warning: oklch(0.75 0.18 85);

  /* Typography */
  --font-sans: "Inter Variable", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;
  --text-4xl: 2.25rem;

  /* Spacing (4px grid) */
  --spacing-0: 0;
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-3: 0.75rem;
  --spacing-4: 1rem;
  --spacing-5: 1.25rem;
  --spacing-6: 1.5rem;
  --spacing-8: 2rem;
  --spacing-10: 2.5rem;
  --spacing-12: 3rem;
  --spacing-16: 4rem;

  /* Border Radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;
  --radius-2xl: 1rem;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 oklch(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px oklch(0 0 0 / 0.1), 0 2px 4px -2px oklch(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px oklch(0 0 0 / 0.1), 0 4px 6px -4px oklch(0 0 0 / 0.1);

  /* Transitions */
  --duration-fast: 150ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;
  --easing-default: cubic-bezier(0.4, 0, 0.2, 1);
}

/* Dark Mode */
@media (prefers-color-scheme: dark) {
  @theme {
    --color-background: oklch(0.15 0.01 250);
    --color-foreground: oklch(0.95 0.01 250);
    --color-muted: oklch(0.25 0.01 250);
    --color-muted-foreground: oklch(0.65 0.02 250);
    --color-accent: oklch(0.25 0.02 250);
    --color-accent-foreground: oklch(0.95 0.01 250);
  }
}

/* Class-based dark mode */
.dark {
  @theme {
    --color-background: oklch(0.15 0.01 250);
    --color-foreground: oklch(0.95 0.01 250);
  }
}

Theme Provider (React 19)

// theme-provider.tsx
'use client'

import { createContext, useContext, useEffect, useState, type ReactNode } from 'react'

type Theme = 'light' | 'dark' | 'system'

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

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

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

interface ThemeProviderProps {
  children: ReactNode
  defaultTheme?: Theme
  storageKey?: string
}

export function ThemeProvider({
  children,
  defaultTheme = 'system',
  storageKey = 'ui-theme',
}: ThemeProviderProps) {
  const [theme, setTheme] = useState<Theme>(defaultTheme)
  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>('light')

  useEffect(() => {
    const stored = localStorage.getItem(storageKey) as Theme | null
    if (stored) setTheme(stored)
  }, [storageKey])

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

    const applyTheme = (t: 'light' | 'dark') => {
      root.classList.remove('light', 'dark')
      root.classList.add(t)
      setResolvedTheme(t)
    }

    if (theme === 'system') {
      const media = window.matchMedia('(prefers-color-scheme: dark)')
      applyTheme(media.matches ? 'dark' : 'light')

      const handler = (e: MediaQueryListEvent) => applyTheme(e.matches ? 'dark' : 'light')
      media.addEventListener('change', handler)
      return () => media.removeEventListener('change', handler)
    } else {
      applyTheme(theme)
    }
  }, [theme])

  const handleSetTheme = (newTheme: Theme) => {
    setTheme(newTheme)
    localStorage.setItem(storageKey, newTheme)
  }

  return (
    <ThemeContext value={{ theme, setTheme: handleSetTheme, resolvedTheme }}>
      {children}
    </ThemeContext>
  )
}

Color System

Color Palette Generator

// color-utils.ts
import { colord, extend } from 'colord'
import a11yPlugin from 'colord/plugins/a11y'

extend([a11yPlugin])

export function generateColorScale(baseColor: string) {
  const base = colord(baseColor)

  return {
    50: base.lighten(0.45).toHex(),
    100: base.lighten(0.4).toHex(),
    200: base.lighten(0.3).toHex(),
    300: base.lighten(0.2).toHex(),
    400: base.lighten(0.1).toHex(),
    500: baseColor,
    600: base.darken(0.1).toHex(),
    700: base.darken(0.2).toHex(),
    800: base.darken(0.3).toHex(),
    900: base.darken(0.4).toHex(),
    950: base.darken(0.45).toHex(),
  }
}

export function checkContrast(foreground: string, background: string) {
  const contrast = colord(foreground).contrast(background)

  return {
    ratio: contrast.toFixed(2),
    passesAA: contrast >= 4.5,
    passesAAA: contrast >= 7,
    passesAALarge: contrast >= 3,
  }
}

OKLCH Color Utilities

// oklch-utils.ts
export function oklch(l: number, c: number, h: number, a = 1) {
  return `oklch(${l} ${c} ${h}${a < 1 ? ` / ${a}` : ''})`
}

export const colors = {
  primary: {
    DEFAULT: 'var(--color-primary)',
    hover: 'var(--color-primary-hover)',
  },
  background: 'var(--color-background)',
  foreground: 'var(--color-foreground)',
  muted: {
    DEFAULT: 'var(--color-muted)',
    foreground: 'var(--color-muted-foreground)',
  },
}

Typography System

Fluid Typography with clamp()

@theme {
  /* Fluid type scale */
  --text-fluid-xs: clamp(0.69rem, 0.66rem + 0.16vw, 0.75rem);
  --text-fluid-sm: clamp(0.83rem, 0.78rem + 0.24vw, 0.94rem);
  --text-fluid-base: clamp(1rem, 0.93rem + 0.36vw, 1.19rem);
  --text-fluid-lg: clamp(1.2rem, 1.09rem + 0.53vw, 1.48rem);
  --text-fluid-xl: clamp(1.44rem, 1.29rem + 0.75vw, 1.86rem);
  --text-fluid-2xl: clamp(1.73rem, 1.52rem + 1.05vw, 2.33rem);
  --text-fluid-3xl: clamp(2.07rem, 1.78rem + 1.47vw, 2.91rem);
}

Text Styles

// text-styles.ts
export const textStyles = {
  h1: 'text-4xl font-bold tracking-tight',
  h2: 'text-3xl font-semibold tracking-tight',
  h3: 'text-2xl font-semibold',
  h4: 'text-xl font-semibold',
  body: 'text-base',
  small: 'text-sm text-muted-foreground',
  code: 'font-mono text-sm',
}

Spacing System

4px Grid System

@theme {
  --spacing-px: 1px;
  --spacing-0: 0;
  --spacing-0.5: 0.125rem;  /* 2px */
  --spacing-1: 0.25rem;     /* 4px */
  --spacing-1.5: 0.375rem;  /* 6px */
  --spacing-2: 0.5rem;      /* 8px */
  --spacing-2.5: 0.625rem;  /* 10px */
  --spacing-3: 0.75rem;     /* 12px */
  --spacing-3.5: 0.875rem;  /* 14px */
  --spacing-4: 1rem;        /* 16px */
  --spacing-5: 1.25rem;     /* 20px */
  --spacing-6: 1.5rem;      /* 24px */
  --spacing-7: 1.75rem;     /* 28px */
  --spacing-8: 2rem;        /* 32px */
  --spacing-9: 2.25rem;     /* 36px */
  --spacing-10: 2.5rem;     /* 40px */
  --spacing-12: 3rem;       /* 48px */
  --spacing-14: 3.5rem;     /* 56px */
  --spacing-16: 4rem;       /* 64px */
  --spacing-20: 5rem;       /* 80px */
  --spacing-24: 6rem;       /* 96px */
}

Component Tokens

// component-tokens.ts
export const componentTokens = {
  button: {
    sm: 'h-9 px-3 text-sm',
    md: 'h-10 px-4',
    lg: 'h-11 px-8',
    icon: 'h-10 w-10',
  },
  input: {
    height: 'h-10',
    padding: 'px-3 py-2',
    border: 'border border-input',
    focus: 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
  },
  card: {
    padding: 'p-6',
    border: 'border rounded-lg',
    shadow: 'shadow-sm',
  },
}

Best Practices

Design Tokens

Three-Tier System: Primitive → Semantic → Component
Meaningful Names: color-primary not color-blue
Single Source of Truth: Define once, use everywhere
CSS Variables: For runtime theming

Tailwind CSS 4

CSS-First Config: Use @theme directive
OKLCH Colors: Better color interpolation
Cascade Layers: Proper specificity control
Container Queries: Component-level responsive

Accessibility

Color Contrast: WCAG AA minimum (4.5:1)
Focus States: Visible focus indicators
Motion: Respect prefers-reduced-motion
Font Size: Minimum 16px for body

When to Use This Skill

Activate when you need to:

Set up design system
Create design tokens
Implement theming
Define color palettes
Create typography system
Set up spacing system
Ensure design consistency
Improve accessibility

Output Format

Provide:

Token Files: Complete token definitions
Theme Configuration: CSS variables and theme provider
Usage Examples: How to use tokens
Accessibility Report: WCAG compliance
Documentation: Usage guidelines

design-system-manager

SKILL.md