CSS Custom Properties at Scale: Tokens, Theming, and Fallbacks
CSS custom properties (variables) are the backbone of design tokens and theming on the web. Used well, they keep colors, spacing, and typography consistent and easy to change. This post covers naming, fallbacks, theming (e.g. dark mode), and how to avoid the pitfalls that show up at scale.
Why custom properties
- Single source of truth: Define a value once (e.g.
--color-primary) and use it everywhere. Change it in one place to update the whole system. - Runtime theming: You can change
--color-bgor--color-texton a root element (e.g. for dark mode) and every component that uses those variables updates. - Scoped overrides: Components can set or override variables for their subtree without touching global CSS.
Naming and structure
Use a clear naming scheme so tokens are predictable. Common patterns: