actual-css 0.11.0 → 0.12.0

package/docs/pages/forms/sticky-actions.md

@@ -1,6 +1,6 @@
 # Sticky Actions
 
-> Use `.form-actions sticky` when long forms need reachable submit actions while scrolling.
+> Use `.cluster.form-actions.sticky` when long forms need reachable submit actions while scrolling.
 
 ## Inside the form
 
@@ -8,8 +8,8 @@ The `<form>` is the bounding parent. The sticky stays pinned to the viewport bot
 
 Scroll the page to see the actions stay reachable.
 
-```html demo
-<form novalidate>
+```html demo sticky
+<form class="stack" novalidate>
   <div class="stack">
     <label class="field">
       <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
@@ -57,7 +57,7 @@ Scroll the page to see the actions stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack compact">
+      <div class="stack tight">
         <label class="choice">
           <input class="radio" type="radio" name="theme" value="light" checked />
           <span>Light</span>
@@ -79,7 +79,7 @@ Scroll the page to see the actions stay reachable.
     </label>
   </div>
 
-  <div class="form-actions sticky">
+  <div class="cluster form-actions sticky">
     <button type="button" class="btn outline">Cancel</button>
     <button type="submit" class="btn primary">Save changes</button>
   </div>
@@ -92,84 +92,86 @@ For a sticky page footer, dialog footer, or card footer, detach the actions and
 
 Scroll the page to see the detached footer stay reachable.
 
-```html demo
-<form id="account-form" novalidate>
-  <div class="stack">
-    <label class="field">
-      <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
-      <input class="input" type="text" autocomplete="name" required placeholder="Jane Doe" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Email <span class="required-mark" aria-hidden="true">*</span></span>
-      <input class="input" type="email" autocomplete="email" required />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Phone</span>
-      <input class="input" type="tel" autocomplete="tel" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Bio</span>
-      <textarea class="textarea" rows="4" placeholder="Tell us about yourself…"></textarea>
-    </label>
-
-    <label class="field">
-      <span class="field-label">Website</span>
-      <input class="input" type="url" autocomplete="url" placeholder="https://example.com" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Language</span>
-      <select class="select">
-        <option>English</option>
-        <option>Français</option>
-        <option>Deutsch</option>
-      </select>
-    </label>
-
-    <label class="field">
-      <span class="field-label">Experience level</span>
-      <input class="range" type="range" min="0" max="10" value="5" />
-    </label>
-
-    <label class="field">
-      <span class="field-label">Profile picture</span>
-      <input class="file" type="file" accept="image/*" />
-    </label>
-
-    <fieldset class="field-group">
-      <legend class="field-label">Theme</legend>
-      <div class="stack compact">
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="light" checked />
-          <span>Light</span>
-        </label>
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="dark" />
-          <span>Dark</span>
-        </label>
-        <label class="choice">
-          <input class="radio" type="radio" name="theme-detached" value="auto" />
-          <span>System</span>
-        </label>
-      </div>
-    </fieldset>
-
-    <label class="choice">
-      <input class="check" type="checkbox" />
-      <span>Email notifications</span>
-    </label>
-  </div>
-</form>
-
-<footer class="form-actions sticky">
-  <button type="button" class="btn outline">Cancel</button>
-  <button type="submit" class="btn primary" form="account-form">
-    Save changes
-  </button>
-</footer>
+```html demo sticky
+<div class="stack">
+  <form id="account-form" novalidate>
+    <div class="stack">
+      <label class="field">
+        <span class="field-label">Full name <span class="required-mark" aria-hidden="true">*</span></span>
+        <input class="input" type="text" autocomplete="name" required placeholder="Jane Doe" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Email <span class="required-mark" aria-hidden="true">*</span></span>
+        <input class="input" type="email" autocomplete="email" required />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Phone</span>
+        <input class="input" type="tel" autocomplete="tel" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Bio</span>
+        <textarea class="textarea" rows="4" placeholder="Tell us about yourself…"></textarea>
+      </label>
+
+      <label class="field">
+        <span class="field-label">Website</span>
+        <input class="input" type="url" autocomplete="url" placeholder="https://example.com" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Language</span>
+        <select class="select">
+          <option>English</option>
+          <option>Français</option>
+          <option>Deutsch</option>
+        </select>
+      </label>
+
+      <label class="field">
+        <span class="field-label">Experience level</span>
+        <input class="range" type="range" min="0" max="10" value="5" />
+      </label>
+
+      <label class="field">
+        <span class="field-label">Profile picture</span>
+        <input class="file" type="file" accept="image/*" />
+      </label>
+
+      <fieldset class="field-group">
+        <legend class="field-label">Theme</legend>
+        <div class="stack tight">
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="light" checked />
+            <span>Light</span>
+          </label>
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="dark" />
+            <span>Dark</span>
+          </label>
+          <label class="choice">
+            <input class="radio" type="radio" name="theme-detached" value="auto" />
+            <span>System</span>
+          </label>
+        </div>
+      </fieldset>
+
+      <label class="choice">
+        <input class="check" type="checkbox" />
+        <span>Email notifications</span>
+      </label>
+    </div>
+  </form>
+
+  <footer class="cluster form-actions sticky">
+    <button type="button" class="btn outline">Cancel</button>
+    <button type="submit" class="btn primary" form="account-form">
+      Save changes
+    </button>
+  </footer>
+</div>
 ```
 
 ## CSS hooks

package/docs/pages/forms/validation.md

@@ -62,7 +62,7 @@ there is no init call. To opt in forms you cannot mark up, call
 `actual-css/js/enhance`.
 
 ```html demo
