You own a shared web-component library. How do you decide what each component exposes as CSS custom properties versus `::part()` names, and what does each choice cost you later?

## Both are API, and the platform gives you no safety net Once a consumer ships CSS that references `--btn-bg` or `::part(label)`, that name is a contract. The platform provides no reflection (nobody can ask what a component supports), no warnings, and no deprecation path. Remove a token and the `var()` quietly falls back to the author's default; remove a part name and the `::part()` rule quietly matches nothing. Both failures are silent and visual, discovered by a designer, not by a build. That asymmetry — high blast radius, zero tooling — is the reason to be stingy with both. ## The two channels are not interchangeable **Custom properties are value-level and author-mediated.** The author writes `background: var(--btn-bg, #333)`, so the consumer supplies a *value* for a decision the author has already framed. The internal element could be a `<button>`, a `<div>`, three nested boxes — the token survives all of it. Misuse is bounded: the worst a consumer can do is pass an ugly colour. The cost is enumeration. Every themeable decision needs a token, and consumers routinely need one you did not think of, which turns into a stream of "please expose X" requests and an ever-growing token list. **Parts are element-level and consumer-mediated.** `part="label"` hands over an element; the consumer writes whatever CSS they like on it. That answers needs you cannot enumerate — a transition, a pseudo-element badge, an absolute-positioned overlay. The cost is that the element's *observable behaviour* becomes API in a way you never declared. You wanted to publish "there is a label"; what you actually published is its display type, its box model, its position in a flex line, its stacking. Refactoring the internals from a flex row to a grid can break consumers who positioned against the old layout, and you will not find out from tests. ## A working decision rule 1. **Is the need a value?** Colour, spacing, radius, font size, border width, shadow, duration → token. This covers the large majority of real theming requests. 2. **Is the need bounded but not a value?** A consumer wants uppercase labels, or a different `text-align` → still a token if the property list is short (`--label-transform`), because you keep the freedom to restructure. 3. **Is the need unbounded or unpredictable?** Adornments, animations, layout overrides on a specific node → part. 4. **Is the element durable?** Only expose a part on something that will still exist, by the same role, after a rewrite. The control, the label, the panel, a row. Never on a wrapper that exists because of today's flexbox choice. 5. **Would exposing it leak state?** If a consumer needs `::part(row)` styled differently when selected, publish state as an extra part name from script (`part="row row-selected"`) rather than expecting them to select structurally — outside CSS cannot use structural pseudo-classes after `::part()`. ## Costs that show up later **Nesting friction with parts.** A part name is visible exactly one level up. A component composed of components needs `exportparts` at every hop, and consumers of the outer component see a flat namespace assembled from several inner ones. Rename an inner part and every forwarding attribute in between needs updating. This is a real tax on composed libraries and a strong argument for exposing few parts on leaf components. **Token sprawl.** The opposite failure: fifty tokens per component, half of them undocumented, several meaning nearly the same thing. Namespacing (`--mylib-btn-bg`) prevents collisions with the consumer's own tokens but makes the list uglier; aliasing to system tokens (`var(--mylib-btn-bg, var(--mylib-color-surface))`) keeps global theming cheap while preserving per-component overrides. **Defaults in the wrong place.** A default declared as `:host { --btn-bg: #333 }` blocks any page-wide value from inheriting in, because a declaration beats inheritance. Library-wide, put defaults in `var()` fallbacks so global tokens work, and reserve `:host` declarations for values that genuinely must not be set from outside. **Locking with `!important`.** Shadow cascade order lets consumers' `::part()` rules beat internal ones for normal declarations. Where a property is load-bearing — the `display` a layout depends on, an `overflow` that prevents clipping bugs — an `!important` inside the shadow tree wins back control. Use it sparingly and document it, or you will field bug reports about overrides that do nothing. ## How I would run it Start closed: ship tokens only, and treat each part request as a design conversation rather than an automatic yes. Keep a single documented table per component listing tokens and parts, since the platform will not tell anyone. Add visual regression tests over a few consumer-style overrides so refactors that move a part's box are caught before release. And be explicit in the docs that markup *under* an exposed part is private — a claim that carries no enforcement, but sets the expectation that the library will not treat every internal reshuffle as a breaking change.