one ladder, four slots — and a TW4 plugin with zero JS

Every painted surface in this registry answers two orthogonal questions. HOW LOUD is it? — the prominence ladder: fill, tonal, outline, ghost, plus fused (the backdrop-fusion rung, promoted 2026-09-08 — paint derived from the ground behind the element). WHAT DOES IT MEAN? — a hue injected into four global, inheritable slots (--jx-fill, --jx-fill-ink, --jx-tonal, --jx-outline). The old semantic-name variants (primary, secondary, destructive as prop values) are retired: they multiplied a color union into every component and fused prominence with meaning. The grammar keeps one small ladder per surface and moves intent to the call site — and since 2026-08-27 the curated intents ship as Tailwind v4 @utility rules authored inside the theme sheet itself: installing the theme IS installing the plugin. This page is the standard and the plugin's manual.

The ladder — fill, tonal, outline, ghost, fused

Prominence is a ladder, and it is the ONLY thing the variant prop encodes. fill speaks loudest (solid ground, same-hue border, inverted ink); tonal is the tinted voice (a 12% tint of the hue); outline draws structure only (transparent ground, border-colored border); ghost is interactive chrome (transparent at rest, tonal on hover, geometry preserved through a transparent border). fused is the backdrop-fusion rung (2026-09-08): paint derived from the ground BEHIND the element — a transparent chip + a backdrop contrast filter pull whatever sits behind toward mid, so the band reads over any ground with zero color tokens; the quietest rung, no own color, the filter IS the frame (forced-colors repaints it CanvasText). link is deliberately NOT on the ladder — it is PressButton's one interaction exception: no frame, no press shadow, primary text, hover underline. Availability is per-component: banners never get fill (readability), badges never get ghost (they are display, not chrome), quotes stop at outline/tonal — quote readability excludes fill/ghost, and ghost is interactive-chrome vocabulary a static quote misuses (the Blockquote row joins the frozen availability table in the same two-rung shape as Alert).

The four tokens — global, inheritable, theme-owned

Variant paint never names a color; it consumes four custom properties defined once on :root (and the byte-identical registry mirror). They are inheritable by nature: mount an injection on a subtree and every ladder consumer inside retunes. They are density-free: color only, no geometry. And the set is closed on purpose — there is no --jx-ghost (ghost derives its hover tint from --jx-tonal) and no --jx-tonal-ink (tonal text IS the hue).

Semantic hue injection — meaning rides the slots

A failed build is not a variant of loudness, so failure is not a variant name. Intent is expressed by injecting a semantic value into the slots, and ONE law governs the vocabulary: action vs status is MANDATORY. destructive is an ACTION hue — it may only ride the fill pair, on things that delete. error is a STATUS hue — it rides the tonal slot, on things that report. The split is not stylistic: destructive stays the theme's monochrome inversion pair (black-on-light, white-on-dark) while error is the red semantic — conflating them painted delete buttons red and failure banners inverted, both wrong.

The intent layer — a Tailwind v4 plugin with zero JS

The arbitrary-property seam (class with bracketed custom properties) works everywhere, but it is verbose, typo-fragile — a misspelled token still emits a well-formed rule that silently dead-styles — and its pair invariant was enforced only by prose. The fix is not a JavaScript plugin: the intent names are authored as TW4-native @utility rules INSIDE the theme sheet. Installing the theme IS installing the plugin; registry consumers need zero JS setup. The set is closed, so a typo matches nothing and emits nothing — a compile-time miss instead of silent dead CSS. And the emission is not an approximation: on the resolved Tailwind 4.3.3, @tailwindcss/node's candidatesToCss probes the @utility output as declaration-equivalent to the arbitrary-property form — identical declarations, predictably different selectors.

The TW4 laws this grammar rides

The grammar is authored as utilities in the markup, which buys theme-scale retuning at the cost of living inside Tailwind's cascade. Three laws keep that trade honest.

Forced colors — explicit degradation

Under forced-colors the color-mix tints do not drop on their own — the r2 review's Chromium probe measured exactly that — so every rung carries its own degradation utilities instead of trusting the engine. A full forced-colors browser probe for all five modules is a pending gate of the variant-grammar contract (see its verification.md honest-gaps list). The system palette gets the message across; the 1px border survives; nothing informational is lost.

Old vocabulary → the grammar

The frozen mapping tables (variant-grammar design.md §5, plus the intent-utility mapping). The one deliberate visual change: the old yellow secondary button softens to tonal + neutral — Owner-reviewed in the browser before release.

Guards & a11y — what the suite locks

A grammar this small only survives if drift fails loudly. Spec files and guards lock the source today; the contrast and forced-colors browser probes are the contract's pending gates.

Elevation — the shadow physics

Paint says what a surface is; elevation says where it sits. Shadow offset ∝ the distance between an element's plane and the surface it casts upon (Owner ruling, 2026-09-01): the website-scaffold's top layer floats above the shell body, so what crosses that gap projects large, what stays in the layer lifts little, and what is cut into the plane casts nothing outward at all. Ink inverts per theme; geometry never drifts between themes.

The entity law — border is objecthood

Elevation says where a surface sits; entity says whether it should BE a surface at all. Border is objecthood: a bordered box asserts itself as a solid object, and inside an already-solid entity (a dialog panel) every extra FILL is another object competing with its container. The law is mathematical, not per-component taste (Owner rulings 2026-09-01 + r14-12): the entity context ACCUMULATES depth — at depth ≥1 a form control is an engraved WELL of the entity’s surface: the GROUND dissolves (the entity’s surface is the basin’s interior — never a second opaque fill, backdrop-filter as the tint) while the well’s hairline EDGE STAYS (a boundary must never ride on the shadow alone; the edge is structure, not objecthood); data-assert-border force-spends the ground back early, and data-dissolve-border opts a flush edge-to-edge field out (the palette’s head — the edge there would double the panel’s border).