-<form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
+<form class="stack needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
   <div class="stack">
     <label class="field">
       <span class="field-label">Password</span>
@@ -81,7 +81,7 @@ there is no init call. To opt in forms you cannot mark up, call
     </label>
   </div>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
     <button class="btn neutral outline" type="reset">Reset</button>
   </div>
@@ -139,7 +139,7 @@ The status bar (`actual-css/js/status`) auto-wires to that event: import it and
         Switch this on to submit.
       </span>
     </div>
-    <div class="form-actions">
+    <div class="cluster form-actions">
       <button class="btn primary" type="submit">Submit</button>
       <button class="btn neutral outline" type="reset">Reset</button>
     </div>
@@ -197,7 +197,7 @@ Add your own with `FormValidator.registerRule(name, (value, el, ...opts) => bool
     <span class="field-error" id="attachment-error">Choose a .pdf or .csv file.</span>
   </label>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
     <button class="btn neutral outline" type="reset">Reset</button>
   </div>
@@ -246,7 +246,7 @@ The `date` rule pairs naturally with `data-mask` — the mask structures input,
     </span>
   </label>
 
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
     <button class="btn neutral outline" type="reset">Reset</button>
   </div>

package/docs/pages/foundations/philosophy.md

@@ -80,8 +80,9 @@ how `.field sm`, `.input-icon sm`, `.join sm`, and `.flyout sm` size the
 controls inside them, while a bare `.sm` on a plain element does nothing.
 
 `.compact` and `.spacious` establish inherited density tokens. Density arranges
-how tightly UI sits — spacing and component geometry — while typography and
-icon size stay unchanged. Participation is opt-in, and a component only joins
+how tightly UI sits — spacing and component geometry — while font size and
+icon size stay unchanged. `.tight` and `.loose` change the rhythm (`--gap`)
+alone. Participation is opt-in, and a component only joins
 where density has an effect independent from its optical size: if the result is
 merely that the component looks smaller or larger, that is size, not density.
 
@@ -126,7 +127,8 @@ affect the same dimension:
 </div>
 ```
 
