CSS Custom Properties / CSS Variables

CSS custom properties — also called CSS variables or CSS vars — are native browser syntax for storing and reusing values in stylesheets: var(--color-primary), var(--space-lg). They're the web's native token runtime.

In a Design System, CSS custom properties are where design tokens become actual CSS. A semantic token like color-action-primary gets transformed into --color-action-primary: #3A7FFF; by tools like Style Dictionary. Components then consume it with color: var(--color-action-primary).

The power of CSS custom properties for theming is immense. Swap the custom property value on a root element or a class, and every component that uses it repaints:

:root { --color-action-primary: #3A7FFF; /* light mode */ } [data-theme="dark"] { --color-action-primary: #60A5FF; /* dark mode */ }

Custom properties also cascade and inherit, making it easy to override values at any level. You can scope tokens to a component, a page, or the whole app. They work in all modern browsers (IE11 excluded).

The discipline required: components must consume only custom properties, never hard-coded colours. One hard-coded #FFF breaks the chain. Some teams lint for this to ensure the system stays intact.

Related: Design tokens · Theming · Semantic tokens · Style Dictionary · Dark mode