Skip to main content

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:

KindPatternExample
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;

emphasis precedes intent so an explicit status outranks the emphasis default, per Rule 22.12.

artwork, decoration, and type back 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 before state so runtime state still wins.

tokens is 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;
}
}

Enforced by

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.