actual-css 0.12.0 → 0.13.0

package/docs/design-notes/architecture.md

@@ -0,0 +1,67 @@
+# Architecture
+
+How to decide what belongs in Actual, and where. The rules an application
+author follows are in [Philosophy](../pages/foundations/philosophy.md) and
+[Building with Actual CSS](../pages/guides/integrating-actual-css.md); naming is
+in [Naming conventions](naming.md), behavior in
+[Enhancement contract](enhancement-contract.md).
+
+The test for where a rule goes: if it changes how someone writes their
+application CSS, it belongs in the guide; if it only decides how Actual is
+built, it belongs here.
+
+## Ownership
+
+- **A component owns its intrinsic anatomy, not page composition.** Padding,
+  surface, slots and states are the component's; outer margins and sibling
+  spacing are not.
+- **A layout primitive on a component replaces its default layout without
+  specificity tricks.** The component's own box layout sits in `:where()`
+  (`.card`, its header and footer slots). `components/` loads after `layout/`,
+  so a plain class declaration would win on source order and flatten
+  `class="card media"` into a column.
+- **Structural anatomy never lends a class's weight to a bare element.**
+  `:where(dialog).modal > :where(form, .stack)`, not `> :is(form, .stack)`,
+  which would give `<form>` the specificity of `.stack`.
+
+## Utilities
+
+A utility makes one reusable adjustment. A class that sets a surface, a border,
+padding and type together has become a component, whatever file it lives in.
+
+## Abstraction
+
+- **Duplication beats an abstraction that couples unrelated components.** Every
+  file under `components/` is a public export (`actual-css/css/components/*`).
+  A shared file imported only by the index would break a single-component
+  import, so `.modal` and `.drawer` each keep the declarations they share.
+- **No generic primitive because two examples look alike.** A primitive names a
+  relationship that recurs across unrelated applications. When the existing
+  answer was hard to find, improve the docs instead.
+- **Bytes do not justify specificity.** A selector is not merged or raised to
+  save a few compressed bytes when it changes who can override it.
+
+## Tokens
+
+A value derived from an overridable token is computed on the element that uses
+it, never as an alias on `:root`: an inherited custom property arrives already
+computed, so an override on a theme island or a region would not reach it. The
+generic focus line (`focus.css`) and the dialog and drawer focus reserves
+follow this rule.
+
+## Decoration
+
+A decorative cue must not dictate geometry, focus or scroll behavior. Scrolling
+strips have no shared edge fade: its mask set their scroll-padding and focus
+reserve, and repeated what a clipped item and the scrollbar already show. The
+strips reserve only their focus line. `.tabs` is the exception: it hides its
+scrollbar, so its fade is the cue, and the fade spans the strip's existing
+scroll-padding instead of setting it.
+
+Starting a strip on its current item is a progressive enhancement, not a
+contract: `scroll-initial-target` on the item, no runtime. One declaration
+replaces a module, its opt-in token and its wait for parsing. Engines without
+the property start at the first item, which the fade or the scrollbar already
+says is not all; do not reintroduce a script fallback for them. `.pagination` does not scroll at all: it wraps, because a
+click on a page navigates instead of moving the strip, so a scrolling row hid
+pages the mouse could not reach.

package/docs/design-notes/steps.md

@@ -82,7 +82,7 @@ and upcoming is the absence of both, because the platform already spells those.
 
 Out of contract — a step name belongs in a `.step-label` — and it degrades in
 the right direction. `:empty` reads an item's own content, so `<li>Account</li>`
-is not empty: it takes the reading width a wrapped label would, and only the
+is not empty: it takes the same authored item floor as a wrapped label, and only the
 placing and aligning that `.step-label` rules provide are missing. It lays out
 and does not fall apart, which is all an out-of-contract markup is owed.
 
@@ -90,11 +90,8 @@ This is the case that makes bare text expensive to support as a first-class
 form, and it is worth stating precisely, because a component that sizes steps
 *per label* pays for it twice.
 
