Rule 22 - CSS: Capability vocabulary
The canonical set of value words and their capability categories.
Rules
22.1. Contributors MUST pick value words from the vocabulary in
docs/content/capability-vocabulary.md. That
document is auto-generated from spec/spec.js (canonical capabilities),
every component {id}.spec.js (per-component custom values), and
every utility / foundation {id}.spec.js (standalone utility classes) by
yarn cli vocab.
22.2. New canonical value words MUST be added by registering the
word in the vocabulary map in spec/spec.js and listing it under
the values of the relevant Capability entry in the same file.
New utility classes MUST be declared as an enum-prop value in that
utility's {id}.spec.js under src/utilities/ or src/foundation/.
Per-component custom values MUST be declared in that component's
{id}.spec.js. The vocabulary reference doc follows automatically -
manual edits to docs/content/capability-vocabulary.md MUST NOT be made;
yarn lint enforces this via yarn cli vocab --check.
22.3. A word's canonical meaning MUST be preserved. If a component needs a subtly different behavior, a different word MUST be used or the vocabulary MUST be extended.
A component whose values do not carry the capability's meaning MUST
declare its own enum prop rather than opting into the capability.
icon's .outline and .solid select which drawing a sprite
symbol displays; they paint no surface, so they are an outlier enum
prop per Rule 53.7 and not Fill values.
// Wrong - Fill's words carry a meaning Fill does not define.capabilities: [c.Fill.use([c.Fill.outline, c.Fill.solid])], // selects sprite artwork// Correct - a component-local enum declares what its own words mean.prop.enum('artwork', { outlier: true, values: ['outline', 'solid'], default: 'outline', description: '…' }),
22.4. Values MUST be organized into the following capabilities.
Each capability maps to a CSS @layer of the same name declared
in src/layers.css. The layer declaration also includes tokens
(the weakest layer, per Rule 21.15),
base (unstyled component), surface, and
state - layers that sit between or bookend the capabilities but
do not back a canonical capability today (they are reserved
for utility, foundation, or runtime-state use per
Rule 24) - plus one layer per outlier
enum prop that carries its own values (artwork, decoration,
type), named after the prop per
Rule 53.17.
| # | Capability | Layer | What it controls |
|---|---|---|---|
| - | (base) | base | Unstyled component defaults |
| 1 | Emphasis | emphasis | Visual prominence weight within the palette |
| 2 | Intent | intent | Semantic status palette (opt-in, no default) |
| 3 | Fill | fill | How the component renders its surface fill |
| 4 | Size | size | T-shirt size scale |
| 5 | Shape | shape | Corner geometry |
| 6 | Fit | fit | How content scales within the component box |
| 7 | Layout | layout | Container width behavior |
| 8 | Orientation | orientation | Primary axis along which children flow |
| 9 | Alignment | alignment | Edge or position the component anchors to |
| 10 | Spacing | spacing | Separation the component draws between its own parts |
| 11 | Position | position | How the component is positioned in the viewport |
| 12 | Visibility | visibility | How the component participates in layout and accessibility |
| 13 | Motion | motion | Whether the component animates or stays still |
| 14 | Elevation | elevation | How far a surface lifts off the page |
| - | (surface) | surface | Reserved for surface-decoration utilities; no canonical capability today |
| 15 | Annotation | annotation | Author-set status marker drawn beside the content |
| - | (state) | state | Runtime state (native / ARIA / data-*) |
22.5. Adding a new capability MUST include adding a corresponding
@layer to src/layers.css.
22.6. Breakpoint-scoped values MUST use the suffix form
.at-{breakpoint} (.at-sm, .at-md, .at-lg, .at-xl). The
bare words .xs, .sm, .md, .lg, .xl are SIZE values only
and MUST NOT be used for breakpoint scoping.
22.7. Value words MUST NOT be prefixed with component names.
Example:
.btn.lgnot.btn-lg.
22.8. Color names (.blue, .dark) MUST NOT be used as
values - emphasis values (.subtle, .neutral, .accent) or
intent values (.info, .warning, .danger, .success) MUST be
used instead.
22.9. Runtime / observed state MUST NOT use value words.
Runtime state is expressed via attributes (native pseudo-classes,
ARIA, or namespaced data-*) per
Rule 24. A bare value class on a
child element that marks a declarative, author-set status in
markup (e.g. .complete on a <li> inside .steps) is a
value, not state - its CSS still lives in the matching
value @layer (e.g. annotation), not @layer state.
Such a word is registered on its capability in spec/spec.js and
left out of every component's .use() list. A .use() puts the
word on the component root, where a child-scoped class matches
nothing, so the registry entry is what gives the word one
canonical meaning and one published description. 22.15 still
checks it against the shipped CSS.
22.10. Utility classes that accept a size tier MUST always include
an explicit size suffix from the canonical ladder
(-xxs, -xs, -sm, -md, -lg, -xl, -xxl, -xxxl).
Individual utility families MAY expose any contiguous subset of the
ladder - space-above-* covers -sm/-md/-lg, w-* and h-*
cover the full eight tiers - but the suffixes themselves are drawn
from this single ladder. Unlike component values where absence
means "default", utility classes MUST NOT have an implicit default -
every usage states its size.
Example:
.space-above-mdnot.space-above.
The spacing utilities (.m{n}, .p{n}, .gap-{n}, .mxn{n}) draw their suffix from the numeric step scale of the --space-x-{n} / --space-y-{n} primitives instead of the t-shirt ladder, and a sizing or margin family MAY add an -auto slot (.mt-auto, .w-auto) for the browser-computed value. Both are standalone families under Rule 21.13.
22.11. A tiered utility family that represents a level scale (depth, z-axis) MAY add a single non-tier reset slot using a descriptive word. The reset slot MUST use a word, not a numeric value or t-shirt suffix, and MUST sit alongside the tier classes (it does not replace them).
Example:
.elevation-flatis the reset slot in the elevation family;.elevation-raisedand.elevation-elevatedare the level classes, drawn from the Elevation capability's own words rather than the size ladder of Rule 22.10.
22.12. emphasis and intent are the two palette dials that
together control what the surface, border, and text colors
mean. They are orthogonal to fill (Rule 22.14), which
controls how the surface is painted.
emphasis is the prominence dial - a quieter or louder weight
relative to the standard neutral contrast. A component that opts in
declares a default (neutral). Emphasis values are:
| Value | Role |
|---|---|
subtle | Lower emphasis. A muted, quieter weight. |
neutral | Default emphasis. The standard weight at balanced contrast. |
accent | Higher emphasis. A stronger, louder weight. |
intent is the semantic status dial - it colors the
component to carry meaning. It is opt-in with no default: a
component reads as neutral (no status) unless it sets one. Intent
values are:
| Value | Role |
|---|---|
info | Informational message. Info palette. |
warning | Warning or caution. Warn palette. |
danger | Error / destructive. Fail palette. |
success | Confirmation. Pass palette. |
The emphasis values are mutually exclusive; the intent values are
mutually exclusive. A component opts into emphasis, intent, or
both, depending on whether prominence, status, or both are
meaningful for it. The default build styles each value within its
own @layer; combinations across the two axes (e.g. subtle on
danger) are not defined in the default vocabulary - if a consumer
needs one they extend the spec deliberately. intent composes with
fill: a button can be intent: danger (destructive palette) and
fill: ghost (no surface) at the same time.
When both an emphasis word and an intent word sit on one element,
the intent renders. The emphasis layer is declared before
intent in src/layers.css (Rule 21.10),
so the two cannot both paint a slot and the status is what survives.
A component MUST NOT re-establish the opposite precedence with a
:not() guard or a compound selector: emphasis carries a default
that every component emits, so a defaulted word that outranked an
explicit status would make the intent unreachable, and on a
component whose markup announces the status (a callout's
aria-label) it would leave assistive technology describing a
surface the reader cannot see.
22.13. The class words .primary, .secondary, and .tertiary
MUST NOT be used as bare value classes on any component root.
They duplicate the canonical Emphasis and Intent ladders declared
in 22.12 and create a parallel emphasis vocabulary that drifts in
consumer-facing markup.
Component-prefixed child classes such as .mobilenav-primary,
.mobilenav-secondary, or .dropdown-primary remain legal - the
hyphenated prefix makes them children per Rule 21.4, not values.
Foundation palette primitives (--color-primary-N,
--color-secondary-N, --color-tertiary-N) and font-family aliases
(--font-family-primary, --font-family-secondary) are CSS custom
properties, not class words, and are out of scope for this rule.
/* Wrong - bare emphasis-tier value */.btn.secondary { ... }/* Correct - canonical Emphasis value */.btn.subtle { ... }/* Correct - component-prefixed child class */.mobilenav-primary { ... }
22.14. The fill capability is the surface paint dial - it
controls whether the component renders with a filled background,
a bordered shape, or no surface at all. It is orthogonal to
intent and emphasis (Rule 22.12), which control what the
colors mean. Fill values are:
| Value | Role |
|---|---|
solid | Filled surface. Background rendered, with a border in the palette's border color or in the surface color where the component reads as filled either way; the palette comes from intent and emphasis. |
outline | Bordered surface. Visible border with a transparent background; the palette comes from intent and emphasis. |
ghost | No surface. Background and border both transparent - only text or icon remains, in the palette's color. |
The three values are mutually exclusive. fill: ghost and
emphasis: subtle look quiet for different reasons - ghost
removes the surface entirely, subtle keeps it but at a lower
weight - and they may be combined.
22.15. Every value declared on a canonical capability in
spec/spec.js MUST be backed by a class selector inside an
@layer named after that capability, in shipped CSS under
src/. The capability registry is the dictionary every
component draws its words from; a word that names no class is
unusable, because markup generated from the spec renders
unstyled and the failure is silent - the class simply never
matches.
The value word IS the class name, verbatim. Rule 21.1 declares
the value pattern as .{value}, and the vocabulary doc, the
component-class registry, and Rule 53.17's own selector matcher
all derive the class by prefixing a dot to the word. No mapping
layer exists, so a word without a class is a broken dictionary
entry rather than an alternative spelling.
A value counts as backed when its class token appears under its
own capability's layer, whether component-scoped (.card.raised
in @layer elevation) or as a global atomic utility (.hidden
in @layer visibility). Requiring the matching layer rather than
merely the class somewhere also catches a value implemented in
the wrong layer, where the capability precedence established by
Rule 21.10 silently stops holding. Whether the right components
opt into it is Rule 53.17's concern, not
this one's.
This is the only check entered from the capability registry
itself. Every other capability check reaches values through a
component's .use() list, so a word that no component opts into
is otherwise never validated at all.
Sidecar token files (*.variables.css), Storybook chrome
(*.stories.css), and src/tools/ are outside the scan: none
of them ship class selectors to consumers.
22.16. Every value a utility or foundation {id}.spec.js declares
as a class word MUST have a selector carrying that word in that
utility's OWN {id}.css. This is the reverse of 22.2: 22.2 stops
a class existing without a declaration, 22.16 stops a declaration
existing without a class.
It is a separate check because a utility's classes are
standalone - .invisible stands alone, it is never
.visibility.invisible - so nothing else reaches them.
Rule 53.17 runs for Components only, so it
never reaches a utility's classes at all, and Rule 22.15 is
satisfied by any component shipping a scoped variant
(a .drawer.invisible inside @layer visibility keeps the
registry happy even after the standalone .invisible is deleted).
Left unchecked, deleting a utility class leaves it published in the
vocabulary reference while the bundle ships nothing behind it.
outlier: true MUST NOT exempt a value here. On an atomic utility
that flag means "not the .{component}.{value} selector shape",
not "not a class"; honoring it would skip exactly the values this
rule exists to protect.
Matching is per value word inside the utility's own file, so both
shapes a utility may use satisfy it: a standalone .invisible, and
a self-scoped .grid.sm where the value rides on the utility class.
// Wrong - the capability declares a word that names no class.Visibility: capability(v.visibility, {values: {[v.assistive]: 'Visually hidden, accessible to screen readers.',},});// ...with no `.assistive` rule anywhere in src/.
Reference
The full word list - canonical values per capability,
component custom values, and utility classes - is in the
auto-generated docs/content/capability-vocabulary.md.
That file is the single rendered surface of the spec system; the
underlying sources are spec/spec.js and every component, utility,
and foundation {id}.spec.js.
The yarn cli utility-spec linter additionally enforces a
one-way contract for the CSS under src/foundation/ and
src/utilities/: every utility-CSS class MUST be declared as an
enum-prop value in a utility, foundation, or component {id}.spec.js.
22.1, 22.2, 22.16, 22.13, 22.15 by yarn cli 22 (vocab in packages/cli/src/commands/vocab.js, findClassesWithoutSpec in packages/cli/src/rules/utility-spec.js, findValuesWithoutCss in packages/cli/src/rules/utility-spec.js, findForbiddenTierValues in packages/cli/src/rules/forbidden-tier-values.js, findUnbackedCapabilityValues in packages/cli/src/rules/capability-css.js). 22.3-22.12, 22.14 are review only. See enforcement.md.