3 layer of design token matter

"Why do you need 3 layers of CSS variables? Just use brand-800 directly." That was me. Here's what changed my mind. I made a table of how shades map in light vs dark mode: Button surface: 800 → 200 (flip to light) Badge surface: 100 → 900 (flip to dark) Disabled state: 400 → 600 (shift middle) Border color: 200 → 800 (flip to dark) See the problem? Every row flips in a DIFFERENT direction. There's no single "reverse the palette" trick that handles all of them. That's the whole reason semantic tokens exist. Layer 1: --color-brand-800 (the raw color) Layer 2: --color-surface-brand-primary: var(--color-brand-800) Layer 3: --color-button-brand-default-surface: var(--color-surface-brand-primary) Dark mode? Override Layer 2. Theme switch? Swap Layer 1. One component needs something different? Override Layer 3. Let me show you the real math at scale. Say your design system has: • 30 components (button, checkbox, input, badge, tab, card...) • 4 states each (default, hover, focus, disabled) • 3