-The density tokens are `--gap`, `--density-space`, and `--control-size`.
+The density tokens are `--gap`, `--density-space`, `--control-size`, and
+`--control-pad-x`.
 Components consume the dimensions that make sense for them and opt out of the
 rest. The absolute `--space-*` scale is not rebound by density scopes.
 Components with bespoke geometry (`.badge`, `.avatar`,

package/docs/pages/foundations/theming.md

@@ -184,16 +184,27 @@ Override the whole minimal recolor set (Tokens · Theme contract), not just
 `--primary`. Every neutral of the default theme — surfaces, text, border,
 `--neutral`, `--hover-overlay`, `--shadow-color` — is tinted toward the default
 primary and never derived from `--primary` at runtime, so a partial override
-leaves the default identity in the greys. `report:theme-contrast` checks
+leaves the default identity in the greys. `actual-css contrast` checks
 contrast, not a leftover tint.
 
 Soft ink is the other half. The default palette ships calibrated
 `--*-soft-fg` hooks; any other theme falls back to the `--soft-fg-mix`
 derivation, which is a single global percentage and therefore guarantees
-nothing about your intents. Verify with `bun run report:theme-contrast`, then
-lower `--soft-fg-mix` or declare the per-role hooks for the intents that miss.
+nothing about your intents. Measure it, then lower `--soft-fg-mix` or declare
+the per-role hooks for the intents that miss:
 
-→ Foundations · Tokens (theme contract)
+```sh
+bunx --bun actual-css contrast --theme src/theme.css
+```
+
+It reads the theme in headless Chrome, in every scheme it declares, and exits 1
+when a soft, focus, invalid-focus or inverse pair misses its threshold, so it
+can gate a CI job.
+
+Starting from a color scale (Tailwind `--color-zinc-*`, a brand ramp): map one
+step per role rather than importing the scale.
+
+→ Foundations · Tokens (theme contract) · Guides · Tailwind (Map the palette to theme roles)
 
 ### Use or adapt a preset palette
 

package/docs/pages/foundations/tokens.md

@@ -167,8 +167,8 @@ to keep that pair ≥ 4.5:1 in both color schemes, enforced by
 presets and custom `[data-theme]` islands keep the `--soft-fg-mix` derivation
 unless they declare the hooks themselves (the framework resets them outside
 the default boundary). A theme that overrides the soft palette is responsible
-for preserving sufficient text contrast; `bun run report:theme-contrast`
-reports every preset's resting and hovered pairs without failing the build.
+for preserving sufficient text contrast; `bunx --bun actual-css contrast --theme FILE`
+measures its resting and hovered pairs.
 
 A theme whose primary should read more muted than its statuses sets only
 `--primary-soft-fg`, and every soft `.primary` foreground follows it. Without a
@@ -236,7 +236,6 @@ Typography tokens cover the document baseline and common component needs.
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   --font-width: 100%;
-  --font-width-dense: 95%;
 
   --line-height: 1.5;
   --font-weight-normal: 400;
@@ -265,18 +264,45 @@ Local `.sm`/`.lg` sizes map `--control-size`, `--control-font-size`, and
   --control-size-md: 2.375rem;  /* 38px → default */
   --control-size-lg: 2.75rem;   /* 44px → .lg */
   --control-size: var(--control-size-md);
-  --control-pad-x: var(--font-size-md);
+  --control-pad-x-sm: var(--font-size-xs); /* .sm, .compact */
+  --control-pad-x-md: var(--font-size-md); /* default */
+  --control-pad-x-lg: var(--font-size-lg); /* .lg, .spacious */
+  --control-pad-x: var(--control-pad-x-md);
   --control-font-size: var(--font-size-md);
   --disabled-opacity: 0.65;
 }
 ```
 
-`--control-pad-x` is a resolved geometry length, stated in the typographic
-tokens rather than an `em`. Every part of one control must see the same
-horizontal distance; an `em` would change value on a descendant with its own
-font size, which is exactly what `--input-icon-size` does to the icon glyph. It
-mirrors `--control-font-size` and is rebound beside it at the `.sm`/`.lg`
-boundaries.
+A theme sets the steps (`--control-size-*`, `--control-pad-x-*`); `.sm`/`.lg`
+and `.compact`/`.spacious` select one. `--control-size` and `--control-pad-x`
+are the selected values: override them on one instance, never in a theme,
+where every size and density boundary would overwrite them.
+
+A `data-theme` island inherits the selected values, so an override set above it
+crosses it. A theme that changes the steps and is used as a nested island must
+re-select them in its own block, from the step weights that size and density
+classes set, so the island keeps the density around it:
+
+```css
+[data-theme="brand"] {
+  --control-pad-x-sm: 0.5rem;
+  --control-pad-x-md: 0.75rem;
+  --control-pad-x-lg: 1rem;
+  --control-pad-x: calc(
+    (var(--control-pad-x-sm) * var(--control-step-sm)) +
+    (var(--control-pad-x-md) * var(--control-step-md)) +
+    (var(--control-pad-x-lg) * var(--control-step-lg))
+  );
+}
+```
+
+Re-select only the token whose steps the theme changes: the same rule for
+`--control-size` would stop an inherited `--control-size` at the island.
+
+`--control-pad-x` is a length, not an `em`: every part of one control must see
+the same horizontal distance, and an `em` would change value on a descendant
+with its own font size, which is exactly what `--input-icon-size` does to the
+icon glyph.
 
 - `.lg` — 44px control height
 - default — 38px control height
@@ -290,42 +316,33 @@ Disabled controls and disabled-prone components read `--disabled-opacity` for th
 
 ### Density
 
-Density contexts swap shared spacing and geometry, plus a slight typographic
-width bonus:
+Density contexts swap shared rhythm and geometry, and never typography:
 
 ```css
