CSS custom properties for theming: inheritance, fallbacks and @property

What it is

A custom property is any declaration whose name starts with --; var(--name, fallback) substitutes its value into another declaration. The MDN guide states that custom properties are subject to the cascade and inherit from the parent, that var() may appear only inside property values (not in selectors, property names or media and container query conditions), and that an invalid substitution behaves differently from ordinary invalid CSS: instead of discarding the declaration, the browser uses the initial or inherited value of the property. @property registers a custom property with a syntax, an inherits flag and an initial-value, which makes it type-checked and animatable.

Why it matters

Theming (brand colours, density, dark mode, per-tenant styling) becomes a matter of redefining a handful of properties on a scope (:root, [data-theme="dark"], a component root) instead of duplicating rules. Because the values live in the cascade, they can be set from inline styles, from JavaScript with style.setProperty, and per subtree, and every rule that reads them updates at once.

How to apply

• Define two layers: raw tokens (--blue-600: #2563eb) and semantic roles (--color-accent: var(--blue-600)); components consume only roles, themes redefine only roles.
• Set defaults on :root and override on a scope element; avoid component-level defaults that quietly become the real values.
• Use the fallback argument for properties a host page may not define (var(--btn-bg, #333)); the var() page documents nested fallbacks.
• Register properties that must animate or be type-safe with @property and give them an initial-value; unregistered properties are untyped and animate discretely.
• Namespace names when shipping components (--acme-btn-bg); all custom properties share one namespace in the cascade.
• Store unitless numbers only if every consumer multiplies them (calc(var(--gap) * 1px)); a value is substituted as tokens, not converted.

Pitfalls

The invalid-substitution rule is silent: color: var(--size) with --size: 16px yields the inherited colour, not an error, and the fallback does not help because the variable is defined. Custom properties cannot drive media query conditions, so breakpoints stay literal. A property defined on :root is inherited by everything, which is convenient for themes and confusing for component-local state; keep local state on the component root. Values set by JavaScript are strings and are not validated until used.

Where var() is resolved

A custom property is substituted on the element where it is declared, at computed-value time, and descendants inherit the result. --color-accent: var(--blue-600) on :root therefore inherits as the resolved colour, and redefining --blue-600 on [data-theme="dark"] or a component root does not change --color-accent there; the alias keeps the value computed at :root. Themes must redefine the role properties (--color-accent) in their scope, or redeclare the aliases alongside a swapped palette. The symptom of getting this wrong, a scoped theme whose colours stay those of the root, looks like a specificity problem but is not one.