actual-css 0.12.0 → 0.14.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/navigation.json

@@ -69,6 +69,7 @@
         "pagination",
         "progress",
         "rating",
+        "segmented",
         "shimmer",
         "skeleton",
         "spinner",
@@ -91,6 +92,7 @@
         "form-actions",
         "joined-controls",
         "choice-cards",
+        "color-swatches",
         "switch",
         "range",
         "otp",

package/docs/pages/components/alert.md

@@ -12,7 +12,7 @@
 - Could have simple or complex html content.
 - A title and a description are plain siblings: the alert owns the small space between its direct content blocks, so neither needs a wrapper. Nested content keeps its own rhythm — wrap several paragraphs in `.prose`, or a differently spaced group in `.stack`, when the message needs a rhythm of its own.
 - Alerts may include a decorative leading icon. Use `.alert-icon` on the icon element; the rest of the content flows into the remaining text column.
-- Use `.compact` or `.spacious` for density changes. The inline padding stays stable.
+- Use `.compact` or `.spacious` on the alert to step its block padding. The inline padding stays stable.
 - Use a [`.close`](close.md) button to make the alert dismissible. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions; the alert makes it compact.
 
 Because alerts are soft by default, adding `.soft` to an intent (`.alert.soft.primary`,
@@ -216,7 +216,7 @@ full-bleed notice.
 
 ## Admonition
 
-An admonition is a structured box with a tinted title bar, an optional icon, and body content on the page surface — like the `!!! note` callouts in mkdocs. Use `.alert-title` for the header and `.alert-body` for the content. Intent classes tint the title bar background and the border.
+An admonition is a structured box with a tinted title bar, an optional icon, and body content on the page surface — like the `!!! note` callouts in mkdocs. Use `.alert-title` for the header and `.alert-body` for the content. Intent classes tint the title bar background and the border; shared variants paint the title bar, so `.solid` fills it — and keeps the body's frame neutral — for a notification that needs to stand out.
 
 ```html demo
 <div class="stack">
@@ -239,6 +239,16 @@ An admonition is a structured box with a tinted title bar, an optional icon, and
       <p>The intent tints the title bar, the border, and the body uses <code>var(--surface)</code>.</p>
     </div>
   </div>
+
+  <div class="alert success admonition solid">
+    <div class="alert-title">
+      <i class="ti ti-circle-check" aria-hidden="true"></i>
+      Saved
+    </div>
+    <div class="alert-body">
+      <p>A solid title bar for an action response.</p>
+    </div>
+  </div>
 </div>
 ```
 

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/button.md

@@ -153,8 +153,9 @@ Keep one variant family inside a group. Because each button keeps its own
 classes, nothing stops `.btn`, `.btn outline` and `.btn soft` from sitting side
 by side — but three fills and three border treatments in one shape read as
 unrelated controls that happen to touch, not as one unit. Change the variant
-only to carry meaning: [Toggle](#toggle) marks the active segment with a solid
-button among outlines, which is the pattern a segmented control wants.
+only to carry meaning: [Toggle](#toggle) marks a pressed button with a solid
+fill among outlines. For one choice among a few on a shared track, use a
+[segmented control](segmented.md) instead.
 
 ## Sizes
 

package/docs/pages/components/list.md

@@ -29,9 +29,12 @@ list markers when order or bullets carry meaning.
 ```
 
 Leading and trailing content are unconstrained: avatars, native choices,
-badges, text, switches, and buttons retain their own component sizing.
-`.list-item-content` has no minimum content floor, so supporting text and long
-tokens wrap instead of widening the page.
+badges, text, switches, and buttons retain their own component sizing. In a
+narrow row, the trailing region moves under the content rather than breaking a
+word of the title; supporting text still wraps beside it, and a token longer
+than the row breaks instead of widening the page. A `.truncate` line inside
+`.list-item-content` gives up its width, so it ellipsizes next to the trailing
+region (wrap, responsive row, overflow).
 
 Both outer regions are optional, and an absent one costs neither space nor a
 gap: `.list-item-content` always takes the row's free space and
@@ -39,14 +42,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 +82,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 +91,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/segmented.md

@@ -0,0 +1,83 @@
+# Segmented control
+
+> One compact choice among a few options, on a shared track with the selected segment raised.
+
+**Related terms:** segmented control, toggle group, pill tabs, view switcher, button group.
+
+`.segmented` is the track and each `.segment` a direct child. The look is
+shared; the semantics come from the markup, so pick the anatomy by what the
+choice does:
+
+| Use           | Markup                 | Selected               | Keyboard      |
+| ------------- | ---------------------- | ---------------------- | ------------- |
+| Pick a value  | `<fieldset>` of radios | `:checked`             | Native arrows |
+| Switch panels | `role="tablist"`       | `aria-selected="true"` | Tabs runtime  |
+| Navigate      | `<nav>` of links       | `aria-current="page"`  | Tab, Enter    |
+
+Segments share the width equally and the track is at least `--control-size`
+tall, so it lines up with `.btn` and `.input`; `.sm` and `.lg` size it like
+any control. A long label wraps instead of truncating, and the row grows with
+it. A parent that stretches its children (`.stack`) makes it full width; add
+`.align-self-start` to keep it at its content width.
+
+## Pick a value
+
+Wrap each radio in its label. The radio is visually hidden but stays focusable
+and submitted; in a browser without `:has()` it stays visible beside the
+label.
+
+```html demo
+<fieldset class="segmented">
+  <legend class="sr-only">Range</legend>
+  <label class="segment"><input type="radio" name="range" value="day">Day</label>
+  <label class="segment"><input type="radio" name="range" value="week" checked>Week</label>
+  <label class="segment"><input type="radio" name="range" value="month">Month</label>
+</fieldset>
+```
+
+## Switch panels
+
+A tablist with `data-enhance="tabs"` takes the [tabs](../enhancements/tabs.md)
+runtime unchanged: it reads the roles, not the classes.
+
+```html demo
+<div class="segmented" role="tablist" aria-label="View" data-enhance="tabs">
+  <button class="segment" type="button" role="tab" id="view-list-tab" aria-selected="true" aria-controls="view-list">List</button>
+  <button class="segment" type="button" role="tab" id="view-grid-tab" aria-selected="false" aria-controls="view-grid" tabindex="-1">Grid</button>
+</div>
+<section role="tabpanel" id="view-list" aria-labelledby="view-list-tab">List view</section>
+<section role="tabpanel" id="view-grid" aria-labelledby="view-grid-tab" hidden>Grid view</section>
+```
+
+## Navigate
+
+```html demo
+<nav class="segmented" aria-label="Period">
+  <a class="segment" href="#day" aria-current="page">Day</a>
+  <a class="segment" href="#week">Week</a>
+  <a class="segment" href="#month">Month</a>
+</nav>
+```
+
+## When to use something else
+
+- Several options on at once (bold, italic): `.join` of `.btn` with
+  `aria-pressed`, see [joined controls](../forms/joined-controls.md).
+- More options than fit on one row: [tabs](../enhancements/tabs.md), whose
+  strip scrolls.
+- Long or descriptive options: [choice cards](../forms/choice-cards.md) or
+  plain radios.
+
+## Hooks
+
+- `--segmented-bg` — track fill.
+- `--segmented-pad` — inset between the track and its segments, also the gap
+  between segments; the segment radius is the track radius minus it.
+- `--segmented-radius` — track corner radius.
+- `--segmented-fg` — label ink of the unselected segments; the selected one
+  takes `--text`.
+- `--segmented-selected-bg` — fill of the selected segment. Its shadow follows
+  `--shadow`, so a flat theme removes it at the theme level.
+- `--segmented-selected-border` — hairline around the selected segment. It is
+  what sets the segment apart where its fill is darker than the track; a theme
+  whose fill is lighter can fade it.