Skip to main content

Rule 23 - CSS: Tokens and options

Design tokens and runtime feature flags - both CSS custom properties on :root.

Tokens​

23.1. Semantic tokens MUST follow the naming pattern: --{target}[-{variant}][-{qualifier}][-{state}]-{concern}[-at-{breakpoint}]

The {target} MAY be either a component name (btn, snippet, linklist), a sub-component prefixed by its parent component (btn-icon, snippet-title, hero-featured-image), or the reserved generic prefix component (see Rule 23.20). A sub-component target MUST match a child class on the parent (per Rule 21.4) - --hero-featured-image-max-width is valid because .hero-featured-image exists; an arbitrary --hero-banner-* prefix is not, and neither is the singular or plural of a child the stylesheet ships (--card-action-* beside .card-actions).

23.19. The {variant} slot MUST be omitted when the variable holds the default value of a capability declared by the component's spec. The component's neutral emphasis, md size, and flat elevation (the spec defaults for those capabilities) MUST use infix-less variable names, each holding the default value's own token per Rule 53.19e:

--callout-background-color: var(--callout-neutral-background-color); /* default (neutral) bg */
--callout-subtle-background-color: …; /* subtle variant */
--callout-padding-block: var(--callout-md-padding-block); /* default (md) padding */
--callout-sm-padding-block: …; /* sm variant */
--callout-shadow: var(--callout-flat-shadow); /* default (flat) shadow */
--callout-raised-shadow: …; /* raised variant */

Non-default values keep the value as the {variant} infix (--{component}-{value}-{concern}). This convention keeps the base layer free of _default clutter while making it impossible to confuse "the default" with "the neutral value" - they are the same thing.

23.20. The generic component prefix is reserved for foundation tokens that any component MAY consume as its starting point. The registered families are:

FamilyValues
--component-padding-block-{size}xs, sm, md, lg, xl
--component-padding-inline-{size}xs, sm, md, lg, xl
--component-padding-{size}sm, md, lg (block + inline shorthand pair)
--component-padding-square-{size}xs, sm, md, lg (equal block and inline)
--component-control-padding-block[-{size}]default, lg
--component-control-padding-inline[-{size}]default, sm, lg
--component-margin-block-{size}xs, sm, lg
--component-gap-{size}xs, sm, md, lg, xl
--component-indentsingle value
--component-font-size-{size}xs, sm, md, lg, xl, xxl, xxxl
--component-font-family[-{face}]default, secondary, mono
--component-font-weight[-{weight}]default, medium, semibold
--component-transition-durationsingle value
--component-radius-{shape}square, rounded, rounded-lg, rounded-circle, pill, circle
--component-border-widthsingle value
--component[-{variant}]-border-colordefault, accent, bold
--component-focus-colorsingle value
--component-shadow-{depth}flat, raised, elevated
--component-shadow-tint-colorsingle value
--component-overlay[-{variant}]-colordefault, subtle
--component-scrim-colorsingle value
--component-selected[-foreground]-colorbackground and foreground of a selected item
--component-stage-…-colordefault, complete; current adds background-color, border-color, ring-color, and a text color
--component-syntax-{token}-colorcomment, function, keyword, number, string
--component-decorative-{n}-{concern}n 1-10, each with background-color and foreground-color

The size values match the Size capability vocabulary and the shape values match Shape, so a capability value always has a foundation token to fall back to. A per-component slot SHOULD reference one of these rather than reaching into the --space-x-* / --space-y-* / --font-size-* / --radius-* primitives directly:

--callout-padding-block: var(--component-padding-block-md);
--callout-padding-inline: var(--component-padding-inline-md);
--callout-sm-padding-block: var(--component-padding-block-sm);

Adding a value to a capability vocabulary (Rule 22) means adding the matching foundation token here in the same change, so no capability value is left without one.

23.2. The concern MUST be the CSS property being set. Compound concerns (e.g. max-width, letter-spacing) MAY be used. A concern alias that names what the property carries rather than the property itself is permitted where a rule registers it: shadow for box-shadow (23.19, 23.20), foreground-color and ring-color (23.20), the -focus-ring-* family (23.28), easing for transition-timing-function, and lift for a transform distance.

23.3. Primitives MUST use the flat pattern --{category}[-{qualifier}]-{value} and hold a literal value. A token in the primitive block of src/variables.css that reads var() states a decision about another token and belongs in the semantic block.

Example: --color-primary-5, --font-size-sm, --space-x-3, --radius-md, --font-family-primary.

23.4. Semantic tokens MUST reference primitives.

