actual-css 0.3.1 → 0.4.1

package/docs/pages/layout/stack.md

@@ -22,6 +22,75 @@ block margins are reset, so vertical rhythm always comes from `--gap`. Inline
 margins stay free — for example `margin-inline: auto` on a child centers it
 without fighting the primitive.
 
+## Don't wrap full-width regions with `.stack`
+
+`.stack` is a column flex container, so a `.center` child — which sets its own
+`inline-size` and `margin-inline: auto` — becomes a flex item that will not
+stretch across the full row; it sizes to its content measure and centers inside
+the flex line. For page-level full-width regions that each constrain their own
+content, keep them in normal block flow instead:
+
+```html
+<header class="center">…</header>
+<main class="center">…</main>
+<footer class="center">…</footer>
+```
+
+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
+
+`--gap` is the primitive's channel, and the density variants set it at the point
+of use. Pick the one that matches how tightly the children belong together:
+
+| Markup | Gap | Use for |
+|--------------------|------|--------------------------------------------------------|
+| `.stack gap-none` | 0 | Lines that form one typographic unit — a name and a job title, a figure and its caption. |
+| `.stack sm` | 8px | A homogeneous series of distinct controls — a radio list, a checkbox list, a compact vertical menu. |
+| `.stack` | 12px | Normal flow between distinct elements. |
+| `.stack lg` | 24px | Sections, or blocks that should read as separated. |
+
+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 `sm` —
+tighter than the default, but still spaced.
+
+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
+tightening it would squeeze the fields.
+
+## Region rhythm goes on `gap`, not on `--gap`
+
+A container that composes other primitives owns its rhythm through the `gap`
+property. Setting `--gap` on it instead re-spaces everything it contains, at any
+depth:
+
+```css
+/* Leaks: --gap is inherited, so every nested stack, cluster and grid — down to
+   a radio list inside a field-group — is pushed to 24px too. */
+.app-region {
+  --gap: var(--space-50);
+}
+
+/* Owns its own rhythm and nothing else. Nested primitives keep --gap. */
+.app-region {
+  gap: var(--space-50);
+}
+```
+
+Both give the region the same spacing; only the second stops there. This is what
+makes a nested `.stack sm` a real density 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
+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.
+
+`.sm` and `.lg` are the deliberate exception: they set `--gap` precisely so a
+density context reaches nested layouts.
+
 ## Grouping items tightly
 
 Stack spacing is a `--gap` between every direct child; the primitive cannot
@@ -52,4 +121,4 @@ additive, so a negative block margin on the child cancels the following gap:
 ```
 
 The stack resets child block margins to zero, so this re-adds a margin on that
-one child only; the rest of the stack keeps its rhythm.
+one child only; the rest of the stack keeps its rhythm.

package/docs/pages/layout/switcher.md

@@ -1,36 +1,20 @@
 # Switcher
 
-Row that becomes a column when space gets tight, useful for small sets of panels.
-
-> **Optional** — import `actual-css/css/optional/layout-extra` or `actual-css/css/optional/index`.
-
-Use `.switcher` for rows that should become columns when space gets tight.
+Use `.switcher` for a small set of peer regions that should switch together
+between one row and a vertical stack. Unlike `.grid`, it never produces a
+partial row such as two items followed by one orphan.
 
 ```html demo
 <section class="switcher">
