Skip to main content
Component tokens are tier 3 of the 3-tier cascade. Each component that has been migrated to the 3-tier model gets one JSON file in 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 is packages/tokens/src/components/button.json in full:
Every $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.
Use kebab-case for compound part names: 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:
Each field has a precise meaning:

Why the indirection?

A component token can feel redundant on first read. If action.primary already exists, why does button.bg.default need to exist too? Three reasons:

1. Retheming without global side effects

You can point button.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 references button.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 reads token_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 to specs/<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 to surface.subtle or 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 to action.primary or a new intent semantic.
Do not add a component token when:
  • 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

The agentic-spec validate command checks component tokens in two ways:
  1. Contract completeness. Every name listed in a spec’s token_contract must have a matching entry in specs/<component>/tokens.json. A missing entry produces an unknown-token finding that blocks the spec from advancing to AI-Ready status.
  2. Tier correctness. Every entry in tokens.json with "tier": "component" must have a references field that points at a valid semantic token — not a primitive. A component entry whose references field contains a primitive path (e.g., {color.blue.6}) produces a bad-token-tier finding.
The validator does not check whether 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.