Tokens · Layer 3
Component tokens
A published contract for restyling one component. They are deliberately few — a component token is justified when a product genuinely needs to diverge there, not simply because a component uses a colour.
Add these sparingly
Every component token is a promise to keep supporting that override. Before adding one, check whether the change belongs at the semantic layer instead — where it would benefit every component at once.
BrowsePermalink to this section
Each token shows the semantic alias it resolves to, so the effect of overriding it is predictable.
Overriding a component tokenPermalink to this section
Because these are plain custom properties, an override is scoped by wherever it is declared — a theme class, a section, or a single instance.
/* Marketing surfaces use a taller, rounder primary button
without changing the brand or any other component. */
.marketing-surface {
--button-primary-background: var(--brand-700);
--button-primary-hover: var(--brand-800);
--card-radius: var(--radius-xl);
}When a component token is justifiedPermalink to this section
Four tests. A proposed token that fails all of them belongs at the semantic layer.
- The component must diverge from its semantic sourceA marketing button that is deliberately deeper than the product's standard brand colour is a real divergence. A button that simply uses the brand colour is not.
- The override has a named consumerSomeone is asking for it today. Tokens added “in case someone needs it” become surface area nobody can safely remove later.
- The change cannot be expressed as a variantIf the difference is a fixed, repeatable style, it is a variant. Tokens are for values a consuming product supplies.
- It resolves to a semantic token by defaultA component token whose default is a raw primitive has skipped a layer, and will not follow a theme change.