-  <article class="card">
-    <h3>Profile</h3>
-    <p>Personal details and preferences.</p>
-  </article>
-  <article class="card">
-    <h3>Security</h3>
-    <p>Password and login settings.</p>
-  </article>
-  <article class="card">
-    <h3>Billing</h3>
-    <p>Invoices and payment methods.</p>
-  </article>
+  <article class="card"><h3>Profile</h3><p>Personal details.</p></article>
+  <article class="card"><h3>Security</h3><p>Login settings.</p></article>
+  <article class="card"><h3>Billing</h3><p>Payment details.</p></article>
 </section>
 ```
 
-This is useful for small sets of panels, not large card collections. Use `.grid` for repeatable collections.
-
-## CSS hooks
+Use `.grid` instead for repeatable collections whose items can reflow
+independently.
 
-- `--switcher-threshold` — container width at which the row becomes a column.
+### Hooks
 
-```css
-.settings-panels {
-  --switcher-threshold: 55rem;
-}
-```
+- `--switcher-threshold` controls the space needed before all peers share a row.

package/docs/pages/layout/topbar.md

@@ -2,7 +2,7 @@
 
 Sticky, frosted top bar shell for app/dashboard layouts with a persistent sidebar.
 
-> **Optional** — import `actual-css/css/optional/layout-extra` or `actual-css/css/optional/index`.
+> **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.
 
@@ -20,4 +20,4 @@ Use `.topbar` for the structural shell of an app-shell header: sticky positionin
 </header>
 ```
 
-This is for the app-shell topbar specifically — a structural need that recurs unchanged across app UIs regardless of brand. It is not for marketing or editorial site headers, which are one-off visual identity per page.
+This is for the app-shell topbar specifically — a structural need that recurs unchanged across app UIs regardless of brand. It is not for marketing or editorial site headers, which are one-off visual identity per page.

package/docs/pages/patterns/actions.md

@@ -49,4 +49,4 @@ Prefer composition over making each component reimplement action-list layout.
   padding: 0;
   list-style: none;
 }
-```
+```

package/docs/pages/patterns/code-block.md

@@ -33,4 +33,4 @@ enhance({
 });
 ```
 
-No core JS, no syntax highlighter — the recipe is the documentation.
+No core JS, no syntax highlighter — the recipe is the documentation.

package/docs/pages/patterns/exclusive-accordion.md

@@ -13,4 +13,4 @@ Browsers that support the `name` attribute on `<details>` get native exclusive a
 </details>
 ```
 
-Not shipping an accordion JS engine is a design decision, not a gap.
+Not shipping an accordion JS engine is a design decision, not a gap.

package/docs/pages/patterns/hierarchical-nav.md

@@ -23,4 +23,4 @@ App shell with a collapsible nav tree. Uses existing primitives only — no tree
 - Native `<details>`: exclusive accordion with `<details name>` (no JS engine)
 - `data-enhance="scrollspy"`: scroll-driven `aria-current`
 - `.scroller`: thin, theme-aware scrollbar
-- No `.nav-heading` / `.nav-sublist` classes — the existing primitives are enough
+- No `.nav-heading` / `.nav-sublist` classes — the existing primitives are enough

package/docs/pages/patterns/icon-input.md