-In behaviour: a row mixing wrapped and unwrapped steps compacts only the
-wrapped ones. Measured at five steps in a 559px region, the unwrapped step
-holds 201px while its four peers shrink to 89px. That skew is what
-`> li:has(.step-label)` produces — bare text has no label, so it takes a
-marker-wide floor while its wrapped peers keep `--step-min`.
+In behaviour: sizing by `> li:has(.step-label)` would give bare text and
+wrapped labels different floors whenever an author sets `--step-min`.
 
 In bytes: the only valid way to express "every step is wrapped" is to enumerate
 positions (see "`:has()` cannot be nested"), which grows the selector for each
@@ -105,7 +102,7 @@ supported count.
 a link and bare text.
 
 The row-level alternative, `.steps-horizontal:not(:has(.step-label)) > li`,
-avoids the skew differently: it makes every step reading-width, so an empty
+avoids the skew differently: it gives every step the authored floor, so an empty
 step in a mixed row becomes a wide gap rather than a marker. It also puts the
 compact form itself behind `:has()`, above the Degraded tier, for a shape that
 needs no modern selector at all.
@@ -156,6 +153,32 @@ stay in the stacked layout.
 property, so overriding `--step-min` moves the scroll budget but not this
 query. Same trade as `--grid-min` in `grid.css`.
 
+## Even marker pitch and wrapping labels
+
+Stacked labelled steps keep an even marker pitch because each outgoing
+connector must reach the next marker's edge. Intrinsic per-label widths would
+move the markers unevenly and make that length depend on a neighbour's width.
+
+The first and last markers align with the row's edges at every width. Each
+end cell takes half a normal share plus half a marker; simply moving the marker
+inside a full cell would stretch the outer connectors. Labels follow the same
+start/end alignment, while the middle steps remain centred. The first connector
+crosses two end-cell widths minus both markers, plus the intervening gap.
+
+It is not behind a viewport query. Edge alignment is the row's geometry, the
+one the compact and inline forms already have, and a breakpoint on the viewport
+would lay out the same 600px row differently on a phone and in a desktop card.
+
+The marker sets the default item floor. A `minmax(0, 1fr)` grid column keeps a
+long label from widening its step; `hyphens: auto` breaks a long word where the
+page's `lang` allows, and `overflow-wrap: anywhere` still lets an unbroken name
+fit when it does not. `--step-gap` separates both the marker from its label and
+one step from the next, so wrapped names cannot run together.
+
+Authors can raise `--step-min` when wrapping costs too much height. The row
+then scrolls once those floors and the intervening gaps outgrow its region.
+This budget changes neither orientation nor the wide inline threshold.
+
 ## The compact form
 
 The whole unlabelled contract, in both orientations:
@@ -235,8 +258,7 @@ having no share to fill — is only as wide as its own marker.
 
 The result is a track flush with both ends of the row, which is what lets it
 line up with the heading or paragraph that names the step. Keeping the centred
-geometry leaves half-cell margins at both ends: measured on five empty steps in
-a 736px row, 60px of dead space on each side, with the first marker floating
+geometry leaves half-cell margins at both ends, with the first marker floating
 inward of a left-aligned heading.
 
 It also matches the inline representation, whose `:last-child { flex: 0 0 auto }`
@@ -244,7 +266,7 @@ is the same declaration for the same reason.
 
 The connector follows from the alignment rather than being tuned to it. The
 base geometry starts a connector at `50% + --step-size / 2` — the right edge of
-a centred marker — and runs it `100% - --step-size`, to the next marker's left
+a centred marker — and runs it `100% - --step-size + --step-gap`, to the next marker's left
 edge. Move the marker to the start of the share and that origin becomes
 `--step-size`; the width is unchanged, and the connector still lands exactly on
 the next marker. Measured at 736px and at 200px: zero gap either side.
@@ -265,7 +287,7 @@ leave in a component whose whole claim is that sizing follows content.
 ### Why `:empty` rather than `:has()`
 
 It says what the markup says, and it reads the item's own content, which is
-what keeps bare text off a marker-wide floor (see "Bare text in an `<li>`").
+what keeps bare text on the same authored floor as labelled peers (see "Bare text in an `<li>`").
 
 It also predates `:has()` by a decade, so the compact form reaches the Degraded
 tier. `:has(.step-label)` appears only in the wide container query, where
