actual-css 0.10.0 → 0.11.1

package/docs/design-notes/enhancement-contract.md

@@ -57,10 +57,11 @@ than the registration root, without crossing shadow boundaries.
 
 > `data-enhance` is a generic opt-in for when HTML does not already provide an unambiguous one.
 
-- **A token** is for a root controller — a behavior that owns a subtree and manages
-  descendants (tabs, flyout, scrollspy, validation).
-- **A self-describing `data-*`** is for a leaf whose attribute is simultaneously the opt-in
-  and the configuration (`data-tooltip`, `data-mask`, `data-filter`,
+- **A token** is for a named behavior whose opt-in carries no configuration,
+  whether it owns a subtree or enhances one leaf (tabs, flyout, range,
+  scrollspy, validation).
+- **A self-describing `data-*`** is for a leaf whose attribute is simultaneously
+  the opt-in and the configuration (`data-tooltip`, `data-mask`, `data-filter`,
   `data-context-menu`).
 - **Elements that are their own opt-in** need nothing (`<dialog>`).
 
@@ -72,6 +73,13 @@ than the registration root, without crossing shadow boundaries.
 on the same root throws; `disconnect()` releases the name; re-registration
 after disconnect is allowed; the same token on a different root is independent.
 
+Named registrations share one `[data-enhance]` discovery gate per root: however
+many behaviors are registered, the observer queries that single selector and
+each registration matches its own `[data-enhance~="name"]` against what it finds.
+`enhance()` records share the same observer and lifecycle with their arbitrary
+selectors. Behaviors on one element start in no guaranteed order and must not
+depend on each other.
+
 `enhance()` stays generic and unguarded — registering the same selector twice
 creates two independent records that both run.
 
@@ -95,8 +103,8 @@ those registrations explicitly.
 
 - Use a command for an immediate trigger-to-current-target action. Commands
   resolve the DOM at event time and do not own element lifecycle.
-- Use `registerEnhancement()` for an opted-in controller that owns listeners or
-  state for a subtree.
+- Use `registerEnhancement()` for a named, opted-in behavior that owns listeners
+  or state for a subtree or leaf.
 - Use `enhance()` for a self-describing leaf behavior that needs connection and
   cleanup lifecycle without a named token.
 - Prefer delegation when no persistent per-element state is required.
@@ -145,7 +153,8 @@ of the contract itself.
 | ------------ | ------------------------------------------------ | ------------------- |
 | `tabs`       | Tab panel switching, arrow-key navigation        | `.tabs`             |
 | `flyout`     | Trigger → panel positioning, open/close          | `.flyout`           |
+| `range`      | Fill share and named-value synchronization       | `.range`            |
 | `scrollspy`  | Scroll-driven nav highlighting                   | `.scrollspy`        |
 | `validation` | Form validation, focus management, server errors | `.needs-validation` |
 
-Four tokens. Everything else stays self-describing.
+Five tokens. Everything else stays self-describing.

package/docs/design-notes/platform-alignment.md

@@ -386,12 +386,16 @@ Prefer native controls and progressive styling.
 
 The concrete signal to watch is `appearance: base-slider` with `::slider-track`, `::slider-fill`, and `::slider-thumb`. Checked on Chrome 152: `CSS.supports('appearance', 'base-slider')` and `CSS.supports('selector(::slider-fill)')` are both false, so there is nothing to enhance against yet.
 
-Until then, `.range` intentionally omits filled tracks and tick marks. Both are reachable today only through techniques Actual should not take on:
+Until then, `.range` intentionally omits tick marks, and its filled track comes
+from the `range` enhancement (one `--range-progress` share driving a
+track gradient) rather than engine-specific pseudo-elements:
 
-- The Chromium filled-track trick needs `overflow: hidden` on the runnable track plus a large `box-shadow` on the thumb. It collides twice with `range.css`: the thumb is wider than the track and would be clipped, and the focus ring already owns the thumb's `box-shadow`.
-- CSS-only tick marks need a step count duplicated out of `min`/`max`/`step` into a custom property, so markup carries the same contract twice and the two can diverge. `datalist` cannot carry it either: its native ticks are part of the appearance that `appearance: none` removes, and no engine renders `<option label>` for a range.
+- The Chromium filled-track trick needs `overflow: hidden` on the runnable track plus a large `box-shadow` on the thumb. It collides twice with `range.css`: the thumb is wider than the track and would be clipped, and the thumb's `box-shadow` is already owned by the focus ring.
+- CSS-only tick marks need a step count duplicated out of `min`/`max`/`step` into a custom property, so markup carries the same contract twice and the two can diverge. `datalist` cannot carry it either: its native ticks are part of the appearance that `appearance: none` removes, and no engine renders `<option label>` for a range — Actual reads the datalist as data only.
 
-When the base-slider parts become interoperable, this becomes a `@supports` enhancement in the shape of `custom-select.css` — less engine-specific CSS, not more.
+When the base-slider parts become interoperable, the `--range-progress`
+calculation becomes a `@supports` enhancement in the shape of
+`custom-select.css` — less engine-specific CSS, not more.
 
 ### Navigation
 

package/docs/design-notes/rich-text.md

@@ -0,0 +1,61 @@
+# Rich text: three levels and why a package demos level 2
+
+Editing text and editing a document are different problems with different
+costs. Actual draws the line at the document boundary, in three levels:
+
+```text
+1. TEXTAREA (native)
+   text, autosize, actions row, plain-text caret helpers
+   → the composer pattern: demo/templates/composer.html
+
+2. HOSTED RICH-TEXT PACKAGE (integration)
+   bold / italic / lists / links / quote, undo, paste cleanup,
+   structured @mentions, / snippets
+   → the rich-text recipe: demo/templates/rich-text.html + @lekoala/rich-text
+
+3. STRUCTURED DOCUMENT ENGINE (integration, heavier)
+   custom document nodes, annotations, collaborative state
+   → no demo; the bridge contract from level 2 applies unchanged
+```
+
+Level 1 stays a real `<textarea>`: form value, IME, undo, mobile,
+accessibility, validation. `contenteditable="plaintext-only"` buys nothing over
+it and loses the native form control, so the framework does not use it. The
+Markdown round-trip some engines offer is still beta upstream and is not the
+storage contract.
+
+## Why a package for the level-2 demo
+
+The demo exists to prove the bridge (tokens, pressed states, focus, invalid,
+composer chrome), not the engine. Owning the toolbar, sanitizer, roving focus
+and lifecycle inside the demo meant Actual did involuntarily much of the
+editor's job. Extracting that into `@lekoala/rich-text` restored the boundary:
+
+```text
+Actual CSS         presentation, tokens, composer chrome, dialogs, validation
+@lekoala/rich-text textarea enhancement, Squire, sanitization, toolbar
+                   semantics + keyboard, links, mentions, suggestions,
+                   form/reset/readonly/disabled, lifecycle
+application        people lookup, templates, attachments, dictation, send
+```
+
+`@lekoala/rich-text` owns the editor UI semantics; Actual owns its visual
+language. Squire is an implementation detail of the integration package: it
+owns selection, editing, paste normalisation and undo/redo, while the package
+owns the product-facing contract around it (progressive enhancement of a real
+`<textarea>`, mandatory sanitization, accessible generated UI, lifecycle and
+cleanup). HTML stays the source of truth, which keeps the storage decoupled
+and the engine choice reversible.
+
+## What was deliberately not demoed
+
+- A second engine demo would prove nothing more about the bridge, and one
+  candidate changes fundamental choices between minor versions — a pinned demo
+  would rot. Spikes belong in `tmp/`, not `demo/`.
+- Plain-text caret helpers stay a textarea-level improvement at level 1.
+  Structured `@mentions` live at level 2 because they are sanitized, atomic
+  entities inserted as HTML — the demo's Snippet/Mention buttons reuse the
+  same suggestion seam as `/` and `@`, so one capability keeps two surfaces
+  without duplicating its logic.
+- Syntax highlighting inside inputs is a search-DSL concern, not a composer
+  concern; layering it onto a textarea rebuilds a fake rich editor.

package/docs/design-notes/steps.md

@@ -630,8 +630,8 @@ so an author who lowers `--step-min` below `--step-size` narrows the scroll
 budget without collapsing 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 two
-border-widths wide at `--focus-outline-offset`, so 4px past a label that sits
+ring is drawn outside its element's border box — `--focus-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
 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

package/docs/navigation.json

@@ -9,7 +9,8 @@
         "modular-import",
         "progressive-enhancement",
         "bootstrap",
-        "tailwind"
+        "tailwind",
+        "design-tools"
       ]
     },
     {
@@ -67,6 +68,7 @@
         "pagination",
         "progress",
         "rating",
+        "shimmer",
         "skeleton",
         "spinner",
         "steps",
@@ -80,6 +82,7 @@
         "overview",
         "controls",
         "combobox",
+        "rich-text",
         "labels",
         "floating-field",
         "states-and-sizes",

package/docs/pages/components/aura.md

@@ -84,22 +84,22 @@ The frame color comes from an intent such as `.primary`, `.success`, or
 a neutral intent produces a neutral aura. Use a chromatic intent when you want
 a visibly luminous effect.
 
-Two hooks tune how loud the effect is. `--aura-intensity` scales both halos at
-once, resting and breathing alike, so the breath stays proportional at every
-setting; `--aura-duration` sets one full rotation of the accent, or one breath
-of the glow.
+The default is a thin lit line with a faint halo. Three hooks tune how loud it
+is: `--aura-width` sets the line, `--aura-intensity` scales both halos at once,
+resting and breathing alike, and `--aura-duration` sets one full rotation of
+the accent, or one breath of the glow.
 
 ```html demo
 <div class="cluster" style="gap: 2rem">
-  <span class="aura aura-glow primary" style="--aura-intensity: 0.4">
-    <span class="card" style="inline-size: 8rem">Muted</span>
+  <span class="aura aura-glow primary" style="--aura-intensity: 0">
+    <span class="card" style="inline-size: 8rem">Line only</span>
   </span>
 
   <span class="aura aura-glow primary">
     <span class="card" style="inline-size: 8rem">Default</span>
   </span>
 
-  <span class="aura aura-glow primary" style="--aura-intensity: 2">
+  <span class="aura aura-glow primary" style="--aura-width: 3px; --aura-intensity: 1">
     <span class="card" style="inline-size: 8rem">Loud</span>
   </span>
 
@@ -113,11 +113,10 @@ Keep exactly one direct child and set `--aura-radius` when its shape differs
 from the common button, card, alert, and badge shapes detected as a visual
 enhancement.
 
-The child must be opaque. The frame paints across the whole box and relies on
-the child to cover all but its edge, so a transparent child — an `.outline`
-alert, a `.ghost` button — is filled edge to edge with the frame color instead
-of framed by it. Give such a child a surface, or move the aura to an opaque
-wrapper around it.
+A transparent or translucent child — an `.outline` alert, a `.ghost` button, a
+glass surface — shows `--surface-opaque` beneath it, the theme's opaque
+neutral, rather than the frame color. On a differently painted band, give the
+child its own surface so it matches the band.
 
 ## CSS hooks
 
@@ -125,7 +124,7 @@ wrapper around it.
 - `--aura-width` — frame thickness.
 - `--aura-blur` — near halo blur; the far halo derives its own blur and its
   spread beyond the frame from this value, so one hook scales both.
-- `--aura-intensity` — multiplies both halo opacities, resting and breathing.
+- `--aura-intensity` — multiplies both halo strengths, resting and breathing.
   It does not touch the frame itself, which stays a crisp line at any setting.
 - `--aura-radius` — child corner radius used to derive the outer radius.
 - `--aura-duration` — one rotation of the accent, or one breath of the glow.

package/docs/pages/components/badge.md

@@ -2,6 +2,12 @@
 
 > Compact label for counts, status, or category tags, with shared intents and variants.
 
+A badge is **information, never a control**: counts, status, categories. It is
+non-interactive by nature — for a selectable option use
+[`.choice-card.chip`](../forms/choice-cards.md#chips); for a value produced by
+a widget that can be removed (combobox multi-value), the widget owns the
+removable tag (see [combobox](../forms/combobox.md)).
+
 - Supports intent colors.
 - Soft by default. Use `.solid` for counters and notification badges, or `.outline` for quieter emphasis.
 - Empty badges are solid status dots: visual variants such as `.soft` and `.outline` do not change their fill.
@@ -180,6 +186,10 @@ Override the existing hooks when the three-step scale does not fit the content.
 Use `.badge soft` for tag visuals. Add a direct [`.close`](close.md) button only when the tag can actually be removed. There is no separate chip component.
 For a compact action or filter, use `.btn.sm` instead; badges describe content
 and must not be turned into toggle controls merely to obtain a compact shape.
+Never put a `.close` inside a `.choice-card.chip` label: the label is already
+an interactive target driving its checkbox/radio, and a nested button would mix
+two interactive targets. A removable tag next to a selectable chip is a sibling
+(a widget tag or a `.badge` + `.close`), never a child of the label.
 
 Inside a badge the close follows the pill's size, keeps a 24px pointer target,
 and tucks into the padding.

package/docs/pages/components/bleed.md

@@ -3,10 +3,11 @@
 `.bleed` lets a direct child of a padded surface reach its edges. Use it for a
 full-width image, a colored header or footer, or a notice band.
 
-It works inside `.card`, `.drawer`, and an accordion panel. The accordion panel
-owns the padding, so place `.bleed` directly inside the panel, after the summary.
-A deeper descendant stays within its wrapper. A modular build imports
-`actual-css/css/components/bleed` alongside the surface component.
+It works inside `.card`, `.drawer`, a modal's direct `<form>` or `.stack`, and
+an accordion panel. The accordion panel owns the padding, so place `.bleed`
+directly inside the panel, after the summary. A deeper descendant stays within
+its wrapper. A modular build imports `actual-css/css/components/bleed`
+alongside the surface component.
 
 ```html demo
 <article class="card stack" style="--card-max-inline-size: 24rem">

package/docs/pages/components/button.md

@@ -89,7 +89,7 @@ every variant keeps working — `.outline` and `.ghost` take the solid ink:
 ```css
 .btn.app-dark {
   --intent: var(--surface-solid);
-  --intent-fg: var(--surface);
+  --intent-fg: var(--surface-solid-fg);
 }
 ```
 

package/docs/pages/components/chat.md

@@ -34,6 +34,11 @@ For a live conversation, put an appropriate live-region or `role="log"` on the
 conversation container according to the product's announcement needs. Do not
 put `role="log"` on individual messages.
 
+For the message input itself, keep a native `<textarea>` inside a surface with
+an actions row — see the [composer template](../../demo/templates/composer.html).
+Formatting needs a hosted editor instead — see the
+[rich-text template](../../demo/templates/rich-text.html).
+
 ## Class reference
 
 | Class                           | Description                                  |

package/docs/pages/components/close.md

@@ -28,7 +28,9 @@
 In a `.modal` or a `.drawer`, the close sits out of the content flow at the
 panel's top inline-end corner. Place it as a direct child of the dialog, of its
 top-level `form` or `header`, or of a `form` inside that header; a `.close`
-deeper in the content keeps its own place. See [Dialog](dialog.md) and
+deeper in the content keeps its own place, so wrapping it in a `.cluster` keeps
+it in the header's row. A header that hosts the corner close reserves inline
+room so a title never runs under it. See [Dialog](dialog.md) and
 [Drawer](drawer.md).
 
 ```html
@@ -43,6 +45,10 @@ deeper in the content keeps its own place. See [Dialog](dialog.md) and
 
 - `--close-size` — inline and block size of the button; `--control-size` unless the container sets it.
 - `--close-icon-size` — size of the X.
+- `--close-bg` — background of the dialog corner close; `--surface-subtle` unless the dialog or a painted band sets it, e.g. `transparent` for a bare X.
+- `--close-color` — ink of the X; `--text-muted` at the dialog corner, otherwise inherited from the context.
+- `--close-hover-color` — ink of the dialog corner close on hover; `--text` unless a band sets its own foreground.
+- `--close-hover-overlay` — hover and active wash that tints the fill the context gave the control; the dialog corner sets it `transparent` so a hover changes only the ink.
 
-Alerts and badges declare both hooks on themselves, so set them on the container
-or on the button.
+Alerts and badges declare both size hooks on themselves, so set them on the
+container or on the button.

package/docs/pages/components/dialog.md

@@ -14,15 +14,44 @@
 | `.dialog-icon`         | Component   | Circular intent-aware icon well.               |
 | `.close`               | Composition | Icon-only close button, at the top end.        |
 
-A [`.close`](close.md) placed as a direct child of the dialog or of its form
-sits outside the content flow, so it does not take part in the dialog's own
-layout.
+## Anatomy
+
+`.modal` is the outer surface and deliberately has no inner padding. Wrap its
+content in a direct `<form>` or `.stack`; that wrapper owns the padding, rhythm,
+and overflow. Put `.stack` on the wrapper, never on `dialog.modal` itself.
+
+For a header band, place `<header>` directly under `dialog.modal`, before the
+body wrapper. Put a flexible `.media` title region first and a `.cluster` of
+controls second. The title has the close control's minimum height; its leading
+icon and every trailing control share the same center axis. A wrapped title
+simply makes the row taller.
+
+A direct `dialog > header` is dialog chrome and forms a distinct header band.
+Put an ordinary content heading inside the padded `form` or `.stack` instead.
+
+Keep a corner [`.close`](close.md) as a direct child of the dialog and put the
+title in the wrapper's direct `<header>`. The button then stays outside the
+content flow while the header reserves enough inline space to keep its title
+clear.
+
+A `.close` placed as a direct child of the chrome header is still the corner
+overlay. That header reserves the same inline room for it, never below its own
+`--modal-pad`, so a wrapping title stays clear either way.
+
+The corner close overlays the panel edge, so a body tall enough to scroll would
+run its scrollbar under the button. Give such a dialog the `scrollable` anatomy:
+the close then sits over the fixed header and the scrollbar starts below it.
+
+Add `.bleed` to that header when it should form a full-width band. It reaches
+the dialog edges, keeps the modal's inner padding, and can take a surface token
+such as `background: var(--surface-subtle)`.
 
 ## Usage
 
 Modals use the platform-native `<dialog class="modal">` element with `commandfor` and `command` buttons.
 
-Use `command="show-modal"` to open a modal dialog.
+Use `command="show-modal"` to open a modal dialog, or `command="--show"` to open
+it non-modally.
 
 Add `aria-haspopup="dialog"` and `aria-controls="<id>"` to opening buttons so
 their semantics are present before either native or framework JavaScript runs.
@@ -84,7 +113,8 @@ For a compact destructive confirmation with a leading status icon, compose
 `dialog-confirmation` with the media object. The icon well accepts the shared
 intent and emphasis classes; `dialog-icon danger soft` creates the tinted red
 circle while keeping the glyph centered. The footer becomes a separate action
-band without changing the semantics of the form or its buttons.
+band whose two actions sit at its edges, so the cancel-style control never sits
+next to the committing one.
 
 ```html demo
 <button class="btn danger"
@@ -120,6 +150,49 @@ band without changing the semantics of the form or its buttons.
 </dialog>
 ```
 
+For a trailing illustration, use a direct `<header>` as the message region and
+compose it as a non-wrapping split cluster. `.grow` keeps the text column
+flexible while `.dialog-icon` stays at the inline end. The confirmation variant
+pads either this header or the leading-icon `.media` shape above.
+
+Use the same anatomy in a `.card` instead when the surface belongs in page
+content and does not need modal focus or a backdrop.
+
+```html demo
+<button class="btn"
+        type="button"
+        commandfor="customize-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="customize-dialog">
+  Customize workspace
+</button>
+
+<dialog class="modal dialog-confirmation"
+        id="customize-dialog"
+        closedby="none"
+        aria-labelledby="customize-dialog-title">
+  <form method="dialog">
+    <header class="cluster"
+            style="--cluster-align: start; --cluster-justify: space-between; --cluster-wrap: nowrap">
+      <hgroup class="grow">
+        <h3 id="customize-dialog-title">Make this workspace your own</h3>
+        <p class="muted">Choose colors and defaults now, or continue with the current settings.</p>
+      </hgroup>
+
+      <span class="dialog-icon success soft" aria-hidden="true">
+        <i class="ti ti-check"></i>
+      </span>
+    </header>
+
+    <footer>
+      <button class="btn primary" value="customize">Customize</button>
+      <button class="btn ghost" value="later">Later</button>
+    </footer>
+  </form>
+</dialog>
+```
+
 ## Information modal
 
 Use this shape for contextual information or lightweight secondary content. It
@@ -162,6 +235,67 @@ has no action button; the header close button dismisses the dialog.
 </dialog>
 ```
 
+## Action modal
+
+Use this shape when contextual information leads to one non-destructive next
+step, such as reviewing a setup before continuing. Unlike an alert dialog, it
+can be dismissed without choosing the action; unlike an information modal, it
+has a primary action in a footer.
+
+Use `.dialog-icon` with the media object for a leading title icon. An `.alert`
+belongs in the body only when the dialog contains a distinct status message;
+the dialog title itself is not an alert.
+
+```html demo
+<button class="btn primary"
+        type="button"
+        commandfor="setup-dialog"
+        command="show-modal"
+        aria-haspopup="dialog"
+        aria-controls="setup-dialog">
+  Continue setup
+</button>
+
+<dialog class="modal"
+        id="setup-dialog"
+        closedby="any"
+        data-dialog-dismissible
+        aria-labelledby="setup-dialog-title">
+  <header>
+    <div class="media items-center grow">
+      <span class="dialog-icon warning soft" aria-hidden="true">
+        <i class="ti ti-alert-triangle"></i>
+      </span>
+
+      <h2 id="setup-dialog-title">Finish workspace setup</h2>
+    </div>
+
+    <div class="cluster">
+      <button class="close"
+              type="button"
+              commandfor="setup-dialog"
+              command="request-close"
+              aria-controls="setup-dialog"
+              aria-label="Close dialog"></button>
+    </div>
+  </header>
+
+  <form method="dialog" class="stack">
+    <div class="card stack">
+      <p><strong>Acme workspace</strong></p>
+      <p>Team plan</p>
+      <p>Starts October 1</p>
+    </div>
+
+    <p>Confirm these settings to finish setting up the workspace.</p>
+
+    <footer>
+      <button class="btn primary inline-size-full" value="continue">Continue</button>
+    </footer>
+  </form>
+</dialog>
+```
+
 ## Scrollable modal
 
 Use `modal scrollable` when the header and footer should stay visible while the
@@ -297,7 +431,9 @@ Available options:
   light dismiss and closes the dialog (or rewrites `closedby="any"` to
   `closedby="closerequest"` so the native dialog does not double-handle).
   It never affects Escape or explicit close requests.
-* `data-dialog-modal="false"` opens with `show()` instead of `showModal()`.
+* `data-dialog-modal="false"` makes direct `openDialog()` calls use `show()`
+  instead of `showModal()`. The `show-modal` and `--show` commands override
+  this default.
 * `data-dialog-view-transition` enables a view transition that morphs the dialog to/from its trigger. Only active when the browser supports `document.startViewTransition` and the user allows motion.
 * `closedby` keeps its native meaning: `"any"` closes on backdrop click and
   Escape, `"closerequest"` closes on Escape only, `"none"` disables both. The
@@ -368,20 +504,16 @@ Prefer native dialog behavior whenever possible. The framework runtime should
 not replace the platform modal system; it should only make dialogs declarative,
 animation-friendly, and consistent across supported browsers.
 
-The close button is anchored to the dialog surface, not the content flow: it
-sits at the top `inline-end`, inside the panel. The button itself is out of
-flow, while the header reserves enough inline padding to keep its title clear.
-Keep the button a direct child of `dialog.modal` so the scrolling content
-(`> form` or `> .stack`) never competes with it.
-
 ## CSS hooks
 
 - `--modal-size` — maximum dialog width. Fallback-only, so a class on the
   dialog or an inherited value both reach it. A dialog is shrink-to-fit: a
   composition that must fill this width sets `inline-size` as well.
+- `--modal-pad` — padding of the direct `<form>` or `.stack` content wrapper.
+- `--modal-header-bg` — background of a direct header band.
 - `--dialog-viewport-gap` — distance kept between the dialog and the viewport edges.
 - `--dialog-icon-size` — diameter of the `.dialog-icon` circle.
 - `--dialog-icon-glyph-size` — size of the glyph centered inside `.dialog-icon`.
 - `--close-size` / `--close-icon-size` — size of the corner `.close` and of its
-  X. The header reserves the close size plus `--space-30` on its inline end so
+  X. The header reserves the close size, its edge inset, and a content gap so
   the title never runs under it.

package/docs/pages/components/meter.md

@@ -70,6 +70,8 @@ marker to that background rather than to the neutral intent.
 
 ### Hooks
 
+- `--meter-track` — track color; raise it when the meter sits on a
+  `--surface-subtle` card, where the default track would disappear.
 - `--bar-height` — bar thickness, shared with `.progress`.
 - `--meter-value` — relative weight of a direct child in a segmented meter.
 

package/docs/pages/components/pagination.md

@@ -7,8 +7,8 @@
 - Use `aria-current="page"` for the current page.
 - Put `.sm` or `.lg` on `.pagination` to scale its controls.
 - Numeric links may use `aria-label="Page N"` for clearer screen reader output.
-- Prefer text labels for Previous and Next. Icon-only controls need an accessible name.
-- Page links can compose with `.btn` for button-like hit targets.
+- Prefer text labels for Previous and Next; a chevron icon may accompany them. Icon-only controls need an accessible name.
+- Compose page links with `.btn.ghost`; `aria-current="page"` fills the current one, so it is the only boxed item.
 - Arrows, page numbers, and truncation ellipses share one geometric system: every item gets the same minimum footprint, and wider content (100, 1000, text labels) grows past it naturally.
 - Truncated ranges are plain text with `.muted` and `aria-hidden="true"`, not `.btn` — they are decorative, not actionable.
 
@@ -24,12 +24,12 @@
 ```html demo
 <nav aria-label="Pagination">
   <ol class="pagination sm">
-    <li><a href="?page=2" class="btn outline" rel="prev">Previous</a></li>
-    <li><a href="?page=1" class="btn outline" aria-label="Page 1">1</a></li>
-    <li><a href="?page=2" class="btn outline" aria-label="Page 2">2</a></li>
-    <li><a href="?page=3" class="btn" aria-current="page" aria-label="Page 3">3</a></li>
-    <li><a href="?page=4" class="btn outline" aria-label="Page 4">4</a></li>
-    <li><a href="?page=5" class="btn outline" rel="next">Next</a></li>
+    <li><a href="?page=2" class="btn ghost" rel="prev"><i class="ti ti-chevron-left" aria-hidden="true"></i> Previous</a></li>
+    <li><a href="?page=1" class="btn ghost" aria-label="Page 1">1</a></li>
+    <li><a href="?page=2" class="btn ghost" aria-label="Page 2">2</a></li>
+    <li><a href="?page=3" class="btn ghost" aria-current="page" aria-label="Page 3">3</a></li>
+    <li><a href="?page=4" class="btn ghost" aria-label="Page 4">4</a></li>
+    <li><a href="?page=5" class="btn ghost" rel="next">Next <i class="ti ti-chevron-right" aria-hidden="true"></i></a></li>
   </ol>
 </nav>
 ```
@@ -42,15 +42,15 @@ buttons — they are decorative, not actionable.
 ```html demo
 <nav aria-label="Pagination">
   <ol class="pagination sm">
-    <li><a href="?page=1" class="btn outline" rel="prev">Previous</a></li>
-    <li><a href="?page=1" class="btn outline" aria-label="Page 1">1</a></li>
+    <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=1" class="btn ghost" aria-label="Page 1">1</a></li>
     <li><span class="muted" aria-hidden="true">…</span></li>
-    <li><a href="?page=7" class="btn outline" aria-label="Page 7">7</a></li>
-    <li><a href="?page=8" class="btn" aria-current="page" aria-label="Page 8">8</a></li>
-    <li><a href="?page=9" class="btn outline" aria-label="Page 9">9</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><span class="muted" aria-hidden="true">…</span></li>
-    <li><a href="?page=20" class="btn outline" aria-label="Page 20">20</a></li>
-    <li><a href="?page=9" class="btn outline" rel="next">Next</a></li>
+    <li><a href="?page=20" class="btn ghost" aria-label="Page 20">20</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>
 ```