actual-css 0.3.1 → 0.4.0

package/docs/pages/layout/stack.md

@@ -22,6 +22,58 @@ 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.
 
+## 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 +104,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/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

@@ -44,4 +44,4 @@ Use native lists plus layout primitives for rich content rows. Reset list chrome
 
 Use `.actions` for action controls and `.nav-list` for navigation links. For structured content items, compose `.list-reset`, `.stack`, `.cluster`, `.media`, and components directly.
 
-`.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.
+`.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.

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.

package/docs/pages/utilities/spacing.md

@@ -4,25 +4,25 @@ Semantic step helpers for gap, padding, and margin — the most common inline-st
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.gap-none` | Utility | `gap: 0` on the element itself. |
-| `.py` | Utility | Block (vertical) padding at the current density step. |
-| `.px` | Utility | Inline (horizontal) padding at the current density step. |
-| `.mbs` | Utility | Block-start margin at the current density step. |
-| `.mbe` | Utility | Block-end margin at the current density step. |
-| `.gap-sm` | Utility | `gap: var(--space-20)` — denser row rhythm. Optional layer. |
-| `.gap-md` | Utility | `gap: var(--space-40)` — default row rhythm. Optional layer. |
-| `.gap-lg` | Utility | `gap: var(--space-50)` — roomier row rhythm. Optional layer. |
-| `.padding-context` | Utility | All-side padding at the current density step. Optional layer. |
-| `.gap-context` | Utility | `gap: var(--gap)`. Optional layer. |
-| `.row-gap-context` | Utility | `row-gap: var(--gap)`. Optional layer. |
-| `.column-gap-context` | Utility | `column-gap: var(--gap)`. Optional layer. |
-| `.margin-inline-auto` | Utility | Horizontally centers a block. Optional layer. |
-| `.margin-inline-start-auto` | Utility | Pushes a block toward the inline end. Optional layer. |
-| `.margin-inline-end-auto` | Utility | Pushes a block toward the inline start. Optional layer. |
-| `.margin-block-start-auto` | Utility | Pushes content toward the block end. Optional layer. |
-| `.margin-block-end-auto` | Utility | Pushes content toward the block start. Optional layer. |
+| Class                       | Kind    | Description                                                   |
+|-----------------------------|---------|---------------------------------------------------------------|
+| `.gap-none`                 | Utility | `gap: 0` on the element itself.                               |
+| `.py`                       | Utility | Block (vertical) padding at the current density step.         |
+| `.px`                       | Utility | Inline (horizontal) padding at the current density step.      |
+| `.mbs`                      | Utility | Block-start margin at the current density step.               |
+| `.mbe`                      | Utility | Block-end margin at the current density step.                 |
+| `.gap-sm`                   | Utility | `gap: var(--space-20)` — denser row rhythm. Optional layer.   |
+| `.gap-md`                   | Utility | `gap: var(--space-40)` — default row rhythm. Optional layer.  |
+| `.gap-lg`                   | Utility | `gap: var(--space-50)` — roomier row rhythm. Optional layer.  |
+| `.padding-context`          | Utility | All-side padding at the current density step. Optional layer. |
+| `.gap-context`              | Utility | `gap: var(--gap)`. Optional layer.                            |
+| `.row-gap-context`          | Utility | `row-gap: var(--gap)`. Optional layer.                        |
+| `.column-gap-context`       | Utility | `column-gap: var(--gap)`. Optional layer.                     |
+| `.margin-inline-auto`       | Utility | Horizontally centers a block. Optional layer.                 |
+| `.margin-inline-start-auto` | Utility | Pushes a block toward the inline end. Optional layer.         |
+| `.margin-inline-end-auto`   | Utility | Pushes a block toward the inline start. Optional layer.       |
+| `.margin-block-start-auto`  | Utility | Pushes content toward the block end. Optional layer.          |
+| `.margin-block-end-auto`    | Utility | Pushes content toward the block start. Optional layer.        |
 
 Spacing helpers follow the density context. The default step is
 `--space-40` (1rem); the `.sm` context tightens it to `--space-20` (0.5rem)
@@ -76,4 +76,4 @@ No `mbs-none` / `mbe-none` — use `margin: 0` via `.list-reset` for lists, or a
 ## CSS hooks
 
 - `--density-space` — the step every padding and margin helper reads; `.sm` sets it to `--space-20`, default to `--space-40`, `.lg` to `--space-50`.
-- `--gap` — base gap of layout primitives; read by the optional `.gap-context`, `.row-gap-context`, and `.column-gap-context` helpers.
+- `--gap` — base gap of layout primitives; read by the optional `.gap-context`, `.row-gap-context`, and `.column-gap-context` helpers.

package/docs/pages/utilities/text.md

@@ -4,15 +4,15 @@ Lightweight helpers for muted or secondary text without a full color scale.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.muted` | Utility | Secondary text color. |
-| `.text-start` | Utility | Logical start-aligned text; sets `--text-align`. |
-| `.text-center` | Utility | Centered text; sets `--text-align`. |
-| `.text-end` | Utility | Logical end-aligned text; sets `--text-align`. |
-| `.text-balance` | Utility | Balanced line wrapping (`text-wrap: balance`). |
-| `.text-pretty` | Utility | Pretty line wrapping (`text-wrap: pretty`). |
-| `.lead` | Utility | Slightly larger, relaxed reading-introduction paragraph. |
+| Class           | Kind    | Description                                              |
+|-----------------|---------|----------------------------------------------------------|
+| `.muted`        | Utility | Secondary text color.                                    |
+| `.text-start`   | Utility | Logical start-aligned text; sets `--text-align`.         |
+| `.text-center`  | Utility | Centered text; sets `--text-align`.                      |
+| `.text-end`     | Utility | Logical end-aligned text; sets `--text-align`.           |
+| `.text-balance` | Utility | Balanced line wrapping (`text-wrap: balance`).           |
+| `.text-pretty`  | Utility | Pretty line wrapping (`text-wrap: pretty`).              |
+| `.lead`         | Utility | Slightly larger, relaxed reading-introduction paragraph. |
 
 ## Muted
 
