Custom properties as plumbing

A Sass variable is compiled away before the browser sees it. A custom property is a real value in the cascade, it inherits, it can be changed at runtime, it can differ per subtree, and JavaScript can read and write it. Those are different tools with the same shape, and confusing them is where the trouble starts.

Work the instrument below in order, because the three panels are increasingly uncomfortable and the third is the one worth the chapter.

The first panel is the easy half: tokens at :root, components reading them, one change re-theming everything. Then tick the subtree box and watch one declaration on one wrapper re-theme only what is inside it. That is inheritance doing exactly what it always does, and it is what makes per-section theming a one-liner, and what makes a token that is "wrong in one corner of the app" so hard to track down. The value is not global. It is wherever you last set it.

The second panel is the trap. Custom properties are substituted at computed-value time, which is after the cascade has already picked a winner. So a var() that fails does not lose gracefully to the previous declaration the way an ordinary typo does, it makes the whole declaration invalid at computed-value time, and the property falls to its inherited-or-initial value. Typo a colour token and your button is not the old colour, it is transparent. Try all four states in the panel; the last one, where a fallback is present and still does not save you, is the one that ends arguments.

That last state is worth stating plainly: var(--x, fallback) uses the fallback when --x is not set. Not when it is set to something wrong. It is a presence check, not a validity check, and a token holding a nonsense value sails straight past it.

The third panel is @property, which is the fix for all of that. Register a custom property with a syntax and the browser knows its type: a wrong value is rejected at parse time instead of poisoning a declaration later, and, the part people actually want, the value can be interpolated, so a registered <angle> or <color> can be animated where an unregistered one snaps.

.button {
  background: var(--brand);
}

/* no @property rule */
:root { --sweep: 0deg; }

Now build. Convert your own project’s stylesheet to tokens: colour, spacing, radius, type scale. Add a dark theme by redefining the tokens under [data-theme="dark"] and nothing else, if you find yourself writing a second rule for a component, your tokens are not granular enough. Then scope a token on one section to prove subtree theming works. Then deliberately typo one and watch what happens, so you have seen it once in your own code.