Component tokens serve one component and are not reused outside it

What it is

button.bg.hover names a background on the button’s anatomy, in the hover state. It is not “a slightly darker surface color”, even if its value happens to match a card’s hover today. A component token has one reader: that component’s implementation. A card, an input, or the nav reading it is borrowing someone else’s bones. Values that must be shared across components travel as a semantic alias or a primitive underneath, not as a component token. Reuse a component token outside its owner and the next button-only restyle silently restyles cards — blast radius quietly widened to “everyone who once took a shortcut”.

Why it happens

A component token encodes an anatomical place: which part, which state. Anatomy is private to the component; the part’s name does not exist, or does not sit in the same place, on another component. An outsider reading it asserts “my patch equals the button’s patch”. When the button later changes its hover (contrast, brand, separating press from hover), every surface that asserted equality changes with it, most of them never having agreed to that change. Sharing belongs on roles: success background, danger border, floating layer — names that do not belong to any one component. Privacy of component tokens pins a component change’s blast radius inside that component. Break privacy and the blast radius becomes “whoever conveniently referenced it”, a list nobody keeps. The convenience motive is strong: the values look the same, one fewer name. Sameness is a snapshot, not a contract.

Where it stops holding

Subparts of the same component may share a component token: the button’s label and the button’s icon both reading button.fg.default still sit in one blast radius. When the same component implementation is copied across products, the token file may travel with it — that is distributing the component, not an outsider referencing it. If theming is implemented as “rewrite button.*”, outsiders reading button.* leak theme into “the button’s theme”; themes should rewrite semantic aliases. Docs that present component tokens as a copyable public palette will be used as a public API — examples must mark them private. A primitive palette is meant to be read by many components and is not under this ban; the ban is treating the anatomy-named layer as a palette.

Applying it

• Keep component tokens in that component’s private file or namespace; do not export them to product repos at build time. Product code referencing button.* should fail the build.
• When two places “happen to share a value”, add a role name at the semantic-alias layer and point both at the role. Do not point the card at the button.
• In review, treat a cross-file reference to a component token as a defect, same grade as a hard-coded color.
• Check: change one button-hover component token and run visual regression. If failing snapshots include cards, inputs, or nav, outsiders are reading it. Then search the corpus: button., input., dialog. on product paths whose files do not belong to that component — each hit is a privacy break. Zero hits and regression moving only the button means privacy holds.

Related

• Same group: R1.09.2 Name tokens by role and state, not by appearance · R1.09.3 Alias chains that run too deep make origin untraceable · R1.09.4 Scale tokens take stepped values; arbitrary numbers break the rhythm
• Adjacent: R1.01 Design tokens · R1.15 Multi-brand and multi-theme
• Search terms: component token · private tokens · semantic alias