Skip to main content

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.

#CapabilityLayerWhat it controls
-(base)baseUnstyled component defaults
1EmphasisemphasisVisual prominence weight within the palette
2IntentintentSemantic status palette (opt-in, no default)
3FillfillHow the component renders its surface fill
4SizesizeT-shirt size scale
5ShapeshapeCorner geometry
6FitfitHow content scales within the component box
7LayoutlayoutContainer width behavior
8OrientationorientationPrimary axis along which children flow
9AlignmentalignmentEdge or position the component anchors to
10SpacingspacingSeparation the component draws between its own parts
11PositionpositionHow the component is positioned in the viewport
12VisibilityvisibilityHow the component participates in layout and accessibility
13MotionmotionWhether the component animates or stays still
14ElevationelevationHow far a surface lifts off the page
-(surface)surfaceReserved for surface-decoration utilities; no canonical capability today
15AnnotationannotationAuthor-set status marker drawn beside the content
-(state)stateRuntime 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.lg not .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-md not .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-flat is the reset slot in the elevation family; .elevation-raised and .elevation-elevated are 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:

ValueRole
subtleLower emphasis. A muted, quieter weight.
neutralDefault emphasis. The standard weight at balanced contrast.
accentHigher 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:

ValueRole
infoInformational message. Info palette.
warningWarning or caution. Warn palette.
dangerError / destructive. Fail palette.
successConfirmation. 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:

ValueRole
solidFilled 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.
outlineBordered surface. Visible border with a transparent background; the palette comes from intent and emphasis.
ghostNo 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.


Enforced by

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.