Example: --btn-background-color, --text-color-neutral, --background-color-neutral, --heading-h1-font-size.

23.5. Components MUST consume semantic tokens. Primitives MUST NOT be used directly in component CSS.

23.6. Component-specific tokens MUST live in the component's sidecar, src/components/{name}/{name}.variables.css (a utility's in src/utilities/{name}/{name}.variables.css), on :root, with a :root[data-color-scheme='dark'] block only for the color tokens whose dark value differs, in a file co-located with the component's CSS. The sidecar is what lets a component ship as a self-contained unit that consumers bundle selectively via yarn cli build --components={name}[,...]; src/variables.css holds foundation tokens only.

The sidecar wraps its :root blocks in @layer tokens per Rule 21.15. Rule 24.12 (color-scheme pairing) lints it too: its :root[data-color-scheme='dark'] block carries only the color tokens whose dark value differs, and no orphan without a :root counterpart. Sidecar files are concatenated by packages/cli/src/commands/build.js after src/variables.css and src/options.css and before any component / utility / foundation rules, so the cascade is layers -> foundation tokens -> options -> sidecar tokens -> rules. Within a component folder, the tokens file is named {name}.variables.css; mixing tokens with rules in {name}.css is NOT allowed.

Example: --link-subtle-color: var(--text-color-subtle); is declared in src/components/link/link.variables.css, and var(--link-subtle-color) resolves the same for the consumer whether the sidecar ships alone or inside the full distribution.

23.7. A component rule MUST name a component token in the primary position of the var() it reads - its own, or one that a dependency declares (Rule 53.27). A foundation token in the primary position is a tier skip and MUST NOT appear.

Where that component token is declared, and what sits in the fallback position behind it, follow from whether a capability value stands behind the slot.

A capability-value rule - declare the token, read it with no fallback. The rule re-points the base slot to a per-value token declared in the sidecar, and that token holds the foundation token of Rule 23.20:

/* {component}.variables.css */
--{component}-{value}-{concern}: var(--{foundation}-{value});

/* {component}.css */
.{component}.{value} {
--{component}-{concern}: var(--{component}-{value}-{concern});
}

The value is identical for every instance, so a :root declaration resolves it correctly. That declaration is what Rule 53.19b requires and what Rule 24.16's re-point points at, and it is what publishes the knob in the component's own sidecar. Tier 3 still reaches it: a sidecar :root block sits in the weakest tokens layer per Rule 21.15, so an unlayered consumer override wins over it either way.

Any other slot - the foundation token MAY sit in the fallback. A base or state slot that no capability value stands behind has no per-value token to declare, so the fallback names the conventional default and the component declares only the slot it deviates on. The -focus-ring-* slots of Rule 23.28 take this form, as does a base slot such as var(--{component}-font-family, var(--body-font-family)).

Where that fallback expression is element-relative - it reads another slot on the same element - it MUST stay inline. A :root declaration would resolve it there and hand every instance one shared value:

button:hover {
background: var(--btn-hover-background-color, color-mix(in srgb, var(--btn-color) var(--hover-mix-amount), var(--btn-background-color)));
}
/* Correct - the value rule reads a declared per-value token. */
.btn.accent {
--btn-background-color: var(--btn-accent-background-color);
}

/* Wrong - a foundation token in the primary position, so tier 3
has no name to override. */
.btn.accent {
--btn-background-color: var(--background-color-accent);
}

/* Wrong - a capability value read through a fallback. The token is
declared nowhere, so the sidecar publishes no knob and another
component re-pointing this slot has to repeat the fallback to
reach the same value. */
.btn.accent {
--btn-background-color: var(--btn-accent-background-color, var(--background-color-accent));
}

What is checked. The primary-position mandate is enforced across every rules file. The declaration behind a capability-value read is enforced through Rule 53.19, whose (b) and (c) reject an undeclared token and a token read through a fallback alike - but only where the capability's .use() declares a default. A capability without one sits outside Rule 53.19, and whether a fallback expression is element-relative is not a property a linter can read, so both of those stay review-caught.

23.8. Tokens that vary per breakpoint MUST append -at-{breakpoint}. The unsuffixed name holds the base value, and each -at-{breakpoint} sibling holds the value from that breakpoint up. A device word - mobile, tablet, desktop - MUST NOT appear in a token name: it states a class of hardware while the query the token feeds states a width, so the two describe different things as soon as a device appears at another width.

/* Correct */
--logo-image-max-height: 2.5rem;
--logo-image-max-height-at-lg: 4rem;

