ui-design-system

UI Design System

Overview

Build and maintain scalable design systems with a token-first architecture. This skill covers the full pipeline from primitive design tokens through semantic mapping to themed component libraries, with deep expertise in Tailwind CSS v4, CSS custom properties, and responsive design patterns.

Phase 1: Token Foundation

1. Audit existing design assets (colors, fonts, spacing, shadows)
2. Define primitive tokens (raw values with no semantic meaning)
3. Create semantic token layer (map primitives to intentions)
4. Build component token layer (map semantics to component parts)

STOP — Present the token hierarchy to user for review before building components.

Token Layer Decision Table

Layer	Purpose	Naming Convention	Example
Primitive	Raw values, single source of truth	--color-blue-500, --space-4	oklch(0.55 0.18 250)
Semantic	Map to purpose/intention	--action-primary, --text-secondary	var(--color-blue-600)
Component	Scoped to specific components	--button-height-md, --card-radius	var(--space-4)

When to Create Each Layer

Situation	Layers Needed
Brand new project	All three (primitive + semantic + component)
Adding dark mode to existing	Semantic + component (remap primitives)
Updating brand colors	Primitive only (semantic/component auto-update)
Adding new component	Component only (reference existing semantic)
Tailwind project with @theme	Primitive via @theme, semantic via CSS vars

Phase 2: Token Implementation

Level 1: Primitive Tokens

Raw values with systematic naming. Single source of truth for all values.

/* Colors — using OKLCH for perceptual uniformity */
--color-blue-50: oklch(0.97 0.01 250);
--color-blue-100: oklch(0.93 0.03 250);
--color-blue-500: oklch(0.55 0.18 250);
--color-blue-900: oklch(0.25 0.10 250);

/* Spacing — 4px base unit */
--space-1: 0.25rem;   /* 4px */
--space-2: 0.5rem;    /* 8px */
--space-3: 0.75rem;   /* 12px */
--space-4: 1rem;      /* 16px */
--space-6: 1.5rem;    /* 24px */
--space-8: 2rem;      /* 32px */
--space-12: 3rem;     /* 48px */
--space-16: 4rem;     /* 64px */

/* Typography */
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'Geist Mono', monospace;
--font-size-xs: 0.75rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
--font-size-xl: 1.25rem;
--font-size-2xl: 1.5rem;
--font-size-3xl: 1.875rem;
--font-size-4xl: 2.25rem;

/* Line Heights */
--leading-tight: 1.25;
--leading-normal: 1.5;
--leading-relaxed: 1.75;

/* 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);
--shadow-lg: 0 10px 15px -3px oklch(0 0 0 / 0.1);