Lesson 21 of 23
In progress
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
Editable. Runs in your browser.
.card {
color: var(–color-ink);
background: var(–color-surface);
border: 1px solid var(–color-brand);
border-radius: var(–radius);
padding: var(–space-4);
}
</style>
<div class="card">One token set, reused everywhere.</div>
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:
Editable. Runs in your browser.
.badge { background: var(–accent); color: #ffffff; padding: 4px 10px; }
</style>
<p><span class="badge">Default accent</span></p>
<div class="promo"><span class="badge">Promo accent</span></div>
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-1to--space-8on 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
Editable. Runs in your browser.
[data-theme="dark"] {
–bg: #12132a;
–ink: #ececf7;
–brand: #a98bf0;
}
body { background: var(–bg); color: var(–ink); }
a { color: var(–brand); }
</style>
<body>
<p>Switch the data-theme attribute on html to change every colour.</p>
<p><a href="#">A link using the brand token</a></p>
</body>
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
Editable. Runs in your browser.
.card {
background: var(–surface);
color: var(–ink);
border: 1px solid var(–brand);
padding: var(–pad);
}
.card–inverted {
–surface: #1f2430;
–ink: #ffffff;
–brand: #a98bf0;
}
</style>
<div class="card">Default card</div>
<div class="card card–inverted">Inverted card</div>
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?
Can I use them in media queries?
Progress is saved in this browser only. No account, no email.