-:root {
-  --font-width: 100%;
-  --font-width-dense: 95%;
-}
-
 .compact {
   --gap: var(--space-20);
   --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
-  font-stretch: var(--font-width-dense);
+  --control-pad-x: var(--control-pad-x-sm);
 }
 
 .spacious {
   --gap: var(--space-50);
   --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
-  font-stretch: var(--font-width);
+  --control-pad-x: var(--control-pad-x-lg);
 }
 ```
 
-Density never changes font size or icon size — it may only use the denser font
-width. `font-stretch` uses a variable `wdth` axis when available, or
-participates in normal width-face matching for families that expose multiple
-widths. Layout must never depend on the narrowing being available. Compact
-density may slightly narrow variable typefaces when they support a width axis.
-This is a density enhancement, not an overflow strategy: never condense a
-component just because its label overflows at some viewport — that hides a
-composition problem. A theme whose typeface has no useful width axis opts out
-with `--font-width-dense: 100%`.
+- **Size** (`.sm`, `.lg`) — typography + geometry, on one component.
+- **Density** (`.compact`, `.spacious`) — rhythm + geometry, on a region.
+- **Rhythm** (`.tight`, `.loose`) — `--gap` only, on a region.
+
+Font size, icon size and font width stay put under density. A condensed table
+or panel is a typographic choice: set `font-stretch` on it in the application.
 
 Participation is opt-in and selective: controls consume `--control-size`
-for geometry; spacing helpers and rhythms consume `--density-space` and `--gap`;
+and `--control-pad-x` for geometry; spacing helpers and rhythms consume `--density-space` and `--gap`;
 components whose size is intrinsic (badge, avatar, spinner, rating, key, prose,
 inline choice/switch) keep their own scales. A local component size overrides
 inherited density for the dimensions they share.
@@ -486,13 +503,13 @@ Rules:
 
 Themes override tokens, not selectors. The themes in `src/css/themes/` are repository-only demo examples, not included in the default stylesheet or the npm package; they exist to show valid ways to use this contract, such as `ocean`, `square`, `cyberpunk`, and `brutalist`.
 
-A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, hover overlay, and shadow color. Pick `--focus` as a mid-tone that holds 3:1 against both `--surface` and `--surface-solid` in every scheme the theme declares; a pastel dark-scheme primary usually fails on the light solid surface. `bun run report:theme-contrast` measures both pairs.
+A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, hover overlay, and shadow color. Pick `--focus` as a mid-tone that holds 3:1 against both `--surface` and `--surface-solid` in every scheme the theme declares; a pastel dark-scheme primary usually fails on the light solid surface. `bunx --bun actual-css contrast --theme FILE` measures both pairs, and exits 1 when a pair misses.
 
-When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. A theme that declares no hook falls back to the `--soft-fg-mix` derivation: one global percentage applied to every role, so it carries no contrast guarantee for a palette it was not tuned against. `bun run report:theme-contrast` prints the resting and hovered soft pair for every intent of every island, which is how a theme finds the roles that need a hook or a lower `--soft-fg-mix`.
+When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. A theme that declares no hook falls back to the `--soft-fg-mix` derivation: one global percentage applied to every role, so it carries no contrast guarantee for a palette it was not tuned against. `actual-css contrast` prints the resting and hovered soft pair for every intent in every scheme the theme declares, which is how a theme finds the roles that need a hook or a lower `--soft-fg-mix`.
 
 The default palette's hooks apply to `:root` and to the `light`/`dark` boundaries only. Any other `data-theme` value resets them to the derivation, whether the attribute sits on `<html>` or on a nested island.
 
-Contrast is measured between opaque colors. A translucent `--surface` has no ratio until it is composited over its backdrop, so `report:theme-contrast` refuses such a theme, and `.soft` mixes over it come out more opaque and more saturated than the surface. A translucent theme owns both: it measures against its real backdrop and replaces any recipe that does not hold there.
+Contrast is measured between opaque colors. A translucent `--surface` has no ratio until it is composited over its backdrop, so `actual-css contrast` reports its pairs as n/a, and `.soft` mixes over it come out more opaque and more saturated than the surface. A translucent theme owns both: it measures against its real backdrop and replaces any recipe that does not hold there.
 
 Shape, shadow, motion, typography, and soft-variant mix tokens are optional knobs. Override them only when the theme actually changes that part of the system.
 
@@ -532,7 +549,7 @@ A minimal recolor theme (illustrative, not a shipped theme):
   --text-muted: hsl(260 10% 42%);
   --text-subtle: hsl(260 8% 56%);
   --border: hsl(260 24% 84%);
-  --focus: var(--primary);
+  --focus: hsl(260 60% 62%);
   --hover-overlay: hsl(260 30% 10% / 0.04);
   --shadow-color: hsl(260 30% 10%);
   --soft-bg-mix: 84%;

package/docs/pages/foundations/typography.md

@@ -115,13 +115,10 @@ baseline stays sans so app UI inherits predictably.
 
 ### Font width
 
-Two public hooks carry the typographic side of density: `--font-width` (normal
-width) and `--font-width-dense` (compact width). The document reads
-`--font-width` through `font-stretch`; `.compact` applies
-`--font-width-dense` and `.spacious` restores `--font-width`. A theme whose
-typeface has no useful width axis sets `--font-width-dense: 100%`. Width is a
-density token, not a responsive escape hatch — never condense text to fix an
-overflowing label.
+`--font-width` sets the document's `font-stretch`: a theme whose typeface has a
+`wdth` axis or several width faces picks its width there. Density does not
+change it. To condense one dense table or panel, set `font-stretch` on that
+element; never condense text to fix an overflowing label.
 
 ## Font weights
 

package/docs/pages/guides/bootstrap.md

@@ -361,12 +361,12 @@ Actual's navbar is intentionally a simpler navigation pattern.
 Keep the desktop navigation as a navbar and compose the mobile experience from a
 drawer or flyout rather than looking for a `.navbar-expand-lg` equivalent:
 
-* desktop → `.navbar` with `.navbar-nav`;
+* desktop → `.navbar` with a `.cluster` link list;
 * mobile → `.drawer` with `.nav-list`;
 * trigger → a `command="show-modal"` / `commandfor` button.
 
 The [Navbar component page](../components/navbar.md) shows this composition
-as *the Actual way*: a horizontal `.navbar-nav` on the desktop bar and a vertical
+as *the Actual way*: a horizontal `.cluster` on the desktop bar and a vertical
 `.nav-list` inside the mobile drawer, opened with the native dialog command
 pattern. There is no collapse/toggler state to keep in sync.
 

package/docs/pages/guides/design-tools.md

@@ -0,0 +1,36 @@
+# Design tools (Figma, Penpot)
+
+`actual-css design` exports a theme to design tools: its tokens for Figma and Penpot, and a Penpot plugin that builds Button, Input, Badge, Alert and Card bound to those tokens. Use it to hand designers the same palette, scale and components the code ships — a design kit, a UI kit, a Figma or Penpot library generated from your theme.
+
+```sh
+bunx --bun actual-css design --theme src/theme.css --out design/
+```
+
+`--theme` is a file declaring one `[data-theme="…"]` block (see [Theming](../foundations/theming.md)); without it the default theme is exported. The command needs Bun, and `--bun` makes `bunx` run it under Bun instead of the CLI's Node shebang: it reads the theme in headless Chrome, so every `light-dark()`, `color-mix()` and `var()` chain resolves exactly as the browser paints it.
+
+## What is exported
+
+| File                                          | Content                              |
+| --------------------------------------------- | ------------------------------------ |
+| `figma/foundations.tokens.json`               | spacing, radius, borders, type sizes |
+| `figma/light.tokens.json`, `dark.tokens.json` | colors, one file per scheme          |
+| `penpot/tokens.json`                          | all tokens, as sets and themes       |
+| `penpot/plugin/`                              | the plugin and component spec        |
+
+Token names are the CSS names without `--`: `surface-raised` in the design tool is `var(--surface-raised)` in code. A scheme exists when the theme declares it: `color-scheme: light dark` exports both, anything else one. Lengths are exported in px, with the CSS value kept in `$extensions["actual-css"]`.
+
+Colors no theme token paints — the soft fills and borders of `.soft` — are exported as recipe tokens named `<variant>-<intent>-<role>` (`soft-danger-bg`, `soft-danger-border`, `soft-danger-fg`), next to the theme colors so they switch with the scheme. Font stacks, line heights, shadows, motion and z-index have no design-tool equivalent and are not exported.
+
+## Figma
+
+Import each file from the Variables panel. Figma makes one collection per file: import `light`, then add `dark` to that collection as a second mode (a paid-plan feature; the free plan allows one mode per collection).
+
+## Penpot
+
+1. Tokens tab → Tools → Import `penpot/tokens.json`. It replaces the file's tokens.
+2. Serve `penpot/plugin/` over http with CORS, and add its `manifest.json` URL in the plugin manager (`Ctrl + Alt + P`).
+3. Run **Build components**.
+
+The components are built on their own page, "Actual CSS components"; drag instances from Assets onto any page. Each is a variant set whose properties are the classes an author stacks — `Intent`, `Variant` and `Size` on Button and Badge, `Intent` and `Variant` on Alert, `Size` on Input — defaulting to the bare class (`.btn`, `.badge`). Fills, borders and text colors are bound to tokens, so switching the Penpot theme between Light and Dark repaints every variant. Radius, padding, height and type are the measured values: run the export again after changing them in the theme.
+
+The components are measured, not modelled: the browser renders the classes and the plugin replays the result, so a theme's own radius or padding shows up without configuration. States (hover, focus, disabled) stay a code concern.

package/docs/pages/guides/integrating-actual-css.md

@@ -76,11 +76,15 @@ Prefer:
   --card-pad: var(--space-50);
 }
 
-.actions {
+.product-actions {
   --cluster-justify: space-between;
 }
 ```
 
