design-system

Design System Skill

Degree of freedom: MIXED. Token taxonomy and variants [HIGH freedom]; existing ui/ / token inventory [LOW freedom — run exactly].

Build scalable, maintainable design systems with consistent tokens, variants, and documentation.

How to reason

1. Inventory — components/ui, tokens, cva, shadcn/Radix
2. Tokenize — semantic tokens, not raw hex in components
3. Variant — cva covers real states (default/destructive/disabled)
4. Document — JSDoc, keyboard/focus, dark mode

Worked example

Inventory: shadcn Button exists; colors are raw #3B82F6 in three pages; no --primary. Tokenize: --primary / --primary-foreground in globals.css; Tailwind maps hsl(var(--primary)). Variant: extend existing buttonVariants — do not add components/Button2.tsx. Document: JSDoc lists variants/sizes; focus ring + dark .dark overrides.

Self-critique before reporting

• Did not fork — existing primitives were extended, not recreated
• Semantic tokens — components reference tokens, not primitives or hex
• A11y + dark — focus, disabled, and dark variants exist
• Right owner — drifted existing system → housekeep-design; plan-only unification → plan-uiux-unification

CRITICAL: Check Existing First [LOW freedom — run exactly]

Before creating ANY design system components, verify:

1. Check for existing design system:

ls -la src/components/ui/
cat package.json | grep -i "shadcn\|radix\|headless"
cat components.json 2>/dev/null # shadcn config

1. Check for existing tokens:

cat tailwind.config.* | head -100
cat src/styles/globals.css | head -50
rg "var\(--" --type css | head -20

1. Check for existing patterns:

rg "cva\(|variants:" --type ts --type tsx | head -10
rg "cn\(|clsx\(|twMerge" --type tsx | head -5

Why: Don't recreate existing primitives. Extend and enhance what exists.

Design Tokens [HIGH freedom]

CSS Custom Properties

/* globals.css */
:root {
 /* Colors - Semantic */
 --background: 0 0% 100%;
 --foreground: 222.2 84% 4.9%;
 --card: 0 0% 100%;
 --card-foreground: 222.2 84% 4.9%;
 --popover: 0 0% 100%;
 --popover-foreground: 222.2 84% 4.9%;
 --primary: 221.2 83.2% 53.3%;
 --primary-foreground: 210 40% 98%;
 --secondary: 210 40% 96.1%;
 --secondary-foreground: 222.2 47.4% 11.2%;
 --muted: 210 40% 96.1%;
 --muted-foreground: 215.4 16.3% 46.9%;
 --accent: 210 40% 96.1%;
 --accent-foreground: 222.2 47.4% 11.2%;
 --destructive: 0 84.2% 60.2%;
 --destructive-foreground: 210 40% 98%;
 --border: 214.3 31.8% 91.4%;
 --input: 214.3 31.8% 91.4%;
 --ring: 221.2 83.2% 53.3%;

 /* Spacing */
 --spacing-xs: 0.25rem;
 --spacing-sm: 0.5rem;
 --spacing-md: 1rem;
 --spacing-lg: 1.5rem;
 --spacing-xl: 2rem;

 /* Border Radius */
 --radius: 0.5rem;
 --radius-sm: calc(var(--radius) - 4px);
 --radius-lg: calc(var(--radius) + 4px);

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

 /* Animation */
 --duration-fast: 150ms;
 --duration-normal: 200ms;
 --duration-slow: 300ms;
 --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
 --ease-in: cubic-bezier(0.4, 0, 1, 1);
 --ease-out: cubic-bezier(0, 0, 0.2, 1);
 --ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
}

.dark {
 --background: 222.2 84% 4.9%;
 --foreground: 210 40% 98%;
 /* ... dark mode overrides */
}