actual-css 0.5.0 → 0.7.0

package/docs/design-notes/surface-reparenting.md

@@ -0,0 +1,122 @@
+# Surface reparenting breaks inherited presentation context
+
+Known defect, present on the current Minimal floor. Tracked separately from
+Popover adoption on purpose: Popover is the likely cure, but the defect exists
+now and needs to be understood on its own terms.
+
+## What happens
+
+`surface.js` moves an open surface out of its place in the document:
+
+```text
+getSurfaceRoot()   → nearest <dialog>, else body
+mountSurface()     → root.append(panel)
+restoreSurface()   → put it back once the exit transition ends
+```
+
+The move exists for good reasons — it escapes `overflow` clipping on any
+ancestor and sidesteps `z-index` stacking. But it also takes the panel out of
+every scope that reached it *by inheritance*. The panel is styled by one set of
+ancestors while it is closed, and by a different set from the moment it becomes
+visible.
+
+Actual leans on inheritance deliberately: theme islands, density, `.inverted`,
+and the custom properties an application scopes to its own containers all
+travel that way. So this is not one bug about themes. It is the same bug in as
+many forms as there are inherited contexts.
+
+## Measured
+
+Chrome, one `.flyout` per scope, values read off the panel before and after the
+click that opens it:
+
+| Scope                     | Closed                                   | Open                 |
+| ------------------------- | ---------------------------------------- | -------------------- |
+| `[data-theme="dark"]`     | `background: rgb(30, 26, 35)`            | `rgb(255, 255, 255)` |
+| `.sm`                     | `--control-size: 2rem`                   | `2.375rem`           |
+| `.inverted`               | `--ui-fg: light-dark(hsl(0 0% 100%), …)` | *(unset)*            |
+| app-scoped `--app-accent` | `rgb(1, 2, 3)`                           | *(unset)*            |
+| `.sm` inside a `<dialog>` | `--control-size: 2rem`                   | `2.375rem`           |
+
+Every context breaks. Three consequences are worth stating plainly:
+
+- The theme case is visible, not theoretical: a flyout inside a dark island
+  turns light at the moment it opens.
+- The density case is measurable: menu rows render 38px instead of the 32px the
+  scope asked for.
+- The dialog case shows the `getSurfaceRoot()` special case does not help. The
+  panel does land inside the dialog, and still loses any scope sitting between
+  that dialog and its trigger. Choosing a nearer root loses less context; it
+  does not preserve it.
+
+Locked by `tests/browser/surface-inherited-context.test.js`, whose assertions
+describe the contract Actual owes and are marked `test.failing` until the
+transport stops reparenting.
+
+## Why the obvious repairs are wrong
+
+**Copying `data-theme` onto the moved panel.** Fixes the one symptom that was
+noticed and leaves the other four broken. It also turns an inherited contract
+into an enumerated one, so every future scope has to be added to a list.
+
+**Snapshotting custom properties before the move.** There is no bounded set to
+snapshot — an application's own hooks are unknowable by definition, and
+`getComputedStyle` cannot enumerate inherited custom properties portably. It
+would also freeze values that should stay live.
+
+**Mounting to a nearer root.** The dialog row above is the experiment: it
+reduces the damage without addressing the cause.
+
+The cause is that the panel is moved at all. The repair is a transport that
+promotes the element without relocating it.
+
+## The actual repair
+
+A native popover renders in the top layer while staying exactly where the
+author put it in the DOM. That removes the reason to reparent, and with it the
+whole mechanism:
+
+```text
+mountedSurfaces
+getSurfaceRoot()
+mountSurface()
+restoreSurface()
+```
+
+`popover="manual"` is the mode that fits: it supplies the top layer and nothing
+else, so `surface.js` keeps its dismissal policy, Escape ordering, focus
+restoration and placement orchestration unchanged. See
+[platform-alignment](platform-alignment.md) for the responsibility split and
+the criteria a component must meet before adopting Popover, and
+[browser-support](browser-support.md) for which tier guarantees it.
+
+That change is gated on Popover being available across Minimal. It is not
+available there today, and adopting it behind a capability branch would keep
+the reparenting code alive for the fallback path — so the defect would remain
+for exactly the browsers the branch was written to serve.
+
+## Until then
+
+The honest interim position is a documented limitation, not a patch:
+
+> A surface managed by `surface.js` is presented in the document's own context,
+> not its trigger's. Do not rely on a scoped theme, density, or custom property
+> reaching an anchored surface through inheritance.
+
+Applications that need a scoped surface today have two workarounds, both of
+which put the scope where the panel lands rather than where it starts: declare
+the scope on an ancestor that survives the move (`body`, or the dialog), or
+carry the scope on the panel element itself.
+
+## Experiment
+
+A branch has demonstrated the repair without changing any other contract:
+[popover-manual-poc](popover-manual-poc.md) records what it measured, what it
+refuted, and the checklist for the release that adopts it. Read that before
+attempting this again — it also holds the negative results.
+
+## Review trigger
+
+Revisit when Popover is guaranteed across Minimal, when a further inherited
+context is found to break, or if a transport that preserves DOM ancestry
+becomes available by another route.