@@ -412,7 +434,7 @@ The contract is one sentence. A step label may be a link, a marker never is, and
 anything else focusable in a step is out of contract.
 
 The one `:has(a[href])` in the file is unrelated: a navigable row reserves
-`padding-block` for its focus ring, because the scroll container clips at the
+padding on both axes for its focus ring, because the scroll container clips at the
 padding edge. See "Scrolling on one axis".
 
 A link needs no styling rule of its own to go with it. `color: inherit` sits in
@@ -442,13 +464,9 @@ with `.sr-only` on `.step-label`, so the text stays in the accessibility tree
 while its box disappears. Or the same rules behind a public class, so the author
 picks the representation instead of a width picking it.
 
-The threshold is not the weak part. Items hold at `flex: 1 0 var(--step-min)`,
-so a row's intrinsic width is `count × --step-min` — 35rem for five steps — and
-the query fires exactly where a five-step stacked row starts to scroll. Four
-steps share that threshold rather than getting their own at 28rem, so between
-448px and 560px they compact although stacked would still fit; splitting the
-difference at 32rem is worse, handing five-step rows a scrolling band instead
-(40px of overflow at 520px, 20px at 540px).
+A fixed hiding threshold cannot reflect the authored item floor or the actual
+length of a label. Wrapping uses the available share directly, without removing
+content or introducing a per-count breakpoint.
 
 ### Why the premise fails
 
@@ -469,7 +487,7 @@ So the question is not "how narrow before labels must go?" but "does this
 sequence carry names at all?", and that one is the author's to answer in
 markup. An unlabelled sequence is compact because it has nothing to show; a
 labelled one keeps everything it was given. When a labelled row does not fit,
-the honest answers are scrolling, more space, or `.steps-vertical`.
+the available answers are wrapping, scrolling, more space, or `.steps-vertical`.
 
 ### What the rule is worth, concretely
 
@@ -611,7 +629,7 @@ retuning surface is `--scroller-thumb` and `--scroller-track`, which belong to
 `.scroller`. Copying those into Steps duplicates the primitive; omitting them
 leaves a scrollbar no documented hook reaches.
 
-Measured on a five-step row in a 380px region, the pairing takes the scrollbar
+Measured on a five-step row with an authored `--step-min: 7rem` in a 380px region, the pairing takes the scrollbar
 from 15px to 10px and the row from 69px to 64px, with the thumb on
 `--text-muted` instead of the OS grey.
 
@@ -620,19 +638,18 @@ Its `.stable-gutter` variant, on the other hand, is a trap worth naming.
 scrollbar — and this row sets `overflow-y: hidden`, so there is never one to
 reserve for. It does not steady the row's height across the appearance of the
 horizontal scrollbar, which is what an author would reach for it to do:
-measured, the row is 54px when it fits and 64px when it scrolls either way,
-while the reserved inline gutter takes 10px off the row's width and pushes
-overflow from 36px to 46px. Strictly worse in both directions.
+the reserved inline gutter narrows the row without reserving space for a
+horizontal scrollbar, making horizontal overflow more likely.
 
 What makes the row scroll rather than squash is the item floor:
 `min-inline-size: max(var(--step-size), var(--step-min))`. The `max()` is there
-so an author who lowers `--step-min` below `--step-size` narrows the scroll
-budget without collapsing items behind their own markers.
+so an author who lowers `--step-min` below `--step-size` cannot collapse items
+behind their own markers.
 
 The cost of scrolling is that clipping happens at the padding edge, and a focus
-ring is drawn outside its element's border box — `--focus-outline` is
+ring is drawn outside its element's border box — the generic outline is
 `--focus-ring-width` wide at `--focus-outline-offset`, so 4px past a label that sits
-flush with the bottom of a stacked row. A navigable row therefore reserves
+flush with the edge of a stacked row. A navigable row therefore reserves
 exactly that much `padding-block`, gated on `.steps-horizontal:has(a[href])`. An
 informational stepper — the common case, with no ring to protect — keeps its
 height, and so does a navigable column: the padding is compensation for the

package/docs/pages/components/avatar.md

