Rule 21 - CSS: Class structure
How CSS classes are named, composed, and layered.
Rules
Naming
21.1. Semetrika MUST use exactly three kinds of class:
| Kind | Pattern | Example |
|---|---|---|
| Component class | .{component} | .btn, .card, .message |
| Child class | .{component}-{child} | .card-header, .modal-body |
| Value | .{value} | .subtle, .outline, .sm |
Runtime / observed state lives on attributes, not classes - see Rule 24.
A selector that styles a class a third-party library writes (.hljs-keyword, .token from a syntax highlighter) is outside the three kinds: the class is the library's contract, not Semetrika's, and Rule 53.27 skips it as a cross-reference.
21.2. All class names MUST be lowercase kebab-case.
21.3. Component class names SHOULD be a single word. Multi-word names MAY be used when no single word exists.
21.4. Child classes MUST use the flat dash pattern
.{component}-{child} and MUST only exist on compound components
with named structural parts. An atomic component (button, badge,
chip) has no structural children; the glyph it renders inside
itself (.btn-icon, .badge-icon, .chip-close) is the one child
it MAY name.
21.5. A child class carries its component's prefix, so a bare child word scoped by its parent MUST NOT stand in for it. The prefixed class MAY sit under a direct-child combinator per Rule 11.13, which keeps the part from matching outside its component.
/* Correct */.card > .card-header {font-weight: bold;}/* Wrong */.card > .header {font-weight: bold;}
Composition
21.6. Values MUST compose via multiple classes on the element. Combined class names MUST NOT be used.
<!-- Correct --><button class="subtle outline sm">Cancel</button><!-- Wrong --><button class="btn-subtle-outline-sm">Cancel</button>
21.7. The .{component}-{value} pattern MUST NOT be used for
values. That form is RESERVED for children only.
21.8. The order of classes on the HTML element MUST NOT affect the
result. Precedence is determined by CSS @layer, not class order.
Layer precedence
21.9. Every value MUST be component-scoped:
button.subtle, a.subtle. Global .subtle selectors
MUST NOT exist.
/* Button's emphasis */@layer emphasis {button.subtle,.btn.subtle {background: var(--btn-subtle-background-color);}}/* Link's emphasis - different properties, same word */@layer emphasis {a.subtle,.link.subtle {color: var(--link-subtle-color);}}
21.10. Semetrika MUST use CSS @layer to guarantee value
capability precedence. The layer declaration in src/layers.css
MUST be loaded first in the bundle.
@layer tokens, base, emphasis, intent, fill, size, shape, fit, layout,orientation, alignment, spacing, position, visibility, motion,elevation, surface, annotation, artwork, decoration, type, state;
emphasisprecedesintentso an explicit status outranks the emphasis default, per Rule 22.12.
artwork,decoration, andtypeback outlier enum props rather than canonical capabilities (see Rule 22.4). They sit after the capabilities so a component-local variant is not overridden by a generic capability, and beforestateso runtime state still wins.
tokensis declared first, so it is the weakest layer (see Rule 21.15).
21.11. Component CSS MUST wrap each set of values in the matching layer.
@layer base {button,.btn {background: var(--btn-background-color);}}@layer fill {button.outline,.btn.outline {background: transparent;border: 1px solid currentColor;}}@layer size {button.sm,.btn.sm {padding: var(--space-y-1) var(--space-x-2);}}
Runtime state on selectors
21.12. Runtime / observed state MUST be expressed via selectors
(native pseudo-classes, ARIA attributes, or namespaced data-*)
per Rule 24, not via classes. The
.is-* state-class convention MUST NOT be used.
A bare value class on a child element that marks a declarative,
author-set status in markup (e.g.
<ol class="steps"><li class="complete">…</li></ol>) is NOT a
state - it is a value and follows
Rule 22. The distinction is who
sets the value: if author markup sets it, it is a value; if
the browser, JS, or another runtime signal sets it, it is state.
Grid column exception
21.13. Two families of standalone utility classes MAY use compound names as the designated exceptions to 21.7. The grid family - spans (.col-1 through .col-12, .col-BP-N), offsets (.col-offset-N, .col-BP-offset-N), auto columns (.col-BP) and ordering (.first, .last, .first-BP, .last-BP) - because a class name cannot start with a digit and a breakpoint-scoped value encodes 2 coupled values. And the tiered utility families of Rule 22.10 (.space-above-md, .elevation-raised, .w-xs, .m1, .gap-3, .at-md), because a standalone utility has no component class for a value to compose with. Grid values that do compose (.auto, .flush, .reverse) MUST still compose per this rule.
Global CSS identifiers
21.14. Internal CSS identifiers that live in the document's
global namespace - named @container (the container-name
value) and @keyframes identifiers - MUST be chosen as bare,
descriptive names and MUST NOT carry a semetrika- prefix.
Semetrika's CSS is the consumer's CSS; the document's identifier
namespace belongs to the design system, so a defensive prefix
solves no collision problem.
/* Correct */:root {container-name: options;}@container options style(--option-loading-mode: spinner) {/* ... */}@keyframes loading-spin {/* ... */}/* Wrong */:root {container-name: semetrika-options;}@container semetrika-options style(--option-loading-mode: spinner) {/* ... */}@keyframes semetrika-loading-spin {/* ... */}
CSS custom properties carry their own naming conventions per
Rule 23 (--option-*,
--{component}-*) and are not subject to this rule.
Token layer
21.15. Every design-token file - src/variables.css,
src/options.css, and every component / utility sidecar
{name}.variables.css - MUST wrap its :root and
:root[data-color-scheme='…'] blocks in the tokens layer.
tokens is declared first in src/layers.css, so it is the weakest
layer: an unlayered consumer override (:root { --x: … }) always wins
regardless of stylesheet or document order, and even when the consumer
scopes their own CSS inside an @layer. At-rules that do not declare
tokens (@property, @keyframes) stay at file scope; only the :root
token blocks are wrapped.
@layer tokens {:root {--btn-accent-color: var(--color-primary-7);}:root[data-color-scheme='dark'] {--btn-accent-color: var(--color-primary-2);}}
Unlayered rules
21.16. Every rule in a shipped stylesheet MUST sit inside a @layer block. The at-rules that declare no selector - @font-face, @property, @keyframes - and @layer statements stay at file scope.
Unlayered normal declarations outrank every layer, whatever their specificity; !important reverses the order, so a layered important declaration outranks an unlayered one. One unlayered rule therefore beats every capability value, visibility value and runtime state that sets the same property on its element, and the precedence 21.10 builds stops holding for it: an unlayered .flex shows an element .hidden hides, an unlayered .p3 pads an element .assistive collapses, and an unlayered component rule competes with a consumer's unlayered override on specificity, where Rule 21.15 promises the consumer always wins.
A utility's classes sit in the layer of what they change. Padding, margin and gap classes take spacing, the layer Rule 22.4 reserves for them, so they still override every layer declared before it.
/* Wrong - unlayered, so it outranks `.hidden` in `@layer visibility`. */.flex {display: flex;}/* Correct */@layer layout {.flex {display: flex;}}
21.10, 21.15, 21.16 by yarn cli 21 (findInvertedPaletteLayers, findUnlayeredTokenBlocks, findUnlayeredRules in packages/cli/src/rules/21.js). 21.1-21.9, 21.11-21.14 are review only. See enforcement.md.