/* Wrong - names the device rather than the breakpoint. */
--logo-image-height-max-mobile: 2.5rem;
--logo-image-height-max-desktop: 4rem;

Example: --container-max-width-at-sm.

Emphasis tiers​

23.21. Foundational semantic color tokens draw their suffix from exactly two vocabularies, each mapping 1:1 onto a capability:

  • The emphasis ladder - subtle, neutral, accent - mapping onto the Emphasis capability values of the same names.
  • The intent set - danger, info, success, warning - mapping onto the Intent capability values of the same names.

No other suffix (e.g. muted, strong, bold, vivid) MAY be used. The two vocabularies do not combine: per Rule 22.12 emphasis and intent are orthogonal dials whose cross products are not defined in the default vocabulary, so --text-color-subtle-danger MUST NOT exist.

A component that needs an intent color MUST consume the semantic token rather than reaching into a palette primitive. Reaching into the palette forces the component to pick a step and to declare its own :root[data-color-scheme='dark'] pair; consuming the semantic token inherits the scheme flip from Rule 23.6's single declaration site.

23.22. Three foundational semantic color families adopt these vocabularies: text, border, and background. Each family declares one token per emphasis tier and one per intent, named --{family}-color-{suffix}.

/* emphasis */
/* text */ --text-color-subtle, --text-color-neutral, --text-color-accent
/* border */ --border-color-subtle, --border-color-neutral, --border-color-accent
/* bg */ --background-color-subtle, --background-color-neutral, --background-color-accent

/* intent */
/* text */ --text-color-danger, --text-color-info, --text-color-success, --text-color-warning
/* border */ --border-color-danger, --border-color-info, --border-color-success, --border-color-warning
/* bg */ --background-color-danger, --background-color-info, --background-color-success, --background-color-warning

23.23. Tier semantics. neutral is the family's default emphasis (full strength). subtle is a reduced-emphasis variant of the family color (mildly dimmer than neutral, used for quieter separation or de-emphasized content). accent is the family color rendered with the tertiary palette, used for stand-out emphasis that does not belong to the brand primary color ladder.

23.23a. Intent semantics. Each intent maps to the palette ramp of the same name. Within one intent, --background-color-{intent} is the tinted surface the intent renders on, and --text-color-{intent} is chosen so it meets WCAG AA (4.5:1) against BOTH the page background and that tinted surface - so the same token is correct whether the text sits on the page or on the intent's own surface. --border-color-{intent} sits between the two, meeting the 3:1 non-text contrast requirement.

The palette step behind each token differs per ramp, because the ramps do not share a perceptual lightness curve - yellow at step 7 is far lighter than red at step 7. Hiding that difference is the reason the semantic token exists; components MUST NOT re-derive it by picking steps themselves.

23.24. Single-value semantic color tokens for specific elements (e.g. --page-background-color, --kbd-color, --heading-color) do NOT take a tier suffix - they map to a single color decision per element and have no emphasis variants.

23.25. The vocabulary is enforced by packages/cli/src/rules/23.js: any CSS variable matching --{text|border|background}-color-* MUST end in one of the three emphasis tier words or one of the four intent words, and any legacy --surface-*, --*-muted-color, or bare --text-color / --border-color / --background-color declaration MUST NOT appear in src/. The check scans every .css file under src/ for both declarations and var() references.

Units​

23.9. All length values MUST use rem, not px. The base font size is 16px, so 1rem = 16px. Pixel values MUST NOT appear in component CSS. Stylelint's unit-disallowed-list enforces this across src/, with the 23.10 exceptions configured as ignores and Storybook chrome (*.stories.css, src/tools/storybook-chrome/) overridden off - chrome is not shipped, so the token contract does not reach it.

src/variables.css sits outside the Stylelint scan entirely, so the --breakpoint-* primitives it declares carry px unchecked. Those values are the device-space thresholds 23.10 describes, recorded once as tokens; a query condition cannot read var(), so every @media and @container condition restates the pixel literal by hand, and the tokens are the record those literals are checked against.

Example: 0.125rem (2px), 0.25rem (4px), 1rem (16px).

23.10. Exceptions: 0 (unitless zero) MAY be used. Values inside calc() that multiply with token-based rem values MAY use unitless numbers or time units (s, ms).

Condition values inside @media and @container queries MAY use px. A breakpoint is a device-space threshold, not a length the component renders: expressed in rem it would move whenever the user changes their root font size, so the same viewport would match different breakpoints for different readers. The rule constrains lengths in declarations; query conditions are outside it.

/* Correct - px threshold, rem length. */
@media (width >= 768px) {
.callout {
padding-inline: 1.5rem;
}
}

