actual-css 0.11.1 → 0.12.0

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

@@ -3,10 +3,10 @@
 `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 actual-css design --theme src/theme.css --out design/
+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: it reads the theme in headless Chrome, so every `light-dark()`, `color-mix()` and `var()` chain resolves exactly as the browser paints it.
+`--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
 

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>

package/docs/pages/guides/tailwind.md

@@ -380,6 +380,76 @@ Actual theme tokens should handle shared theme behavior. Local CSS remains appro
 
 This is particularly important when migrating a Tailwind application with a large custom color palette.
 
+### Map the Tailwind palette to theme roles
+
+Tailwind's theme is a set of ramps: `--color-zinc-50` … `--color-zinc-950`,
+one per hue. Actual's theme contract is a set of roles: `--surface`,
+`--border`, `--text-muted`, `--primary`, `--focus`. Each element picks a
+step in Tailwind; Actual picks once per role, in the theme, and every
+component reads the role. Map one neutral family and one brand hue, then
+stop: the rest of the ramp has no consumer.
+
+A starting point for a zinc and blue application:
+
+| Role               | Light      | Dark       |
+| ------------------ | ---------- | ---------- |
+| `--surface`        | `white`    | `zinc-950` |
+| `--surface-raised` | `white`    | `zinc-900` |
+| `--surface-subtle` | `zinc-100` | `zinc-800` |
+| `--surface-solid`  | `zinc-900` | `zinc-100` |
+| `--border`         | `zinc-200` | `zinc-700` |
+| `--text`           | `zinc-950` | `zinc-50`  |
+| `--text-muted`     | `zinc-600` | `zinc-400` |
+| `--text-subtle`    | `zinc-500` | `zinc-500` |
+| `--neutral`        | `zinc-600` | `zinc-400` |
+| `--primary`        | `blue-600` | `blue-400` |
+| `--focus`          | `blue-500` | `blue-500` |
+
+Each scheme is one `light-dark()` pair on the role, instead of a `dark:`
+variant on every element:
+
+```css
+[data-theme="app"] {
+  color-scheme: light dark;
+
+  --surface: light-dark(var(--color-white), var(--color-zinc-950));
+  --border: light-dark(var(--color-zinc-200), var(--color-zinc-700));
+  --primary: light-dark(var(--color-blue-600), var(--color-blue-400));
+  --primary-fg: light-dark(var(--color-white), var(--color-zinc-950));
+  --focus: var(--color-blue-500);
+  /* … the other roles of the table */
+}
+```
+
+Tailwind v4 emits only the theme variables your sources use; declare the
+palette with `@theme static` while the theme reads them, and replace them with
+their literal values before Tailwind leaves the build.
+
+What the ramp does not decide for you:
+
+- **Foreground pairs.** Tailwind has no `-fg` step. White on `blue-600` holds
+  4.5:1, white on `blue-500` does not, so a dark-scheme primary lightened to
+  `blue-400` needs a dark `--primary-fg`. Every intent needs its pair:
+  `--warning-fg` on an amber is dark ink.
+- **Focus.** `--focus` must hold 3:1 on `--surface` and `--surface-solid` in
+  both schemes, so it is a mid-tone, not the primary step. `blue-500` holds
+  on `white`, `zinc-900`, `zinc-950` and `zinc-100`: one value covers both
+  schemes.
+- **Neutral temperature.** `slate`, `gray`, `zinc`, `neutral` and `stone` are
+  the same ramp at different temperatures; `neutral` is pure grey. Pick the
+  family that leans toward your primary, and take every neutral role from it.
+- **No subtle intent steps.** Do not map `blue-50` / `blue-100` to tinted
+  surfaces: `.soft` mixes the intent into the local surface, so there is no
+  `--primary-subtle` to fill.
+- **Shadow and hover ink.** Tailwind shadows are black; Actual derives
+  `--shadow` and `--shadow-popout` from one `--shadow-color`. Take it from the
+  neutral family's darkest step, and `--hover-overlay` as a few percent of
+  `--text`.
+
+`bunx --bun actual-css contrast --theme FILE` measures the focus, soft and inverse
+pairs in both schemes. Check the text tiers on `--surface-subtle` by hand:
+`zinc-500` holds 4.5:1 on `white` but not on `zinc-100`.
+
 ## Forms
 
 Tailwind applications often construct form controls from utility combinations or use an additional forms plugin.

package/docs/pages/guides/upgrading.md

