actual-css 0.11.1 → 0.13.0

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 theme, on `:root` or in a `[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

@@ -8,7 +8,8 @@ In short: **use Actual for generic structure and behavior; add product-specific
 classes for brand and compositions rather than forcing a generic primitive.** A
 local rule is not a failure of Actual — overfitting the framework to a
 product-specific look is. Reach for an Actual primitive first, and write
-application CSS when the need is genuinely product-specific (see §6–7).
+application CSS when the need is genuinely product-specific (see §9–10). The
+principles behind this order are in [Philosophy](../foundations/philosophy.md).
 
 ## 1. Start with the theme
 
@@ -60,7 +61,29 @@ For example, three panels that must all stack together are a `.switcher`, not au
 
 If local CSS mainly makes one layout primitive behave like another, reconsider the primitive first.
 
-## 3. Tune before replacing
+## 3. Keep outer spacing in the layout
+
+Components own their internal rhythm; layout primitives own the space between
+components.
+
+```html
+<div class="stack">
+  <article class="card">…</article>
+  <article class="card">…</article>
+</div>
+```
+
+```css
+/* Avoid */
+.card + .card {
+  margin-block-start: var(--space-50);
+}
+```
+
+A card then moves between a stack, a grid or a sidebar without its outer
+spacing to undo.
+
+## 4. Tune before replacing
 
 Actual primitives expose public hooks for common adjustments.
 
@@ -76,11 +99,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
@@ -93,7 +120,12 @@ over reimplementing their layout:
 
 **Rule:** tune the recipe before replacing the recipe.
 
-## 4. Reuse the existing vocabulary
+`--gap` is inherited: set on a region, it re-spaces every nested stack, cluster
+and grid too. Set it on the layout that reads it, as `.feature-grid` does above.
+For a region's own rhythm, set the `gap` property instead; see
+[Region rhythm](../layout/stack.md#region-rhythm-goes-on-gap-not-on-gap).
+
+## 5. Reuse the existing vocabulary
 
 Before introducing a generic application class, check whether Actual already expresses the idea.
 
@@ -109,7 +141,7 @@ Small alignment change    → existing utility
 
 Application classes should primarily describe product-specific concepts, not recreate generic framework utilities.
 
-## 5. Use structural component markup
+## 6. Use structural component markup
 
 When a component exposes meaningful structure, use it.
 
@@ -136,7 +168,44 @@ Connection restored.
 
 Persistent state such as metrics, availability, queue size or account information belongs in normal page content.
 
-## 6. Keep application CSS for application identity
+## 7. Style state through its attribute
+
+Use the native attribute or the ARIA state the markup already needs, then
+`data-*` for state with no equivalent. Classes stay for presentation.
+
+```html
+<a class="nav-link" aria-current="page">Settings</a>
+<button class="btn primary" disabled>Save</button>
+```
+
+```css
+.checkout-form[aria-busy="true"] { … }
+```
+
+Not `.nav-link.active` or `.is-disabled`: a state class duplicates the attribute
+and drifts from it. Two runtime markers are off limits too:
+
+- `data-enhance` turns behavior on; it is never a styling hook.
+- `.is-*` classes (`.is-open`, `.is-static`) are runtime internals: neither set
+  nor select them.
+
+## 8. Bring third-party widgets onto the tokens
+
+A date picker, rich text editor or data grid can come from a dedicated package.
+Map its public visual hooks to Actual tokens instead of restyling it:
+
+```css
+.third-party-picker {
+  --picker-bg: var(--surface-raised);
+  --picker-border: var(--border);
+  --picker-text: var(--text);
+  --picker-focus: var(--focus);
+}
+```
+
+The package keeps its behavior; the theme reaches it through the tokens.
+
+## 9. Keep application CSS for application identity
 
 Custom CSS is expected for things such as:
 
@@ -162,7 +231,7 @@ A better target is:
 
 > No duplicated framework behavior and no palette literals outside the token layer.
 
-## 7. Before adding a CSS rule
+## 10. Before adding a CSS rule
 
 Ask, in this order:
 
@@ -171,9 +240,10 @@ Ask, in this order:
 3. Can a public hook configure it?
 4. Does an existing utility express the adjustment?
 5. Can the color be derived from a theme token?
-6. Is this genuinely application-specific CSS?
+6. Does an attribute already name the state?
+7. Is this genuinely application-specific CSS?
 
-If the answer reaches step 6, write the CSS.
+If the answer reaches step 7, write the CSS.
 
 That is the intended integration model:
 

package/docs/pages/guides/introduction.md

@@ -22,7 +22,8 @@ cascade layers, import order, or a project-owned build-time prefix transform.
 The distinction is structural, not stylistic: presentation lives in classes,
 JavaScript behavior opts in through `data-enhance` tokens, semantics come from
 ARIA and native HTML, and per-widget configuration uses self-describing
-`data-*` attributes.
+`data-*` attributes. [Philosophy](../foundations/philosophy.md) lays out the
+layers and the order to follow before adding CSS.
 
 ## Install
 
@@ -52,7 +53,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.13/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map
@@ -72,9 +73,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 also imports `actual-css/css/layout/cluster`, in any order.
+
 Individual modules can be imported through their domain path:
 
 ```css

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