@@ -12,12 +12,12 @@
 
 ## Class reference
 
-| Class           | Kind        | Description                                  |
-| --------------- | ----------- | -------------------------------------------- |
-| `.avatar`       | Component   | Initials or image in a circular box.         |
-| `.avatar-stack` | Composition | Overlapping avatar group.                    |
-| `.badge:empty`  | Composition | Status dot, at the bottom-end corner.        |
-| `.sm` / `.lg`   | Size        | Optical size; also rescales `.avatar-stack`. |
+| Class           | Kind        | Description                            |
+| --------------- | ----------- | -------------------------------------- |
+| `.avatar`       | Component   | Initials or image in a circular box.   |
+| `.avatar-stack` | Composition | Overlapping avatar group.              |
+| `.badge:empty`  | Composition | Status dot, at the bottom-end corner.  |
+| `.sm` / `.lg`   | Size        | Optical size, on an avatar or a stack. |
 
 `.avatar` works on `div`, `a` and `button`. The status dot is an empty
 `.badge` inside an `.avatar`, and needs an `aria-label` of its own.
@@ -79,6 +79,9 @@ is suppressed inside the avatar.
 
 ## Avatar stack
 
+Set `.sm` or `.lg` on `.avatar-stack` to size the group; its avatars inherit
+that size without their own size classes. Child sizes do not resize the stack.
+
 ```html demo
 <div class="avatar-stack" role="group" aria-label="Team members">
   <div class="avatar" role="img" aria-label="John Doe" style="--avatar-bg:#E5EEE4">
@@ -93,16 +96,19 @@ is suppressed inside the avatar.
 </div>
 ```
 
-## CSS hooks
+### Hooks
 
 - `--avatar-size` — inline and block size.
 - `--avatar-radius` — corner radius; set a smaller value for squared avatars.
+- `--avatar-font-size` — initials size.
 - `--avatar-bg` — background; `data-tone` adjusts the derived foreground.
 - `--avatar-stack-size` — stack-scoped size that each avatar falls back to.
+- `--avatar-stack-font-size` — stack-scoped initials size, paired with `--avatar-stack-size`.
 - `--avatar-stack-overlap` — how far stacked avatars overlap.
 - `--avatar-stack-ring` — separating ring width inside `.avatar-stack`.
 
-Prefer intents for avatar colors. Inside `.avatar-stack`, `--avatar-size` falls
-back to a stack-scoped value so the whole group resizes together with `.sm`/`.lg`;
-set `--avatar-size` on an individual avatar to opt one out.
-`--avatar-stack-overlap` is derived from `--avatar-stack-size`, not `--avatar-size`.
+Prefer intents for avatar colors. Inside `.avatar-stack`, `--avatar-size` and
+`--avatar-font-size` fall back to the stack-scoped pair, which `.sm`/`.lg` on
+the stack set, so the whole group resizes together; set `--avatar-size` on an
+individual avatar to opt one out. `--avatar-stack-overlap` is derived from
+`--avatar-stack-size`, not `--avatar-size`.

package/docs/pages/components/breadcrumb.md

@@ -4,8 +4,11 @@
 
 - Use a semantic `<nav>` landmark.
 - Put `.breadcrumb` on the ordered list.
-- Use `aria-current="page"` for the current page.
-- Separators are generated with CSS (`li + li::before`).
+- Use `aria-current="page"` for the current page, on its link or on its `<li>`,
+  and keep it last.
+- Separators are generated with CSS (`> li + li::before`).
+- Put each ancestor label in an `<a>` or a `<span>`: that box carries the
+  ellipsis. The current page may be bare text in an `<li aria-current="page">`.
 
 ```html demo
 <nav aria-label="Breadcrumb">
@@ -17,3 +20,14 @@
   </ol>
 </nav>
 ```
+
+## Narrow space
+
+A trail stays on one line and never scrolls. When it does not fit, labels
+truncate with an ellipsis: ancestors first, down to a couple of characters
+each, then the current page. A link keeps its full text as its accessible
+name; add a `title` if pointer users should see it on hover.
+
+Truncation does not remove levels. For a deep hierarchy on a phone, collapse
+it in markup — keep the root and the current page, and replace the middle
+levels with a `…` item, or render only a link to the parent page.