@@ -0,0 +1,74 @@
+# Upgrading to 0.12
+
+Each step below is a search for a removed class or hook and its replacement.
+The [changelog](https://github.com/lekoala/actual-css/blob/master/CHANGELOG.md)
+lists every change; this page keeps the ones that need an edit.
+
+**Related terms:** migration, breaking changes, update, version.
+
+## Action rows
+
+`.actions`, `.navbar-nav` and the layout of `.form-actions` are gone. A row of
+actions is a `.cluster`; a vertical list is `stack list-reset`. Replace
+`class="actions"` and `class="navbar-nav"` with `class="cluster"`, and
+`class="form-actions"` with `class="cluster form-actions"`:
+
+```html
+<menu class="cluster">…</menu>
+<ul class="cluster">…</ul>
+<div class="cluster form-actions">…</div>
+<ul class="stack list-reset">…</ul>
+```
+
+- The row takes the framework `--gap` (0.75rem). The former `.actions` used
+  0.5rem: add `.tight` to keep it.
+- The former `.navbar-nav` used `--space-10` (0.25rem), which no utility
+  reproduces. If the tighter navbar rhythm matters, set
+  `gap: var(--space-10)` on that row in application CSS.
+- `.form-actions` has no top margin and no `--form-actions-margin-block-start`:
+  put `.stack` on the form. `--form-actions-justify` and `--form-actions-align`
+  still apply. In a modular build, import `layout/cluster` before
+  `forms/form-actions`.
+- `.justify-content-*` aligns only its own element and no longer reaches a
+  nested `.cluster`. Put the utility on the row it should align.
+
+## Dialogs
+
+- `.dialog-confirmation` is removed. Compose `.media` with `.dialog-icon`, then
+  a `<footer class="bleed background-subtle cluster justify-content-space-between">`;
+  the recipe is in [Dialog](../components/dialog.md).
+- A `dialog.modal` body `<footer>` has no layout of its own: write
+  `<footer class="cluster justify-content-end">`.
+- `--modal-header-bg` is removed: put a `.background-*` utility on the
+  `dialog.modal > header` band. Only that default fill has zero specificity;
+  the header's layout keeps its structural rule.
+- The confirmation recipe uses the regular 1rem modal inset where the former
+  `.dialog-confirmation` used 1.5rem. Set `--modal-pad: var(--space-50)` on
+  the dialog to keep the roomier treatment.
+
+## Cards
+
+The layout of a `.card` header or footer row is a zero-specificity default: any
+author rule that targets the slot replaces it, not only a `.media`, `.cluster`,
+`.form-actions` or `.justify-content-*` class. Check application CSS for bare
+element rules such as `header { … }` or `footer { … }`, which now win over the
+card's slot row.
+
+## Themes and density
+
+- A theme sets `--control-pad-x-sm`, `--control-pad-x-md` and
+  `--control-pad-x-lg` instead of `--control-pad-x`. Used as a nested island,
+  it re-selects them in its own block; see
+  [Tokens](../foundations/tokens.md).
+- `--font-width-dense` is removed, and `.compact` no longer condenses type: set
+  `font-stretch` on the element that should render condensed.
+
+## Rendering changes without an edit
+
+These need no markup change; compare the affected screens.
+
+- `.sm` controls have 13px of inline padding instead of 14px.
+- `.compact` and `.spacious` controls get narrower or wider, not only shorter
+  or taller.
+- `.nav-list` rows sit `--space-10` apart instead of `--space-20`.
+- `.card.compact` lowers the gap between its children to `--space-20`.

package/docs/pages/layout/cluster.md

@@ -17,6 +17,30 @@ between items always comes from `--gap`. Unlike `.stack`, which resets only the
 block axis, cluster resets margins on both axes — a wrapping cluster's `gap`
 controls inline spacing between items and block spacing between wrapped rows.
 
+## Action rows
+
+Actions are content; the cluster owns the geometry. A semantic action list is a
+`<menu>` (or `<ul>`) with `.cluster`:
+
+```html demo
+<menu class="cluster">
+  <li><button class="btn primary" type="button">Save</button></li>
+  <li><button class="btn outline" type="button">Cancel</button></li>
+</menu>
+```
+
+There is no `.actions` class. A dense row is `cluster tight`; a vertical action
+list is `stack list-reset`.
+
+## List chrome
+
+`.cluster` neutralizes the native chrome of a `<ul>`, `<ol>` or `<menu>` it is
+applied to. The element stays a list in the DOM and for assistive technology,
+but a horizontal, wrapping group cannot carry markers and indentation
+meaningfully, so they are removed. `.stack` makes no such change — an
+`<ol class="stack">` keeps its numbers. Use `.list-reset` alone for a plain list
+with no layout.
+
 ## CSS hooks
 
 - `--cluster-justify` — main-axis distribution (`justify-content`).
@@ -48,8 +72,10 @@ wraps to several lines — set `--cluster-align`.
 ```
 
 The optional utility layer ships `.justify-content-start`, `.justify-content-center`,
-`.justify-content-end` and `.justify-content-space-between`, which set
-`--cluster-justify` for you. See the utilities page.
+`.justify-content-end` and `.justify-content-space-between`. They set
+`justify-content` on that one row only; a nested `.cluster` keeps its own
+alignment. `--cluster-justify` is inherited, so setting it on a region reaches
+nested clusters too. See the utilities page.
 
 ## Controls inside a wrapping cluster
 

package/docs/pages/layout/overview.md

@@ -57,4 +57,4 @@ Prefer a parent `gap` for relationships between peers instead of encoding siblin
 
 Before adding a divider or other separating chrome, consider whether additional spacing already expresses the boundary clearly.
 
-Density changes the amount of space available, not the relationships that space communicates. When a composition contains local, group, and section rhythms, preserve their relative hierarchy with nested or local `--gap` values rather than relying on one inherited gap at every level. See [Choosing a density](./stack.md#choosing-a-density) for the nesting and density mechanics.
+Density changes the amount of space available, not the relationships that space communicates. When a composition contains local, group, and section rhythms, preserve their relative hierarchy with nested or local `--gap` values rather than relying on one inherited gap at every level. See [Choosing a rhythm](./stack.md#choosing-a-rhythm) for the nesting mechanics, and `.tight` / `.loose` for a gap-only change.

package/docs/pages/layout/stack.md

@@ -39,19 +39,24 @@ content, keep them in normal block flow instead:
 Use `.stack` for the vertical rhythm *between* related items inside one region,
 not as the wrapper that lays out independent full-width regions of a page.
 
-## Choosing a density
+## Choosing a rhythm
 
-`--gap` is the primitive's channel, and the density context variants set it at
-the point of use. Apply the density class on the stack itself to size one
-instance, or on an ancestor to reach nested layouts. Pick the one that matches
-how tightly the children belong together:
+`--gap` is the primitive's channel. `.tight` and `.loose` set it and nothing
+else; apply one on the stack to space one instance, or on an ancestor to reach
+nested layouts. Pick the one that matches how tightly the children belong
+together:
 
 | Markup            | Gap  | Use for                                    |
 | ----------------- | ---- | ------------------------------------------ |
 | `.stack gap-none` | 0    | Lines forming one typographic unit         |
-| `.stack compact`  | 8px  | A homogeneous series of controls           |
+| `.stack tight`    | 8px  | A homogeneous series of controls           |
 | `.stack`          | 12px | Normal flow between distinct elements      |
-| `.stack spacious` | 24px | Sections, or blocks that read as separated |
+| `.stack loose`    | 24px | Sections, or blocks that read as separated |
+
+**Size** changes a component's scale. **Density** (`.compact`, `.spacious`)
+changes UI geometry and rhythm together: gap, padding, control size. **Rhythm**
+(`.tight`, `.loose`) changes the gap only — closer or farther items, tighter
+spacing without smaller buttons. Use one rhythm class per element.
 
 One typographic unit means a name and a job title, or a figure and its caption.
 A homogeneous series means a radio list, a checkbox list, or a compact vertical
@@ -60,13 +65,13 @@ menu.
 The distinction between the first two matters. `42` above `Open issues` is
 almost a single block of text, so it takes `gap-none`. Three `.choice` labels
 stay three separate controls that happen to form one group, so they take
-`compact` — tighter than the default, but still spaced.
+`tight` — tighter than the default, but still spaced.
 
-`.compact` and `.spacious` rebind `--gap` to `--space-20` and `--space-50`.
-Because the token is inherited, the same two classes also tighten the inner gap
-of any nested stack, cluster, and grid. For a one-off gap that must *not* follow
-density, set the `gap` property directly on the instance (the next section
-explains why).
+`.tight` and `.loose` rebind `--gap` to `--space-20` and `--space-50`, the same
+steps `.compact` and `.spacious` use. Because the token is inherited, they also
+tighten the inner gap of any nested stack, cluster, and grid. For a one-off gap
+that must *not* reach nested layouts, set the `gap` property directly on the
+instance (the next section explains why).
 
 A stack that mixes kinds keeps the default: five `.field` wrappers and one lone
 `.choice` is a form that contains a checkbox, not a list of options, and
@@ -92,7 +97,7 @@ depth:
 ```
 
 Both give the region the same spacing; only the second stops there. This is what
-makes a nested `.stack compact` a real density choice — 12px down to 8px — rather
+makes a nested `.stack tight` a real rhythm choice — 12px down to 8px — rather
 than a patch cancelling a rhythm inherited from three levels up.
 
 Setting `--gap` is still the right move on the element that *consumes* it: a
@@ -100,8 +105,8 @@ one-off `--gap` on a card body or an actions row tunes that primitive and
 nothing below it, because the setter is the consumer. The leak only appears when
 a container sets the token and its children read it.
 
-`.compact` and `.spacious` are the deliberate exception: they set `--gap`
-precisely so a density context reaches nested layouts.
+The rhythm and density classes are the deliberate exception: they set `--gap`
+precisely so the context reaches nested layouts.
 
 ## Grouping items tightly
 

package/docs/pages/layout/topbar.md

@@ -4,7 +4,7 @@ Sticky, frosted top bar shell for app/dashboard layouts with a persistent sideba
 
 > **Module** — import `actual-css/css/layout/topbar` or `actual-css/css/layout`.
 
-Use `.topbar` for the structural shell of an app-shell header: sticky positioning, stacking, and a frosted background. Row content — search, breadcrumb, actions — stays local to the page.
+Use `.topbar` for the structural shell of an app-shell header: sticky positioning, stacking, and a frosted background. Its children sit in a centered row by default; a layout primitive on the same element, such as `topbar cluster`, replaces that row. Row content — search, breadcrumb, actions — stays local to the page.
 
 ```html demo
 <header class="topbar">