Options​

23.11. Runtime feature flags MUST use the --option- prefix.

Example: --option-animations, --option-rounded-corners, --option-elevation, --option-card-elevation, --option-loading-mode.

23.12. Options MUST take one of two forms. Use the numeric form by default; use the enum form only when the option selects between mutually exclusive visual modes that cannot be expressed as a multiplier.

Numeric form. A scalar in [0, 1] consumed via calc() as a multiplier.

Example: transition-duration: calc(0.2s * var(--option-animations));

Enum form. A custom-ident registered via @property and consumed via @container style() queries on a named options container (per Rule 21.14). Enum options MUST include an explicit none value that disables the feature.

@property --option-loading-mode {
syntax: '<custom-ident>';
inherits: true;
initial-value: overlay;
}

@container options style(--option-loading-mode: spinner) {
[aria-busy='true']::after {
/* spinner visuals */
}
}

23.13. For numeric options, 0 MUST disable the feature and 1 MUST enable at full strength. Fractional values SHOULD scale proportionally. For enum options, none MUST disable the feature; every other value selects a specific mode. An enum option that selects a motion mode (--option-loading-mode, --option-reveal-mode) owns the durations of that mode, and its none value is the off switch, so --option-animations does not scale it.

23.14. Global options - those consumed by more than one component (e.g. --option-animations, --option-rounded-corners, --option-elevation) - MUST be declared in src/options.css, which is concatenated immediately after src/variables.css. Per-component options - those consumed by exactly one component or utility (e.g. --option-card-elevation, --option-checkbox-animations, the registered @property --option-loading-mode) - MUST be declared in the owning component's sidecar {name}.variables.css per Rule 23.6. The bundle concatenates sidecars after src/options.css, so global option declarations are always in scope when a per-component option resolves.

23.15. A component MUST NOT reference an option that does not exist. A new global option MUST be added to src/options.css first; a new per-component option MUST be added to the component's sidecar {name}.variables.css first.

23.16. Options MUST act as multipliers or gates. Options MUST NOT replace token values.

23.17. prefers-reduced-motion: reduce MUST automatically set --option-animations to 0.

Order​

23.18. Token blocks in src/variables.css MUST appear in the canonical order enforced by packages/cli/src/rules/23.js. The PALETTE and PRIMITIVE TOKENS sections are intentionally hand-ordered (lightest → darkest, smallest → largest) and not touched. Inside the two SEMANTIC TOKENS sections (Typography and Color), blocks are sorted alphabetically by prefix; the file holds foundation prefixes only, since component and utility tokens live in their sidecars per Rule 23.6, and a component prefix that did appear would sort after the foundation ones. Within a single block the declarations are sorted alphabetically by token name, with own-prop declarations placed before any sub-component groups (a sub-component is a hyphen-named child class as detected by collectChildClassNames). Run yarn lint-fix to apply.

No underscore-prefixed custom properties​

23.26. Custom properties MUST NOT use the --_{shortname} underscore-prefix form. Every custom property declared anywhere under src/ MUST carry its full name per Rule 23.1 - --{target}[-{variant}][-{qualifier}][-{state}]-{concern} - whether it is a public design token or an internal slot that only the rule declaring it ever reads.

An underscore name states no target, so nothing in the name records which component owns it, a search for that component's tokens never reaches it, and two utilities that both reach for --_m collide silently wherever their elements nest. Brevity across a large permutation matrix does not pay for that: the matrix is written once and read repeatedly. A slot that belongs to one component is already scoped by being declared on that component's own element rather than on :root, so the name does not have to carry the privacy as well.

/* Wrong - names no target, and a search for the layout utility's
tokens never surfaces it. */
.layout {
--_m: 3;
}
.layout-center {
grid-row-start: var(--_m);
}

/* Correct - the child class names the target, the property names
the concern. */
.layout {
--layout-center-grid-row-start: 3;
}
.layout-center {
grid-row-start: var(--layout-center-grid-row-start);
}

The check scans every .css file under src/ for declarations and var() reads alike. Stylelint's custom-property-pattern (^[a-z][a-z0-9-]*$) rejects the declaration form as a second guard.

One focus-ring shape​

23.28. Every component paints its focus indicator through the -focus-ring-* slots, read with the foundation token in the fallback per Rule 23.7. Three of them carry the ring every component draws - width, color, offset:

.tabs-tab:focus-visible {
outline: var(--tabs-focus-ring-width, var(--focus-ring-width)) solid var(--tabs-focus-ring-color, var(--focus-ring-color));
outline-offset: var(--tabs-focus-ring-offset, var(--focus-ring-offset));
}
/* The component declares only the slot it deviates on. */
--navbar-focus-ring-color: var(--link-color);