package/docs/pages/components/list.md

@@ -39,14 +39,10 @@ gap: `.list-item-content` always takes the row's free space and
 leading region or not. A settings row — a label, a description, and one
 control on the end edge — is the two-region form.
 
-Regions align to the row's first line: the leading check or avatar, the title,
-and the trailing metadata or control sit on one horizontal line while
-supporting text wraps beneath — a structured row, not a centered button. For a
-shared two-line arrangement where leading and trailing truly need to center,
-the app composes the alignment itself rather than switching this default.
-A pure traversal affordance such as a trailing caret can opt out of the
-first-line rule on its own item with `align-self: center`, keeping metadata
-rows unaffected.
+Regions center on the row. When supporting text runs to three lines or more,
+add `.items-start` to the row, or to the `.list` for every row, so the leading
+avatar and the trailing control stay on the title line instead of floating
+mid-paragraph (top-align, align to first line).
 
 ```html demo
 <ul class="list">
@@ -83,7 +79,7 @@ For a navigable row, keep the list semantics and put `.list-item` on the link:
         <strong class="list-item-title">Profile</strong>
         <span class="list-item-text">Name, photo, and contact details</span>
       </span>
-      <i class="ti ti-chevron-right list-item-trailing" style="align-self: center" aria-hidden="true"></i>
+      <i class="ti ti-chevron-right list-item-trailing" aria-hidden="true"></i>
     </a>
   </li>
 </ul>
@@ -92,10 +88,10 @@ For a navigable row, keep the list semantics and put `.list-item` on the link:
 Do not attach click JavaScript to the entire row. Use a link for navigation and
 a button or native control for actions.
 
-In a master/detail navigation, mark the current row with `aria-current` on its
-link, using the value that matches the semantics (`page`, `location`, …).
-Presence is the contract: set the attribute on the current row and remove it
-elsewhere, never `aria-current="false"`. The [Workspaces example](../examples/overview.md)
+Mark the current row on its link with `aria-current="page"` when the row opens
+a page, or `aria-current="true"` when it is the current item of a master/detail
+view (a conversation, a thread, a record) that is not a page of its own. Any
+other value is inert. The [Workspaces example](../examples/overview.md)
 shows a current row with trailing actions and a flyout. Navigable rows usually
 want a non-zero `--list-item-pad-inline`: without that gutter, the current
 indicator touches the leading region and the trailing touches the row edge.

package/docs/pages/components/navbar.md

@@ -6,10 +6,9 @@
 - `.navbar-brand` is the brand link at the inline start.
 - Horizontal links live in a `.cluster`; its items are `.nav-link`.
 - `.nav-list` is the shared vertical navigation list, reused by `.drawer` for stacked links.
-- Mark the current page with `aria-current="page"` on the active `.nav-link`.
-- Presence is the contract: set `aria-current` on the current link and remove
-  it elsewhere, never `aria-current="false"`. Scrollspy follows the same rule
-  with `aria-current="location"`.
+- Mark the current page with `aria-current="page"` on the active `.nav-link`,
+  or the current section of the page with `aria-current="location"` (what
+  scrollspy sets). Any other value is inert.
 
 For a public or normally scrolling page, `.navbar` belongs inside the semantic
 site header. Do not use `.topbar` or `.app-layout` unless the page actually has
@@ -59,31 +58,36 @@ section titles, a pinned account footer, and the native current state.
 There is no collapse/toggler mechanism. For a responsive navigation, keep the
 horizontal `.navbar` for the desktop bar and compose the mobile experience from
 a `.drawer` with a vertical `.nav-list`, opened by a `command="show-modal"` /
-`commandfor` trigger. Keep that trigger outside the `<nav>` subtree you hide at
-narrow widths, or hiding the nav hides the control that opens it.
+`commandfor` trigger. Keep that trigger in the bar but outside the `<nav>`
+subtree you hide at narrow widths, or hiding the nav hides the control that
+opens it: the bar is then the `<header>`, and the links get their own `<nav>`.
 
 When the compact layout drops labels, keep that text in the DOM and hide it
 visually instead of replacing it with `aria-label` strings: one source for the
 accessible name.
 
 ```html demo
