packages/tokens/src/components/<name>.json. A component token is an explicit, named binding between a semantic intent and a single visible part of a component — for example, the default background fill of a button, or the focus ring on a text input.
Component tokens are the tier that the spec’s token_contract field lists. When an agent reads a spec and sees token_contract: [button.bg.default, button.border.focus], those names are component tokens. The TSX reads them. The validator checks that they exist.
Anatomy of a component token file
Every component token file follows the same structure: a top-level object keyed by component name, then by part, then by state. Here ispackages/tokens/src/components/button.json in full:
$value on the right-hand side references a semantic token in curly-brace notation. No primitive appears directly. {radius.md} is permitted because it resolves through the semantic tier — radius.md is a primitive, but component tokens reference it via a semantic binding. (Where a dimension token has no semantic alias, component tokens reference the primitive by convention for non-color values.)
Naming convention
Component token names follow one of two patterns:<component>.<part>.<state>— when a part has multiple states. Example:button.bg.hover,button.fg.disabled,button.border.focus.<component>.<part>— when a part has a single, stateless binding. Example:button.radius.
bg-destructive, fg-on-filled, bg-outline. The full dot-path — button.bg-destructive.hover — is what the spec’s token_contract and the validator use.
Currently shipped component token files
Every component in
packages/tokens/src/components/ has been migrated to the 3-tier model with a full token file. If you add a new component to the system, create its token file there before writing the TSX.
Complete tokens.json entry example
The spec stores component token metadata in specs/<component>/tokens.json. Each entry records the full chain from component token to semantic to primitive to resolved light value. Here is a representative set from specs/button/tokens.json:
Why the indirection?
A component token can feel redundant on first read. Ifaction.primary already exists, why does button.bg.default need to exist too? Three reasons:
1. Retheming without global side effects
You can pointbutton.bg.default at a different semantic without affecting every other component that uses action.primary. This lets you retheme one component — for example, making marketing splash buttons use a brand accent — while keeping primary actions blue everywhere else. Without component tokens, every rethem decision is a global one.
2. Mechanical drift detection
When the TSX referencesbutton.bg.default, the validator can ask a yes/no question: does the TSX use this token? When the TSX references action.primary directly, the same value appears in Button, Badge, TextInput, and inline links — and the validator cannot tell which usage is intentional. Component tokens give the validator a component-scoped surface to check.
3. Unambiguous agent contracts
When an agent readstoken_contract: [button.bg.default], there is exactly one possible binding. The name encodes the component, the part, and the state. When an agent reads action.primary in a component spec, it must infer whether this is a button background, a link color, or a focus indicator. The narrower the name, the less the agent has to guess — and the less room there is for hallucination.
When to add a new component token
Add a new entry to a component’s token file — and tospecs/<component>/tokens.json — when the spec’s token_contract lists a name that does not yet exist, and the decision belongs to the component level rather than to the system level. Concrete cases:
- A new state. The Button gains a loading state. Add
button.bg.loading, bind it tosurface.subtleor a new semantic if needed. - A new variant. The Badge gains a brand variant. Add
badge.bg.brand, reference the appropriate semantic. - A new visible part. Tabs gains a bottom-border indicator. Add
tabs.indicator.color, bind it toaction.primaryor a new intent semantic.
- The intent spans multiple components. That belongs in semantic tier.
- You want a literal hex. A literal means either the primitive tier has a gap (extend it there) or the semantic tier lacks a named intent (add it there).
Validation
Theagentic-spec validate command checks component tokens in two ways:
- Contract completeness. Every name listed in a spec’s
token_contractmust have a matching entry inspecs/<component>/tokens.json. A missing entry produces anunknown-tokenfinding that blocks the spec from advancing toAI-Readystatus. - Tier correctness. Every entry in
tokens.jsonwith"tier": "component"must have areferencesfield that points at a valid semantic token — not a primitive. A component entry whosereferencesfield contains a primitive path (e.g.,{color.blue.6}) produces abad-token-tierfinding.
packages/tokens/src/components/<name>.json matches the spec’s declared entries — that file is the build output. The spec’s tokens.json is the contract. Keep them in sync by running the token build after every spec change.