+`.product-actions` is an application class composed onto the primitive:
+`<div class="cluster product-actions">`. The hook is read by `.cluster`, so the
+CSS stays a local adjustment, not a reimplementation.
+
 over reimplementing their layout:
 
 ```css

package/docs/pages/guides/introduction.md

@@ -52,7 +52,7 @@ optimizing — the bare `actual-css` entrypoint and `actual-css/full` both resol
 to the complete compiled framework:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.11/dist/actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.12/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map
@@ -72,9 +72,8 @@ shared by buttons, badges, alerts, and cards; a subtree that needs another
 palette is a `data-theme` island, not a class. `.ghost` and `.link` are
 button-only. Size variants `.sm` and `.lg` scale typography and
 participating component geometry consistently. Density contexts `.compact` and
-`.spacious` change geometry and spacing without changing font size or icons;
-`.compact` may slightly narrow typefaces that support a width axis.
-Undocumented `is-*` classes are runtime internals.
+`.spacious` change geometry and spacing without changing font size, font width
+or icons. Undocumented `is-*` classes are runtime internals.
 
 ```html
 <button class="btn">Click me</button>

package/docs/pages/guides/modular-import.md

@@ -98,6 +98,9 @@ cells, so they read as a list:
 - **Utilities** — `actual-css/css/utilities`
   base and extra utilities
 
+`.form-actions` composes with `.cluster`: a build that takes forms without the
+layout family imports `actual-css/css/layout/cluster` before the forms.
+
 Individual modules can be imported through their domain path:
 
 ```css

package/docs/pages/guides/progressive-enhancement.md

@@ -760,12 +760,12 @@ field, and dispatches a bubbling `actual:invalid` event with
 `{ form, firstInvalid, message }`. Valid fields are not marked automatically.
 
 ```html demo
-<form class="needs-validation" data-enhance="validation"
+<form class="stack needs-validation" data-enhance="validation"
       data-validation-message="Please check the fields.">
   <input class="input" name="email" type="email" required
          aria-describedby="email-error" />
   <span class="field-error" id="email-error">Enter a valid email.</span>
-  <div class="form-actions">
+  <div class="cluster form-actions">
     <button class="btn primary" type="submit">Submit</button>
   </div>
 </form>