-<nav class="navbar" aria-label="Main">
+<header class="navbar">
   <a class="navbar-brand" href="/">Actual CSS</a>
-  <ul class="cluster">
-    <li><a class="nav-link" href="/" aria-current="page">Home</a></li>
-    <li><a class="nav-link" href="/docs">Docs</a></li>
-  </ul>
-</nav>
-
-<button class="btn ghost"
-        type="button"
-        command="show-modal"
-        commandfor="site-nav"
-        aria-haspopup="dialog"
-        aria-controls="site-nav"
-        aria-label="Open menu">
-  <i class="ti ti-menu-2" aria-hidden="true"></i>
-</button>
+  <div class="cluster">
+    <nav class="site-links" aria-label="Main">
+      <ul class="cluster">
+        <li><a class="nav-link" href="/" aria-current="page">Home</a></li>
+        <li><a class="nav-link" href="/docs">Docs</a></li>
+      </ul>
+    </nav>
+
+    <button class="btn ghost site-menu"
+            type="button"
+            command="show-modal"
+            commandfor="site-nav"
+            aria-haspopup="dialog"
+            aria-controls="site-nav"
+            aria-label="Open menu">
+      <i class="ti ti-menu-2" aria-hidden="true"></i>
+    </button>
+  </div>
+</header>
 
 <dialog class="drawer"
         id="site-nav"
@@ -107,6 +111,22 @@ accessible name.
 </dialog>
 ```
 
+The demo shows both controls; the application picks one per width:
+
+```css
+@media (width < 40rem) {
+  .site-links {
+    display: none;
+  }
+}
+
+@media (width >= 40rem) {
+  .site-menu {
+    display: none;
+  }
+}
+```
+
 The drawer can be hidden until opened: give the `dialog` the `hidden` attribute
 in the HTML and let the command runtime manage it, or rely on the drawer being
 rendered only on the mobile layout. `command` and `commandfor` work without

package/docs/pages/components/pagination.md

@@ -54,3 +54,22 @@ buttons — they are decorative, not actionable.
   </ol>
 </nav>
 ```
+
+## Narrow screens
+
+When the items do not fit, the row wraps: every page stays visible and
+clickable. That is the fallback, not the mobile design. For a phone or a
+narrow column (responsive, mobile, small screen), render a shorter range — the
+server knows which pages matter around the current one:
+
+```html demo
+<nav aria-label="Pagination">
+  <ol class="pagination sm">
+    <li><a href="?page=7" class="btn ghost" rel="prev"><i class="ti ti-chevron-left" aria-hidden="true"></i> Previous</a></li>
+    <li><a href="?page=7" class="btn ghost" aria-label="Page 7">7</a></li>
+    <li><a href="?page=8" class="btn ghost" aria-current="page" aria-label="Page 8">8</a></li>
+    <li><a href="?page=9" class="btn ghost" aria-label="Page 9">9</a></li>
+    <li><a href="?page=9" class="btn ghost" rel="next">Next <i class="ti ti-chevron-right" aria-hidden="true"></i></a></li>
+  </ol>
+</nav>
+```

package/docs/pages/components/steps.md