@@ -22,4 +22,4 @@ The icon keeps a fixed `--input-icon-size` (1.25rem); density contexts shrink th
 </div>
 ```
 
-Trailing icons are supported too: an icon that follows the input is positioned at the end and the input grows its end padding. It stays decorative — `pointer-events: none` means an interactive trailing control such as a clear button is not covered by this class.
+Trailing icons are supported too: an icon that follows the input is positioned at the end and the input grows its end padding. It stays decorative — `pointer-events: none` means an interactive trailing control such as a clear button is not covered by this class.

package/docs/pages/patterns/icon-slot.md

@@ -0,0 +1,61 @@
+# Icon slot
+
+> Contained icon zones — a leading icon, an icon disc, a status marker — appear
+> across product UI: notifications, activity feeds, list actions, cards. There
+> is no dedicated primitive; the same small contract is composed from existing
+> pieces.
+
+A contained icon zone must be a **stable box** that never shrinks, always
+centers its glyph, and clips overflow:
+
+- fixed `inline-size` / `block-size` (or `aspect-ratio: 1` for a disc);
+- `display: grid; place-items: center;` for reliable centering;
+- `flex: 0 0 auto` so a flex row never compresses it;
+- `overflow: hidden`;
+- a child `svg` constrained to the box.
+
+## The contract
+
+```css
+.product-icon {
+  flex: 0 0 auto;
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+}
+
+.product-icon svg {
+  inline-size: 100%;
+  block-size: 100%;
+}
+```
+
+For a round disc, add the `.circle` utility — it supplies the `border-radius`:
+
+```css
+.product-icon.circle {
+  background: var(--surface-subtle);
+}
+```
+
+## Reuse the existing icon slots
+
+Several components already embody this slot — reach for them before composing
+your own:
+
+- `.alert-icon` — the leading icon in an alert.
+- `.avatar` — initials or image in a fixed circular box.
+- `.btn.icon-only` — a square icon button sized to the control height.
+- `.input-icon` — a leading icon in a search/filter input.
+
+```html demo
+<div class="media">
+  <span class="avatar primary"><abbr>AM</abbr></span>
+  <div class="stack">
+    <strong>Ada Meridian</strong>
+    <span class="muted">Senior designer.</span>
+  </div>
+</div>
+```

package/docs/pages/patterns/intent-nesting.md

@@ -1,3 +1,3 @@
 # Intent Nesting
 
-Intent on an ancestor must not tint nested components, and a local intent inside an intent-carrying ancestor must win. Both directions are verified in `tests/css-audit.test.js` and the kitchen-sink demo template. Intent classes only expose `--intent` and `--intent-fg`; each consuming component opens a local intent boundary in a `:where()` block that resets exactly the tokens it consumes to initial. Parent intents do not leak into nested components, and a local intent class still wins because it has higher specificity than `:where()`.
+Intent on an ancestor must not tint nested components, and a local intent inside an intent-carrying ancestor must win. Both directions are verified in `tests/css-audit.test.js` and the kitchen-sink demo template. Intent classes only expose `--intent` and `--intent-fg`; each consuming component opens a local intent boundary in a `:where()` block that resets exactly the tokens it consumes to initial. Parent intents do not leak into nested components, and a local intent class still wins because it has higher specificity than `:where()`.

package/docs/pages/patterns/navigation-list.md

@@ -232,4 +232,4 @@ A project may add `.side-nav` only when it needs specific visual behavior such a
 }
 ```
 
-Keep this separate from layout primitives. `.cluster` and `.stack` should not style links.
+Keep this separate from layout primitives. `.cluster` and `.stack` should not style links.

package/docs/pages/patterns/overview.md

@@ -55,4 +55,4 @@ If list chrome should be removed, use an explicit pattern.
   <li><a href="/docs">Docs</a></li>
   <li><a href="/components">Components</a></li>
 </ul>
-```
+```

package/docs/pages/patterns/structured-lists.md

@@ -1,47 +1,45 @@
 # Structured Lists
 
-Use native lists plus layout primitives for rich content rows. Reset list chrome only when markers are not part of the content.
+Choose list markup from the content semantics, then add only the layout or
+component contract the collection needs.
 
-```html demo
-<figure class="stack">
-  <figcaption><strong>Most played songs this week</strong></figcaption>
+| Need | Use |
+| --- | --- |
+| Bullets or order carry meaning | Native `<ul>` or `<ol>` |
+| One leading element and one flexible content region | [`.media`](../layout/media.md) |
+| Repeated application rows with leading, content, and trailing regions | [`.list`](../components/list.md) |
+| A list of navigation links | [`.nav-list`](./navigation-list.md) |
+| A richer collection with its own item structure | Native list plus layout primitives and components |
 
-  <ul class="list-reset stack gap-none">
-    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
-      <div class="avatar">
-        <img src="https://i.pravatar.cc/48?img=5" alt="Dio Lupa" />
-      </div>
-      <div class="cluster">
-        <div class="stack grow" style="--gap: var(--space-10)">
-          <strong>Dio Lupa</strong>
-          <span class="muted">Remaining Reason</span>
-        </div>
-        <span class="muted">3:45</span>
-        <button class="btn ghost" type="button" aria-label="Play">
-          <i class="ti ti-player-play" aria-hidden="true"></i>
-        </button>
-      </div>
-    </li>
+`.media` and `.list` are not interchangeable. `.media` is geometry for one
+two-part composition and requires exactly two direct children. `.list` owns the
+repeated-row treatment: three regions, row padding, minimum touch height,
+dividers, navigable-row hover, and supporting text.
 
-    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
-      <div class="avatar">
-        <img src="https://i.pravatar.cc/48?img=10" alt="Astral Planes" />
-      </div>
-      <div class="cluster">
-        <div class="stack grow" style="--gap: var(--space-10)">
-          <strong>Astral Planes</strong>
-          <span class="muted">Neon Drift</span>
-        </div>
-        <span class="muted">4:12</span>
-        <button class="btn ghost" type="button" aria-label="Play">
-          <i class="ti ti-player-play" aria-hidden="true"></i>
-        </button>
-      </div>
-    </li>
-  </ul>
-</figure>
-```
+Keep native markers when they communicate sequence, rank, or grouping. Remove
+them with `.list-reset` only when they are not part of the content. A reset
+changes list chrome; it does not create a row component.
 