package/docs/design-notes/widget-primitives.md

@@ -4,21 +4,38 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 
 ## Primitives
 
-| Need | Primitive | Import |
-|------|-----------|--------|
-| Opt-in discovery + lifecycle + cleanup | `enhance`, `registerEnhancement` | `actual-css/js/enhance` |
-| Per-document LIFO Escape dismissal | `escape` (`registerEscapeDismissal`) | `actual-css/js/escape` |
-| Positioning, flip/shift, `--available-height`, `data-placement` | `floating` (`track`, `reposition`, `repositionAt`) | `actual-css/js/floating` |
-| Open/close, sheet on mobile, backdrop, outside-click, Escape, focus restore | `surface` | `actual-css/js/surface` |
-| Directional item lookup, edges, wrapping, RTL | `keys` (`itemForKey`, `firstItem`, `lastItem`, `nextItem`) | `actual-css/js/keys` |
-| Menu-item vocabulary, usable-item filtering | `menu` | `actual-css/js/menu` |
-| Focusable lookup, visibility | `focus` | `actual-css/js/focus` |
-| One remembered tab stop with directional navigation | `focus-group` (`connectFocusGroup`) | `actual-css/js/focus-group` |
-| Caret-safe value rewriting | `input` (`onTextInput`, `setCaret`, `dispatchInput`) | `actual-css/js/input` |
-| Character policies | `filter` | `actual-css/js/filter` |
-| Event namespace | `events` (`EVENTS`, `ACTUAL_EVENT_PREFIX`) | `actual-css/js/events` |
-| Declarative triggers | `command` (`registerCommands`) | `actual-css/js/command` |
-| State classes the runtime writes | `selectors` (`CLASSES`) | `actual-css/js/selectors` |
+| Need                               | Primitive     | Import                      |
+| ---------------------------------- | ------------- | --------------------------- |
+| Discovery, lifecycle, cleanup      | `enhance`     | `actual-css/js/enhance`     |
+| Per-document LIFO Escape dismissal | `escape`      | `actual-css/js/escape`      |
+| Positioning, flip and shift        | `floating`    | `@lekoala/floating`         |
+| Open/close, sheet, backdrop, focus | `surface`     | `actual-css/js/surface`     |
+| Directional item lookup            | `keys`        | `actual-css/js/keys`        |
+| Menu-item vocabulary               | `menu`        | `actual-css/js/menu`        |
+| Focusable lookup, visibility       | `focus`       | `actual-css/js/focus`       |
+| One remembered tab stop            | `focus-group` | `actual-css/js/focus-group` |
+| Caret-safe value rewriting         | `input`       | `actual-css/js/input`       |
+| Character policies                 | `filter`      | `actual-css/js/filter`      |
+| Event namespace                    | `events`      | `actual-css/js/events`      |
+| Declarative triggers               | `command`     | `actual-css/js/command`     |
+| State classes the runtime writes   | `selectors`   | `actual-css/js/selectors`   |
+
+The named exports each module carries:
+
+- `enhance` — `enhance`, `registerEnhancement`
+- `escape` — `registerEscapeDismissal`
+- `floating` — `autoUpdate`, `reposition`, `repositionAt`, plus
+  `--available-height` and `data-placement`
+- `keys` — `itemForKey`, `firstItem`, `lastItem`, `nextItem`, with edge,
+  wrapping and RTL handling
+- `focus-group` — `connectFocusGroup`
+- `input` — `onTextInput`, `setCaret`, `dispatchInput`
+- `events` — `EVENTS`, `ACTUAL_EVENT_PREFIX`
+- `command` — `registerCommands`
+- `selectors` — `CLASSES`
+
+`surface` also owns outside-click and Escape dismissal, and focus restore.
+`menu` filters to usable items.
 
 ## Focus group
 

