Design Tokens & CSS Architecture

Establish a robust design token system and CSS architecture that scales — the foundation for every professional component library.

55 min•By Priygop Team•Last updated: Feb 2026

Design Token System

CSS Custom Properties as Tokens: Define all design decisions as variables — :root { --color-primary: #6366f1; --color-primary-hover: #4f46e5; --radius-md: 8px; --shadow-md: 0 4px 6px rgba(0,0,0,0.1); }. Single source of truth for the entire library
Color Palette: Use HSL for flexible color manipulation — --color-primary-h: 239; --color-primary-s: 84%; --color-primary-l: 67%. Generate shades: hsl(var(--color-primary-h), var(--color-primary-s), 95%) for light variant
Spacing Scale: Consistent 4px base unit — --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; --space-8: 32px. All padding/margin use token values, never arbitrary numbers
Typography Scale: Modular scale with fluid sizes — --text-sm: clamp(0.8rem, 0.75rem + 0.25vw, 0.875rem); --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.0625rem). Line heights: --leading-tight: 1.25; --leading-normal: 1.5
Dark Mode Tokens: Override semantic tokens per theme — [data-theme='dark'] { --color-bg: #0f172a; --color-surface: #1e293b; --color-text: #f1f5f9; --color-border: #334155; }. Components update automatically
File Organization: Separate files by concern — tokens.css (all variables), reset.css (browser normalization), utilities.css (helper classes), components/ folder (one file per component). Import order matters for cascade

Modern CSS Reset: *, *::before, *::after { box-sizing: border-box; margin: 0; } — eliminates inconsistencies. html { -moz-text-size-adjust: none; -webkit-text-size-adjust: none; text-size-adjust: none; }
Sensible Defaults: body { min-height: 100dvh; line-height: 1.5; font-family: var(--font-sans); color: var(--color-text); background: var(--color-bg); -webkit-font-smoothing: antialiased; }
Media Defaults: img, picture, video, canvas, svg { display: block; max-width: 100%; } — responsive media by default. Prevent images from overflowing containers
Form Reset: input, button, textarea, select { font: inherit; } — form elements inherit body font instead of using browser defaults. Remove default appearance with appearance: none for custom styling
Reduced Motion: @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } } — respect user preferences
Typography Defaults: h1-h6 with balanced text-wrap, p with pretty text-wrap, a with color: inherit, and ul/ol with list-style: none inside nav elements for automatic semantic styling