-Use `.actions` for action controls and `.nav-list` for navigation links. For structured content items, compose `.list-reset`, `.stack`, `.cluster`, `.media`, and components directly.
+For a collection whose items are complete compositions rather than application
+rows, keep the native list and compose each item independently:
 
-`.media` is a two-slot object: it lays out exactly two children — the leading element and one content column. Trailing metadata and actions belong inside the content column (nest a `.cluster` and put `.grow` on the flexible part), never as extra row children: additional children silently wrap onto a second grid row.
+```html demo
+<ul class="list-reset grid" style="--grid-min: 16rem">
+  <li>
+    <article class="card stack">
+      <span class="badge">Guide</span>
+      <h2>Choose a layout</h2>
+      <p>Match intrinsic behavior to the structure of the content.</p>
+      <a href="#layout-guide">Read the guide</a>
+    </article>
+  </li>
+  <li>
+    <article class="card stack">
+      <span class="badge">Reference</span>
+      <h2>Compose spacing</h2>
+      <p>Use shared rhythm without coupling content to a component.</p>
+      <a href="#spacing-reference">View the reference</a>
+    </article>
+  </li>
+</ul>
+```

package/docs/pages/utilities/accessibility.md

@@ -4,8 +4,8 @@ Text hidden visually but still available to assistive technology.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
+| Class      | Kind    | Description                                                     |
+|------------|---------|-----------------------------------------------------------------|
 | `.sr-only` | Utility | Visually hides text while keeping it in the accessibility tree. |
 
 ## Screen reader only
@@ -31,4 +31,4 @@ Use `.sr-only` for text that should be available to assistive technology but vis
   white-space: nowrap;
   border: 0;
 }
-```
+```

package/docs/pages/utilities/flex.md

