Component Tokens

Component tokens are the bridge between the semantic token layer and component declarations. They are scoped to a single component and reference semantic tokens. They may not reference primitive tokens directly. Component tokens allow a component to adapt semantic values for its specific structural needs without introducing raw values into the component declaration.

Component Token Naming

Component token names are scoped to the component: component-name.property.variant. For example: button.background.default, button.text.hover, input.border.focus, card.shadow.default. The scoping prefix (button, input, card) is the component's declared identifier. All token names within a component's scope MUST use that prefix.

Component Token Declaration

Component tokens are declared within the component specification, not in a separate file. This co-location ensures that token changes and component changes are versioned together. When a component is deprecated, its component tokens are deprecated with it. When a new variant is added to a component, new component tokens are declared in the same component version increment.

Constraints on Component Token References

• Component tokens MUST reference semantic tokens, not primitive tokens.
• Component tokens may not reference component tokens from a different component.
• Component tokens are consumed only by the component that declares them.
• Component tokens may reference semantic tokens from any category, not only the category matching the property name.
• Alias chains involving component tokens are subject to the three-hop maximum resolution rule.