Rule 24 - CSS: State and color scheme
How CSS responds to runtime state and color scheme.
State handling
State here means runtime / observed state - values that change
in response to user interaction, scroll position, network result,
or other ambient conditions. Declarative, author-set "marker"
classes on child elements (e.g. a <li> marked complete in
markup) are NOT state for the purposes of this rule - they are
values and are governed by
Rule 22.
24.1. Runtime state MUST follow a strict three-tier priority. A lower tier MUST NOT be used when a higher one covers the case.
24.2. Tier 1 - Native pseudo-classes MUST be used when
available: :hover, :focus-visible, :disabled, :checked,
:required, :read-only, :invalid.
24.3. Tier 2 - ARIA attribute selectors MUST be used when
the ARIA attribute accurately describes the element's semantic
state: [aria-invalid], [aria-busy], [aria-pressed],
[aria-expanded], [aria-current], [aria-disabled].
24.4. Tier 3 - Data attributes MAY be used only when Tiers 1
and 2 do not cover the case. The attribute MUST be namespaced to
the owning component or utility:
[data-{component}-{state}] ([data-tabs-active]) or
[data-{utility}-{state}] ([data-scrollspy-scrolled]). When a
state is conceptually shared across more than one component (e.g.
"active trail" across navbar, sidenav, and mobilenav), the
attribute MAY use a shared functional namespace such as
data-nav-active-trail.
The {state} segment MUST be an adjective or past participle
that matches ARIA vocabulary precedent (expanded, busy,
pressed, current, disabled, checked), on its own or
qualifying a named part as {part}-{adjective} (backdrop-open,
scroll-lock) when the state belongs to that part rather than to
the root. Examples in this codebase: active, scrolled, placed,
collapsed, collapsing, open. Verb-inflected forms (e.g.
.is-stuck as the "state form" of .sticky) MUST NOT be invented;
they add an irregular vocabulary that diverges from the ARIA
precedent above.
The legacy .is-* state-class form MUST NOT be used. Existing
declarations MUST be migrated to a data attribute or removed in
favor of the equivalent ARIA attribute or DOM operation.
24.5. aria-label values MUST NOT be used as CSS selectors
(localizable, will break).
24.6. ARIA attributes MUST NOT be added purely for visual effect without semantic truth.
Color scheme
24.7. Semetrika MUST ship exactly two color schemes: light (default,
implicit) and dark (opted in via data-color-scheme="dark").
24.8. Color scheme MUST be set at page level on <html> ONLY.
Setting data-color-scheme on <body>, on a section, on a
component, or on any other descendant element MUST NOT have any
effect. Per-component / per-section color schemes are not a
supported feature of the design system. The CSS overrides are
scoped to :root[data-color-scheme='dark'] and
:root[data-color-scheme='light'] to enforce this - a stray
attribute lower in the tree resolves to nothing.
<!-- Light (default) --><html></html><!-- Forced light, explicit --><html data-color-scheme="light"></html><!-- Forced dark --><html data-color-scheme="dark"></html>
24.9. Components MUST use semantic tokens (--text-color-neutral,
--background-color-neutral). Palette primitives MUST NOT be used
for scheme-aware properties.
24.10. Tokens that vary by color scheme MUST be declared on
:root (the light value) and overridden in a single
:root[data-color-scheme='dark'] block (the dark value). No
auto-resolution helper (e.g. light-dark()) is used.
A token appears in the dark block only when its value genuinely
differs - see Rule 24.12. A token whose value is the same in
both schemes, or whose value references a semantic token that
already flips, is declared once on :root.
@layer tokens {:root {--page-background-color: var(--color-neutral-1);}:root[data-color-scheme='dark'] {--page-background-color: var(--color-primary-9);}}
24.11. The :root[data-color-scheme='dark'] block MUST also set
color-scheme: dark (and the sibling :root[data-color-scheme='light']
block MUST set color-scheme: light) so native browser UI
(scrollbars, default form controls, date pickers) follows the
design-system scheme.
24.12. The :root[data-color-scheme='dark'] block MUST carry only
genuine differences. A dark entry whose value is byte-identical to
its :root counterpart MUST NOT be written: it states nothing, and
a token absent from the dark block simply inherits its light
declaration. Where that declaration references a scheme-aware
semantic token, the flip has already happened upstream and
repeating it per component is noise.
A dark entry with no matching :root declaration is an orphan and
MUST NOT be written either.
Palette primitives (--color-{family}-{step}) are absolute brand
colors and are exempt. The rule is enforced by
packages/cli/src/rules/24.js and runs as part of yarn lint.
/* Wrong - the dark entry repeats the light value verbatim. */:root {--btn-subtle-color: var(--text-color-subtle);}:root[data-color-scheme='dark'] {--btn-subtle-color: var(--text-color-subtle);}/* Correct - declare it once; `--text-color-subtle` flips upstream. */:root {--btn-subtle-color: var(--text-color-subtle);}
24.13. Any token whose value is a pure color (hex,
rgba()/rgb(), color-mix(), currentColor, transparent,
hsl()/hsla(), or a var(--…) reference that resolves to a
color token) MUST have a name ending in one of:
-color-color-subtle/-color-neutral/-color-accent(the three emphasis tiers for thetext,border, andbackgroundfoundational families)-color-danger/-color-info/-color-success/-color-warning(the four intents on the same three families)-background-color-border-color-shadow-color
Composite values (e.g. --callout-border: 0.1875rem solid var(--border-color-neutral);)
are not subject to this rule. If a composite includes a color that
should flip by scheme, extract the color into a separate
-*-color token and reference it from the composite via var().
Suffixes like -bg, -fg, or a bare -border on a pure-color
value are NOT allowed and will fail lint. The rule is enforced by
packages/cli/src/rules/24.js.
24.14. Further scheme values (data-color-scheme="brand-x",
data-color-scheme="high-contrast") MUST NOT be added.
Consumer-specific color modes are consumer-level CSS.
24.15. Semetrika ships a color-scheme control - the
scheme-switcher component, built on the cycle utility - that
resolves the user's preference (light / dark / system),
writes the resolved scheme to <html> via data-color-scheme,
persists the preference in localStorage, and tracks the OS query
while the preference is system. The no-FOUC <head> snippet that
applies the stored preference before the first paint remains the
consumer application's responsibility, because a stylesheet cannot
inline a head script. See
Foundation/Color scheme for
the scheme contract and the canonical snippet, and the
scheme-switcher component for the shipped control.
Value implementation pattern
24.16. Component CSS MUST follow the per-value variable, base
slot pattern. The base layer reads --{component}-{concern} (the
slot) via var(), and each @layer {capability} block contains one
selector per declared spec value that re-points that slot to
--{component}-{value}-{concern}.
A value-layer selector MUST re-point the base slot rather than assign the CSS property, whenever the base layer already renders that property and 24.16c permits it. The base rule then lists the component's entire knob surface in one place, and every capability layer reads as a flat list of remappings.
@layer base {.callout {background-color: var(--callout-background-color);box-shadow: var(--callout-shadow);}}@layer elevation {/* Correct - re-points the slot the base layer renders. */.callout.raised {--callout-shadow: var(--callout-raised-shadow);}/* Wrong - assigns the property, so the slot stops being thesingle place the shadow is decided. */.callout.raised {box-shadow: var(--callout-raised-shadow);}}
This is what makes container-driven sizing work: an ancestor can
set --callout-shadow and every nested callout follows, because
nothing closer to the element has assigned the property. Direct
assignment in the value layer would block that.
Where the base layer does NOT render the property, a slot MAY be
added: give the base rule a var() read whose default is the value
the component renders today. That is visually inert and turns the
property into an override point it did not have. Naming follows
24.16b - the slot takes the infix-less name, so a value currently
holding it is renamed to --{component}-{value}-{concern} first.
/* `--image-border-radius` held the `rounded` value while the baserule rendered no radius at all, so the plain name was taken by avalue and nothing could reach an unclassed image. */--image-rounded-border-radius: var(--component-radius-rounded-lg);--image-border-radius: 0;@layer base {img,.image {border-radius: var(--image-border-radius);}}@layer shape {img.rounded,.image.rounded {--image-border-radius: var(--image-rounded-border-radius);}}
A value MUST still assign directly where the property belongs to
that value alone and a base read would be meaningless - .circle
setting aspect-ratio: 1, or a layout value setting
grid-template-columns. Adding a slot for those would invent a knob
for a property the component does not otherwise have.
24.16a. Converting a component to this shape MUST NOT collapse distinct rules into a derived one, even where they currently resolve to the same value. Collapsing removes the ability to give one value its own treatment later, which is a silent loss of expressiveness rather than a simplification.
@layer fill {/* Wrong - folds four intents into one derivation. Renders thesame today, but no intent can then be given a hover fill thatdiffers from its text color without re-adding a rule. */.btn.outline:hover {--btn-hover-background-color: var(--btn-color);}/* Correct - each intent keeps its own rule. */.btn.outline.danger:hover {--btn-hover-background-color: var(--btn-danger-color);}.btn.outline.success:hover {--btn-hover-background-color: var(--btn-success-color);}}
24.16b. A base slot is named --{component}-{concern} and holds
the component's default for that property. Where a capability that
declares a default governs the property, the slot's value MUST be
the default value's own token, so the two cannot drift apart:
/* Emphasis declares `neutral` as its default. */--btn-color: var(--btn-neutral-color);
Where 2 defaulted capabilities govern one slot, the slot mirrors
the default of the capability whose layer src/layers.css declares
first, and the later capability's default selector carries its own
contribution. Button's Emphasis re-points --btn-border-color per
palette in @layer emphasis and its Fill default solid clears it
in @layer fill, so the unclassed element renders the palette
border and solid removes it.
A base slot is an override point in its own right: setting
--btn-color on an ancestor retargets every plain button beneath
it. It does NOT override a value class, because the value class
sets the same slot on the element itself and the closer declaration
wins. A consumer restyling a danger button therefore overrides
--btn-danger-color, matching the class that is on the element -
the same contract as before this rule changed.
24.16c. A value MUST keep assigning the property directly unless all four of these hold. A re-point renders nothing on its own - it only feeds a base declaration - so each condition is about whether that base declaration still reaches the page.
- The base declaration wins its cascade. Another file may
declare the same property on the same bare element subject in the
same layer, where specificity ties and document order decides. A
value in a later layer beats that rule; a slot it reads does not.
typography.csssetsfont-sizeandcoloronblockquote, soblockquote's own base declarations lose and its size and emphasis values MUST stay direct. - The base declaration is not narrower than the value. A base
declaration inside a
@media,@container, or@supportsblock makes its slot effective only inside that condition, while the value class applies everywhere. Re-pointing then silently drops the value wherever the condition is false. Deflist rendered itscolumn-gaponly above 768px while.horizontalgoes two-column at every width, so the gap had to move out of the media block before the orientation value could re-point it. - The slot has exactly one reader. Re-pointing moves every
declaration that reads the slot, including one in the same rule.
--timeline-line-widthsets the connector thickness and also appears inside a siblingcalc(), so re-pointing it toautofor the horizontal orientation poisons the calc. - The value's expression is not the slot itself. A value whose expression already reads the slot renders nothing of its own; it exists to re-declare the property and so outrank an earlier layer. Re-pointing it would be self-referential. Give the value its own token first, per 24.17, then re-point to that.
/* Wrong - self-referential, and silently drops the property. */.card.solid {--card-background-color: var(--card-background-color);}/* Right - the value owns a token, and the slot defaults to it. */--card-solid-background-color: var(--page-background-color);--card-background-color: var(--card-solid-background-color);.card.solid {--card-background-color: var(--card-solid-background-color);}
24.16d. Where a value governs a property under a pseudo-class, it
MUST re-point the slot the base rule reads under that same
pseudo-class. .link.danger re-points --link-color and
.link.danger:hover re-points --link-hover-color; pointing a
resting value at a :hover slot would recolor a state that is
never entered.
24.17. Every spec-declared enum value (including the default)
MUST have a matching selector inside the @layer named after
that enum (the capability layer for a visual capability, or
{prop.name} for an outlier enum prop). The default-value selector exists so that
adding the class after a non-default class resets the property
back to the default - empty rule bodies do NOT satisfy this
requirement.
@layer elevation {.callout.flat {--callout-shadow: var(--callout-flat-shadow); /* explicit reset */}.callout.raised {--callout-shadow: var(--callout-raised-shadow);}}
Within a layer, source order determines the winner when multiple
classes from the same layer end up on the same element. The
non-default values are declared AFTER the default so that
class="callout flat raised" resolves to raised. If a component
needs the opposite precedence (default-always-wins), it MUST flip
the source order and document the choice in a header comment.
Intent distinctness
24.19. Within one component, two intents MUST NOT resolve to the same color for the same concern when that component's other intents differ there. Intent exists to carry status; two statuses rendering identically means one of them says nothing.
The rule compares resolved values, not sources, so it holds however a token was authored: 2 different semantic references can resolve to the same color, and only the resolved value shows it. Which sources a sidecar may reference is Rule 23.5's concern, not this one's.
A value shared by EVERY intent that declares the concern is a
deliberate common default, not a collision — four transparent
backgrounds mean the status is carried by the text or border
instead. Only color concerns are compared; a shared border-width
says nothing about status.
/* Wrong - success and info are the same color, while danger andwarning differ, so the component does distinguish intents hereand two of them have collided. */--btn-danger-color: var(--text-color-danger);--btn-info-color: var(--text-color-info);--btn-success-color: var(--text-color-info);--btn-warning-color: var(--text-color-warning);/* Fine - every intent shares the value, so it is a common default. */--btn-danger-background-color: transparent;--btn-info-background-color: transparent;--btn-success-background-color: transparent;--btn-warning-background-color: transparent;
Emphasis distinctness
24.20. Within one component, two emphasis values MUST NOT resolve to the same color on every color concern the pair declares. Emphasis exists to carry prominence; two values rendering identically means one rung of the ladder is unreachable.
Emphasis is compared per PAIR over the union of the two values' concerns, where Rule 24.19 compares intents per concern. The two vocabularies have different shapes. Four intents are peers, so two of them sharing one concern while the others differ is already the defect. Three emphasis values are a ladder, and a quieter rung is routinely built by sharing the text color and changing only the surface - comparing those per concern would reject the normal construction.
A concern only one of the pair declares still separates them: the other renders nothing there, which is a visible difference.
/* Wrong - 'subtle' and 'neutral' resolve identically on every concernthey declare, so the 'subtle' class changes nothing. */--sidenav-neutral-background-color: transparent;--sidenav-neutral-color: var(--text-color-neutral);--sidenav-subtle-background-color: transparent;--sidenav-subtle-color: var(--text-color-neutral);/* Correct - the pair shares its surface and differs in text weight. */--sidenav-neutral-background-color: transparent;--sidenav-neutral-color: var(--text-color-neutral);--sidenav-subtle-background-color: transparent;--sidenav-subtle-color: var(--text-color-subtle);
The check reads tokens, so a difference it cannot see passes it: one that renders on a zero-width border, a border painted its background's color, or a rule body assigning a literal instead of reading its value token. Those stay review-caught.
24.11, 24.12, 24.13, 24.19, 24.20 by yarn cli 24 (findColorSchemeViolations, findIndistinctIntents, findIndistinctEmphasis in packages/cli/src/rules/24.js). 24.1-24.10, 24.14-24.17 are review only. See enforcement.md.