@@ -63,11 +63,30 @@ handle, and cleanup happens per element when an element leaves the DOM.
 
 ## The full runtime
 
-Loading `dist/actual.full.js` as a plain `<script>` (no `type="module"`, no
-bundler, no `import`) gets the full runtime. Static HTML that needs to trigger
-something from its own inline `<script>` dispatches the module's public event
-instead of calling into a global — `actual:status` for the status bar, for
-example:
+Import `actual-css/js/full` to enable the full runtime:
+
+```js
+import "actual-css/js/full";
+```
+
+The same entrypoint exposes the public enhancement API from the same runtime
+instance, for adopters that extend the runtime they already run:
+
+```js
+import { applyEnhancement, enhance, registerEnhancement } from "actual-css/js/full";
+
+registerEnhancement("autosubmit", (form) => {
+  // ...
+});
+```
+
+For anything beyond that extension API, keep using `actual-css/js/*`.
+
+The same entrypoint produces the `dist/actual.full.js` standalone for a
+classic `<script>`, where no global API is exposed. Static HTML that needs to
+trigger something from its own inline `<script>` dispatches the module's
+public event instead of calling into a global — `actual:status` for the
+status bar, for example:
 
 ```html
 <script src="actual.full.js"></script>
@@ -110,8 +129,7 @@ needed.
 The JS is designed to run on its own, without Actual's stylesheet.
 
 - **`data-enhance` tokens** register named behaviors. The runtime discovers
-  components through `data-enhance="tabs"`, `data-enhance="flyout"`,
-  `data-enhance="range"`, `data-enhance="scrollspy"`, and
+  components through `data-enhance="tabs"`, `data-enhance="flyout"`, `data-enhance="range"`, `data-enhance="scrollspy"`, and
   `data-enhance="validation"` — no Actual presentation class needed.
   Self-describing attributes (`data-mask`, `data-tooltip`,
   `data-context-menu`) stay framework-neutral by construction.
@@ -760,12 +778,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,151 @@
+# Upgrading
+
+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. Apply the
+sections in order when skipping a release.
+
+**Related terms:** migration, breaking changes, update, version.
+
+## 0.12 to 0.13
+
+### Layout hooks stop at each layout
+
+`--cluster-justify`, `--cluster-align` and `--cluster-wrap` are reset on every
+`.cluster`, and `--grid-columns` and `--grid-min` on every `.grid`. A value set
+on an ancestor, including an outer cluster or grid, no longer reaches the
+layout inside it. Search application CSS and inline styles for these hooks on
+anything but the layout itself, then set them on the row or grid, or select it:
+
+```css
+.toolbar > .cluster {
+  --cluster-justify: space-between;
+}
+```
+
+`--gap` still inherits, so a density context keeps reaching every nested
+layout.
+
+### Avatar stacks
+
+`.avatar-stack` no longer takes its size from a child `.avatar.sm` or
+`.avatar.lg`. Move the size class to the stack and drop it from its avatars:
+
+```html
+<div class="avatar-stack sm" role="group" aria-label="Team members">
+  <div class="avatar" role="img" aria-label="John Doe">…</div>
+</div>
+```
+
+### Focus outline
+
+`--focus-outline` has no default value any more. Search application CSS for
+`var(--focus-outline)` and write the generic line instead:
+
+```css
+outline: var(--focus-ring-width) solid var(--focus-outline-color);
+```
+
+Setting `--focus-outline` still replaces the generic line.
+
+### List rows
+
+`.list-item` regions center on the row. For rows with long supporting text,
+add `.items-start` to the row or to the `.list` to keep them top-aligned.
+
+### Step rows
+
+`.steps-horizontal` budgets each step from its marker instead of `7rem`, so a
+row fits narrower widths before it scrolls. To keep the previous budget on a
+row, set `--step-min: 7rem` on it.
+
+### Current links and rows
+
+`.nav-link` shows its current state only for `aria-current="page"` or
+`aria-current="location"`, and `a.list-item` only for `aria-current="page"` or
+`aria-current="true"`. Search markup for other values on these classes and
+use the matching one.
+
+### Tabs
+
+`data-enhance="tabs"` only wires an element that also carries
+`role="tablist"`. Search markup for the token and add the role where it is
+missing; the console names each list it skipped.
+
+### Rendering changes without an edit
+
+- A horizontal `.tabs` strip never wraps: a strip that does not fit scrolls
+  horizontally, with no scrollbar and faded edges.
+- `.breadcrumb` never wraps either: a trail that does not fit truncates its
+  labels with an ellipsis, ancestors first. Ancestor labels need an `<a>` or
+  `<span>`.
+- The focus reserve of a scrolling dialog or drawer body no longer grows with
+  `--border-width`: 1px narrower under `prefers-contrast: more`.
+
+## 0.11 to 0.12
+
+### 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, also import `layout/cluster`.
+- `.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/center.md