A component MUST NOT name a focus concern outside this set: -focus-ring-width, -focus-ring-offset, -focus-ring-color, -focus-ring-style, -focus-box-shadow, -focus-background-color, and -focus-border-color. The four -focus-ring-* names are the ring itself, -focus-ring-style taken only by a component whose ring is not solid. -focus-box-shadow is the ring on a control that cannot take an outline (the range thumb). The last two belong to a control that also restyles its own surface while focused, which is a different decision from the ring around it.

The bans this draws are the shapes that accumulated instead: a -focus-color or -focus-outline-color that says which color but not which of the two surfaces it paints, a -focus-width or -focus-offset that drops the family word, and a compound -focus-ring shorthand, which hides the width from --focus-ring-width so retuning the foundation leaves that component behind.

The focus ring is the only indication a keyboard user has of where they are, so it is the one surface where a component quietly resolving its own way is most expensive. One shape also means a consumer restyling every ring on the page overrides one name per component rather than discovering which of five each one chose.

The reserved component prefix is outside the rule - --component-focus-color is the registered foundation family of Rule 23.20, not a per-component slot.

Axis-bound spacing primitives​

23.27. The spacing primitives name an axis: --space-x-{step} is the inline scale and --space-y-{step} the block scale. A declaration that sets a length on one axis MUST read that axis's scale.

The axis comes from the property. A physical or logical longhand states it outright - padding-left, margin-inline-end and column-gap are inline; padding-top, margin-block-start and row-gap are block. A padding / margin / inset / gap shorthand states it by position, so the slot count decides: two values are block inline, four are top right bottom left. A custom property states it when its own name carries one of CSS's logical names (--component-padding-inline-md is inline, --component-margin-block-sm is block); a name that states no axis is not subject to the rule.

23.27a. A value that covers both axes at once MUST NOT name either scale. A one-value shorthand applies the same length to the block and inline sides, so a primitive there is half true whichever one it names. Write the pair instead - the two-value form says what it means and survives one scale being retuned.

/* Correct */
.p3 {
padding: var(--space-y-3) var(--space-x-3);
}
.pl3 {
padding-left: var(--space-x-3);
}
.gap-x-3 {
column-gap: var(--space-x-3);
}

/* Wrong - an inline length read off the block scale. */
.pl3 {
padding-left: var(--space-y-3);
}

/* Wrong - one value covering both axes names only one of them. */
.p3 {
padding: var(--space-y-3);
}

The two scales hold the same value at every step today, so a mismatch renders identically to the correct form. No baseline moves, no test fails, and no reviewer can see it; the name is the only evidence, which is why this is checked rather than left to review. The day one scale is retuned, every mismatched declaration silently renders the other axis's step.

Storybook chrome (*.stories.css, src/tools/) is outside the scan - Rule 61.12 bars design tokens there outright, so a spacing primitive in chrome is a different violation.

Foundation tokens re-pointed in scope​

23.29. A component or utility stylesheet MUST NOT declare a foundation token - one that src/variables.css or src/options.css declares - except a color token inside @layer surface.

A token declared on an element re-points it for every descendant rule that reads it, so the declaration re-themes whatever a consumer places inside the component, not only the parts the component owns. The one case that needs it is a component that paints its own surface: a hero over a background image and scrim re-points the text and heading colors, so the typography placed on that surface stays legible. Anything else a component adjusts goes through its own tokens (Rule 23.7), or through a composed component's base slots (Rule 24.16).

/* Correct - the on-image surface keeps nested headings legible. */
@layer surface {
.hero:has(> .hero-background) {
--heading-color: var(--hero-on-image-color);
}
}

/* Wrong - a spacing primitive re-pointed for everything inside the card. */
@layer base {
.card {
--space-y-4: 1rem;
}
}

Enforced by

23.25, 23.18, 23.4, 23.7, 23.5, 23.26, 23.8, 23.28, 23.27, 23.29, 23.3, 23.1 by yarn cli 23 (findTierVocabViolations, lint, findLiteralColorViolations, findTierReferenceViolations, findUnderscoreCustomProperties, findDeviceBreakpointTokens, findFocusSlotViolations, findAxisMismatchedSpacing, findFoundationTokenWrites, findPrimitiveVarReferences, findChildTokenNearMisses in packages/cli/src/rules/23.js). 23.2, 23.6, 23.9-23.17, 23.19-23.24 are review only. See enforcement.md.