@@ -40,4 +40,4 @@ Use `.text-start`, `.text-center`, or `.text-end` when a component or layout pri
 
 ## Lead
 
-`.lead` is a slightly larger, more relaxed reading-introduction paragraph (`1.125em`, `--line-height-relaxed`). Use it for introductory text in editorial surfaces. For fluid headline sizing, use `src/css/optional/typography-fluid.css`.
+`.lead` is a slightly larger, more relaxed reading-introduction paragraph (`1.125em`, `--line-height-relaxed`). Use it for introductory text in editorial surfaces. For fluid headline sizing, use `src/css/typography/fluid.css`.

package/llms.txt

@@ -10,14 +10,56 @@ Actual CSS uses a small public grammar: `.component [intent] [variant] [size] [m
 
 ## Package Entrypoints
 
-`package.json#exports` is the canonical package surface. Use `actual-css` for the
-full CSS framework and `actual-css/js` for the complete runtime. The composition
-guides in [README](README.md) and [Progressive Enhancements](docs/pages/enhancements/overview.md)
+`package.json#exports` is the canonical package surface.
+
+- `actual-css` — the minimal core: tokens, theme contract, reset, base elements, and universal variants. Components and layout primitives are NOT included.
+- `actual-css/full` — the complete framework: core plus every component, form, layout, typography, effect, and utility family.
+- `actual-css/js` — the enhancement loader only; it discovers `data-enhance` markers and loads enhancers on demand.
+- `actual-css/js/full` — the complete runtime with all built-in enhancers pre-registered.
+- `actual-css/reserved-classes.json` — machine-readable list of every class name the framework can generate. Use it to validate class usage in HTML (an "unknown class" checker) instead of guessing names from other frameworks.
+- Individual families and modules are importable separately (`actual-css/css/components`, `actual-css/css/layout/grid`, `actual-css/js/dialog`, …); see [README](README.md) and [Modular imports](docs/pages/guides/modular-import.md).
+
+The composition guides in [README](README.md) and [Progressive Enhancements](docs/pages/enhancements/overview.md)
 show supported CSS modules and individual enhancer imports without duplicating
 the full export list here.
 
-In 0.2, presentation (`class`) and behavior (`data-enhance`) are separate layers.
+Presentation (`class`) and behavior (`data-enhance`) are separate layers.
 Behaviour primitives (`enhance`, `floating`, `surface`, `keys`, `menu`, `focus`,
 `events`) are independently importable for building custom widgets.
 See [enhancement contract](docs/design-notes/enhancement-contract.md) and
 [widget primitives](docs/design-notes/widget-primitives.md).
+
+## Choosing a layout primitive
+
+Pick from the relationship between children, not the number of children in one mockup:
+
+- Responsive collection of cards/items where an incomplete final row is acceptable → `.grid`
+- Known structural density, at most N columns → `.grid-N`
+- Peer regions that must switch together → `.switcher`
+- Main content plus a secondary region (content + aside) → `.sidebar-layout`
+- Fixed media followed by flexible content → `.media`
+- Explicit region placement on a shared 12-column canvas → `.column-layout`
+- Vertical flow → `.stack`; wrapping inline items → `.cluster`
+
+Use `--grid-columns` on `.grid` for exact track templates that do not match a
+built-in layout contract: arbitrary structural counts (seven calendar days),
+asymmetric fractional tracks, or mixed intrinsic/flexible tracks. See
+[Choosing a layout](docs/pages/layout/choosing.md).
+
+`.status-bar` is transient feedback only; persistent metrics or application
+state belong in normal content such as cards, badges and alerts.
+
+## Before generating application CSS
+
+Read [Building with Actual CSS](docs/pages/guides/integrating-actual-css.md)
+before writing application styles.
+
+1. Start with Actual's vocabulary: theme tokens, then layout primitives, then components, then their public hooks, then small utilities, then application CSS.
+2. Choose layout primitives by relationship, not item count.
+3. Prefer component/layout hooks over replacement rules (tune before replacing).
+4. Search the class manifest before inventing generic utilities.
+5. Keep literal palette colors inside the theme/token block; derive decorative colors from tokens.
+6. Use application CSS for genuinely product-specific styling — brand marks, unusual geometry, bespoke animation.
+
+The goal is no duplicated framework behavior and no palette literals outside the
+token layer, not zero application CSS.