package/docs/navigation.json

@@ -77,6 +77,7 @@
       "pages": [
         "overview",
         "controls",
+        "combobox",
         "labels",
         "floating-field",
         "states-and-sizes",

package/docs/pages/components/alert.md

@@ -21,13 +21,16 @@ itself needs to change, not `.soft`.
 
 ## Class reference
 
-| Class            | Kind        | Description                                                                       |
-|------------------|-------------|-----------------------------------------------------------------------------------|
-| `.alert`         | Component   | Inline status surface; soft by default.                                           |
-| `.alert-icon`    | Composition | Decorative leading icon; pins to the first grid column.                           |
-| `.alert-dismiss` | Modifier    | Compact dismiss button using the `--icon-close` mask and the `--dismiss` command. |
-| `.callout`       | Variant     | Neutral panel with a thick accent border on the leading edge.                     |
-| `.admonition`    | Variant     | Structured box with a tinted title bar and body on the page surface.              |
+| Class            | Kind        | Description                                   |
+| ---------------- | ----------- | --------------------------------------------- |
+| `.alert`         | Component   | Inline status surface; soft by default.       |
+| `.alert-icon`    | Composition | Decorative leading icon, in the first column. |
+| `.alert-dismiss` | Modifier    | Compact dismiss button.                       |
+| `.callout`       | Variant     | Neutral panel, thick accent leading edge.     |
+| `.admonition`    | Variant     | Tinted title bar, body on the page surface.   |
+
+`.alert-dismiss` draws itself with the `--icon-close` mask and acts through the
+`--dismiss` command.
 | `.alert-title`   | Composition | Admonition title bar; hosts the dismiss button.                                   |
 | `.alert-body`    | Composition | Admonition body resting on the page surface.                                      |
 | Shared intents   | Intent      | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`.                      |
@@ -117,10 +120,12 @@ Use `.alert-dismiss` to let a user remove an inline alert. The button is transpa
 ```html demo
 <div class="alert warning" id="warning-alert">
   <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
-  <div>
+
+  <div class="stack" style="--gap: var(--space-10)">
     <strong>Warning</strong>
     <p>Something needs your attention.</p>
   </div>
+
   <button
     class="alert-dismiss"
     type="button"

package/docs/pages/components/aura.md

@@ -5,6 +5,32 @@
 Aura adds a decorative intent-colored border and halo around one direct child.
 It is visual emphasis only and does not change the child's semantics.
 
+```html demo
+<div class="cluster" style="gap: 2.5rem">
+  <span class="aura primary">
+    <article class="card" style="inline-size: 13rem">
+      <p><strong>Rotating arc</strong></p>
+      <p class="muted">One lit segment travels around the frame.</p>
+    </article>
+  </span>
+
+  <span class="aura aura-glow primary">
+    <article class="card" style="inline-size: 13rem">
+      <p><strong>Breathing glow</strong></p>
+      <p class="muted">The whole perimeter lights and breathes.</p>
+    </article>
+  </span>
+</div>
+```
+
+`.aura` sends a short accent of light travelling around the frame, over a
+permanent halo that keeps the object present between two passes. Add
+`.aura-glow` to light the whole perimeter evenly instead, as a halo that
+breathes slowly.
+
+Aura reads best when it has enough perimeter to travel around, and is naturally
+more pronounced on dark surfaces. It still composes on small shapes:
+
 ```html demo
 <div class="cluster">
   <span class="aura primary">
@@ -14,22 +40,92 @@ It is visual emphasis only and does not change the child's semantics.
   <span class="aura aura-glow secondary">
     <span class="badge">New</span>
   </span>
+
+  <span class="aura aura-glow success">
+    <span class="badge success soft">Live</span>
+  </span>
+
+  <span class="aura danger">
+    <span class="badge danger solid" aria-label="12 unread notifications">12</span>
+  </span>
+</div>
+```
+
+Note the intent on the wrapper, not on the child: `.aura` is an intent
+boundary, so the badge or alert inside keeps its own color and the frame keeps
+the one you gave the wrapper. Matching them reads as one object; deliberately
+mismatching them reads as two.
+
+```html demo
+<div class="stack" style="max-inline-size: 28rem">
+  <span class="aura warning">
+    <div class="alert warning" role="alert">
+      <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
+      <div>Your trial ends in three days.</div>
+    </div>
+  </span>
+
+  <span class="aura aura-glow danger">
+    <div class="alert danger" role="alert">
+      <i class="ti ti-credit-card-off alert-icon" aria-hidden="true"></i>
+      <div>Two payment methods failed. <a href="#">Review them</a>.</div>
+    </div>
+  </span>
 </div>
 ```
 
-The animated conic frame runs only when the user has not requested reduced
-motion. Add `.aura-glow` for a static, solid frame. The component uses an
-intent such as `.primary`, `.success`, or `.danger`; it does not introduce
-separate aura color variants.
+Motion changes how the light lives, never whether the effect is there: when the
+user has requested reduced motion, the travelling accent becomes two opposite
+lit corners — a deliberate composition rather than a rotation frozen at an
+arbitrary angle — and the glow stays a full, still halo.
+
+The frame color comes from an intent such as `.primary`, `.success`, or
+`.danger`; there are no separate aura color variants. The intent is sovereign:
+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.
+
+```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>
+
+  <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="card" style="inline-size: 8rem">Loud</span>
+  </span>
+
+  <span class="aura primary" style="--aura-duration: 2s">
+    <span class="card" style="inline-size: 8rem">Fast accent</span>
+  </span>
+</div>
+```
 
 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.
+
 ## CSS hooks
 
 - `--aura-color` — frame and halo color; follows the local intent.
 - `--aura-width` — frame thickness.
-- `--aura-blur` — halo blur radius.
+- `--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.
+  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` — rotation duration when motion is allowed.
+- `--aura-duration` — one rotation of the accent, or one breath of the glow.

package/docs/pages/components/avatar.md

@@ -12,12 +12,15 @@
 
 ## Class reference
 
-| Class                             | Kind        | Description                                                             |
-|-----------------------------------|-------------|-------------------------------------------------------------------------|
-| `.avatar`                         | Component   | Initials or image in a circular box; works on `div`, `a`, and `button`. |
-| `.avatar-stack`                   | Composition | Overlapping avatar group.                                               |
-| `.badge:empty` (inside `.avatar`) | Composition | Status dot at the bottom-end corner; give it an `aria-label`.           |
-| `.sm` / `.lg`                     | Size        | Density; also rescales the whole `.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        | Density; also rescales `.avatar-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.
 
 ## Basic usage
 

package/docs/pages/components/badge.md

@@ -20,13 +20,17 @@ full-width badge is intentional.
 
 ## Class reference
 
-| Class           | Kind        | Description                                                  |
-|-----------------|-------------|--------------------------------------------------------------|
-| `.badge`        | Component   | Compact label; soft by default.                              |
-| `.badge:empty`  | Composition | Truly-empty badge renders as a solid dot.                    |
-| Shared intents  | Intent      | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
-| Shared variants | Variant     | `.solid` (filled), `.outline` (bordered), `.surface` (untinted) emphasis. |
-| `.sm` / `.lg`   | Size        | Compact density.                                             |
+| Class           | Kind        | Description                               |
+| --------------- | ----------- | ----------------------------------------- |
+| `.badge`        | Component   | Compact label; soft by default.           |
+| `.badge:empty`  | Composition | Truly-empty badge renders as a solid dot. |
+| Shared intents  | Intent      | `.primary`, `.secondary`, `.success`, …   |
+| Shared variants | Variant     | `.solid`, `.outline`, `.surface`.         |
+| `.sm` / `.lg`   | Size        | Compact density.                          |
+
+The shared intents are `.primary`, `.secondary`, `.success`, `.warning` and
+`.danger`. The variants set emphasis: `.solid` is filled, `.outline` bordered,
+`.surface` untinted.
 
 ## Basic usage
 

package/docs/pages/components/button.md

@@ -4,23 +4,23 @@ Actions and navigation with shared intents, variants, sizes, and loading, presse
 
 ## Class reference
 
-| Class         | Kind      | Description                                                                                |
-|---------------|-----------|--------------------------------------------------------------------------------------------|
-| `.btn`        | Component | Base button. Solid by default; works on `<button>`, `<a href>`, and button-like `<input>`. |
-| `.primary`    | Intent    | Primary action.                                                                            |
-| `.secondary`  | Intent    | Secondary action.                                                                          |
-| `.success`    | Intent    | Positive outcome.                                                                          |
-| `.warning`    | Intent    | Caution.                                                                                   |
-| `.danger`     | Intent    | Destructive action.                                                                        |
-| `.neutral`    | Intent    | Neutral tone (the `.btn` default).                                                         |
-| `.soft`       | Variant   | Muted intent-tinted surface.                                                               |
-| `.outline`    | Variant   | Transparent with an intent-colored border.                                                 |
-| `.solid`      | Variant   | Filled intent background — the `.btn` default.                                             |
-| `.surface`    | Variant   | Page surface with a neutral border; the intent colors the label only.                      |
-| `.ghost`      | Variant   | Borderless text button (button-only).                                                      |
-| `.link`       | Variant   | Underlined text button (button-only).                                                      |
-| `.sm` / `.lg` | Size      | Compact or large control height.                                                           |
-| `.icon-only`  | Variant   | Square icon button sized to the control height.                                            |
+| Class         | Kind      | Description                                        |
+| ------------- | --------- | -------------------------------------------------- |
+| `.btn`        | Component | Base button, solid by default.                     |
+| `.primary`    | Intent    | Primary action.                                    |
+| `.secondary`  | Intent    | Secondary action.                                  |
+| `.success`    | Intent    | Positive outcome.                                  |
+| `.warning`    | Intent    | Caution.                                           |
+| `.danger`     | Intent    | Destructive action.                                |
+| `.neutral`    | Intent    | Neutral tone (the `.btn` default).                 |
+| `.soft`       | Variant   | Muted intent-tinted surface.                       |
+| `.outline`    | Variant   | Transparent with an intent-colored border.         |
+| `.solid`      | Variant   | Filled intent background — the `.btn` default.     |
+| `.surface`    | Variant   | Page surface, neutral border, intent on the label. |
+| `.ghost`      | Variant   | Borderless text button (button-only).              |
+| `.link`       | Variant   | Underlined text button (button-only).              |
+| `.sm` / `.lg` | Size      | Compact or large control height.                   |
+| `.icon-only`  | Variant   | Square icon button sized to the control height.    |
 
 ## Basic usage
 

package/docs/pages/components/card.md

@@ -4,14 +4,21 @@ Flexible content container with optional header, body, and footer regions, plus
 
 ## Class reference
 
-| Class       | Kind             | Description                                                                                                                                                                                                     |
-|-------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `.card`     | Component        | Neutral raised surface for grouped content.                                                                                                                                                                     |
-| `.raised`   | Variant          | Elevated surface with a soft shadow.                                                                                                                                                                            |
-| `.subtle`   | Variant          | Lower contrast against the page surface.                                                                                                                                                                        |
-| `.surface`  | Variant          | Shared variant: the page surface instead of `--surface-raised`, with the intent in the text only.                                                                                                               |
-| `.inverted` | Surface modifier | Inverse surface treatment: paints `--surface-solid` and swaps the foreground to `--surface`, so it inverts in dark themes instead of always reading as dark. Apply as `class="card inverted"`, or on any block. |
-| `.compact`  | Variant          | Tighter padding for dense contexts.                                                                                                                                                                             |
+| Class       | Kind             | Description                                 |
+| ----------- | ---------------- | ------------------------------------------- |
+| `.card`     | Component        | Neutral raised surface for grouped content. |
+| `.raised`   | Variant          | Elevated surface with a soft shadow.        |
+| `.subtle`   | Variant          | Lower contrast against the page surface.    |
+| `.surface`  | Variant          | The page surface; intent in the text only.  |
+| `.inverted` | Surface modifier | Inverse surface treatment.                  |
+| `.compact`  | Variant          | Tighter padding for dense contexts.         |
+
+`.surface` is a shared variant: it paints the page surface instead of
+`--surface-raised` and leaves the intent to the text.
+
+`.inverted` paints `--surface-solid` and swaps the foreground to `--surface`,
+so it inverts in dark themes instead of always reading as dark. Write it as
+`class="card inverted"`, or on any block.
 
 ## Basic usage
 

package/docs/pages/components/chat.md

@@ -37,7 +37,7 @@ put `role="log"` on individual messages.
 ## Class reference
 
 | Class                           | Description                                  |
-|---------------------------------|----------------------------------------------|
+| ------------------------------- | -------------------------------------------- |
 | `.chat`                         | Message row grid.                            |
 | `.chat-start` / `.chat-end`     | Logical inline placement.                    |
 | `.chat-avatar`                  | Avatar grid slot; compose it with `.avatar`. |

package/docs/pages/components/dialog.md

@@ -6,13 +6,16 @@
 
 ## Class reference
 
-| Class                  | Kind      | Description                                                                      |
-|------------------------|-----------|----------------------------------------------------------------------------------|
-| `.modal`               | Component | Centered modal surface built on the native `<dialog>` element.                   |
-| `.scrollable`          | Variant   | Keeps the header and footer visible while the dialog body scrolls.               |
-| `.dialog-confirmation` | Variant   | Separates a confirmation message from its full-width action band.                |
-| `.dialog-icon`         | Component | Circular intent-aware icon well for confirmation messages.                       |
-| `.dialog-close`        | Component | Icon-only close button anchored to the modal's top end, out of the content flow. |
+| Class                  | Kind      | Description                                    |
+| ---------------------- | --------- | ---------------------------------------------- |
+| `.modal`               | Component | Centered surface on the native `<dialog>`.     |
+| `.scrollable`          | Variant   | Header and footer stay while the body scrolls. |
+| `.dialog-confirmation` | Variant   | Message above a full-width action band.        |
+| `.dialog-icon`         | Component | Circular intent-aware icon well.               |
+| `.dialog-close`        | Component | Icon-only close button, at the top end.        |
+
+`.dialog-close` sits outside the content flow, so it does not take part in the
+dialog's own layout.
 
 ## Usage
 

package/docs/pages/components/drawer.md

@@ -7,7 +7,7 @@
 ## Class reference
 
 | Class           | Kind      | Description                                                |
-|-----------------|-----------|------------------------------------------------------------|
+| --------------- | --------- | ---------------------------------------------------------- |
 | `.drawer`       | Component | Modal side-sheet built on the native `<dialog>` element.   |
 | `.drawer-close` | Component | Icon-only close button that sits inside the drawer header. |
 

package/docs/pages/components/fab.md

@@ -12,10 +12,12 @@ the layout keeps it clear of adaptive application navigation and safe areas.
 ```html
 <div class="fab">
   <button class="btn circle primary lg icon-only" type="button" aria-label="Create">
-    <span aria-hidden="true">+</span>
+    <i class="ti ti-plus" aria-hidden="true"></i>
   </button>
 </div>
 ```
+The plain FAB button carries the application's own icon — it is a product
+action, not a toggle.
 
 Use native `details` for a no-JavaScript speed dial. List actions in their
 visual top-to-bottom order so keyboard focus follows the same sequence.
@@ -26,9 +28,7 @@ visual top-to-bottom order so keyboard focus follows the same sequence.
     class="btn circle primary icon-only"
     style="--btn-min-size: 3.5rem"
     aria-label="Create"
-  >
-    <span aria-hidden="true">+</span>
-  </summary>
+  ></summary>
 
   <div class="fab-actions">
     <div class="fab-action">
@@ -65,9 +65,7 @@ not the FAB's containing component. Production `.fab` remains viewport-fixed.
       class="btn circle primary icon-only"
       style="--btn-min-size: 3.5rem"
       aria-label="Create"
-    >
-      <span aria-hidden="true">+</span>
-    </summary>
+    ></summary>
 
     <div class="fab-actions">
       <div class="fab-action">
@@ -101,13 +99,16 @@ Each `.fab-action` keeps its `.fab-label` and secondary button on one compact
 line. The example uses the button's existing `.lg` density for 44px secondary
 actions and its `--btn-min-size` hook for a dominant 56px trigger. Size still
 belongs to Button rather than introducing FAB-specific size modifiers.
-When the summary contains one decorative icon, FAB rotates it by 45 degrees in
-the open state so a plus naturally becomes a close symbol.
+Unlike the plain FAB, the speed dial trigger takes no icon: FAB owns it as a
+toggle and masks the shared `--icon-plus` glyph while closed and `--icon-close` —
+the same close symbol used by alerts and dialogs — while open, both sized by
+`--fab-icon-size`. No application icon and no rotated glyph is involved, so the
+two states stay visually identical in size and stroke.
 
 ## Class reference
 
 | Class          | Description                                               |
-|----------------|-----------------------------------------------------------|
+| -------------- | --------------------------------------------------------- |
 | `.fab`         | Fixed viewport placement; use `details` for a speed dial. |
 | `.fab-actions` | Collapsible vertical action list.                         |
 | `.fab-action`  | One horizontal label-and-button unit.                     |
@@ -117,6 +118,7 @@ the open state so a plus naturally becomes a close symbol.
 
 - `--fab-offset` — minimum viewport-edge offset.
 - `--fab-gap` — gap between actions and between the trigger and action list.
+- `--fab-icon-size` — size of the speed dial toggle's open and close markers.
 
 FAB is hidden in print and uses `--z-menu`, leaving tooltips and status UI above
 it. Dialogs remain in the browser's top layer.

package/docs/pages/components/indicator.md

@@ -9,12 +9,12 @@ that owns its appearance.
 
 ## Class reference
 
-| Class             | Kind      | Description                                      |
-|-------------------|-----------|--------------------------------------------------|
-| `.indicator`      | Component | Positioning context for an overlaid child.       |
-| `.indicator-item` | Part      | Item attached to the top-end corner by default.  |
-| `.start`          | Placement | Moves the item to the inline-start corner.       |
-| `.bottom`         | Placement | Moves the item to the bottom corner.             |
+| Class             | Kind      | Description                                     |
+| ----------------- | --------- | ----------------------------------------------- |
+| `.indicator`      | Component | Positioning context for an overlaid child.      |
+| `.indicator-item` | Part      | Item attached to the top-end corner by default. |
+| `.start`          | Placement | Moves the item to the inline-start corner.      |
+| `.bottom`         | Placement | Moves the item to the bottom corner.            |
 
 Combine `.bottom.start` for bottom-start. Logical inline placement follows the
 document direction automatically.