@@ -145,23 +145,28 @@ names, or when a step should be navigable:
 ```
 
 **Actual CSS never hides an authored step label.** Labels stay visible at every
-width. If a labelled row does not fit its space, it scrolls — and the honest
-answers to that are more room, fewer stages, or `.steps-vertical`.
+width. Stacked steps keep their markers evenly spaced, and long names wrap
+inside their share, hyphenated when the page declares a `lang`. The first and
+last steps align with the row's edges, labels included, so the track lines up
+with the heading above it. Short labels fit a phone with no width budget.
 
-Since scrolling is the fallback, a labelled row is worth pairing with
-`.scroller`, which gives the native scrollbar the theme's density and colour
-instead of the OS default:
+Set `--step-min` when names need a wider minimum share. If the markers or that
+minimum do not fit, the row scrolls; use `.steps-vertical` when every name must
+remain visible without horizontal scrolling.
+
+In supporting browsers, a row that scrolls starts on its `aria-current="step"`
+instead of step 1. A row
+that raises `--step-min` can scroll, so it is worth pairing with `.scroller`,
+which gives the native scrollbar the theme's density and colour instead of the
+OS default:
 
 ```html
 <ol class="steps steps-horizontal scroller">
 ```
 
-Steps does not apply it for you, because scrollbar treatment is an app-wide
-decision rather than a per-component one. Every other scroll container —
-`.table`, a `.flyout`, a scrolling `dialog` — leaves the scrollbar alone too,
-so a page that thinned only its stepper would show two kinds of scrollbar. Put
-`.scroller` on whatever scrolls, once. See the sizing and wrapping page for its
-hooks.
+Steps does not apply it for you; see
+[one-row strips](../utilities/sizing-wrapping.md#one-row-strips) for the
+page-wide rule and the hooks.
 
 Do not add `.stable-gutter` here. It reserves gutter on the inline axis, for a
 vertical scrollbar this row never draws, so it narrows the row instead of
@@ -361,8 +366,9 @@ On `.steps`, so both orientations read them:
 
 `.steps-horizontal` only:
 
-- `--step-min` — minimum item width in the stacked horizontal layout
-- `--step-gap` — marker-to-label space in the stacked horizontal layout
+- `--step-min` — minimum width budget for stacked steps; the first and last
+  cells use half that budget plus half the marker width
+- `--step-gap` — marker-to-label and between-step space in the stacked layout
 - `--step-connector` — default horizontal connector background
 - `--step-inline-connector` — optional connector background for wide horizontal steps
 
@@ -372,12 +378,11 @@ On `.steps`, so both orientations read them:
 
 ## Notes
 
-Do not mix labelled and unlabelled steps in one sequence. Each step is sized on
-its own content, so a mixed sequence renders a narrow marker between reading-
-width steps — it lays out, but it reads as a gap rather than as progress.
+Do not mix labelled and unlabelled steps in one sequence. Empty steps align
+their markers to the start; labelled steps centre them over their names.
 
 A step name belongs in a `.step-label`. Bare text in an `<li>` is outside the
-contract: it is content, so it gets a reading width like a label, but no rule
+contract: it takes the same item floor as a label, but no rule
 places or aligns it.
 
 The **2 to 5** range applies to the horizontal orientation, and the inline
@@ -399,9 +404,8 @@ to stay distinguishable there. Steps deliberately ships no forced-colors
 override of its own: painting the marker `Highlight` makes the number or glyph
 inside it unreadable, which is worse than the ambiguity it removes.
 
-The inline threshold is calibrated to the default `--step-min`. Container
-queries cannot read custom properties, so changing `--step-min` moves the
-scroll budget but not the threshold.
+The inline threshold reserves connector space for five named stages. Changing
+`--step-min` moves the stacked scroll budget without moving that threshold.
 
 See [Steps representations and thresholds](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/steps.md)
 for why the contract is shaped this way, and which alternatives were measured

package/docs/pages/enhancements/scrollspy.md

@@ -4,15 +4,15 @@
 
 Scrollspy is a behavior hook, not a visual component. It marks a navigation
 region for the JavaScript enhancement. Pair it with `.nav-list` and `.nav-link`,
-or style `[aria-current]` yourself.
+or style `[aria-current="location"]` yourself.
 
 ## Class reference
 
-| Class        | Kind        | Description                                                     |
-| ------------ | ----------- | --------------------------------------------------------------- |
-| `.scrollspy` | Component   | Marks the nav region for the enhancer; adds no visual styles.   |
-| `.nav-list`  | Composition | Vertical list of navigation links.                              |
-| `.nav-link`  | Component   | Navigation link whose active state comes from `[aria-current]`. |
+| Class        | Kind        | Description                                                   |
+| ------------ | ----------- | ------------------------------------------------------------- |
+| `.scrollspy` | Component   | Marks the nav region for the enhancer; adds no visual styles. |
+| `.nav-list`  | Composition | Vertical list of navigation links.                            |
+| `.nav-link`  | Component   | Navigation link, current on `aria-current="location"`.        |
 
 ## Usage