@greypan/web-ui 8.0.0 → 9.0.0

package/README.md

@@ -25,6 +25,8 @@ import '@greypan/web-ui'
 // import '@greypan/web-ui/components/button'
 ```
 
+A subpath import registers only the component it names, so import every tag the page uses.
+
 ```html
 <web-ui-button variant="primary">Click me</web-ui-button> <web-ui-icon .icon="${lucidePlus}"></web-ui-icon>
 ```
@@ -43,7 +45,7 @@ camelCase, Attributes use kebab-case, Events use kebab-case.
 | Event     | kebab-case | `open-change`, `sidebar-collapsed-change`     |
 
 - **Boolean attributes** follow native HTML presence semantics: absent → `false`, presence → `true`. A framework
-  binding that writes `disabled="false"` produces the string `"false"`, which is truthy — **bind dynamic booleans as
+  binding that writes `disabled="false"` produces the string `"false"`, which is truthy. **Bind dynamic booleans as
   properties** (camelCase), not attributes, so `false` is written as a real property.
 - **Vue**: dynamic binding must go to **Properties** with camelCase names (`:sidebarCollapsed="x"`, `:open="x"`).
   A kebab-case binding like `:sidebar-collapsed="x"` is written as a string attribute and cannot express `false`;
@@ -52,7 +54,7 @@ camelCase, Attributes use kebab-case, Events use kebab-case.
   `v-model` is supported on value-bearing controls (`web-ui-input`, `web-ui-select`, `web-ui-autocomplete`, …) and
   compiles to the element `value` property + `input` event.
 - **React**: React 19 writes DOM properties for custom-element props, so use camelCase props (`open={open}`,
-  `noScrollLock`, `value={value}`). Never pass complex data (objects, arrays) through attribute strings — bind
+  `noScrollLock`, `value={value}`). Never pass complex data (objects, arrays) through attribute strings. Bind
   them as properties. Kebab-case JSX props on a custom element are written as attributes.
 
 ### React
@@ -90,7 +92,7 @@ function App() {
 
 React 19 registers Custom Element events using the suffix of the JSX `on` key unchanged. Event names are
 case-sensitive: bind `open-change` as `onopen-change`, not `onOpenChange`. Standard `input`, `change`, `focus`,
-and `blur` events use React's conventional `onInput`, `onChange`, `onFocus`, and `onBlur` handlers — their
+and `blur` events use React's conventional `onInput`, `onChange`, `onFocus`, and `onBlur` handlers. Their
 `currentTarget` is typed as the component instance, so `value` and `checked` are read cast-free. The `target`
 follows React SyntheticEvent semantics (`EventTarget`) and is not narrowed. Kebab-case custom events carry their
 `CustomEvent` detail typed. Boolean properties follow native HTML semantics: absence is `false` and presence is
@@ -126,7 +128,7 @@ useEffect(() => {
 In `portal` mode the library physically moves panel content into the overlay Shadow DOM:
 
 - React removes nodes through its recorded insertion parent, so a bare conditional child (`{condition && <el/>}`) whose node was already migrated cannot be removed while the panel is open: the commit fails and the node can reappear when the panel closes.
-- Conditionally render inside a stable wrapper element instead — React records the wrapper as the insertion parent, so wrapper-local additions and removals keep working while the panel is open and across open/close cycles (example below).
+- Conditionally render inside a stable wrapper element instead. React records the wrapper as the insertion parent, so wrapper-local additions and removals keep working while the panel is open and across open/close cycles (example below).
 - Bare conditional additions while the panel is open (appending to the host) keep working and migrate into the panel automatically.
 - Keeping content mounted and toggling visibility remains a valid fallback.
 
@@ -143,12 +145,12 @@ Portal panels support live rendering for Lit child parts: `${condition ? html`<e
 automatically, removals and element-to-element swaps work while the panel is open, and on close content is
 restored to its original anchor position. lit-html child-part markers stay in the host light DOM, so
 subsequent patches keep anchoring correctly. Boundary: reordering a `repeat()` list while a panel is open is
-not supported — lit inserts relative to host part markers while sibling items already live in the panel, the
+not supported. Lit inserts relative to host part markers while sibling items already live in the panel, the
 same cross-container anchoring boundary as Vue's keyed `v-for`. Apply list reorders while the panel is closed.
 
 `web-ui-dropdown` manages menu items through the shared menu portal, which reconciles from both the host and
 the panel: child-part additions while the panel is open work, but lit cannot reach items that already live in
-the panel, so removals and element swaps there are not supported — apply them while the panel is closed.
+the panel, so removals and element swaps there are not supported. Apply them while the panel is closed.
 `web-ui-context-menu` does not observe host-side insertions and is not covered by these live-rendering
 guarantees.
 
@@ -160,7 +162,7 @@ Portal panels support live rendering: content conditionally added or removed whi
 `v-if` inside `web-ui-select`, `web-ui-autocomplete`, `web-ui-popover`, `web-ui-tooltip`, `web-ui-dropdown`,
 `web-ui-context-menu`) migrates into the open panel automatically in template order, and on close everything
 is restored to its original anchor position so subsequent patches keep working. Boundary: splicing or
-reordering a keyed `v-for` list while a panel is open is not supported — Vue's keyed children diff resolves
+reordering a keyed `v-for` list while a panel is open is not supported. Vue's keyed children diff resolves
 insertion anchors against sibling nodes already migrated into the panel, so its patch fails and items can be
 lost, regardless of compilation path (compiled templates included). Apply such list updates while the panel
 is closed, or keep to appends/removals at the list tail.
@@ -192,7 +194,7 @@ import '@greypan/web-ui/types/vue'
 ```
 
 Boolean properties must be bound with the **camelCase property name**, not the kebab-case attribute. Vue writes
-attribute bindings as strings, and boolean attributes follow presence semantics — so `:sidebar-collapsed="false"`
+attribute bindings as strings, and boolean attributes follow presence semantics, so `:sidebar-collapsed="false"`
 produces the string `"false"`, which is truthy. Binding the camelCase name (`:sidebarCollapsed="false"`, or the
 `.prop` modifier) makes Vue write the DOM property directly:
 
@@ -240,20 +242,20 @@ family by the nature of the interaction. Do not assume `controlled` means the sa
 **User-originated events only (all `open`-style components: collapse, popover, dropdown, tooltip, dialog, drawer, back-top).**
 `*-change` events (`open-change`, etc.) fire only for user-originated toggles; assigning the property programmatically
 (`el.open = true`) or calling an imperative method (`show()`, `close()`, `toggle()`) never emits. Components self-manage
-their `open` value unless you coordinate externally — you may observe the event and write it back for your own state, but
+their `open` value unless you coordinate externally. You may observe the event and write it back for your own state, but
 the component does not require or wait for that write-back.
 
 **Request-then-write-back (`controlled` on dialog and drawer only).**
 With `controlled`, user close actions (Escape, backdrop, built-in close, drag-release) only _request_ `open=false`; the
 component does not change its own state, and it stays open until the consumer writes `open=false`. This is the modal
-confirmation semantics — closing a dialog or drawer is typically an operation that needs consumer approval (unsaved form,
+confirmation semantics. Closing a dialog or drawer is typically an operation that needs consumer approval (unsaved form,
 confirmation), and unlike instantaneous open/close, it is not safe for the component to self-commit. Only these two modal
 components use this mode; the instant open/close family (collapse, popover, dropdown, tooltip) does not need it.
 
 **Native form-model (input, textarea, input-number, select, checkbox, radio, switch, autocomplete).**
 The control manages its own value/checked state internally; user interaction flips it immediately and then dispatches
 native `input`/`change` events. Assigning the property programmatically (`el.checked = true`) overrides the internal
-state. This mirrors native `<input type="checkbox">` — there is no `controlled` prop because the value is always readable
+state. This mirrors native `<input type="checkbox">`. There is no `controlled` prop because the value is always readable
 and writable, and React/Vue layers provide their own controlled wrappers on top.
 
 For interactions that need an external round-trip before the flip is durable (e.g. a switch that should only stay on
@@ -269,6 +271,8 @@ The flip-before-approval window is accepted; there is no `controlled` prop for a
 
 All form controls participate in native `FormData`, constraint validation, `form.reset()` and browser form-state restoration. The control captures its reset default once, after declarative attributes have been applied on its first connection. Later runtime property updates do not redefine that default. A disabled ancestor `fieldset` disables validation and interaction without mutating the control's public `disabled` property. For checkbox/radio groups, the group is the single submission, reset and restoration owner; managed child controls do not submit or restore an independent state.
 
+`web-ui-button` is also form-associated so its host can own an outer form and forward `submit`/`reset` activation. It contributes no value to `FormData`.
+
 ## All Components
 
 | Category               | Component                                                 |
@@ -338,7 +342,7 @@ Text input with clearable, prefix/suffix slots.
 
 **Events:** `input`, `change`, `focus`, `blur`
 
-**Methods:** `focus()`, `blur()` — delegate to the internal native input (the host itself is not focusable)
+**Methods:** `focus()`, `blur()`, `select()`, which delegate to the internal native input (the host itself is not focusable). `focus()` and `select()` are no-ops while `disabled`; `readonly` still allows focus and selection.
 
 **Slots:** `prefix`, `default`, `suffix`
 
@@ -352,28 +356,28 @@ Text input with clearable, prefix/suffix slots.
 
 Multi-line text input with auto-resize.
 
-| Attribute         | Type      | Default | Description                                                                                       |
-| ----------------- | --------- | ------- | ------------------------------------------------------------------------------------------------- |
-| `value`           | `string`  | `''`    | Textarea value                                                                                    |
-| `placeholder`     | `string`  | `''`    | Placeholder text                                                                                  |
-| `rows`            | `number`  | `3`     | Visible rows                                                                                      |
-| `name`            | `string`  | `''`    | Form field name                                                                                   |
-| `disabled`        | `boolean` | `false` | Disabled state                                                                                    |
-| `readonly`        | `boolean` | `false` | Read-only state                                                                                   |
-| `required`        | `boolean` | `false` | Required validation                                                                               |
-| `clearable`       | `boolean` | `false` | Show clear button                                                                                 |
-| `full`            | `boolean` | `false` | Full width                                                                                        |
-| `borderless`      | `boolean` | `false` | Ghost form: removes border, background, and shadow; keeps padding, height metrics, and focus ring |
-| `autosize`        | `boolean` | `false` | Auto-resize height                                                                                |
-| `max-height`      | `number`  | `0`     | Autosize max height (px); `0` = unlimited                                                         |
-| `minlength`       | `number`  | —       | Minimum length validation                                                                         |
-| `maxlength`       | `number`  | —       | Maximum length validation                                                                         |
-| `aria-label`      | `string`  | —       | Accessible label                                                                                  |
-| `aria-labelledby` | `string`  | —       | Accessible label reference                                                                        |
+| Attribute         | Type      | Default | Description                                                                                          |
+| ----------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `value`           | `string`  | `''`    | Textarea value                                                                                       |
+| `placeholder`     | `string`  | `''`    | Placeholder text                                                                                     |
+| `rows`            | `number`  | `3`     | Visible rows                                                                                         |
+| `name`            | `string`  | `''`    | Form field name                                                                                      |
+| `disabled`        | `boolean` | `false` | Disabled state                                                                                       |
+| `readonly`        | `boolean` | `false` | Read-only state                                                                                      |
+| `required`        | `boolean` | `false` | Required validation                                                                                  |
+| `clearable`       | `boolean` | `false` | Show clear button                                                                                    |
+| `full`            | `boolean` | `false` | Full width                                                                                           |
+| `borderless`      | `boolean` | `false` | Ghost form: removes border, background, and shadow; keeps padding, height metrics, and focus ring    |
+| `autosize`        | `boolean` | `false` | Auto-resize height; also forces `resize: none`, because the native grip fights a script-owned height |
+| `max-height`      | `number`  | `0`     | Autosize max height (px); `0` = unlimited                                                            |
+| `minlength`       | `number`  | —       | Minimum length validation                                                                            |
+| `maxlength`       | `number`  | —       | Maximum length validation                                                                            |
+| `aria-label`      | `string`  | —       | Accessible label                                                                                     |
+| `aria-labelledby` | `string`  | —       | Accessible label reference                                                                           |
 
 **Events:** `input`, `change`, `focus`, `blur`
 
-**Methods:** `focus()`, `blur()`, `select()`
+**Methods:** `focus()`, `blur()`, `select()`, which delegate to the internal native textarea. `focus()` and `select()` are no-ops while `disabled`; `readonly` still allows focus and selection.
 
 **Slots:** `prefix`, `suffix`
 
@@ -388,13 +392,15 @@ Multi-line text input with auto-resize.
 
 Inline plain-text editor: click the text to edit in place, `Enter` and `blur` commit, `Escape` cancels. The text layer and the editing layer share one box, so entering edit mode does not move a single pixel.
 
-| Attribute     | Type      | Default | Description                                                                                                                                                |
-| ------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`       | `string`  | `''`    | Current value; the declarative value captured on first connection becomes the `form.reset()` default; later attribute or property changes do not update it |
-| `placeholder` | `string`  | `''`    | Text shown while the value is empty                                                                                                                        |
-| `name`        | `string`  | `''`    | Form field name                                                                                                                                            |
-| `disabled`    | `boolean` | `false` | Disabled state; behavior only, no visual dimming                                                                                                           |
-| `aria-label`  | `string`  | —       | Accessible label                                                                                                                                           |
+| Attribute           | Type      | Default | Description                                                                                                                                                |
+| ------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`             | `string`  | `''`    | Current value; the declarative value captured on first connection becomes the `form.reset()` default; later attribute or property changes do not update it |
+| `placeholder`       | `string`  | `''`    | Text shown while the value is empty                                                                                                                        |
+| `name`              | `string`  | `''`    | Form field name                                                                                                                                            |
+| `disabled`          | `boolean` | `false` | Disabled state; behavior only, no visual dimming                                                                                                           |
+| `readonly`          | `boolean` | `false` | Read-only state; focus, selection, and copying remain available, but edits cannot commit                                                                   |
+| `commit-on-unmount` | `boolean` | `false` | End an in-progress edit by committing when the element is unmounted; see below                                                                             |
+| `aria-label`        | `string`  | —       | Accessible label                                                                                                                                           |
 
 **Events:** `input` (per keystroke), `change` (commit), `cancel` (cancel; shares its name with the native `<dialog>` `cancel`, so it neither bubbles nor crosses shadow boundaries and is dispatched on the component itself only). React has no synthetic event covering `cancel`: listen with `addEventListener('cancel', ...)`
 
@@ -402,7 +408,19 @@ Inline plain-text editor: click the text to edit in place, `Enter` and `blur` co
 
 Clicking places the caret at the clicked offset; keyboard focus places it at the end of the text. `Enter` and `blur` both commit the draft and dispatch `change` exactly once; `Enter` does not insert a newline and returns focus to the host, while `blur` leaves the focus wherever the user moved it. `Escape` alone cancels: the value returns to what it was when editing started, `cancel` is dispatched with no `change`, focus returns to the host, and the key is consumed by the editing layer, so an outer overlay (drawer, menu) is not closed by the same press. The `cancel` event neither bubbles nor crosses shadow boundaries and is dispatched on the component itself only: when the component is projected inside an overlay's shadow root, such as a drawer title, it never reaches the overlay's native `cancel` close pipeline, so listen on the component itself. A value that already contains newlines still renders as several lines; only typing `Enter` no longer adds one. An empty value keeps showing the placeholder, and the editing layer always sizes itself to its own content, so an empty or whitespace-only draft still has room for the caret even where the host itself collapses (a flex item with `min-width: 0`, a table cell).
 
-`select()` enters edit mode with the whole content selected, and re-selects it when already editing. While `disabled` it does nothing, matching `focus()`.
+`select()` enters edit mode with the whole content selected, and re-selects it when already editing. While `disabled` it does nothing, matching `focus()`. While `readonly`, focus and selection remain available, but input is rejected and leaving edit mode does not dispatch `change`.
+
+**Unmounting mid-edit.** What happens when an element being edited is removed from the DOM depends on the engine, and the difference is the reason this property exists:
+
+- **Chromium** dispatches `blur` on the editing layer, so a plain `value` commit already happens today and the default `false` leaves that untouched. `blur` and the `change` it triggers are dispatched synchronously _after_ the unmount callback has run, so the commit arrives after whatever state the caller updates in response to the removal has already been applied.
+- **WebKit (Safari, iOS)** dispatches no `blur` at all. With the default `false` nothing is committed and the draft is dropped along with the element.
+- **Gecko (Firefox)** is **unverified**: no Firefox build would start on the machine this was measured on, so nothing is claimed here. Treat Gecko as unknown rather than as matching either column above, and enable the property if you need the unmount commit to be the thing that saves the draft.
+
+If your code relies on a draft surviving the row being recycled, **enable `commit-on-unmount`**: on Safari and iOS it is the only thing that saves the draft, and in Chromium it moves the commit ahead of the removal-driven `blur`. In both engines the unmount then ends an open editing session by committing — the draft becomes the new value, edit mode exits, and `change` is dispatched exactly once, from the same code `Enter` and `blur` use. Measured on Chromium and WebKit; the browser test suite runs on Chromium only, so the WebKit result comes from a one-off cross-engine run rather than from CI, and Gecko was not measured at all.
+
+Unlike `Enter` and `blur`, which a user action triggers and which therefore always count as an intent to commit, unmount carries no such intent. The commit therefore only fires when the draft really differs from the value captured when editing began, so a session that changed nothing does not produce an empty `change`. An element that is not editing at all has nothing to commit and dispatches nothing, and neither does one that is `disabled` or `readonly` — matching the `blur` path, which dispatches no commit in either state. What happens to a draft that already exists differs between the two, though: under `disabled` the draft stays on the element, while under `readonly` it is genuinely lost. `readonly` does not retract input typed earlier, and on unmount there is no `blur` left to commit it — on WebKit there is no `blur` at all. The path is reachable: enter editing while editable, type a draft, flip to `readonly`, then unmount. It is not treated as a cancel, because cancelling means restoring the value editing started from and there is no focus to return or host to hand a result to at unmount; the user simply sees their typing disappear, with neither `change` nor `cancel`.
+
+The commit fires from the unmount callback, so `change` still travels the composed path and reaches listeners on the component or any ancestor, including ancestors that are themselves being unmounted: dispatching does not require an ancestor to still be in the document. Listeners must therefore not assume the component is still connected; hand the result to state outside the host tree explicitly (for example in a `queueMicrotask`) when it has to outlive the removal. Note that this reach is not guaranteed for an unmount React drives from its own render: such a removal never reaches React's delegated event root, so `onChange` will not fire there and the value has to be read from the element instead — the same caveat that applies to `cancel` above. Setting `display: none` on an ancestor is not a removal — the component stays connected and dispatches nothing in either engine, so end the edit explicitly in that case.
 
 The host is an inline-level box: it sizes to its content unless a width is set, and grows with wrapped lines. Font, color, text alignment and white space are inherited from the surrounding context, so the component reads as ordinary text until it is edited.
 
@@ -457,7 +475,7 @@ Select dropdown with option items, keyboard navigation, and portal support.
 
 **Events:** `input`, `change`, `open-change` (`CustomEvent<{ open: boolean }>`)
 
-**Slots:** `default` (project `<web-ui-option>` elements), `trigger` (custom trigger content — replaces the default label and chevron area)
+**Slots:** `default` (project `<web-ui-option>` elements), `trigger` (custom trigger content, replacing the default label and chevron area)
 
 **Methods:** none
 
@@ -501,11 +519,11 @@ Editable combobox with input filtering and single option selection.
 
 **Methods:** `focus()`, `blur()`
 
-**Slots:** `default` (project `<web-ui-option>` elements), `trigger` (custom trigger content — replaces the default input), `empty` (replace the “no matches” state; falls back to “No matches”)
+**Slots:** `default` (project `<web-ui-option>` elements), `trigger` (custom trigger content, replacing the default input)
 
-Typing filters the option list by label (`contains` or `prefix`, or `none` to disable filtering). Selecting an option fills the input with its label and exposes the option's value via `selected-value`; `change` fires on selection commit. Supports ArrowDown/ArrowUp/Enter/Escape keyboard navigation.
+Typing filters the option list by label (`contains` or `prefix`, or `none` to disable filtering). When no option matches, the dropdown stays closed; deleting characters so at least one option matches reopens it. Selecting an option fills the input with its label and exposes the option's value via `selected-value`; `change` fires on selection commit. Supports ArrowDown/ArrowUp/Enter/Escape keyboard navigation.
 
-**Trigger:** the default trigger is an internal `web-ui-input`. Put any editable component in the `trigger` slot to replace it — the wrapper keeps the combobox ARIA and marks itself with `data-custom-trigger`, and the dropdown stays anchored to the trigger element. Programmatic `focus()` / `blur()` delegate to the active trigger: `web-ui-input` and `web-ui-textarea` move focus to their native control, while a custom trigger without its own focus redirection is focused as the host itself.
+**Trigger:** the default trigger is an internal `web-ui-input`. Put any editable component in the `trigger` slot to replace it. The wrapper keeps the combobox ARIA and marks itself with `data-custom-trigger`, and the dropdown stays anchored to the trigger element. Programmatic `focus()` / `blur()` delegate to the active trigger: `web-ui-input` and `web-ui-textarea` move focus to their native control, while a custom trigger without its own focus redirection is focused as the host itself.
 
 ```html
 <web-ui-autocomplete placeholder="Describe the issue">
@@ -517,11 +535,9 @@ Typing filters the option list by label (`contains` or `prefix`, or `none` to di
 
 The custom trigger exposes the same contract as the default one: a string `value` for the text, focusable, and the events the component delegates from it (`input`, `click`, `focus`, `blur`). `web-ui-input` and `web-ui-textarea` satisfy it as-is; a custom element is usable when it exposes a string `value` property. The wrapper div is not a tab stop (`tabindex="-1"`): sequential focus belongs to the trigger itself, so a custom trigger has to be focusable for keyboard users to reach the combobox.
 
-Multiline triggers (a trigger whose editable element is a `<textarea>`) keep Enter for newlines: Enter never selects the highlighted option and never commits a custom value, so close the panel with Escape or blur. Selecting an option still writes its label back to the trigger. A single-line custom trigger keeps the default Enter behavior. ArrowUp/ArrowDown follow the same exception while the panel is open: they move the text caret instead of navigating options, so keyboard option navigation is unavailable in that state — select with a pointer click. With the panel closed, ArrowDown/ArrowUp still open it.
-
-When `allow-custom-value` is enabled, pressing Enter with no active option and no matching candidate commits the raw input as a custom value and closes the panel. `change` fires and `selected-value` remains empty. The component does not create an option automatically or trim the raw value. Text matching a disabled option cannot bypass the disabled state or derive as a selected option.
+Multiline triggers (a trigger whose editable element is a `<textarea>`) keep Enter for newlines: Enter never selects the highlighted option and never commits a custom value; close the panel with Escape or blur. Selecting an option still writes its label back to the trigger. A single-line custom trigger keeps the default Enter behavior. ArrowUp/ArrowDown follow the same exception while the panel is open: they move the text caret instead of navigating options, so keyboard option navigation is unavailable in that state. Select with a pointer click. With the panel closed, ArrowDown/ArrowUp still open it.
 
-Use `<div slot="empty">…</div>` for static, non-interactive empty-state content. Portal rendering moves this node into the floating panel and restores it to the host after close.
+When `allow-custom-value` is enabled, pressing Enter with no active option and no matching candidate commits the raw input as a custom value and keeps the dropdown closed. `change` fires and `selected-value` remains empty. The component does not create an option automatically or trim the raw value. Text matching a disabled option cannot bypass the disabled state or derive as a selected option.
 
 **CSS Custom Properties:**
 
@@ -585,11 +601,11 @@ Individual checkbox.
 
 Uses native `<label>` with `role="checkbox"` and `aria-checked`. Enter/Space keyboard toggle.
 
-**Layout:** the host is an inline-flex box whose height is set by its content, so the inherited page line-height can no longer inflate it or shift the indicator up and down; it aligns against surrounding text with `vertical-align: middle`. The indicator measures `--wui-selection-control-size` (`18px`), and `<web-ui-radio>` shares the same box contract.
+**Layout:** the host is an inline-flex box whose height is set by its content, so the inherited page line-height can no longer inflate it or shift the indicator up and down; it aligns against surrounding text with `vertical-align: middle`. The indicator measures `--wui-selection-control-size` (`18px`), and `<web-ui-radio>` shares the same box contract. The 10px between indicator and label belongs to the label: when the default slot renders nothing — it is empty, or it carries only a visually hidden accessible name such as an `.sr-only` span — the gap collapses and the host is exactly as wide as the indicator. Emptiness is decided from the label's rendered width rather than from the slot's assigned nodes, because a hidden name is assigned content that paints no box, and hiding the label with `display: none` would take that name out of the accessibility tree.
 
-**Check animation:** the checkmark is the control's own stroked path rather than a `<web-ui-icon>` asset, wrapped in `<web-ui-svg-draw-lines>` (with `no-autoplay`, so a control that mounts already checked shows a static check). Checking draws it in left to right at a constant speed over `--wui-duration-trigger` (160ms by default), read from the resolved theme at the time of the toggle so the stroke lands on the same beat as the indicator's background transition; unchecking retracts the same path back to blank instead of only fading out. Neither plays inside a `motion="reduced"` theme scope, where both states switch instantly.
+**Check animation:** the checkmark is a stroked check from `@/icons`, rendered by a nested `<web-ui-icon>` inside `<web-ui-svg-draw-lines>` (with `no-autoplay`, so a control that mounts already checked shows a static check). Checking draws it in from the left tip at a constant speed over `--wui-duration-trigger` (160ms by default), read from the resolved theme at the time of the toggle so the stroke lands on the same beat as the indicator's background transition; unchecking retracts the same path back to blank instead of only fading out. Neither plays inside a `motion="reduced"` theme scope, where both states switch instantly. The stroke color is `--wui-color-on-control`, passed down through `<web-ui-icon>`'s `--wui-icon-color`, because the indicator behind it is `--wui-color-accent` once checked. Two constraints follow from that arrangement: the asset has to stay stroked (`fill: none` + `stroke: currentColor`) — a solid icon animates the dash but paints nothing, so the check would just appear — and it renders at `<web-ui-icon>`'s own default 18px, since the host cannot reach the `<svg>` inside the icon's shadow root to scale it with `--wui-selection-control-size`.
 
-**Idle states:** the unchecked indicator is filled with `--wui-color-surface-control`, the same control surface neutral buttons use, so it stays separable from `--wui-color-page` in dark mode. Hovering anywhere in the trigger row — indicator, gap or slotted label — tints that surface with a 6% state layer over `--wui-color-surface-control`. Hover applies only on `(hover: hover) and (pointer: fine)` devices; there is no pressed state, and checked and disabled controls keep their own surface. `<web-ui-radio>` shares the same states.
+**Idle states:** the unchecked indicator is filled with `--wui-color-surface-control`, the same control surface neutral buttons use, so it stays separable from `--wui-color-page` in dark mode. Hovering over the indicator, the gap or the slotted label inside the trigger row tints that surface with a 6% state layer over `--wui-color-surface-control`. Hover applies only on `(hover: hover) and (pointer: fine)` devices; there is no pressed state, and checked and disabled controls keep their own surface. `<web-ui-radio>` shares the same states.
 
 #### `<web-ui-radio>`
 
@@ -607,7 +623,7 @@ Individual radio button.
 
 **Slots:** `default` (label text)
 
-**Layout:** shares the selection-control box contract with `<web-ui-checkbox>` — host height comes from its content, alignment against surrounding text is `vertical-align: middle`, and the indicator measures `--wui-selection-control-size`.
+**Layout:** shares the selection-control box contract with `<web-ui-checkbox>`, including the rule that the indicator-label gap only exists while the label renders something. Host height comes from its content, alignment against surrounding text is `vertical-align: middle`, and the indicator measures `--wui-selection-control-size`.
 
 #### `<web-ui-switch>`
 
@@ -630,7 +646,7 @@ Uses `role="switch"` and `aria-checked`. Pointer events for pressed visual state
 
 #### `<web-ui-segmented>`
 
-Segmented control — single-select button group.
+Segmented control: a single-select button group.
 
 | Attribute  | Type                | Default | Description                          |
 | ---------- | ------------------- | ------- | ------------------------------------ |
@@ -644,7 +660,7 @@ Segmented control — single-select button group.
 
 **Slots:** `default` (project `<web-ui-segmented-trigger>` elements)
 
-**Variants:** `inset` (default, sunken) renders an opaque `--wui-color-surface` track with a constant 1px ring and drop shadow, and a solid `--wui-color-surface-segmented` resting indicator that reads as embedded in the track. In light appearance that token equals `--wui-color-page`, so the track sits flush with the page and the recess reads from the ring and shadow alone; in dark appearance `--wui-color-surface` is the one-step-above-page elevation, so the track keeps lifting off the page. `raised` renders the classic flat `--wui-color-surface-segmented` track (no ring, no shadow) with a solid `--wui-color-surface-selected` resting indicator carrying a soft shadow that floats above the track. In both variants the pressed/dragged indicator is transparent glass — backdrop blur, ring fading in over 80ms, 1.5x scale — easing back to the resting surface on release. Illegal values fall back to `inset`.
+**Variants:** `inset` (default, sunken) renders an opaque `--wui-color-surface` track with a constant 1px ring and drop shadow, and a solid `--wui-color-surface-segmented` resting indicator that reads as embedded in the track. In light appearance that token equals `--wui-color-page`, so the track sits flush with the page and the recess reads from the ring and shadow alone; in dark appearance `--wui-color-surface` is the one-step-above-page elevation, so the track keeps lifting off the page. `raised` renders the classic flat `--wui-color-surface-segmented` track (no ring, no shadow) with a solid `--wui-color-surface-selected` resting indicator carrying a soft shadow that floats above the track. In both variants the pressed/dragged indicator is transparent glass, with backdrop blur, a ring fading in over 80ms and a 1.5x scale, easing back to the resting surface on release. Illegal values fall back to `inset`.
 
 Form-associated: integrates with native `<form>` via `ElementInternals`.
 
@@ -652,9 +668,9 @@ Manages child trigger `checked` state based on `value`. `disabled` supplies inhe
 
 Press the selected segment and drag horizontally to slide the indicator; on release it snaps to the nearest option (a fast flick switches by velocity). Touch surfaces declare `touch-action: none` and suppress `touchmove` defaulting during an active drag, so iOS Safari does not interrupt the gesture.
 
-**Pressed state:** the track is an opaque surface (`--wui-color-surface`, page-colored in light appearance) with no backdrop filter in every state — its 1px ring and drop shadow never change. The indicator is the layer that turns to glass. At rest it is a solid `--wui-color-surface-segmented` surface with all glass output off. While pressed or dragging it gains backdrop blur, the glass ring fading in over 80ms, and a 1.5x scale over a fully transparent background: the indicator samples its blur entirely from inside the track, and against the previous glass track a fully transparent indicator measured only +0.5 gray levels on a uniform dark backdrop while striped backdrops showed through the sample (std 1.89 gray levels inside the indicator). The opaque track makes that sample uniform (std 0), which is what gives the pressed thumb a perceptible body — no tint and no edge-decoration suppression are needed. The background never fades in — it lands on the first pressed frame — and on release the indicator eases back to the solid gray rest surface over `--wui-duration-press`.
+**Pressed state:** the track is an opaque surface (`--wui-color-surface`, page-colored in light appearance) with no backdrop filter in every state. Its 1px ring and drop shadow never change. The indicator is the layer that turns to glass. At rest it is a solid `--wui-color-surface-segmented` surface with all glass output off. While pressed or dragging it gains backdrop blur, the glass ring fading in over 80ms, and a 1.5x scale over a fully transparent background: the indicator samples its blur entirely from inside the track, and against the previous glass track a fully transparent indicator measured only +0.5 gray levels on a uniform dark backdrop while striped backdrops showed through the sample (std 1.89 gray levels inside the indicator). The opaque track makes that sample uniform (std 0), which is what gives the pressed thumb a perceptible body. No tint and no edge-decoration suppression are needed. The background never fades in. It lands on the first pressed frame. And on release the indicator eases back to the solid gray rest surface over `--wui-duration-press`.
 
-**Label color:** every label stays `--wui-color-text-secondary` — checked or not, `inset` or `raised`, at rest and while a press or drag is active. Selection is carried by the indicator alone; no label takes the accent color.
+**Label color:** every label stays `--wui-color-text-secondary`. Checked or not, `inset` or `raised`, at rest and while a press or drag is active. Selection is carried by the indicator alone; no label takes the accent color.
 
 #### `<web-ui-checkbox-group>`
 
@@ -678,11 +694,11 @@ Syncs child checkbox `checked` state. `disabled` supplies inherited effective di
 
 ##### Tokens
 
-| Token                      | Default | Description                   |
-| -------------------------- | ------- | ----------------------------- |
-| `--wui-checkbox-group-gap` | `8px`   | Gap between member checkboxes |
+| Token                      | Default              | Description                   |
+| -------------------------- | -------------------- | ----------------------------- |
+| `--wui-checkbox-group-gap` | `var(--wui-space-2)` | Gap between member checkboxes |
 
-Set it on the group element itself, or on an ancestor inside the same `<web-ui-theme>` scope. The theme host declares `8px` for its own subtree, so an override placed above a `<web-ui-theme>` element does not reach the group.
+Set it on the group element itself, or on an ancestor inside the same `<web-ui-theme>` scope. The theme host declares the spacing step for its own subtree, so an override placed above a `<web-ui-theme>` element does not reach the group. Its default now resolves through `--wui-space-2`, so overriding that step on the theme host also moves the gap between members; setting this token still wins over both.
 
 ```css
 web-ui-checkbox-group {
@@ -712,11 +728,11 @@ Radio group managing single selection.
 
 ##### Tokens
 
-| Token                   | Default | Description               |
-| ----------------------- | ------- | ------------------------- |
-| `--wui-radio-group-gap` | `8px`   | Gap between member radios |
+| Token                   | Default              | Description               |
+| ----------------------- | -------------------- | ------------------------- |
+| `--wui-radio-group-gap` | `var(--wui-space-2)` | Gap between member radios |
 
-Set it on the group element itself, or on an ancestor inside the same `<web-ui-theme>` scope. The theme host declares `8px` for its own subtree, so an override placed above a `<web-ui-theme>` element does not reach the group.
+Set it on the group element itself, or on an ancestor inside the same `<web-ui-theme>` scope. The theme host declares the spacing step for its own subtree, so an override placed above a `<web-ui-theme>` element does not reach the group. Its default now resolves through `--wui-space-2`, so overriding that step on the theme host also moves the gap between members; setting this token still wins over both.
 
 ```css
 web-ui-radio-group {
@@ -747,10 +763,11 @@ Styled button with variants and loading state.
 
 **Slots:** `prefix`, `default`, `suffix`
 
-`submit` and `reset` do not submit or reset an ancestor form outside the component's Shadow DOM. Use a
-form-associated control when external form submission behavior is required.
+`submit` and `reset` forward activation through the host's form owner to its native `<form>` after the composed
+`click` event finishes, so calling `preventDefault()` on that click cancels the action. The inner button still has no
+form owner of its own, and `SubmitEvent.submitter` is therefore `null`. The button contributes no value to `FormData`.
 
-Disabled and loading states prevent `click` events.
+Disabled, loading, and `formDisabled` states—including those caused by an ancestor `fieldset`—prevent `click` events.
 
 When `icon` and `loading` are both set, the button renders only the spinner, and the default-slot icon is not
 projected. The icon-mode geometry stays square by default, except for `full` or an explicit width.
@@ -779,6 +796,14 @@ Button group that manages child button layout and direction.
 
 Applies the direction to the grouped button layout without changing child button attributes.
 
+**CSS Custom Properties:**
+
+| Property                            | Default | Description                                                                     |
+| ----------------------------------- | ------- | ------------------------------------------------------------------------------- |
+| `--wui-button-group-divider-length` | `20px`  | Length of the divider between adjacent buttons; its cross axis always stays 1px |
+
+Set it on the group host. The token controls the long edge in both directions, so a horizontal group shortens the divider's height and a vertical group shortens its width.
+
 ---
 
 ### Overlay / Modal
@@ -790,6 +815,7 @@ Modal dialog using native `<dialog>` with `showModal()`.
 | Attribute           | Type      | Default | Description                                                                    |
 | ------------------- | --------- | ------- | ------------------------------------------------------------------------------ |
 | `open`              | `boolean` | `false` | Dialog visibility                                                              |
+| `closable`          | `boolean` | `false` | Show the built-in close button                                                 |
 | `no-scroll-lock`    | `boolean` | `false` | Do not lock body scroll when open                                              |
 | `no-backdrop-close` | `boolean` | `false` | Do not close on backdrop click                                                 |
 | `no-escape-close`   | `boolean` | `false` | Do not close when Escape is pressed                                            |
@@ -803,22 +829,29 @@ Modal dialog using native `<dialog>` with `showModal()`.
 
 Uses native `<dialog>` with `@cancel` prevention. Escape calls `close()` unless `no-escape-close` is present. Click on backdrop closes dialog unless `no-backdrop-close` is present. With `controlled`, both only emit the close request instead.
 
+With `closable`, a built-in close button is rendered in both content modes, and it follows the same close path as Escape and backdrop clicks (so `controlled` applies to it identically). The two modes place it differently: without a `body` slot the button sits in a `.title-row` flex line next to the title; with a `body` slot the title row does not exist, so the button is a direct child of the glass card and is absolutely positioned at its top-right corner (offset by `--wui-dialog-close-top` / `--wui-dialog-close-right`). It uses the same `ooui:close` icon as the drawer close button. Omitting `closable` renders nothing at all — no button and no extra wrapper.
+
 > **Escape ownership:** Escape is arbitrated by a single shared owner, so one keypress closes only the **innermost** open overlay (popover, select, autocomplete, dropdown, context-menu, drawer and dialog all take part). With a select open inside a drawer, the first Escape closes the select and only the second closes the drawer. Sibling overlays that do not nest fall back to open order, closing the most recently opened one. A panel that is still playing its exit transition stays on screen and still catches the Escape, but any overlay that is still open outranks it, so one keypress still closes exactly one layer. `image-preview` takes part as well: its native `<dialog>` is registered with the same arbiter, so Escape is decided by layer order; the component's `cancel` handler only vetoes the native instant close, keeping the top layer until the exit transition finishes.
 
 **CSS Custom Properties:**
 
-| Property                      | Default                                      | Description                                                                           |
-| ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `--wui-dialog-width`          | `360px`                                      | Dialog width                                                                          |
-| `--wui-dialog-max-height`     | `90vh`                                       | Dialog max height                                                                     |
-| `--wui-dialog-overlay-bg`     | `var(--wui-color-backdrop)`                  | Backdrop background                                                                   |
-| `--wui-dialog-bg`             | `var(--wui-color-surface-overlay)`           | Glass card background, falls back to `rgb(246 246 246 / 0.88)`                        |
-| `--wui-dialog-padding`        | `20px 24px 24px`                             | Dialog surface padding                                                                |
-| `--wui-dialog-title-gap`      | `16px`                                       | Spacing below the title                                                               |
-| `--wui-dialog-desc-gap`       | `24px`                                       | Spacing below the body content                                                        |
-| `--wui-dialog-footer-gap`     | `10px` / `12px` (horizontal)                 | Spacing between footer buttons                                                        |
-| `--wui-dialog-footer-justify` | `flex-end` (default) / `center` (horizontal) | Footer `justify-content`; override to `flex-end` for right-aligned horizontal buttons |
-| `--wui-dialog-scale-enter`    | `1.1`                                        | Enter scale start: the panel shrinks in from `1.1` to `1`, and exit reverses it       |
+| Property                          | Default                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| --------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--wui-dialog-width`              | `360px`                                      | Dialog width                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `--wui-dialog-max-height`         | `90vh` / `min(90vh, 90dvh)` (dvh engines)    | Max height of the content area (`.desc`), not of the card. Two fallback tiers: `90vh` on the base rule, `min(90vh, 90dvh)` inside `@supports (height: 100dvh)` — an engine without `dvh` support only ever gets `90vh`. See the note below for the chrome conversion                                                                                                                                                                                                                                                                 |
+| `--wui-dialog-close-top`          | `16px`                                       | `closable` button offset from the card top (body mode)                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `--wui-dialog-close-right`        | `16px`                                       | `closable` button offset from the card right edge (body mode)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `--wui-dialog-overlay-bg`         | `var(--wui-color-backdrop)`                  | Backdrop background                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `--wui-dialog-bg`                 | `var(--wui-color-surface-overlay)`           | Glass card background, falls back to `rgb(248 248 248 / 0.92)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--wui-dialog-padding`            | `20px 24px 24px`                             | Dialog surface padding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `--wui-dialog-title-gap`          | `16px`                                       | Spacing below the title                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `--wui-dialog-desc-gap`           | `24px`                                       | Spacing below the body content                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--wui-dialog-desc-focus-padding` | `6px`                                        | Focus-ring margin reserved on **all four** sides of the content area. `.desc` is a scroll container and, because one axis must be non-`visible`, a clip box as well, so a control flush against any of its four edges would have its ring clipped by the padding box; the margin covers the `5px` ring (`offset: 2` + `width: 3`) on every axis. Hosts do not need to reserve this themselves. Paired negative margins keep the chrome height unchanged, so this can be retuned to a platform's font metrics without moving the card |
+| `--wui-dialog-footer-gap`         | `10px` / `12px` (horizontal)                 | Spacing between footer buttons                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `--wui-dialog-footer-justify`     | `flex-end` (default) / `center` (horizontal) | Footer `justify-content`; override to `flex-end` for right-aligned horizontal buttons                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `--wui-dialog-scale-enter`        | `1.1`                                        | Enter scale start: the panel shrinks in from `1.1` to `1`, and exit reverses it                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+
+> **Height semantics:** the token caps the content area, not the card. The title row and the footer stay sized by their content, and anything past the cap scrolls inside `.desc`; the card itself is bounded only by a literal `100vh` / `100dvh` backstop, which catches the case where the viewport is too short to fit chrome plus the cap. A host that wants to bound the **whole card** must still measure its own chrome (card padding + title row + gaps + footer) and subtract it from the token — the three dialogs in the Interweave frontend subtract 142, 142 and 106 respectively. What no longer needs that number is making the content area scroll: before, `.desc` had neither a cap nor `overflow`, so the only element that could scroll was a host-sized inner box, and a host that wanted overflow to scroll had to compute that height itself.
 
 #### `<web-ui-drawer>`
 
@@ -839,7 +872,7 @@ Side drawer using native `<dialog>` with closing animation. In non-headless mode
 
 **Events:** `open-change` (`CustomEvent<{ open: boolean }>`). With `controlled`, Escape, backdrop, the built-in close button and drag-release only request `open=false`; the drawer remains open until the consumer writes `open=false`. Programmatic APIs (`show()`, `close()`, assigning `open`) stay direct and never emit. If native dialog closure occurs while a request is pending, the drawer restores its open top-layer state and emits the same request. With nested drawers, an inner `open-change` bubbles through the outer root (composed event); distinguish by `event.target`.
 
-**Slots:** `header`, `default`, `footer` — with `headless`, only the `default` slot is rendered.
+**Slots:** `header`, `default`, `footer`. With `headless`, only the `default` slot is rendered.
 
 **Methods:** `show()`, `close()`
 
@@ -847,42 +880,57 @@ Side drawer using native `<dialog>` with closing animation. In non-headless mode
 
 Closing keeps the native dialog in the top layer until the `--wui-duration-drawer-exit` transition completes (240ms by default), then calls `dialog.close()`. Escape always follows this close path; `no-backdrop-close` controls backdrop clicks only.
 
-When `closable` is set, the built-in close button is positioned at the header's top-right corner (defaults `16px` down and `20px` in from the edge) instead of stretching across the drawer body.
+When `closable` is set, the built-in close button is positioned at the header's top-right corner (defaults `16px` down and `16px` in from the edge) instead of stretching across the drawer body. The `16px` down resolves through `--wui-space-4` so it tracks the drawer's header padding; the `16px` in is the button's own offset to the panel's right edge, which is not the header's horizontal padding (`20px`), so it stays a literal.
+
+**Drag to close:** With `draggable`, a gray capsule drag bar (4×56px by default, visually centered 10px from the inner edge) appears on the drawer's inner edge (left edge for `right`, right edge for `left`, bottom edge for `top`, top edge for `bottom`) while open:
+
+The visual center follows half of `--wui-drawer-content-padding`, floored at half the bar thickness plus 4px: zeroing that padding to let content fill the panel edge-to-edge still leaves the capsule a visible inset, so it neither crosses the panel's inner edge nor sits flush against it.
+
+The capsule is a visual marker only: it is `pointer-events: none` and never swallows a press. What you press is a hit surface. On `left` / `right` that is the drag zone alone. On `top` / `bottom` there are three: the drag zone, a band along the grab edge (exactly as wide as the capsule, and at least `--wui-drawer-drag-edge-size` thick), and the header (`placement=bottom`) or footer (`placement=top`) section in full. The edge band's height is the larger of the capsule's own outer edge and that token, so it covers the capsule's band by construction — pressing the capsule starts a drag and hovering it lights it up, on every placement.
+
+The drag zone yields to the header (`placement=bottom`) or the footer (`placement=top`), so that section never pushes the capsule away from the edge — and that section takes the drag itself instead of sitting inert: a press anywhere in it starts a drag, title text included. Controls are kept clear **one by one, at the event layer**, rather than by cutting the hit surface geometrically. A press whose composed path contains an interactive element — native `button` / `input` / `select` / `textarea` / `label` / `a[href]` / `summary`, anything `contenteditable`, an interactive ARIA `role` (`button`, `checkbox`, `switch`, `tab`, `menuitem`, `option`, `slider`, …), or any explicit `tabindex` other than `-1` — reaches the control and starts no drag. A custom control that is not natively interactive has to carry one of those markers to be recognised; adding `role` or `tabindex` is the way in, and it is the right call for accessibility anyway. Geometric cutting was rejected on purpose: it would have to measure each control's position, so it breaks the moment a control moves, and it relocates the A6 defect rather than removing it. The trade is explicit. The built-in close button sits against the panel's right edge, outside the capsule's span, so it stays clickable; a control placed inside the capsule's horizontal span is still covered by the drag surface over the band's height.
 
-**Drag to close:** With `draggable`, a gray capsule drag bar (4×56px by default, visually centered 10px from the inner edge inside a 20px-thick hit zone) appears on the drawer's inner edge (left edge for `right`, right edge for `left`, bottom edge for `top`, top edge for `bottom`) while open:
+One consequence follows from the handle occupying that span: a control placed inside it whose top edge falls within the band's height (`--wui-drawer-drag-edge-size`, `20px` by default, or the capsule's own outer edge when that is thicker) has its upper part covered by the drag surface, since the handle is drawn there and a drag has to start where the handle is. `z-index` does not lift it clear — Chromium keeps the band above slotted content — so the levers are `--wui-drawer-drag-bar-length`, which sets the capsule length and the band width together, and `--wui-drawer-drag-edge-size`, which sets the band's thickness.
 
 - Dragging follows the pointer in real time; the backdrop fades proportionally.
-- Backdrop click now only honors a genuine tap chain: the press must start on the backdrop itself and the press-to-release travel must stay within the tap magnitude. The click the browser generates for a press–drag–release lands on the common ancestor (`dialog`) regardless of where the press started — pressing on the panel content or on the backdrop itself and releasing over the backdrop used to close the drawer through that click. The component records the pointerdown origin and validates it on click, so such drag releases always rebound. A `detail`-0 click (keyboard / programmatic) never consumes the pointer record.
+- Backdrop click now only honors a genuine tap chain: the press must start on the backdrop itself and the press-to-release travel must stay within the tap magnitude. The click the browser generates for a press–drag–release lands on the common ancestor (`dialog`) regardless of where the press started. Pressing on the panel content or on the backdrop itself and releasing over the backdrop used to close the drawer through that click. The component records the pointerdown origin and validates it on click, so such drag releases always rebound. A `detail`-0 click (keyboard / programmatic) never consumes the pointer record.
 - Releasing with a net displacement past half the drawer size (floor of 10px), or with a fast closing flick, closes the drawer; otherwise it animates back open. The close direction is placement-aware, and each part of the decision matches Base UI's `useSwipeDismiss`:
   - Both the displacement origin and the decision clock reset to the first `pointermove`, absorbing the gap between the press and that move; its whole travel is discarded, so a gesture needs at least two moves to accumulate displacement.
-  - The flick is judged by the **whole gesture's** average velocity — net displacement ÷ gesture duration, divisor floored at 50ms — reaching 500px/s, not by the instantaneous velocity at release. A sliding window only describes the last short stretch of the trace, so under a whole-gesture average sweeping back towards the edge can no longer read as a flick. A zero-length duration yields zero velocity instead of a floored divisor, so an unmeasurable gesture is never read as a flick.
+  - The flick is judged by the **whole gesture's** average velocity. Net displacement ÷ gesture duration, divisor floored at 50ms. The flick commits when the average reaches 500px/s, not by the instantaneous velocity at release. A sliding window only describes the last short stretch of the trace, so under a whole-gesture average sweeping back towards the edge can no longer read as a flick. A zero-length duration yields zero velocity instead of a floored divisor, so an unmeasurable gesture is never read as a flick.
   - Any release whose net displacement isn't in the close direction animates back open.
   - The distance test also uses the net displacement, so grabbing the drawer mid-rebound and releasing without dragging further never counts as "already past half way".
   - A withdrawal of 10px or more from the point where the close direction was confirmed cancels the flick, so dragging out into the overscroll and sweeping back never closes. Displacement that has already crossed the distance threshold clears the mark again, so a gesture that is past half way is unaffected by a small retreat. Upstream has the same guard (`cancelledSwipe`), but never reaches it on the drawer path because `DrawerViewport.onRelease` always returns a decision.
   - Dragging in the opening direction is damped by a square root (`sign(d) · |d| ** 0.5`), matching `applyDirectionalDamping`. The damping applies to the gesture's increment, added on top of the offset the drag started from, and self-limits rather than being capped at a fixed distance.
-- The release velocity only shapes the settle transition's duration (180–420ms); the settle itself is a single CSS transition on `transform`, handed back by JS at release — no WAAPI animation is created.
+- The release velocity only shapes the settle transition's duration (180–420ms); the settle itself is a single CSS transition on `transform`, handed back by JS at release. No WAAPI animation is created.
 - With `controlled`, release past the threshold only emits `open-change(false)`; the drawer holds at the closed position briefly (120ms write-back window) and animates back open if the consumer rejects or misses the write-back.
 - Drag-to-open is not supported because the closed drawer renders nothing outside the native dialog.
 - Under `prefers-reduced-motion`, release settles instantly, with no transition.
 
 **CSS Custom Properties:**
 
-| Property                          | Default                            | Description                                                                  |
-| --------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- |
-| `--wui-drawer-width`              | `320px`                            | Drawer width                                                                 |
-| `--wui-drawer-height`             | `300px`                            | Drawer height (top/bottom)                                                   |
-| `--wui-drawer-bg`                 | `var(--wui-color-surface-overlay)` | Drawer body background                                                       |
-| `--wui-drawer-radius`             | `var(--wui-radius-overlay, 28px)`  | Floating card corner radius (non-headless)                                   |
-| `--wui-drawer-inset`              | `8px`                              | Floating card viewport inset (non-headless); `0` gives edge-to-edge geometry |
-| `--wui-drawer-overlay-bg`         | `rgb(0 0 0 / 0.12)`                | Backdrop background                                                          |
-| `--wui-drawer-drag-zone-size`     | `20px`                             | Drag-to-close hit zone thickness on the inner edge (draggable)               |
-| `--wui-drawer-drag-bar-thickness` | `4px`                              | Drag bar capsule thickness (short axis)                                      |
-| `--wui-drawer-drag-bar-length`    | `56px`                             | Drag bar capsule length (along the drawer edge)                              |
-| `--wui-drawer-header-padding`     | `16px 20px`                        | Header section padding                                                       |
-| `--wui-drawer-close-top`          | `16px`                             | Built-in close button offset from the top of the header                      |
-| `--wui-drawer-close-right`        | `16px`                             | Built-in close button offset from the right edge of the drawer               |
-| `--wui-drawer-content-padding`    | `20px`                             | Content area padding; also drives drag bar visual center (half value)        |
-| `--wui-drawer-footer-padding`     | `16px 20px`                        | Footer section padding                                                       |
+| Property                          | Default                            | Description                                                                                                                                                                                                                                                                       |
+| --------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--wui-drawer-width`              | `320px`                            | Drawer width                                                                                                                                                                                                                                                                      |
+| `--wui-drawer-height`             | `300px`                            | Drawer height (top/bottom)                                                                                                                                                                                                                                                        |
+| `--wui-drawer-bg`                 | `var(--wui-color-surface-overlay)` | Drawer body background                                                                                                                                                                                                                                                            |
+| `--wui-drawer-radius`             | `var(--wui-radius-overlay, 28px)`  | Floating card corner radius (non-headless)                                                                                                                                                                                                                                        |
+| `--wui-drawer-inset`              | `8px`                              | Floating card viewport inset (non-headless); `0` gives edge-to-edge geometry                                                                                                                                                                                                      |
+| `--wui-drawer-nested-peek-base`   | `43.2px`                           | Nested-stack reveal step base `A` (`28.8px` at `width <= 640px`); total stack width grows as `A · ln(n)`, so a single layer never moves and each extra layer reveals less. `0` disables the reveal. See the note below.                                                           |
+| `--wui-drawer-overlay-bg`         | `rgb(0 0 0 / 0.12)`                | Backdrop background                                                                                                                                                                                                                                                               |
+| `--wui-drawer-drag-zone-size`     | `20px`                             | Drag-to-close hit zone thickness on the inner edge (draggable)                                                                                                                                                                                                                    |
+| `--wui-drawer-drag-zone-inset`    | `var(--wui-space-1, 4px)`          | Breathing gap between the drag hit zone and the header (`placement=bottom`) or footer (`placement=top`) it yields to. `0` when that section is absent                                                                                                                             |
+| `--wui-drawer-drag-bar-thickness` | `4px`                              | Drag bar capsule thickness (short axis)                                                                                                                                                                                                                                           |
+| `--wui-drawer-drag-bar-length`    | `56px`                             | Drag bar capsule length (along the drawer edge)                                                                                                                                                                                                                                   |
+| `--wui-drawer-drag-edge-size`     | `20px`                             | Thickness of the capsule's hit band along the grab edge (`top` / `bottom` only). Floored by the capsule's own outer edge, so the capsule band is always covered; the default matches `--wui-drawer-drag-zone-size`, so the handle is never harder to hit than the strip beside it |
+| `--wui-drawer-header-padding`     | `16px 20px`                        | Header section padding                                                                                                                                                                                                                                                            |
+| `--wui-drawer-close-top`          | `16px`                             | Built-in close button offset from the top of the header                                                                                                                                                                                                                           |
+| `--wui-drawer-close-right`        | `16px`                             | Built-in close button offset from the right edge of the drawer                                                                                                                                                                                                                    |
+| `--wui-drawer-content-padding`    | `20px`                             | Content area padding; also drives drag bar visual center (half value, floored at half the bar thickness + 4px)                                                                                                                                                                    |
+| `--wui-drawer-footer-padding`     | `16px 20px`                        | Footer section padding                                                                                                                                                                                                                                                            |
+
+`--wui-drawer-nested-peek-base` needs no declaration of yours: the `43.2px` default is the `initialValue` of the property the component registers with `CSS.registerProperty` (in `components/drawer/index.ts`), and narrow viewports get a smaller `28.8px` base from the `@media (width <= 640px)` rule in `components/drawer/style.css`. Those two places are where the shipped defaults live. Setting the token on the host (or any ancestor) overrides both, at any viewport width.
+
+With the shipped defaults, a four-layer stack of `320px` drawers reveals `29.94px` / `17.52px` / `12.43px` per step on desktop and `19.96px` / `11.68px` / `8.29px` on narrow viewports, for a total stack width of `59.89px` and `39.93px` respectively. A single layer never moves, because `ln(1)` is `0`.
 
 #### `imagePreview()`
 
@@ -946,7 +994,7 @@ Every presentation option defaults to off: with no options passed only the image
 
 Pinch-to-zoom is always on and has no option: the stage already owns pointer interaction, so there is nothing for a gesture to conflict with. The first finger still drives pan/swipe as usual and the second finger starts the pinch, which aborts any in-flight pan or swipe. A pinch does not close the preview, and the compatibility `click` that mixed input may synthesize afterwards is swallowed rather than treated as a backdrop click.
 
-Clicking anywhere outside the image, or pressing Escape, closes the preview. The native dialog always exposes the accessible name `图片预览`. With `swipe` on and more than one image, the images live on a single carousel track: the current image and its neighbors sit side by side in slides of equal size, the stage clips the overflow, and the whole track translates with the finger. Releasing past the distance threshold (15% of the stage width, rounded) slides the next image in, as does a fast flick whose sampled velocity is at least 320px/s even below that distance; a flick covering at least 16px whose velocity (windowed sample or whole-gesture average) reaches 160px/s also commits; otherwise it bounces back. With `loop` on the wrap-around neighbor is always present beside the current image, and at the non-looping bounds the strip bounces back instead of crossing the boundary. While it applies, the swipe gesture takes over the drag entirely: at 1x only horizontal movement changes images, and vertical movement is ignored (no pan, no vertical follow). Once zoomed in, dragging always pans on both axes and never changes images. Because panning also works at 1x, `resetZoom()` is offered whenever the image is zoomed _or_ displaced — the reset button in the toolbar is enabled for a panned 1x image too.
+Clicking anywhere outside the image, or pressing Escape, closes the preview. The native dialog always exposes the accessible name `图片预览`. With `swipe` on and more than one image, the images live on a single carousel track: the current image and its neighbors sit side by side in slides of equal size, the stage clips the overflow, and the whole track translates with the finger. Releasing past the distance threshold (15% of the stage width, rounded) slides the next image in, as does a fast flick whose sampled velocity is at least 320px/s even below that distance; a flick covering at least 16px whose velocity (windowed sample or whole-gesture average) reaches 160px/s also commits; otherwise it bounces back. With `loop` on the wrap-around neighbor is always present beside the current image, and at the non-looping bounds the strip bounces back instead of crossing the boundary. While it applies, the swipe gesture takes over the drag entirely: at 1x only horizontal movement changes images, and vertical movement is ignored (no pan, no vertical follow). Once zoomed in, dragging always pans on both axes and never changes images. Because panning also works at 1x, `resetZoom()` is offered whenever the image is zoomed _or_ displaced. The reset button in the toolbar is enabled for a panned 1x image too.
 
 A close request does not destroy the native dialog immediately: it stays in the top layer until the exit transition completes, then `dialog.close()` runs, the host is removed from the DOM, and `closed` resolves. Page scroll is locked while open unless `noScrollLock` is `true`.
 
@@ -990,33 +1038,33 @@ In-flow expand/collapse container with animated height (or width) transition. Si
 
 The initial `open` attribute settles instantly without playing the animation. Nested collapses are supported.
 
-**Trigger semantics:** interaction comes from the element you put in the default slot — a native `<button>`, `<web-ui-button>`, or any other interactive element supplies Enter/Space activation and focus natively. The collapse writes `aria-expanded` / `aria-controls` (pointing at its content track) and `aria-disabled` onto the first assigned element in the trigger slot. Use an interactive element as the trigger: a plain `<span>` is clickable but has no keyboard/focus semantics.
+**Trigger semantics:** interaction comes from the element you put in the default slot. A native `<button>`, `<web-ui-button>`, or any other interactive element supplies Enter/Space activation and focus natively. The collapse writes `aria-expanded` / `aria-controls` (pointing at its content track) and `aria-disabled` onto the first assigned element in the trigger slot. Use an interactive element as the trigger: a plain `<span>` is clickable but has no keyboard/focus semantics.
 
 **Closed-state semantics:** the consumer's light DOM is never moved or unmounted. Default closed state applies `hidden` to the internal content container; with `keep-mounted` the inner container is marked `inert` while staying measurable inside the collapsed track.
 
-**`peek` (partial reveal):** setting `peek` makes the closed state reveal the first `peek` of the content along the animation axis (`horizontal` switches it to width) instead of collapsing to zero — the track stays at the content height and the inner container is clamped. It implies `keep-mounted` semantics: the content stays mounted but is `inert`, so the clipped portion is not focusable or clickable. Content shorter than `peek` collapses to its own size rather than leaving blank space. Because a fixed length and an auto height cannot be interpolated by CSS, the two `peek` ↔ expanded directions are driven by explicit pixel lengths (measured once per toggle); every other animation path stays a zero-measurement grid `fr` transition.
+**`peek` (partial reveal):** setting `peek` makes the closed state reveal the first `peek` of the content along the animation axis (`horizontal` switches it to width) instead of collapsing to zero. The track stays at the content height and the inner container is clamped. It implies `keep-mounted` semantics: the content stays mounted but is `inert`, so the clipped portion is not focusable or clickable. Content shorter than `peek` collapses to its own size rather than leaving blank space. Because a fixed length and an auto height cannot be interpolated by CSS, the two `peek` ↔ expanded directions are driven by explicit pixel lengths (measured once per toggle); every other animation path stays a zero-measurement grid `fr` transition.
 
 ```html
 <web-ui-collapse peek="120px">
   <button type="button">Toggle me</button>
-  <div slot="content">Long content — only the first 120px show while closed</div>
+  <div slot="content">Long content. Only the first 120px show while closed</div>
 </web-ui-collapse>
 ```
 
-**Edge fade:** the revealed area ends in an alpha-gradient fade (right edge when `horizontal`) so the clipped portion melts into the background instead of ending in a hard line. The length is derived from `peek` — there is no second attribute to set. Tune it with CSS custom properties instead:
+**Edge fade:** the revealed area ends in an alpha-gradient fade (right edge when `horizontal`) so the clipped portion melts into the background instead of ending in a hard line. The length is derived from `peek`. There is no second attribute to set. Tune it with CSS custom properties instead:
 
 | Custom property                  | Default       | Description                                                           |
 | -------------------------------- | ------------- | --------------------------------------------------------------------- |
 | `--wui-collapse-peek-edge-ratio` | `0.4`         | Fade length as a fraction of `peek`                                   |
 | `--wui-collapse-peek-edge-max`   | `112px`       | Upper bound, so a large `peek` cannot produce an oversized fade band  |
 | `--wui-collapse-peek-edge`       | —             | Explicit fade length; wins over the derived value                     |
-| `--wui-collapse-peek-edge-color` | `transparent` | Fade-stop color (must carry alpha — `mask-image` reads alpha channel) |
+| `--wui-collapse-peek-edge-color` | `transparent` | Fade-stop color (must carry alpha - `mask-image` reads alpha channel) |
 
-Set the ratio to `0` to turn the fade off. The derivation is pure CSS `calc(peek * ratio)`, so a `rem`-based `peek` scales the fade with the root font size and nothing has to be measured in JS. Known limitation: a percentage `peek` does not derive to a length, so the fade silently falls back to "none" — set `--wui-collapse-peek-edge` explicitly in that case.
+Set the ratio to `0` to turn the fade off. The derivation is pure CSS `calc(peek * ratio)`, so a `rem`-based `peek` scales the fade with the root font size and nothing has to be measured in JS. Known limitation: a percentage `peek` does not derive to a length, so the fade silently falls back to "none". Set `--wui-collapse-peek-edge` explicitly in that case.
 
-The fade is a four-stop ease-out gradient rather than a linear one: the body stays fully opaque to the start of the fade band, drops to 60% alpha within the first 30% of the band, then 26%, then reaches the edge color. A linear gradient hugs 1.0 alpha across the first 40% of the band, so the eye perceives a much shorter fade than declared — front-loading the drop makes the band visibly soft from its very start, nearly doubling the perceived length at the same size.
+The fade is a four-stop ease-out gradient rather than a linear one: the body stays fully opaque to the start of the fade band, drops to 60% alpha within the first 30% of the band, then 26%, then reaches the edge color. A linear gradient hugs 1.0 alpha across the first 40% of the band, so the eye perceives a much shorter fade than declared. Front-loading the drop makes the band visibly soft from its very start, nearly doubling the perceived length at the same size.
 
-The fade band is positioned in percentages, relative to the container's **current rendered height** — which is what `max-height` animates. So the band tracks the cut edge frame by frame during the collapse animation without the `mask-image` string ever needing to interpolate. Its length is driven by a registered `<length>` custom property so it can fade in and out with the toggle instead of popping in once the close animation settles.
+The fade band is positioned in percentages, relative to the container's **current rendered height**, which is what `max-height` animates. So the band tracks the cut edge frame by frame during the collapse animation without the `mask-image` string ever needing to interpolate. Its length is driven by a registered `<length>` custom property so it can fade in and out with the toggle instead of popping in once the close animation settles.
 
 ```html
 <!-- 调强渐隐：比例 0.5 → 120px peek 配 60px 渐隐 -->
@@ -1089,10 +1137,12 @@ Tooltip overlay using pointer/focus triggers.
 
 Right-click context menu.
 
-| Attribute        | Type      | Default | Description                |
-| ---------------- | --------- | ------- | -------------------------- |
-| `disabled`       | `boolean` | `false` | Disabled state             |
-| `no-scroll-lock` | `boolean` | `false` | Allow background scrolling |
+| Attribute          | Type      | Default | Description                                                   |
+| ------------------ | --------- | ------- | ------------------------------------------------------------- |
+| `disabled`         | `boolean` | `false` | Right-click does not open the menu; no visual dimming         |
+| `no-scroll-lock`   | `boolean` | `false` | Allow background scrolling                                    |
+| `long-press`       | `boolean` | `false` | Open on a touch long press (opt-in; mouse uses `contextmenu`) |
+| `long-press-delay` | `number`  | `500`   | Hold duration in ms before `long-press` opens the menu        |
 
 **Events:** `open-change` (`CustomEvent<{ open: boolean }>`)
 
@@ -1100,10 +1150,26 @@ Right-click context menu.
 
 **Methods:** `openAt(x: number, y: number)`, `close()`
 
+**CSS Custom Properties:**
+
+| Property                              | Default                            | Description                      |
+| ------------------------------------- | ---------------------------------- | -------------------------------- |
+| `--wui-context-menu-safe-area-bottom` | `env(safe-area-inset-bottom, 0px)` | Bottom inset a touch menu clears |
+
 Opens on `contextmenu` event. Menu items: `<web-ui-dropdown-item>`, `<web-ui-dropdown-divider>`, `<web-ui-dropdown-header>`. Supports keyboard navigation (Arrow keys, Enter, Escape) and submenu hover with `pointerenter`.
 
+While the menu is open it is modal: it renders into a transparent `<dialog>` in the browser's top layer, so nothing on the page below can be clicked or hit-tested. Clicking outside therefore dismisses the menu without also activating whatever was underneath — a row, a checkbox, a link. The scrim is deliberately invisible; it exists to absorb the hit, not to dim the page. One consequence to know about: for the ~160ms exit transition after a menu item is activated, the scrim has already left the top layer, so the page below is briefly clickable again and the menu's stacking level is that of the normal flow.
+
+`long-press` is opt-in and touch-only: a pointer held for `long-press-delay` (default `500` ms, matching the platform long press) opens the menu, through the same path as a right-click. It only reacts to `pointerType === 'touch'`, and holding while moving more than 10px cancels it, so scrolling never opens a menu. Because the browser also reports that same hold as a native gesture, the `contextmenu` and `click` it emits afterwards are absorbed rather than allowed to reopen — or immediately light-dismiss — the menu the long press just opened.
+
+A `long-press` menu opens downward from the press point: its top edge sits at the press `y` and it is centred horizontally on the press `x`, which is how native iOS and Android long-press menus appear. When there is not enough room below, the panel flips above the press point rather than running off the screen, and both axes are clamped into the viewport while clearing `--wui-context-menu-safe-area-bottom` so it does not sit under a home indicator. The split is by input, not by viewport width: a narrow window still anchors a mouse right-click at the cursor's top-left corner. Only the horizontal alignment differs — both paths run the same `computePosition` pass, so touch and mouse cannot drift apart.
+
+`disabled` suppresses menu behaviour only: right-click and `openAt()` do not open a menu. It does not dim or otherwise restyle what you put in the default slot — the component renders no menu surface of its own to dim, and disabling the right-click menu is not the same as disabling your trigger. If a disabled state should read as disabled, render it on your own content.
+
 While the menu is open, consumer code may conditionally render, move, or remove menu items (e.g. Vue `v-if`) without re-inserting them at the host element; changes inside the portal are reconciled automatically, and framework anchors are returned to the host on close so subsequent framework patches keep working.
 
+On close, focus returns to whatever was focused when the menu opened. That is the browser's own modal-dialog behaviour rather than something the component reimplements, which is also why it only works while the menu is the top layer. Activating a menu item is the one path that hands focus back early — at the click, before the exit transition — so that an item action which moves focus elsewhere (opening an inline editor, say) ends up keeping it: the closing menu never reaches in and pulls focus back out of the new target, so nothing that commits on blur fires a spurious edit.
+
 ---
 
 ### Menu
@@ -1193,24 +1259,48 @@ Badge / notification count.
 
 Empty state placeholder.
 
-| Attribute     | Type                             | Default    | Description      |
-| ------------- | -------------------------------- | ---------- | ---------------- |
-| `title`       | `string`                         | `''`       | Title text       |
-| `description` | `string`                         | `''`       | Description text |
-| `size`        | `'small' \| 'medium' \| 'large'` | `'medium'` | Empty state size |
+| Attribute     | Type     | Default | Description                                                    |
+| ------------- | -------- | ------- | -------------------------------------------------------------- |
+| `title`       | `string` | `''`    | Title text                                                     |
+| `description` | `string` | `''`    | Description text                                               |
+| `size`        | `number` | `56`    | Layout scale in px; invalid or non-positive values become `56` |
+
+`size` is the one knob for the whole placeholder. It drives the icon container, `min-height`, padding, and the title/description font size, so a large icon no longer sits in medium-sized whitespace:
+
+| `size` | Icon box | Glyph  | `min-height` | Padding block/inline | Title  | Description |
+| ------ | -------- | ------ | ------------ | -------------------- | ------ | ----------- |
+| `40`   | `40px`   | `17px` | `171px`      | `23px/17px`          | `14px` | `13px`      |
+| `56`   | `56px`   | `24px` | `240px`      | `32px/24px`          | `16px` | `14px`      |
+| `72`   | `72px`   | `31px` | `309px`      | `41px/31px`          | `16px` | `14px`      |
+
+The derived values are `min-height: round(size * 30 / 7)`, `padding-block: round(size * 4 / 7)`, and `padding-inline: round(size * 3 / 7)`; the default glyph is `round(size * 3 / 7)`.
+
+Font size is one step rather than a scale: below `56` the title is `14px` and the description `13px`, and from `56` up they are `16px` and `14px`. A bigger placeholder gets its presence from whitespace, not from bigger text.
+
+**Migrating from the `'small' \| 'medium' \| 'large'` enum:** `size` is now a number, and the removed tiers had hand-tuned metrics that these ratios only approach — `small` was `160px` tall with `20px 16px` padding, `large` was `320px` with `48px 32px`. Section margins and content width never followed the tiers.
+
+| Old value | New value | Default glyph |
+| --------- | --------- | ------------- |
+| `small`   | `40`      | `17`          |
+| `medium`  | `56`      | `24`          |
+| `large`   | `72`      | `31`          |
 
 **Slots:** `default` (title, overrides `title` prop), `icon`, `description`, `action`
 
 **CSS Custom Properties:**
 
-| Property                            | Default     | Description                    |
-| ----------------------------------- | ----------- | ------------------------------ |
-| `--wui-empty-min-height`            | `240px`     | Min height (medium)            |
-| `--wui-empty-padding`               | `32px 24px` | Padding (medium)               |
-| `--wui-empty-icon-size`             | `56px`      | Icon container size (medium)   |
-| `--wui-empty-content-width`         | `480px`     | Max width of title/description |
-| `--wui-empty-title-font-size`       | `16px`      | Title font size (medium)       |
-| `--wui-empty-description-font-size` | `14px`      | Description font size (medium) |
+Each one overrides the value `size` derives, so all eight stay authoritative — including the two font sizes. Defaults are the values at the default `size` of `56`.
+
+| Property                            | Default     | Description                                 |
+| ----------------------------------- | ----------- | ------------------------------------------- |
+| `--wui-empty-min-height`            | `240px`     | Min height                                  |
+| `--wui-empty-padding`               | `32px 24px` | Padding                                     |
+| `--wui-empty-icon-size`             | `56px`      | Icon container size; overrides `size`       |
+| `--wui-empty-content-width`         | `480px`     | Max width of title, description, and action |
+| `--wui-empty-title-margin-top`      | `16px`      | Space between the icon and the title        |
+| `--wui-empty-title-font-size`       | `16px`      | Title font size                             |
+| `--wui-empty-description-font-size` | `14px`      | Description font size                       |
+| `--wui-empty-action-margin-top`     | `20px`      | Space above the action slot                 |
 
 #### `<web-ui-icon>`
 
@@ -1225,6 +1315,8 @@ Icon renderer using Iconify data objects.
 
 Has `aria-hidden="true"`.
 
+**Canvas:** the SVG `viewBox` is read from `icon.left`/`icon.top`/`icon.width`/`icon.height`, defaulting to `0` for the offsets and to Iconify's spec default `16` for the sizes. Generated assets always carry their canvas, so the size fallback only matters for raw `IconifyIcon` objects passed in directly.
+
 ```js
 import { lucideLoaderCircle } from '@greypan/web-ui/icons'
 html`<web-ui-icon .icon=${lucideLoaderCircle} spin />`
@@ -1336,16 +1428,17 @@ Responsive page layout with an optional full-width banner, a collapsible desktop
 
 At `640px` and below, the sidebar becomes a `web-ui-drawer` with its built-in glass body, scrollable content, and drag zone. The layout maps `sidebar-width` to `--wui-drawer-width` and `--wui-layout-sidebar-radius` to `--wui-drawer-radius`. The mobile toggle appears in the header row as a glass button. Its left inset defaults to `8px`; align it with your own header padding via `--wui-layout-mobile-toggle-inset`.
 
-`header-glow` adds a pointer-transparent decorative glow behind header-slot content and the mobile toggle. It is a Header background rather than a foreground layer, so slotted content remains above it. Override its color with `--wui-layout-header-glow-color` (default: `--wui-color-page`). The glow concentration and spread are controlled by the internal variable `--wui-layout-header-glow-height` (default: `150%`); increase for stronger coverage, decrease for a subtler effect. Layout layers are ordered as Header (`10`) < Auxiliary (`20`) < Banner (`30`) < Tabbar (`40`) < Sidebar (`50`).
+`header-glow` adds a pointer-transparent decorative glow behind header-slot content and the mobile toggle. It is a Header background rather than a foreground layer, so slotted content remains above it. The glow takes its colour from `--wui-color-page`, so it follows light and dark appearance on its own; override that property on `web-ui-layout`, on the theme, or anywhere above it to change it. Two pseudo-elements build it. `::before` paints the colour as a `linear-gradient` inside the header box, fading to fully transparent, and `::after` adds a real `backdrop-filter: blur(4px)` layer whose `mask` fades that blur toward zero alpha at the bottom edge. Keeping the two apart means blur strength and colour strength do not pull on each other. Both expand with a negative `margin` rather than a `transform`. Horizontal clipping is owned by `.layout-content`, so the glow never produces a horizontal scrollbar. Layout layers are ordered as Header (`10`) < Auxiliary (`20`) < Banner (`30`) < Tabbar (`40`) < Sidebar (`50`).
 
-The sidebar card surface is `--wui-color-surface-sidebar`. In light mode it carries the same value as the shared `--wui-color-surface-overlay`; in dark mode it sits one notch above `--wui-color-page`, level with `--wui-color-surface`. It is a separate token because dialog, drawer and toast share `--wui-color-surface-overlay` and are not elevated along with the sidebar.
+The sidebar card surface is `--wui-color-surface-sidebar`. In light mode it keeps its translucent neutral layer; in dark mode it sits one notch above `--wui-color-page`, level with `--wui-color-surface`. It is a separate token because dialog, drawer and toast share `--wui-color-surface-overlay` and may use a different surface.
 
 **CSS Custom Properties:**
 
-| Property                           | Default | Description                                      |
-| ---------------------------------- | ------- | ------------------------------------------------ |
-| `--wui-layout-sidebar-radius`      | `24px`  | Border radius of sidebar card (desktop & mobile) |
-| `--wui-layout-mobile-toggle-inset` | `8px`   | Left inset of the mobile header toggle           |
+| Property                            | Default | Description                                                                          |
+| ----------------------------------- | ------- | ------------------------------------------------------------------------------------ |
+| `--wui-layout-sidebar-radius`       | `24px`  | Border radius of sidebar card (desktop & mobile)                                     |
+| `--wui-layout-mobile-toggle-inset`  | `8px`   | Left inset of the mobile header toggle                                               |
+| `--wui-layout-sidebar-toggle-width` | `44px`  | Width of the desktop sidebar collapse toggle; floored at `--wui-control-size` (36px) |
 
 #### `<web-ui-back-top>`
 
@@ -1379,7 +1472,7 @@ Role: `button`, keyboard Enter scrolls to top.
 
 #### `<web-ui-svg-draw-lines>`
 
-SVG line drawing animation using `stroke-dashoffset`. Animates geometry in-place — no cloning, no DOM manipulation. Two playback directions: the reveal draws geometry from nothing to fully drawn, `replay({ reverse: true })` retracts it along the same path back to nothing.
+SVG line drawing animation using `stroke-dashoffset`. Animates geometry in-place. No cloning, no DOM manipulation. Two playback directions: the reveal draws geometry from nothing to fully drawn, `replay({ reverse: true })` retracts it along the same path back to nothing.
 
 | Attribute     | Type      | Default    | Description                                            |
 | ------------- | --------- | ---------- | ------------------------------------------------------ |
@@ -1389,13 +1482,13 @@ SVG line drawing animation using `stroke-dashoffset`. Animates geometry in-place
 
 All attributes are reflected.
 
-**Auto-play:** the first time slotted content settles, one reveal plays by itself. Set `no-autoplay` to leave the geometry as authored and decide when to play — that is how `<web-ui-checkbox>` avoids drawing a checkmark that was already checked on mount.
+**Auto-play:** the first time slotted content settles, one reveal plays by itself. Set `no-autoplay` to leave the geometry as authored and decide when to play. That is how `<web-ui-checkbox>` avoids drawing a checkmark that was already checked on mount.
 
-**Methods:** `replay(options?: { reverse?: boolean }): Promise<void>` — cancels running animation, re-collects geometry elements from current DOM, and starts a new animation. All targets animate in parallel with the same duration/easing. Resolves when all complete. A reverse run ends on blank and leaves that end state in the DOM: the animation itself is cancelled, while the dash values that hide the stroke stay as inline styles until the next `replay()` replaces or undoes them. A reveal run restores the authored inline styles instead. A retract always starts from the full stroke, so interrupting a reveal draws the whole path back rather than only the part that was visible. When the nearest theme scope uses `motion="reduced"`, or its `motion="system"` mode matches `prefers-reduced-motion: reduce`, no animation starts — but a previous retract's blank is still undone, so the geometry returns to as authored and visibility is left entirely to the consumer's own styles.
+**Methods:** `replay(options?: { reverse?: boolean }): Promise<void>`. Cancels running animation, re-collects geometry elements from current DOM, and starts a new animation. All targets animate in parallel with the same duration/easing. Resolves when all complete. A reverse run ends on blank and leaves that end state in the DOM: the animation itself is cancelled, while the dash values that hide the stroke stay as inline styles until the next `replay()` replaces or undoes them. A reveal run restores the authored inline styles instead. A retract always starts from the full stroke, so interrupting a reveal draws the whole path back rather than only the part that was visible. When the nearest theme scope uses `motion="reduced"`, or its `motion="system"` mode matches `prefers-reduced-motion: reduce`, no animation starts. But a previous retract's blank is still undone, so the geometry returns to as authored and visibility is left entirely to the consumer's own styles.
 
-**Reverse end state:** the blank a retract leaves behind is inline style on the geometry it animated, including nodes inside nested open shadow roots such as `<web-ui-icon>`. Copying those nodes (`cloneNode`, an `innerHTML` round-trip) carries the blank along, and detaching and re-appending one keeps the stroke hidden — a finished retract is a DOM state rather than a live animation, so nothing is left to restore it. Call `replay()` to draw them again. Because the component reaches into nested open shadow roots, two `<web-ui-svg-draw-lines>` must not cover the same geometry: each records the inline dash values the first time it animates an element, so a blank left by the inner one becomes the outer one's idea of the consumer's own value.
+**Reverse end state:** the blank a retract leaves behind is inline style on the geometry it animated, including nodes inside nested open shadow roots such as `<web-ui-icon>`. Copying those nodes (`cloneNode`, an `innerHTML` round-trip) carries the blank along, and detaching and re-appending one keeps the stroke hidden. A finished retract is a DOM state rather than a live animation, so nothing is left to restore it. Call `replay()` to draw them again. Because the component reaches into nested open shadow roots, two `<web-ui-svg-draw-lines>` must not cover the same geometry: each records the inline dash values the first time it animates an element, so a blank left by the inner one becomes the outer one's idea of the consumer's own value.
 
-**Slots:** `default` — SVG content to animate. Accepts inline `<svg>` elements (light DOM) as well as components that render an SVG in an open shadow root, such as `<web-ui-icon>`. Closed shadow roots are skipped.
+**Slots:** `default`. SVG content to animate. Accepts inline `<svg>` elements (light DOM) as well as components that render an SVG in an open shadow root, such as `<web-ui-icon>`. Closed shadow roots are skipped.
 
 Finds `path`, `rect`, `circle`, `line`, `polyline`, `polygon`, `ellipse` elements by recursively traversing the light DOM and all open shadow roots. Paths ending with `Z`/`z` receive a temporary gap fix for proper closing-segment rendering. After a reveal completes or is cancelled, all in-line styles are restored.
 
@@ -1403,42 +1496,82 @@ Finds `path`, `rect`, `circle`, `line`, `polyline`, `polygon`, `ellipse` element
 
 Theme provider defining CSS custom property tokens.
 
-| Attribute    | Type                              | Default    | Description                                   |
-| ------------ | --------------------------------- | ---------- | --------------------------------------------- |
-| `appearance` | `'light' \| 'dark' \| 'system'`   | `'light'`  | Color scheme                                  |
-| `motion`     | `'full' \| 'reduced' \| 'system'` | `'system'` | Motion preference for this nested theme scope |
+| Attribute             | Type                              | Default    | Description                                            |
+| --------------------- | --------------------------------- | ---------- | ------------------------------------------------------ |
+| `appearance`          | `'light' \| 'dark' \| 'system'`   | `'light'`  | Color scheme                                           |
+| `resolved-appearance` | `'light' \| 'dark'`               | `'light'`  | Resolved color scheme; read-only reflected host output |
+| `motion`              | `'full' \| 'reduced' \| 'system'` | `'system'` | Motion preference for this nested theme scope          |
 
-**Methods:** `getOverlayRoot()` — returns this theme-owned overlay root
+**Methods:** `getOverlayRoot()`. Returns this theme-owned overlay root
 
 **Portal mounting contract:** Every active `<web-ui-theme>` is also the default scoped theme-owned overlay root. Portal-based components without an explicit `overlayContainer` resolve to the nearest active theme's `getOverlayRoot()`; target-less portal calls prefer the root theme's theme-owned overlay root. When no active theme provides a root, they fall back to the global fallback overlay root.
 
 Defines foundation, color, layer, shadow, and motion tokens for its subtree. `motion="system"` follows `prefers-reduced-motion`; use `motion="reduced"` to reduce animation in a scope or `motion="full"` in a nested theme to restore normal token values. System appearance follows `prefers-color-scheme`.
 
-Appearance changes are animated with the View Transitions API according to this scope's `motion`: `full` always reveals, `reduced` applies the new appearance immediately with no reveal, and `system` follows `prefers-reduced-motion`. A root theme reveals the whole page; a nested theme reveals only its own capture box. The origin is the last pointer-down position when available, otherwise the theme box or viewport center. Dark-to-light and light-to-dark directions are reversed. Unsupported browsers, reduced-motion scopes, zero durations, and another request already in the same flight fall back to applying the new appearance immediately; `appearance="system"` does not animate OS light/dark changes in this version.
+`resolved-appearance` is a read-only derived host attribute (also exposed as the `resolvedAppearance` property): it is always `light` or `dark`, mirrors an explicit `appearance` directly, resolves `appearance="system"` from `prefers-color-scheme`, and updates live when the OS flips. A theme without `appearance` remains inactive but reports the default `light`. Because the component owns the attribute and restores external edits, consumers can bind selectors or Tailwind custom variants to `resolved-appearance` without carrying a second theme state.
+
+Appearance changes are animated with the View Transitions API according to this scope's `motion`: `full` always reveals, `reduced` applies the new appearance immediately with no reveal, and `system` follows `prefers-reduced-motion`. A root theme reveals the whole page; a nested theme reveals only its own capture box. The origin is the last pointer-down position when available, otherwise the theme box or viewport center. The reveal direction follows the resolved appearance, including `appearance="system"` resolving from `prefers-color-scheme`; dark-to-light and light-to-dark directions are reversed. Unsupported browsers, reduced-motion scopes, zero durations, and another request already in the same flight fall back to applying the new appearance immediately; `appearance="system"` does not animate OS light/dark changes in this version.
+
+During an active reveal, the View Transitions rendering-suppression rules force pointer hit-testing onto the document element, so CSS `pointer-events` overrides cannot keep the underlying page interactive. The theme calls `skipTransition()` only on `pointerdown` or wheel; `pointermove` and `pointerup` never end the reveal, so follow-up movement from the initiating control or ordinary pointer movement cannot interrupt it. The event that triggers the skip is still spec-defined to target the document element, but the disabled hit-test window ends there instead of running for the full reveal duration.
 
 **Migration from the removed `transition` attribute:** drop it and express the intent with `motion` instead. A theme that carried `transition` keeps the same reveal under the default `motion="system"`; add `motion="full"` to reveal even when the system prefers reduced motion. A theme that did not carry it now reveals by default, so pass `motion="reduced"` to keep appearance changes instant.
 
 The host uses `display: contents` and does not paint any background: the library never draws on the host page, so the embedding application keeps full control of the surface behind the themed subtree. Custom properties still inherit to slotted content reliably.
 
-**Root page color sync:** the outermost active theme also mirrors its computed `--wui-color-page` onto `document.documentElement` as an inline custom property. That closes the one place the token cannot reach on its own: custom properties stop inheriting at the document element, so a consumer rule such as `body { background: var(--wui-color-page) }` only colors the scrollable area, while the canvas behind an overscroll bounce (macOS rubber-banding) stays at the user-agent background. With the mirrored property the bounce area follows the theme too. The write happens when a theme connects and whenever its appearance changes, including `appearance="system"` following an OS light/dark flip; the value written is the theme's computed value, so an override of `--wui-color-page` on the host is mirrored as it stands. **Not live:** the component does not observe the host's own style changes, so a runtime change to that property on the host — an inline style edit, a class toggle, a host-level media query — reaches the root only at the next write trigger, which is a connect, an `appearance` change to a different value, or an OS light/dark flip; re-assigning `appearance` to the value it already has is not a trigger, because the update is skipped when nothing changed. For a page color that has to change independently of the theme's appearance, own the variable yourself on `:root` or `body` with `!important`, which outranks this inline write, or drive the color through `appearance`. Only the outermost theme writes: nested themes keep their own scope and never touch the root value. Ownership follows connect order and passes to the next connected theme when the outermost one disconnects; when the last theme disconnects the value is deliberately kept rather than removed, so a page that swaps themes does not flash back to the user-agent background in between. The library writes exactly this one custom property on the document element and nothing else there.
+**Root page color sync:** the outermost active theme also mirrors its computed `--wui-color-page` onto `document.documentElement` as an inline custom property. That closes the one place the token cannot reach on its own: custom properties stop inheriting at the document element, so a consumer rule such as `body { background: var(--wui-color-page) }` only colors the scrollable area, while the canvas behind an overscroll bounce (macOS rubber-banding) stays at the user-agent background. With the mirrored property the bounce area follows the theme too. The write happens when a theme connects and whenever its appearance changes, including `appearance="system"` following an OS light/dark flip; the value written is the theme's computed value, so an override of `--wui-color-page` on the host is mirrored as it stands. **Not live:** the component does not observe the host's own style changes, so a runtime change to that property on the host (an inline style edit, a class toggle, a host-level media query) reaches the root only at the next write trigger, which is a connect, an `appearance` change to a different value, or an OS light/dark flip; re-assigning `appearance` to the value it already has is not a trigger, because the update is skipped when nothing changed. For a page color that has to change independently of the theme's appearance, own the variable yourself on `:root` or `body` with `!important`, which outranks this inline write, or drive the color through `appearance`. Only the outermost theme writes: nested themes keep their own scope and never touch the root value. Ownership follows connect order and passes to the next connected theme when the outermost one disconnects; when the last theme disconnects the value is deliberately kept rather than removed, so a page that swaps themes does not flash back to the user-agent background in between. The library writes exactly this one custom property on the document element and nothing else there.
 
 **Foundation tokens:**
 
 | Property                  | Default | Description                                      |
 | ------------------------- | ------- | ------------------------------------------------ |
-| `--wui-font-size`         | `14px`  | Base font size for controls                      |
 | `--wui-input-width`       | `200px` | Default width for compact form controls          |
 | `--wui-control-size`      | `36px`  | Default height and square min-width for controls |
 | `--wui-overlay-min-width` | `200px` | Minimum anchored overlay width                   |
 | `--wui-focus-ring-width`  | `3px`   | Focus indicator width                            |
 
+**Typography tokens:** font sizes are named by the role the text plays, not by scale position — `caption` for dense chrome labels, `readout` for numeric readouts, the unsuffixed base for body copy, and `title` for bounded card headings. Weights are named by weight, and line heights by how much vertical air the text needs. These are appearance-independent: they stay the same under both light and dark.
+
+| Property                     | Default | Description                                                     |
+| ---------------------------- | ------- | --------------------------------------------------------------- |
+| `--wui-font-size-caption`    | `12px`  | Dense chrome labels (badge, toast timestamp, menu section head) |
+| `--wui-font-size-readout`    | `13px`  | Numeric readouts (image preview count and zoom ratio)           |
+| `--wui-font-size`            | `14px`  | Base font size for body copy and controls                       |
+| `--wui-font-size-title`      | `18px`  | Bounded card headings (dialog, drawer)                          |
+| `--wui-font-weight-medium`   | `500`   | Medium weight for emphasized inline text                        |
+| `--wui-font-weight-semibold` | `600`   | Semibold weight for headings                                    |
+| `--wui-line-height-tight`    | `1.2`   | Tight leading for large headings                                |
+| `--wui-line-height-snug`     | `1.4`   | Snug leading for mid-size headings                              |
+| `--wui-line-height-normal`   | `1.5`   | Normal leading for body copy                                    |
+| `--wui-line-height-relaxed`  | `1.6`   | Relaxed leading for long-form reading                           |
+
+`line-height: 1` and `line-height: 0` inside components are intentionally not tokenized: the former vertically centers a single-line control label, the latter collapses a wrapper box onto its content. Neither is typographic leading, and tokenizing them would invite callers to retune them as if they were.
+
+**Spacing tokens:** a six-step scale on a 4px base, stopping at 24px — the largest spacing value the component layer writes as an _effective_ static rhythm literal. (The one wider padding, `<web-ui-empty>`'s `32px 24px`, is derived in JS from `--wui-empty-size`, so it belongs to that size axis rather than to the rhythm; see the exclusions below.) These do not replace the per-component override tokens (`--wui-button-px`, `--wui-dialog-padding`, and friends) — they act as the fallback default _for_ those tokens, so each component still decides its own padding while the scale says where that value sits in the overall rhythm. Overriding a step therefore gives the embedding application a density lever across every migrated call site — a lever over rhythm, not over structure; see the exclusions below.
+
+| Property        | Default | Description                        |
+| --------------- | ------- | ---------------------------------- |
+| `--wui-space-1` | `4px`   | Tight inset (badge, menu)          |
+| `--wui-space-2` | `8px`   | Control gap, group gap, inline pad |
+| `--wui-space-3` | `12px`  | Horizontal control padding         |
+| `--wui-space-4` | `16px`  | Standard section separation        |
+| `--wui-space-5` | `20px`  | Overlay content padding            |
+| `--wui-space-6` | `24px`  | Wide overlay inset                 |
+
+The scale deliberately omits `1px`, `2px`, `6px`, `7.5px`, `10px`, and negative values. `1px` is the structural width of hairlines and stroke rings; `2px`, `6px`, and `7.5px` are optical corrections; `10px` is a half-step coupling value off the 4px grid; negative margins cancel a flex gap or a button's padding. Each answers a different "why this number", none of them share spacing semantics, and folding them into one ruler would make overriding any one of them disturb the rest.
+
+A second exclusion is by meaning rather than by value: offsets that align to the viewport edge or to the host's own content edge stay off the scale even when they land on the 4px grid — `--wui-image-preview-edge-gap`, `--wui-toast-viewport-gap`, `--wui-layout-mobile-toggle-inset`, `--wui-back-top-right` / `--wui-back-top-left` / `--wui-back-top-bottom`, `--wui-drawer-inset`, and `--wui-drawer-close-right`. Their reference frame is the screen or the host's content edge, not the rhythm between neighbours, so folding them in would make "tighten `--wui-space-2`" unexpectedly move a component away from the screen edge. `--wui-drawer-close-top` is the counter-example: it does resolve through `--wui-space-4`, because it tracks the drawer's header padding and the two must move together.
+
+A third exclusion is spacing that a component derives from a **size** prop instead of writing as rhythm: `<web-ui-empty>` scales its `padding`, `min-block-size`, and glyph with `--wui-empty-size`, so its padding is `23px 17px` / `32px 24px` / `41px 31px` at the `40` / `56` / `72` steps. Four of those six values are odd, so a 4px scale cannot represent them at all. The `56` step's `32px 24px` landing on the base is a coincidence of the size choice, not a sign that the value belongs to the rhythm: `56` is the only one of the three that divides by 7, its quotient is exactly 8, and 8 is itself a multiple of 4 — no rounding happens on that step at all. A density lever that is silently inert on two of three sizes and coincidentally live on the third is worse than no lever, and the whole set moves whenever `size` does — so these stay off the scale. Reach for a literal `px` there instead.
+
+Overrides must sit inside the `<web-ui-theme>` scope, since the theme host declares the steps for its own subtree. One known boundary: the overlay styles in `assets/*.css` are injected either into a theme-owned overlay root, where the scale applies, or into the document-level fallback overlay root — a plain `div` that sees no theme tokens — where overlay spacing always resolves to its literal fallback.
+
 **Selection control tokens (radio, checkbox):**
 
-| Property                       | Default | Description                                     |
-| ------------------------------ | ------- | ----------------------------------------------- |
-| `--wui-selection-control-size` | `18px`  | Indicator (circle / box) width and height       |
-| `--wui-radio-group-gap`        | `8px`   | Member spacing inside `<web-ui-radio-group>`    |
-| `--wui-checkbox-group-gap`     | `8px`   | Member spacing inside `<web-ui-checkbox-group>` |
+| Property                       | Default              | Description                                     |
+| ------------------------------ | -------------------- | ----------------------------------------------- |
+| `--wui-selection-control-size` | `18px`               | Indicator (circle / box) width and height       |
+| `--wui-checkbox-group-gap`     | `var(--wui-space-2)` | Member spacing inside `<web-ui-checkbox-group>` |
+| `--wui-radio-group-gap`        | `var(--wui-space-2)` | Member spacing inside `<web-ui-radio-group>`    |
 
 **Radius tokens:**
 
@@ -1452,7 +1585,6 @@ The host uses `display: contents` and does not paint any background: the library
 
 | Property                     | Default | Description                  |
 | ---------------------------- | ------- | ---------------------------- |
-| `--wui-layer-base`           | `0`     | Base content                 |
 | `--wui-layer-inline-overlay` | `1`     | Overlay local to a component |
 | `--wui-layer-header`         | `10`    | Page header                  |
 | `--wui-layer-auxiliary`      | `20`    | Floating utility controls    |
@@ -1468,41 +1600,41 @@ The host uses `display: contents` and does not paint any background: the library
 
 **Color tokens:**
 
-| Property                           | Light default                                                | Dark default                                                 | Description                     |
-| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------- |
-| `--wui-color-page`                 | `#fff`                                                       | `#242628`                                                    | Page background                 |
-| `--wui-color-surface`              | `#fff`                                                       | `#2c2c2e`                                                    | Plain surface                   |
-| `--wui-color-surface-raised`       | `#f2f2f7`                                                    | `#2c2c2e`                                                    | Raised surface                  |
-| `--wui-color-surface-control`      | `#dfdfdf`                                                    | `#3a3a3c`                                                    | Neutral control surface         |
-| `--wui-color-surface-track`        | `#e5e5ea`                                                    | `#444446`                                                    | Slider and switch track surface |
-| `--wui-color-surface-menu`         | `rgb(246 246 246 / 0.82)`                                    | `rgb(44 44 46 / 0.78)`                                       | Menu and floating panel surface |
-| `--wui-color-surface-glass`        | `rgb(250 250 250 / 0.34)`                                    | `rgb(44 44 46 / 0.42)`                                       | Liquid glass surface            |
-| `--wui-color-surface-glass-hover`  | `color-mix(... text 6%, surface-glass)`                      | `color-mix(... text 6%, surface-glass)`                      | Full glass hover background     |
-| `--wui-color-surface-glass-active` | `color-mix(... text 15%, surface-glass)`                     | `color-mix(... text 15%, surface-glass)`                     | Full glass pressed background   |
-| `--wui-color-surface-overlay`      | `rgb(246 246 246 / 0.82)`                                    | `rgb(32 34 34 / 0.9)`                                        | Translucent overlay surface     |
-| `--wui-color-surface-sidebar`      | `rgb(246 246 246 / 0.82)`                                    | `rgb(44 44 46 / 0.8)`                                        | Sidebar panel surface           |
-| `--wui-color-surface-segmented`    | `#e5e5ea`                                                    | `#3a3a3c`                                                    | Segmented indicator surface     |
-| `--wui-color-surface-selected`     | `#fff`                                                       | `#5c5c5e`                                                    | Selected surface                |
-| `--wui-color-text`                 | `#1b1b1b`                                                    | `#e9eaea`                                                    | Primary text                    |
-| `--wui-color-text-secondary`       | `#6a6a6a`                                                    | `#a1a1a6`                                                    | Secondary text                  |
-| `--wui-color-text-tertiary`        | `color-mix(in srgb, var(--wui-color-text) 35%, transparent)` | `color-mix(in srgb, var(--wui-color-text) 42%, transparent)` | Tertiary text and quiet icons   |
-| `--wui-color-text-disabled`        | `color-mix(in srgb, var(--wui-color-text) 32%, transparent)` | `color-mix(in srgb, var(--wui-color-text) 38%, transparent)` | Disabled foreground text        |
-| `--wui-color-state-layer-hover`    | `color-mix(in srgb, var(--wui-color-text) 6%, transparent)`  | `color-mix(in srgb, var(--wui-color-text) 6%, transparent)`  | Transparent hover overlay       |
-| `--wui-color-state-layer-active`   | `color-mix(in srgb, var(--wui-color-text) 15%, transparent)` | `color-mix(in srgb, var(--wui-color-text) 15%, transparent)` | Transparent pressed overlay     |
-| `--wui-color-border`               | `rgb(0 0 0 / 0.1)`                                           | `rgb(255 255 255 / 0.14)`                                    | Normal border and divider       |
-| `--wui-color-glass-border`         | `transparent`                                                | `rgb(255 255 255 / 0.05)`                                    | Glass border tint               |
-| `--wui-color-glass-highlight`      | `rgb(255 255 255 / 0.9)`                                     | `rgb(255 255 255 / 0.1)`                                     | Glass edge highlight            |
-| `--wui-color-glass-corner`         | `rgb(255 255 255 / 0.5)`                                     | `rgb(255 255 255 / 0.2)`                                     | Glass corner sheen on border    |
-| `--wui-color-glass-shade`          | `rgb(0 0 0 / 0.03)`                                          | `rgb(0 0 0 / 0.5)`                                           | Glass corner shade on border    |
-| `--wui-color-accent`               | `#08f`                                                       | `#0a84ff`                                                    | Accent and focused input border |
-| `--wui-color-on-accent`            | `#fff`                                                       | `#fff`                                                       | Foreground on accent            |
-| `--wui-color-on-control`           | `#fff`                                                       | `#f2f2f7`                                                    | Foreground on control inner     |
-| `--wui-color-success`              | `#16a34a`                                                    | `#30d158`                                                    | Success                         |
-| `--wui-color-warning`              | `#d97706`                                                    | `#ff9f0a`                                                    | Warning                         |
-| `--wui-color-danger`               | `#dc2626`                                                    | `#ff453a`                                                    | Danger                          |
-| `--wui-color-info`                 | `#2563eb`                                                    | `#64d2ff`                                                    | Info                            |
-| `--wui-color-backdrop`             | `rgb(0 0 0 / 0.12)`                                          | `rgb(0 0 0 / 0.48)`                                          | Modal backdrop                  |
-| `--wui-color-focus-ring`           | `rgb(0 136 255 / 0.4)`                                       | `rgb(10 132 255 / 0.62)`                                     | Focus indicator color           |
+| Property                           | Light default                                                        | Dark default                                                            | Description                                    |
+| ---------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `--wui-color-page`                 | `#fff`                                                               | `#242628`                                                               | Page background                                |
+| `--wui-color-surface`              | `#fff`                                                               | `#2c2c2e`                                                               | Plain surface                                  |
+| `--wui-color-surface-raised`       | `#f2f2f7`                                                            | `#2c2c2e`                                                               | Raised surface                                 |
+| `--wui-color-surface-control`      | `#dfdfdf`                                                            | `#3a3a3c`                                                               | Neutral control surface                        |
+| `--wui-color-surface-track`        | `#e5e5ea`                                                            | `#444446`                                                               | Slider and switch track surface                |
+| `--wui-color-surface-menu`         | `rgb(250 250 250 / 0.76)`                                            | `rgb(49 48 50 / 0.74)`                                                  | Menu and floating panel surface                |
+| `--wui-color-surface-glass`        | `rgb(250 250 250 / 0.34)`                                            | `rgb(44 44 46 / 0.42)`                                                  | Liquid glass surface                           |
+| `--wui-color-surface-glass-hover`  | `color-mix(... text 6%, surface-glass)`                              | `color-mix(... text 6%, surface-glass)`                                 | Full glass hover background                    |
+| `--wui-color-surface-glass-active` | `color-mix(... text 15%, surface-glass)`                             | `color-mix(... text 15%, surface-glass)`                                | Full glass pressed background                  |
+| `--wui-color-surface-overlay`      | `rgb(248 248 248 / 0.92)`                                            | `rgb(32 34 34 / 0.92)`                                                  | Translucent overlay surface                    |
+| `--wui-color-surface-sidebar`      | `rgb(233 233 233 / 0.82)`                                            | `rgb(44 44 46 / 0.8)`                                                   | Sidebar panel surface                          |
+| `--wui-color-surface-segmented`    | `#e5e5ea`                                                            | `#3a3a3c`                                                               | Segmented indicator surface                    |
+| `--wui-color-surface-selected`     | `#fff`                                                               | `#5c5c5e`                                                               | Selected surface                               |
+| `--wui-color-text`                 | `#1b1b1b`                                                            | `#e9eaea`                                                               | Primary text                                   |
+| `--wui-color-text-secondary`       | `#6a6a6a`                                                            | `#a1a1a6`                                                               | Secondary text                                 |
+| `--wui-color-text-tertiary`        | `color-mix(in srgb, var(--wui-color-text) 35%, transparent)`         | `color-mix(in srgb, var(--wui-color-text) 42%, transparent)`            | Tertiary text and quiet icons                  |
+| `--wui-color-text-disabled`        | `color-mix(in srgb, var(--wui-color-text) 32%, transparent)`         | `color-mix(in srgb, var(--wui-color-text) 38%, transparent)`            | Disabled foreground text                       |
+| `--wui-color-state-layer-hover`    | `color-mix(in srgb, var(--wui-color-text) 6%, transparent)`          | `color-mix(in srgb, var(--wui-color-text) 6%, transparent)`             | Transparent hover overlay                      |
+| `--wui-color-state-layer-active`   | `color-mix(in srgb, var(--wui-color-text) 15%, transparent)`         | `color-mix(in srgb, var(--wui-color-text) 15%, transparent)`            | Transparent pressed overlay                    |
+| `--wui-color-border`               | `rgb(0 0 0 / 0.1)`                                                   | `rgb(255 255 255 / 0.14)`                                               | Normal border and divider                      |
+| `--wui-color-glass-highlight`      | `rgb(255 255 255 / 0.9)`                                             | `rgb(255 255 255 / 0.1)`                                                | Inset highlight on the surface                 |
+| `--wui-color-glass-ring`           | `rgb(0 0 0 / 0.05)`                                                  | `rgb(255 255 255 / 0.05)`                                               | Base tint of the 1px ring                      |
+| `--wui-color-glass-ring-sheen`     | `rgb(255 255 255 / 0.5)`                                             | `rgb(255 255 255 / 0.2)`                                                | Corner sheen on the ring                       |
+| `--wui-color-glass-ring-shade`     | `rgb(0 0 0 / 0.03)`                                                  | `rgb(0 0 0 / 0.5)`                                                      | Corner shade on the ring                       |
+| `--wui-color-accent`               | `#08f`                                                               | `#0a84ff`                                                               | Accent and focused input border                |
+| `--wui-color-on-accent`            | `#fff`                                                               | `#fff`                                                                  | Foreground on accent                           |
+| `--wui-color-on-control`           | `#fff`                                                               | `#f2f2f7`                                                               | Foreground on control inner                    |
+| `--wui-color-success`              | `#16a34a`                                                            | `#30d158`                                                               | Success                                        |
+| `--wui-color-warning`              | `#d97706`                                                            | `#ff9f0a`                                                               | Warning                                        |
+| `--wui-color-danger`               | `#dc2626`                                                            | `#ff453a`                                                               | Danger                                         |
+| `--wui-color-info`                 | `#2563eb`                                                            | `#64d2ff`                                                               | Info                                           |
+| `--wui-color-backdrop`             | `rgb(0 0 0 / 0.12)`                                                  | `rgb(0 0 0 / 0.48)`                                                     | Modal backdrop                                 |
+| `--wui-color-focus-ring`           | `color-mix(in srgb, var(--wui-color-accent, #08f) 40%, transparent)` | `color-mix(in srgb, var(--wui-color-accent, #0a84ff) 62%, transparent)` | Focus indicator color, derived from the accent |
 
 **Shadow tokens:**
 
@@ -1570,7 +1702,7 @@ Every call returns the final id of that toast, so callers never branch on create
 | `target`    | `Element`                                                                                         | —                         | Used to find nearest theme-owned overlay root   |
 | `container` | `HTMLElement`                                                                                     | —                         | Explicit mount container (highest priority)     |
 
-**Upsert semantics** — what a second call with the same `id` does:
+**Upsert semantics**. What a second call with the same `id` does:
 
 | Target state                  | Result                                                                          |
 | ----------------------------- | ------------------------------------------------------------------------------- |
@@ -1578,22 +1710,22 @@ Every call returns the final id of that toast, so callers never branch on create
 | Still queued in the same tick | The queued options are patched and applied on mount; no second toast is created |
 | Closed, or still exiting      | A new toast is created; the one leaving finishes its exit animation on its own  |
 
-`duration` restarts the countdown only when it is passed explicitly (the one exception is a hover pause: the new value is recorded without starting the timer, and the countdown runs with it once the pointer leaves); `message`, `heading` and `type` are plain properties and leave the timer alone. The `error` shortcut's 5000 ms default is applied when the toast is created, so it does not count as an explicit `duration` — repeated `toast.error(msg, { id })` calls do not reset the countdown. Changing `position` moves the element to the new container and keeps the remaining time (via `moveBefore` where available, with a pause/resume fallback elsewhere); if the countdown already elapsed while the main thread was blocked, the fallback closes the toast on resume instead of leaving it open. `container` and `target` are read from the first call only — moving a toast to a different overlay root is not supported.
+`duration` restarts the countdown only when it is passed explicitly (the one exception is a hover pause: the new value is recorded without starting the timer, and the countdown runs with it once the pointer leaves); `message`, `heading` and `type` are plain properties and leave the timer alone. The `error` shortcut's 5000 ms default is applied when the toast is created, so it does not count as an explicit `duration`. Repeated `toast.error(msg, { id })` calls do not reset the countdown. Changing `position` moves the element to the new container and keeps the remaining time (via `moveBefore` where available, with a pause/resume fallback elsewhere); if the countdown already elapsed while the main thread was blocked, the fallback closes the toast on resume instead of leaving it open. `container` and `target` are read from the first call only. Moving a toast to a different overlay root is not supported.
 
-**Close semantics** — `toast.close(id)` covers every state a toast can be in, including the two before it becomes visible:
+**Close semantics.** `toast.close(id)` covers every state a toast can be in, including the two before it becomes visible:
 
 | Target state                       | Result                                                          |
 | ---------------------------------- | --------------------------------------------------------------- |
 | Visible                            | Plays the exit animation, then emits `toast-close`              |
 | Mounted, `show()` has not run yet  | No exit animation to play: emits `toast-close` immediately      |
-| Still queued in the same microtask | Dropped before it mounts — nothing appears, no event is emitted |
+| Still queued in the same microtask | Dropped before it mounts - nothing appears, no event is emitted |
 | Already exiting                    | No-op; that toast finishes its own exit                         |
 
 `toast.clear()` has the same scope: it drops queued entries and closes everything mounted.
 
 **Events:** `toast-close` (`CustomEvent<{ id: string; reason: 'auto' | 'manual' | 'programmatic' | 'clear' }>`)
 
-Hover pauses the auto-close timer (uses `pointerenter`/`pointerleave`); leaving resumes the **remaining** time instead of restarting the full duration. If the `pointerleave` is missed while paused — the pointer is dragged out of the window, or the element is moved or removed while hovered — a document-level `pointerover`/`pointerout`/`pointerleave` fallback resumes the countdown, so a hovered toast cannot stay on screen forever. Batch-mounts toasts created in the same microtask.
+Hover pauses the auto-close timer (uses `pointerenter`/`pointerleave`); leaving resumes the **remaining** time instead of restarting the full duration. If the `pointerleave` is missed while paused (the pointer is dragged out of the window, or the element is moved or removed while hovered), a document-level `pointerover`/`pointerout`/`pointerleave` fallback resumes the countdown, so a hovered toast cannot stay on screen forever. Batch-mounts toasts created in the same microtask.
 
 **CSS Custom Properties:**