@@ -4,19 +4,19 @@ Small flex helpers for grow behavior and other one-line needs.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.grow` | Utility | Makes an item take available flex space without overflowing. |
-| `.items-start` | Utility | Aligns children to the block-start edge; sets `--items-align`. |
-| `.items-center` | Utility | Centers children on the cross axis; sets `--items-align`. |
-| `.items-end` | Utility | Aligns children to the block-end edge; sets `--items-align`. |
-| `.dot` | Utility | Inline separator dot for metadata rows. |
-| `.justify-content-start` | Utility | `justify-content: flex-start` and `--cluster-justify`. Optional layer. |
-| `.justify-content-center` | Utility | `justify-content: center` and `--cluster-justify`. Optional layer. |
-| `.justify-content-end` | Utility | `justify-content: flex-end` and `--cluster-justify`. Optional layer. |
+| Class                            | Kind    | Description                                                               |
+|----------------------------------|---------|---------------------------------------------------------------------------|
+| `.grow`                          | Utility | Makes an item take available flex space without overflowing.              |
+| `.items-start`                   | Utility | Aligns children to the block-start edge; sets `--items-align`.            |
+| `.items-center`                  | Utility | Centers children on the cross axis; sets `--items-align`.                 |
+| `.items-end`                     | Utility | Aligns children to the block-end edge; sets `--items-align`.              |
+| `.dot`                           | Utility | Inline separator dot for metadata rows.                                   |
+| `.justify-content-start`         | Utility | `justify-content: flex-start` and `--cluster-justify`. Optional layer.    |
+| `.justify-content-center`        | Utility | `justify-content: center` and `--cluster-justify`. Optional layer.        |
+| `.justify-content-end`           | Utility | `justify-content: flex-end` and `--cluster-justify`. Optional layer.      |
 | `.justify-content-space-between` | Utility | `justify-content: space-between` and `--cluster-justify`. Optional layer. |
-| `.flex-wrap` | Utility | `flex-wrap: wrap` on any flex container. Optional layer. |
-| `.flex-nowrap` | Utility | `flex-wrap: nowrap` on any flex container. Optional layer. |
+| `.flex-wrap`                     | Utility | `flex-wrap: wrap` on any flex container. Optional layer.                  |
+| `.flex-nowrap`                   | Utility | `flex-wrap: nowrap` on any flex container. Optional layer.                |
 
 ## Grow
 
@@ -65,8 +65,8 @@ flex containers:
 
 - `.items-start` / `.items-center` / `.items-end` set `--items-align`, read by `.alert` and `.card`.
 - `.text-start` / `.text-center` / `.text-end` set `--text-align`, read by `.table` cells.
-- `.justify-content-*` (optional layer) set `--cluster-justify`, read by `.cluster`.
-- `.flex-wrap` / `.flex-nowrap` (optional layer) set `flex-wrap` directly on any flex container.
+- `.justify-content-*` (utilities/extra) set `--cluster-justify`, read by `.cluster`.
+- `.flex-wrap` / `.flex-nowrap` (utilities/extra) set `flex-wrap` directly on any flex container.
 
 Set the property directly when you need a value the helpers do not ship.
 
@@ -102,4 +102,4 @@ Always mark it `aria-hidden="true"` — it is a visual separator, not content.
 
 - `--items-align` — cross-axis alignment, set by `.items-start` / `.items-center` / `.items-end`.
 - `--text-align` — text alignment, set by `.text-start` / `.text-center` / `.text-end`.
-- `--cluster-justify` — main-axis distribution, set by the optional `.justify-content-*` helpers and read by `.cluster`.
+- `--cluster-justify` — main-axis distribution, set by the optional `.justify-content-*` helpers and read by `.cluster`.

package/docs/pages/utilities/links.md

@@ -4,10 +4,10 @@ Link styling for chrome that is conceptually a link but should not look like pro
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
+| Class         | Kind    | Description                                               |
+|---------------|---------|-----------------------------------------------------------|
 | `.link-plain` | Utility | Removes the underline and inherits the surrounding color. |
-| `.link-muted` | Utility | Muted link that shifts to the full text color on hover. |
+| `.link-muted` | Utility | Muted link that shifts to the full text color on hover.   |
 
 ## Plain
 
@@ -15,4 +15,4 @@ Link styling for chrome that is conceptually a link but should not look like pro
 
 ## Muted
 
-`.link-muted` is a `.link-plain` that starts in the muted text color and shifts to the full text color on hover. Use for navigation lists, table of contents, and other secondary navigation surfaces.
+`.link-muted` is a `.link-plain` that starts in the muted text color and shifts to the full text color on hover. Use for navigation lists, table of contents, and other secondary navigation surfaces.

package/docs/pages/utilities/list.md

@@ -4,11 +4,11 @@ Utilities for list chrome reset, readable measure, and editorial kicker labels.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.list-reset` | Utility | Removes native list margin, padding, and markers. |
-| `.measure` | Utility | Caps a block at a readable width via `--prose-measure`. |
-| `.overline` | Component | Small editorial kicker label: muted, uppercase, letterspaced. |
+| Class         | Kind      | Description                                                   |
+|---------------|-----------|---------------------------------------------------------------|
+| `.list-reset` | Utility   | Removes native list margin, padding, and markers.             |
+| `.measure`    | Utility   | Caps a block at a readable width via `--measure`.             |
+| `.overline`   | Component | Small editorial kicker label: muted, uppercase, letterspaced. |
 
 ## List reset
 
@@ -16,7 +16,7 @@ Utilities for list chrome reset, readable measure, and editorial kicker labels.
 
 ## Measure
 
