Custom Properties

• They are properties. --brand is a real, inherited property with a value. It participates in the cascade like any other: origin, layers, specificity, order all apply (The Cascade).
• The value is an almost-uninterpreted token stream. The parser validates that it is balanced tokens and stores it. No type checking happens until it is substituted, which is what allows a custom property to hold a whole declaration fragment, a comma-separated list, or nonsense.
• `var()` substitutes at computed-value time. By the time layout runs, var() is gone; the property holds a concrete computed value. This is why a custom property change costs style recalculation on everything that reads it, and why it can be animated only when the browser knows its type.
• Invalid at computed value time (IACVT). If substitution produces something the property cannot accept, the declaration does not fall back to an earlier one — it becomes unset. For an inherited property that means it inherits; for a non-inherited one it takes the initial value. Fixing this is what the var(--x, fallback) second argument is for.
• The guaranteed-invalid value. An unset custom property has a special empty value that makes any var() referencing it fall back, or become IACVT if there is no fallback. --x: initial deliberately restores that state.
• `@property` registers a type. Declaring syntax, inherits and initial-value gives the property a real type, a real initial value, an inheritance setting you choose, and — because the browser now knows how to interpolate it — the ability to be transitioned and animated (Cheap and Expensive Animation).
• They are readable and writable from script. el.style.setProperty('--x', v) and getComputedStyle(el).getPropertyValue('--x') work, which makes them the standard bridge between application state and style without touching a stylesheet (Design Tokens).

1:root {
2  --brand: oklch(0.6 0.18 260);
3  --gap: 1rem;
4}
5 
6/* Scoped to a subtree, not to a file. Everything inside .compact
7   sees a different --gap, including components that never heard of it. */
8.compact { --gap: 0.5rem; }
9 
10.stack > * + * { margin-block-start: var(--gap); }
11 
12/* Fallback: used when --accent is guaranteed-invalid (absent, or
13   explicitly set to 'initial'). Not used when --accent is present
14   but nonsense -- that is the next case. */
15.badge { background: var(--accent, var(--brand)); }
16 
17/* Invalid at computed value time. --pad exists and parsed fine;
18   it just is not a valid <length>. The declaration does NOT fall
19   back to the rule above -- it becomes 'unset', and padding takes
20   its initial value of 0. */
21.card { padding: 1rem; }
22.card { --pad: banana; padding: var(--pad); }   /* padding: 0 */
23 
24/* Registration turns that silent cliff into a rejected value with a
25   defined default -- and makes the property animatable. */
26@property --accent {
27  syntax: "<color>";
28  inherits: false;    /* does not leak into nested .badge instances */
29  initial-value: rebeccapurple;
30}

--accent is absent
  var(--accent, var(--brand))  ->  guaranteed-invalid  ->  fallback used
  background: oklch(0.6 0.18 260)                                  OK

--pad: banana
  var(--pad)                   ->  substitutes to the token 'banana'
  padding: banana              ->  not a valid <length>
                               ->  INVALID AT COMPUTED VALUE TIME
                               ->  padding: unset -> initial -> 0     BREAK

--a: var(--b); --b: var(--a)
  cycle detected               ->  both guaranteed-invalid
  every declaration using either -> unset                            BREAK

• Declare a token on the narrowest element that needs it. :root for genuine global design tokens; the component root for anything a component owns. This is an invalidation decision disguised as a naming decision.
• Always give var() a fallback when the property may legitimately be absent — var(--gap, 1rem). Without one, an absent property makes the whole declaration unset, which is a much larger and much more confusing failure than a wrong value.
• Register anything you intend to animate, and anything where a wrong type should fail loudly. @property --brand { syntax: "<color>"; inherits: true; initial-value: #000; } turns a silent IACVT into a rejected value with a sane default.
• Use inherits: false on registered properties that are genuinely local — a component's internal geometry — so the value does not leak into nested instances of the same component.
• Drive theming by setting a small number of properties on one element rather than by swapping stylesheets. One class on :root that redefines a dozen tokens is one style invalidation and no network request (Design Systems).
• For anything animating every frame, prefer writing a registered property (or a compositable property directly) over toggling classes, and confirm in a trace that layout is not being invalidated (The Frame Budget).