@@ -15,7 +15,8 @@ Constrain readable content and center it in the viewport, with width and padding
 </main>
 ```
 
-Tune width and side padding with local variables.
+Tune width and side padding with `--center-size` and `--center-pad`. Both
+inherit: set them on `:root` for the site's content width, or on one region.
 
 ```css
 .docs-page {

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`).
@@ -37,19 +61,28 @@ separate `.split` or `.spread` primitive; this is the same relationship.
 </div>
 ```
 
+Once the row wraps, `space-between` puts an item alone on its line at the
+start. To keep the end item on the end edge when it wraps, add
+`.margin-inline-start-auto` to it.
+
 To align a row to its top edge instead of centering it — useful when one item
-wraps to several lines — set `--cluster-align`.
+wraps to several lines — set `--cluster-align` on the cluster itself.
 
 ```css
-.filters {
+.cluster.filters {
   --cluster-align: start;
   --cluster-justify: space-between;
 }
 ```
 
 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. The `--cluster-*` hooks behave the same way: each cluster resets
+them, so a value applies to the cluster it is set on and never to a nested
+one. To align nested rows, select them (`.toolbar > .cluster`). `--gap` keeps
+inheriting, so a density context still reaches every nested cluster. See the
+utilities page.
 
 ## Controls inside a wrapping cluster
 

package/docs/pages/layout/grid.md

@@ -172,3 +172,5 @@ stacked, prefer `.switcher`.
 - `--grid-min` tunes the minimum item width of the intrinsic `.grid` recipe.
   It does not apply to `.grid-N`.
 - `--grid-columns` replaces that recipe with an author-owned template.
+
+Both stop at a nested `.grid`: set them on the grid itself.

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/sidebar-layout.md

@@ -47,3 +47,6 @@ When the layout stacks (narrow space), the aside stays on top.
 
 - `--sidebar-layout-size` sets the aside's preferred width.
 - `--sidebar-content-min` sets the main region's minimum viable width.
+
+The regions read both, so they also reach the regions of a nested
+`.sidebar-layout`; set them on the nested layout to give it its own sizes.