-`.measure` caps a block at a readable width using `--prose-measure`. It does not center — combine with `.center` for the common centered reading column, or with `margin-inline: auto` for a one-off centered block.
+`.measure` caps a block at a readable width using `--measure`. It does not center — combine with `.center` for the common centered reading column, or with `margin-inline: auto` for a one-off centered block.
 
 Use it for any content that needs a comfortable measure: prose articles, TOC lists, form fields, callouts. Avoid using it for full-bleed surfaces.
 
@@ -28,5 +28,5 @@ The overline exists because categories, kicker labels, and section markers recur
 
 ## CSS hooks
 
-- `--prose-measure` — the readable measure `.measure` caps at; defaults to `70ch`.
-- `--overline-radius` — the pill chip's corner radius; defaults to `--radius-full`.
+- `--measure` — the readable measure `.measure` caps at; defaults to `70ch`.
+- `--overline-radius` — the pill chip's corner radius; defaults to `--radius-full`.

package/docs/pages/utilities/overflow.md

@@ -4,13 +4,13 @@ Explicit overflow handling for content that may exceed its container.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.overflow-auto` | Utility | Enables scrolling when content exceeds the container. |
-| `.overflow-hidden` | Utility | Clips overflowing content. Optional layer. |
-| `.overflow-clip` | Utility | Clips overflowing content without a scroll container. Optional layer. |
-| `.overflow-x-auto` | Utility | Horizontal scrolling only. Optional layer. |
-| `.overflow-y-auto` | Utility | Vertical scrolling only. Optional layer. |
+| Class              | Kind    | Description                                                           |
+|--------------------|---------|-----------------------------------------------------------------------|
+| `.overflow-auto`   | Utility | Enables scrolling when content exceeds the container.                 |
+| `.overflow-hidden` | Utility | Clips overflowing content. Optional layer.                            |
+| `.overflow-clip`   | Utility | Clips overflowing content without a scroll container. Optional layer. |
+| `.overflow-x-auto` | Utility | Horizontal scrolling only. Optional layer.                            |
+| `.overflow-y-auto` | Utility | Vertical scrolling only. Optional layer.                              |
 
 Use `.overflow-auto` when content may overflow its container, especially tables and code-like regions.
 
@@ -40,4 +40,4 @@ Use `.overflow-auto` when content may overflow its container, especially tables
 }
 ```
 
-The optional layer extends the same concern with axis-specific and clipping variants. For quiet, custom scrollbar chrome instead of the native OS scrollbar, pair `.overflow-auto` with `.scroller` on the Sizing And Wrapping page.
+The extra utilities extend the same concern with axis-specific and clipping variants. To give the native scrollbar the theme's density and colour, pair `.overflow-auto` with `.scroller` on the Sizing And Wrapping page.

package/docs/pages/utilities/overview.md

@@ -15,4 +15,4 @@ Utilities are a small escape hatch for common single-purpose needs. They should
 - No color scales such as `.text-primary` or `.bg-success` — intent colors belong to components and state.
 - No breakpoint utility variants — use container queries or layout primitives.
 - No utility variants for hover, focus, dark mode, or arbitrary selectors — use component states.
-- No full spacing scale with every step and direction — the 17 spacing helpers across the core and optional layers cover the most common escape hatches.
+- No full spacing scale with every step and direction — the 17 spacing helpers across the core and extra utilities cover the most common escape hatches.

package/docs/pages/utilities/shape.md

@@ -4,8 +4,8 @@ Rare shape utilities for cases that must be perfectly round or square.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
+| Class     | Kind    | Description                                         |
+|-----------|---------|-----------------------------------------------------|
 | `.circle` | Utility | Forces a perfectly round shape via `--radius-full`. |
 
 Shape utilities should be rare because shape is mostly theme-level.
