Lesson 21 of 23

In progress

Course progress

HTML and CSS

Custom properties and design tokens

Define colours, spacing and type as custom properties, scope them to components, and change a whole theme from one block.

A colour repeated in forty rules is forty places to change and forty chances to miss one. Custom properties turn those decisions into named values that can be overridden in one place.

What you will learn

  • Declare custom properties and read them with var().
  • Scope tokens to a component and provide fallbacks.
  • Change a theme by redefining tokens, not rules.

Declaring and using tokens

HTML
Editable. Runs in your browser.





Press Run to see the output.

:root matches the document element, so the values are available everywhere by inheritance. Names are case-sensitive, must start with two hyphens, and are usually lowercase with hyphens.

A custom property can hold any value, including a whole shadow or a gradient. It is substituted as text, not parsed as a typed value, which is why var(--space-4) * 2 does not work without calc().

Fallbacks and scoping

var(--color-brand, #5b33a6) uses the fallback when the property is undefined. That is useful for a component that should work in a context that has not defined the token.

Custom properties inherit, which makes scoping natural:

HTML
Editable. Runs in your browser.





Press Run to see the output.

The badge rule is written once. The container changes the value, and every badge inside it follows. That is the pattern behind theming, dark mode and per-section colour variants.

Do not over-scope. If every component defines its own colour tokens, the design drifts. Keep the core palette global and override only where a variant is deliberate.

A token layer worth having

A small set covers most sites:

  • --color-bg, --color-surface, --color-ink, --color-ink-soft, --color-brand, --color-border.
  • --space-1 to --space-8 on a single scale.
  • --font-body, --font-heading, --text-base, --leading.
  • --radius, --shadow, --container.

Notice that names describe roles, not colours. --color-ink can become light in dark mode; --color-navy cannot without lying.

Changing a theme with one attribute

HTML
Editable. Runs in your browser.





Press Run to see the output.

The rules for body and links do not know which theme is active. They read tokens, and the tokens change. Adding a third theme is a new block, not a new stylesheet.

JavaScript can set the attribute, and the same pattern works with prefers-color-scheme as the default. Lesson 23 puts the two together.

Tokens and JavaScript

Custom properties are readable and writable from scripts:

document.documentElement.style.setProperty('--brand', '#b23b1e');

That is useful for user-chosen accent colours or a preview panel. Keep the values in one place, and avoid writing inline styles on many elements; the point of the token is to change one thing.

Naming and maintenance

Group tokens by purpose in the :root block with comments: colour, space, type, layout. Keep the scale short. A palette with fourteen greys is a palette nobody can choose from, and a scale with twenty steps is the same problem in another dimension and a different unit of measurement entirely.

When a token is used once, ask whether it needs to exist. Tokens earn their place by being reused or by being part of a theme that switches.

Defining tokens inside a media query on :root but using them on an element that has its own --color-bg declaration creates a confusing override. Inheritance means the nearest definition wins, so inspect computed values rather than guessing which block applied.

Create a card component that uses tokens for surface, ink, brand and padding. Add a .card--inverted variant that redefines those tokens locally, without changing any of the card’s rules.

Show solution
HTML
Editable. Runs in your browser.





Press Run to see the output.

The variant changes three values and reuses every structural rule. That is the whole idea of tokens: decisions in one layer, structure in another.

Recap

  • Custom properties are inherited values read with var() and optional fallbacks.
  • Name tokens by role so a theme can change without renaming anything.
  • A variant or theme redefines tokens in a scope; the component rules stay untouched.

Next, you will build a dark theme that passes contrast and respects the system setting.

Are custom properties supported everywhere?
Yes in all current browsers. Very old browsers ignore them, which is one reason to keep a sensible fallback for critical colours.
Can I use them in media queries?
Not as the query condition itself. You can use them inside the declarations of a media query, and you can switch them with a selector such as `[data-theme]`.

Progress is saved in this browser only. No account, no email.

Admin

About the author

Admin

Instructor and technical writer at tutorials.in

Writes beginner lessons for tutorials.in. Each lesson is checked against the language or tool documentation, and examples are run before publishing.

Reviewed by the editorial team before publishing. Last updated November 16, 2026.