A component's internals live in a shadow root that page CSS cannot select. How do CSS custom properties let the page theme it anyway, and what are the limits of that contract?

## Why custom properties cross at all A custom property is just a property whose name starts with `--`, and the spec defines it as **inherited**. Inheritance is computed over the flattened tree, which stitches shadow trees into the document, so a custom property declared anywhere up the chain — `:root`, `body`, or the host element itself — has a computed value on nodes inside the shadow root. Nothing had to be selected. That is the whole trick: encapsulation blocks selector matching, and custom properties are a channel that does not need selector matching. ```css /* page */ my-button { --btn-bg: crimson; } /* inside the shadow root */ button { background: var(--btn-bg, #333); } ``` The page never selected the inner `<button>`. It set a value on the host; the value inherited down; `var()` substituted it. ## The contract is opt-in from the inside Substitution only happens where the component author wrote a `var()`. A page can declare `--anything-at-all` and it will inherit into the shadow tree harmlessly, doing nothing. This is what makes custom properties the *safe* theming primitive: the surface is exactly the set of tokens the author chose to honour, and everything else — the internal element names, the layout, the nesting — stays private and refactorable. That is also the limit. Tokens are **value-level**. A consumer can change a background, a radius, a gap, a font size. They cannot reorder the internals, add a pseudo-element, change `display`, or style a state the author did not expose, unless the author wired a token for it. If a consumer's need is unbounded, tokens are the wrong tool and a `part` is the right one. ## Where the default lives decides who wins This is the detail interviews probe, because it produces a genuinely confusing bug. There are two places to put a default value: ```css /* option A: declare on the host */ :host { --btn-bg: #333; } button { background: var(--btn-bg); } /* option B: fallback in the var() */ button { background: var(--btn-bg, #333); } ``` They behave differently under inheritance. In option A, `:host` puts a **cascaded declaration on the host element**. A declaration always beats a value that merely arrives by inheritance — inheritance is the fallback when nothing was declared. So a page-wide `body { --btn-bg: crimson }` never reaches the component: the host declares its own value and the inherited one is discarded before it ever gets there. The component looks stubbornly un-themeable, and the consumer's devtools show `--btn-bg: crimson` on `body` and `#333` on the host, which reads as a bug in the browser until you know the rule. In option B nothing is declared on the host, so the inherited `crimson` survives and `var()` uses it; `#333` applies only when no ancestor supplied a value. **Option B is the default you want for tokens meant to be set page-wide.** Note what does still work in option A: a page rule that targets the host directly — `my-button { --btn-bg: crimson }` — declares on the same element as `:host`. When two declarations from different trees collide on one element, the shadow cascade order makes the **outer tree win** for normal declarations, so the page's value takes effect. That is why some consumers report "it works when I target the element, not when I set it on `:root`" — a precise symptom of an option-A default. ## Practical patterns **Alias to a design-system token.** Give the component its own namespaced knob but default it to the system token: `background: var(--btn-bg, var(--color-surface, #333));`. Consumers theming globally set `--color-surface`; consumers theming one component set `--btn-bg`. **Token per visual decision, not per CSS declaration.** `--btn-bg` used by three rules is a contract; three separate tokens for the same visual concept is churn. **Custom properties reach into slotted content too.** Light-DOM children inherit from where the slot sits in the flattened tree, so a token declared in the shadow tree on the slot's ancestor reaches nodes the page authored — a useful way to hand values *outward*. **They are also runtime-settable.** `el.style.setProperty('--btn-bg', 'crimson')` themes one instance from script, and reading back with `getComputedStyle(el).getPropertyValue('--btn-bg')` gives the resolved value. ## What it costs you Token names are public API the moment someone ships against them. There is no reflection — a page cannot ask a component which tokens it supports, so the list lives in documentation and nowhere else, and a rename is a silent breaking change: the old name simply stops matching a `var()` and the consumer gets your default back with no error. Treat the token list like an exported function signature, keep it small, and prefer adding a token over broadening one's meaning.