@@ -22,4 +22,4 @@ Use `.circle` only when an element must be perfectly round.
 }
 ```
 
-Do not add `.rounded-sm`, `.rounded-lg`, `.square`, or `.pill` unless repeated real use proves they are needed.
+Do not add `.rounded-sm`, `.rounded-lg`, `.square`, or `.pill` unless repeated real use proves they are needed.

package/docs/pages/utilities/sizing-wrapping.md

@@ -4,12 +4,12 @@ Small layout corrections for controls, labels, and compact rails.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.fit` | Utility | Shrinks a control or element to its content width. |
-| `.text-nowrap` | Utility | Keeps text on one line. |
-| `.truncate` | Utility | Ellipsizes overflowing single-line text. |
-| `.scroller` | Utility | Quiet custom scrollbar chrome for scroll containers. Optional layer. |
+| Class                     | Kind    | Description                                                               |
+|---------------------------|---------|---------------------------------------------------------------------------|
+| `.fit`                    | Utility | Shrinks a control or element to its content width.                        |
+| `.text-nowrap`            | Utility | Keeps text on one line.                                                   |
+| `.truncate`               | Utility | Ellipsizes overflowing single-line text.                                  |
+| `.scroller`               | Utility | Theme-aware scrollbar density and colour for scroll containers. Optional layer. |
 | `.scroller.stable-gutter` | Variant | Reserves scrollbar gutter space so layout does not shift. Optional layer. |
 
 Use `.fit` when a control or element should shrink to its content instead of filling the available inline space.
@@ -66,10 +66,22 @@ Use `.truncate` on the flexible item that should ellipsize inside a constrained
 
 Use `.scroller` to apply optional framework scrollbar treatment to a scroll container. It styles the scrollbar only; pair it with `.overflow-auto` or a component that already creates overflow.
 
+The utility is two standard declarations and nothing else — the engine keeps
+drawing the scrollbar, `.scroller` only hands it a density and a colour that
+follow the theme. There is no `::-webkit-scrollbar` chrome: rebuilding a thumb
+by hand means re-implementing the hover, the corner and the light/dark
+adaptation that `color-scheme` already provides, and the hand-built version
+never quite matches the native one anyway.
+
+`scrollbar-color` and `scrollbar-width` land in Chromium 121 and Safari 18.2,
+above the capability floor. An engine that knows neither ignores both
+declarations and draws its native scrollbar — the intended fallback, not a
+broken state.
+
 `scroller` is not imported by `actual.css`. Import it explicitly when a project wants Actual CSS scrollbar chrome instead of the native OS default:
 
 ```css
-@import "actual-css/css/optional/scroller";
+@import "actual-css/css/layout/scroller";
 ```
 
 ```html demo
@@ -84,11 +96,8 @@ Use `.scroller` to apply optional framework scrollbar treatment to a scroll cont
 
 ```css
 .scroller {
-  --scroller-size: 0.625rem;
-  --scroller-padding: 0.125rem;
   --scroller-track: transparent;
   --scroller-thumb: var(--border);
-  --scroller-thumb-hover: var(--text-muted);
 
   scrollbar-color: var(--scroller-thumb) var(--scroller-track);
   scrollbar-width: thin;
@@ -98,18 +107,16 @@ Use `.scroller` to apply optional framework scrollbar treatment to a scroll cont
 Customize locally when a scroll surface needs more contrast:
 
 ```html
-<div class="overflow-auto scroller"
-     style="--scroller-thumb: var(--text-muted); --scroller-thumb-hover: var(--text)">
+<div class="overflow-auto scroller" style="--scroller-thumb: var(--text-muted)">
   ...
 </div>
 ```
 
-For rounded scroll containers, keep the thumb visually away from the edge by tuning `--scroller-padding` rather than adding extra wrappers or masking pseudo-elements.
+Thickness is not a hook: `scrollbar-width` takes `thin` or `auto`, not a length.
+Hover is left to the engine — it varies by platform, and matching it by hand was
+the part of a custom scrollbar that never held up.
 
 ## CSS hooks
 
-- `--scroller-size` — scrollbar thickness.
-- `--scroller-padding` — inset between the thumb and the track edge.
 - `--scroller-track` — scrollbar track color.
 - `--scroller-thumb` — scrollbar thumb color.
-- `--scroller-thumb-hover` — scrollbar thumb color on hover.