@greypan/web-ui 3.0.1 → 5.0.0

package/README.md

@@ -31,6 +31,30 @@ import '@greypan/web-ui'
 
 ## Framework Setup
 
+### Cross-framework API conventions
+
+`web-ui-*` elements expose three surfaces. The **DOM / JavaScript API is the source of truth**: Properties use
+camelCase, Attributes use kebab-case, Events use kebab-case.
+
+| Surface   | Naming     | Examples                                      |
+| --------- | ---------- | --------------------------------------------- |
+| Property  | camelCase  | `open`, `sidebarCollapsed`, `noScrollLock`    |
+| Attribute | kebab-case | `open`, `sidebar-collapsed`, `no-scroll-lock` |
+| 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
+  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`;
+  use the camelCase property. The `.prop` modifier is only valid with the camelCase name
+  (`:sidebarCollapsed.prop="x"`). String/number values may stay on kebab-case attributes (`:max-height="120"`).
+  `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
+  them as properties. Kebab-case JSX props on a custom element are written as attributes.
+
 ### React
 
 Requires `@types/react >= 19` as optional peer dependency.
@@ -129,6 +153,21 @@ import '@greypan/web-ui/types/vue'
 </template>
 ```
 
+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"`
+produces the string `"false"`, which is truthy. Binding the camelCase name (`:sidebarCollapsed="false"`, or the
+`.prop` modifier) makes Vue write the DOM property directly:
+
+```vue
+<web-ui-layout
+  header-glow
+  :sidebarCollapsed="sidebarCollapsed"
+  :sidebarOpen="sidebarOpen"
+  @sidebar-collapsed-change="sidebarCollapsed = $event.detail.collapsed"
+  @sidebar-open-change="sidebarOpen = $event.detail.open"
+/>
+```
+
 Vue events are typed cast-free: `@input`/`@change` on value-bearing components resolve to the component emit, so
 `$event.target` is the component instance and `value`/`checked` are read directly. `$event.detail` keeps the
 `CustomEvent` payload type for kebab-case events like `open-change`. Named handlers annotate with
@@ -148,45 +187,85 @@ Components own their role and interaction state. Browser-native composed events
 remain the primary interaction API. Kebab-case custom events such as `open-change` describe user-originated component
 state changes; assigning a property programmatically does not emit them.
 
+### Cursor behavior
+
+Interactive controls use the native arrow cursor instead of the hand cursor. Disabled controls use `not-allowed`.
+Slider, switch, and segmented controls keep the arrow cursor during hover and press feedback, then switch to
+`grabbing` only while a drag is active. Dedicated drag handles and resize controls keep their specialized cursors.
+Cursor styles live inside Shadow DOM, so a plain document-level selector cannot override them.
+
+### Controlled state semantics
+
+`web-ui-*` elements do not use a single "controlled" contract; three distinct state models exist, chosen per component
+family by the nature of the interaction. Do not assume `controlled` means the same thing across components.
+
+**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
+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), 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
+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 after an API call succeeds), use the
+optimistic-update path: flip immediately, observe `change`, set the control's `loading` during the request (this blocks
+further interaction and shows a spinner), and on failure write the property back (`el.checked = false`) plus surface a
+toast. The flip-before-approval window is accepted; there is no `controlled` prop for a reject-before-flip contract.
+
+### Form-associated controls
+
+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.
+
 ## All Components
 
-| Category             | Component                                                 |
-| -------------------- | --------------------------------------------------------- |
-| **Form Controls**    | [`<web-ui-input>`](#web-ui-input)                         |
-|                      | [`<web-ui-textarea>`](#web-ui-textarea)                   |
-|                      | [`<web-ui-input-number>`](#web-ui-input-number)           |
-|                      | [`<web-ui-select>`](#web-ui-select)                       |
-|                      | [`<web-ui-autocomplete>`](#web-ui-autocomplete)           |
-|                      | [`<web-ui-slider>`](#web-ui-slider)                       |
-|                      | [`<web-ui-checkbox>`](#web-ui-checkbox)                   |
-|                      | [`<web-ui-radio>`](#web-ui-radio)                         |
-|                      | [`<web-ui-switch>`](#web-ui-switch)                       |
-|                      | [`<web-ui-segmented>`](#web-ui-segmented)                 |
-|                      | [`<web-ui-checkbox-group>`](#web-ui-checkbox-group)       |
-|                      | [`<web-ui-radio-group>`](#web-ui-radio-group)             |
-| **Buttons**          | [`<web-ui-button>`](#web-ui-button)                       |
-|                      | [`<web-ui-button-group>`](#web-ui-button-group)           |
-| **Overlay / Modal**  | [`<web-ui-dialog>`](#web-ui-dialog)                       |
-|                      | [`<web-ui-drawer>`](#web-ui-drawer)                       |
-| **Floating**         | [`<web-ui-popover>`](#web-ui-popover)                     |
-|                      | [`<web-ui-tooltip>`](#web-ui-tooltip)                     |
-|                      | [`<web-ui-context-menu>`](#web-ui-context-menu)           |
-| **Menu**             | [`<web-ui-dropdown>`](#web-ui-dropdown)                   |
-|                      | [`<web-ui-dropdown-item>`](#web-ui-dropdown-item)         |
-|                      | [`<web-ui-dropdown-divider>`](#web-ui-dropdown-divider)   |
-|                      | [`<web-ui-dropdown-header>`](#web-ui-dropdown-header)     |
-| **Data Display**     | [`<web-ui-avatar>`](#web-ui-avatar)                       |
-|                      | [`<web-ui-badge>`](#web-ui-badge)                         |
-|                      | [`<web-ui-empty>`](#web-ui-empty)                         |
-|                      | [`<web-ui-icon>`](#web-ui-icon)                           |
-|                      | [`<web-ui-spinner>`](#web-ui-spinner)                     |
-| **Layout & Utility** | [`<web-ui-layout>`](#web-ui-layout)                       |
-|                      | [`<web-ui-back-top>`](#web-ui-back-top)                   |
-|                      | [`<web-ui-svg-draw-lines>`](#web-ui-svg-draw-lines)       |
-|                      | [`<web-ui-theme>`](#web-ui-theme)                         |
-| **Notification**     | [`<web-ui-toast>`](#web-ui-toast)                         |
-| **Sub-items**        | [`<web-ui-option>`](#web-ui-option)                       |
-|                      | [`<web-ui-segmented-trigger>`](#web-ui-segmented-trigger) |
+| Category               | Component                                                 |
+| ---------------------- | --------------------------------------------------------- |
+| **Form Controls**      | [`<web-ui-input>`](#web-ui-input)                         |
+|                        | [`<web-ui-textarea>`](#web-ui-textarea)                   |
+|                        | [`<web-ui-input-number>`](#web-ui-input-number)           |
+|                        | [`<web-ui-select>`](#web-ui-select)                       |
+|                        | [`<web-ui-autocomplete>`](#web-ui-autocomplete)           |
+|                        | [`<web-ui-slider>`](#web-ui-slider)                       |
+|                        | [`<web-ui-checkbox>`](#web-ui-checkbox)                   |
+|                        | [`<web-ui-radio>`](#web-ui-radio)                         |
+|                        | [`<web-ui-switch>`](#web-ui-switch)                       |
+|                        | [`<web-ui-segmented>`](#web-ui-segmented)                 |
+|                        | [`<web-ui-checkbox-group>`](#web-ui-checkbox-group)       |
+|                        | [`<web-ui-radio-group>`](#web-ui-radio-group)             |
+| **Buttons**            | [`<web-ui-button>`](#web-ui-button)                       |
+|                        | [`<web-ui-button-group>`](#web-ui-button-group)           |
+| **Overlay / Modal**    | [`<web-ui-dialog>`](#web-ui-dialog)                       |
+|                        | [`<web-ui-drawer>`](#web-ui-drawer)                       |
+| **In-flow Disclosure** | [`<web-ui-collapse>`](#web-ui-collapse)                   |
+| **Floating**           | [`<web-ui-popover>`](#web-ui-popover)                     |
+|                        | [`<web-ui-tooltip>`](#web-ui-tooltip)                     |
+|                        | [`<web-ui-context-menu>`](#web-ui-context-menu)           |
+| **Menu**               | [`<web-ui-dropdown>`](#web-ui-dropdown)                   |
+|                        | [`<web-ui-dropdown-item>`](#web-ui-dropdown-item)         |
+|                        | [`<web-ui-dropdown-divider>`](#web-ui-dropdown-divider)   |
+|                        | [`<web-ui-dropdown-header>`](#web-ui-dropdown-header)     |
+| **Data Display**       | [`<web-ui-avatar>`](#web-ui-avatar)                       |
+|                        | [`<web-ui-badge>`](#web-ui-badge)                         |
+|                        | [`<web-ui-empty>`](#web-ui-empty)                         |
+|                        | [`<web-ui-icon>`](#web-ui-icon)                           |
+|                        | [`<web-ui-spinner>`](#web-ui-spinner)                     |
+| **Layout & Utility**   | [`<web-ui-layout>`](#web-ui-layout)                       |
+|                        | [`<web-ui-back-top>`](#web-ui-back-top)                   |
+|                        | [`<web-ui-svg-draw-lines>`](#web-ui-svg-draw-lines)       |
+|                        | [`<web-ui-theme>`](#web-ui-theme)                         |
+| **Notification**       | [`<web-ui-toast>`](#web-ui-toast)                         |
+| **Sub-items**          | [`<web-ui-option>`](#web-ui-option)                       |
+|                        | [`<web-ui-segmented-trigger>`](#web-ui-segmented-trigger) |
 
 ## API Reference
 
@@ -198,46 +277,52 @@ Form controls implement `static formAssociated = true` and integrate with native
 
 Text input with clearable, prefix/suffix slots.
 
-| Attribute     | Type      | Default  | Description         |
-| ------------- | --------- | -------- | ------------------- |
-| `value`       | `string`  | `''`     | Input value         |
-| `type`        | `string`  | `'text'` | HTML input type     |
-| `placeholder` | `string`  | `''`     | Placeholder text    |
-| `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`  | No border           |
-| `aria-label`  | `string`  | —        | Accessible label    |
+| Attribute     | Type      | Default  | Description                                                                                       |
+| ------------- | --------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `value`       | `string`  | `''`     | Input value                                                                                       |
+| `type`        | `string`  | `'text'` | HTML input type                                                                                   |
+| `placeholder` | `string`  | `''`     | Placeholder text                                                                                  |
+| `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 |
+| `aria-label`  | `string`  | —        | Accessible label                                                                                  |
 
 **Events:** `input`, `change`, `focus`, `blur`
 
 **Slots:** `prefix`, `default`, `suffix`
 
+**CSS Custom Properties:**
+
+| Property                  | Default                          | Description        |
+| ------------------------- | -------------------------------- | ------------------ |
+| `--wui-input-clear-color` | `var(--wui-color-text-tertiary)` | Clear button color |
+
 #### `<web-ui-textarea>`
 
 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` | No border                                 |
-| `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                                                                                |
+| `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`
 
@@ -245,6 +330,13 @@ Multi-line text input with auto-resize.
 
 **Slots:** `prefix`, `suffix`
 
+**CSS Custom Properties:**
+
+| Property                     | Default                          | Description        |
+| ---------------------------- | -------------------------------- | ------------------ |
+| `--wui-textarea-width`       | `200px`                          | Textarea width     |
+| `--wui-textarea-clear-color` | `var(--wui-color-text-tertiary)` | Clear button color |
+
 #### `<web-ui-input-number>`
 
 Numeric input with step buttons and keyboard control.
@@ -289,32 +381,60 @@ Select dropdown with option items, keyboard navigation, and portal support.
 
 Child `<web-ui-option>` elements register via `option-register` / `option-unregister` events. Supports ArrowDown/ArrowUp/Enter/Escape keyboard navigation.
 
+**CSS Custom Properties:**
+
+| Property                  | Default                            | Description                     |
+| ------------------------- | ---------------------------------- | ------------------------------- |
+| `--wui-select-max-width`  | `500px`                            | Dropdown max width              |
+| `--wui-select-max-height` | `200px`                            | Dropdown scroll area max height |
+| `--wui-overlay-min-width` | `200px`                            | Dropdown min width              |
+| `--wui-select-bg-hover`   | `--wui-color-surface-glass-hover`  | Trigger hover background        |
+| `--wui-select-bg-active`  | `--wui-color-surface-glass-active` | Trigger pressed/open background |
+
+Portal panels mirror these variables from the host element when created; change the host before opening a portal panel for a new value to apply.
+
 #### `<web-ui-autocomplete>`
 
 Editable combobox with input filtering and single option selection.
 
-| Attribute          | Type                               | Default      | Description                                                               |
-| ------------------ | ---------------------------------- | ------------ | ------------------------------------------------------------------------- |
-| `value`            | `string`                           | `''`         | Current input text (form value)                                           |
-| `selected-value`   | `string`                           | `''`         | Value of the option exactly matching the input label (derived, read-only) |
-| `placeholder`      | `string`                           | `''`         | Placeholder text                                                          |
-| `filter`           | `'none' \| 'prefix' \| 'contains'` | `'contains'` | Candidate filtering mode (matched against option label)                   |
-| `name`             | `string`                           | `''`         | Form field name                                                           |
-| `disabled`         | `boolean`                          | `false`      | Disabled state                                                            |
-| `readonly`         | `boolean`                          | `false`      | Read-only state (no typing, no dropdown)                                  |
-| `required`         | `boolean`                          | `false`      | Required validation                                                       |
-| `portal`           | `boolean`                          | `false`      | Render dropdown in theme overlay                                          |
-| `no-scroll-lock`   | `boolean`                          | `false`      | Do not lock body scroll when open                                         |
-| `overlayContainer` | `HTMLElement \| () => HTMLElement` | —            | Explicit portal container                                                 |
-| `aria-label`       | `string`                           | —            | Accessible name                                                           |
-| `aria-labelledby`  | `string`                           | —            | Accessible name references                                                |
+| Attribute            | Type                               | Default      | Description                                                                                       |
+| -------------------- | ---------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
+| `value`              | `string`                           | `''`         | Current input text (form value)                                                                   |
+| `selected-value`     | `string`                           | `''`         | Value of the enabled option exactly matching the input label (derived, read-only)                 |
+| `placeholder`        | `string`                           | `''`         | Placeholder text                                                                                  |
+| `borderless`         | `boolean`                          | `false`      | Ghost form: removes border, background, and shadow; keeps padding, height metrics, and focus ring |
+| `filter`             | `'none' \| 'prefix' \| 'contains'` | `'contains'` | Candidate filtering mode (matched against option label)                                           |
+| `name`               | `string`                           | `''`         | Form field name                                                                                   |
+| `disabled`           | `boolean`                          | `false`      | Disabled state                                                                                    |
+| `readonly`           | `boolean`                          | `false`      | Read-only state (no typing, no dropdown)                                                          |
+| `required`           | `boolean`                          | `false`      | Required validation                                                                               |
+| `allow-custom-value` | `boolean`                          | `false`      | Allow Enter to submit a custom value that is not among candidates                                 |
+| `portal`             | `boolean`                          | `false`      | Render dropdown in theme overlay                                                                  |
+| `no-scroll-lock`     | `boolean`                          | `false`      | Do not lock body scroll when open                                                                 |
+| `overlayContainer`   | `HTMLElement \| () => HTMLElement` | —            | Explicit portal container                                                                         |
+| `aria-label`         | `string`                           | —            | Accessible name                                                                                   |
+| `aria-labelledby`    | `string`                           | —            | Accessible name references                                                                        |
 
 **Events:** `input`, `change`, `focus`, `blur`, `open-change` (`CustomEvent<{ open: boolean }>`)
 
-**Slots:** `default` (project `<web-ui-option>` elements)
+**Slots:** `default` (project `<web-ui-option>` elements), `empty` (replace the “no matches” state; falls back to “No matches”)
 
 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.
 
+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.
+
+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.
+
+**CSS Custom Properties:**
+
+| Property                        | Default | Description                     |
+| ------------------------------- | ------- | ------------------------------- |
+| `--wui-autocomplete-max-width`  | `500px` | Dropdown max width              |
+| `--wui-autocomplete-max-height` | `200px` | Dropdown scroll area max height |
+| `--wui-overlay-min-width`       | `200px` | Dropdown minimum width          |
+
+Portal panels mirror these variables from the host element when created; change the host before opening a portal panel for a new value to apply.
+
 #### `<web-ui-slider>`
 
 Range slider with marks and vertical orientation.
@@ -337,6 +457,18 @@ Range slider with marks and vertical orientation.
 
 Supports ArrowLeft/Right/Up/Down, Home/End, PageUp/PageDown keyboard navigation. Uses pointer capture for drag interaction across mouse, touch, and pen.
 
+**CSS Custom Properties:**
+
+| Property                       | Default                             | Description            |
+| ------------------------------ | ----------------------------------- | ---------------------- |
+| `--wui-slider-width`           | `200px`                             | Slider width           |
+| `--wui-slider-vertical-height` | `200px`                             | Vertical slider height |
+| `--wui-slider-height`          | `var(--wui-slider-track-size, 6px)` | Track thickness        |
+| `--wui-slider-track-size`      | `6px`                               | Track size             |
+| `--wui-slider-thumb-width`     | `30px`                              | Thumb width            |
+| `--wui-slider-thumb-height`    | `20px`                              | Thumb height           |
+| `--wui-slider-marks-inset`     | `0`                                 | Marks inset from edges |
+
 #### `<web-ui-checkbox>`
 
 Individual checkbox.
@@ -451,16 +583,16 @@ Radio group managing single selection.
 
 Styled button with variants and loading state.
 
-| Attribute    | Type                                                         | Default    | Description                                       |
-| ------------ | ------------------------------------------------------------ | ---------- | ------------------------------------------------- |
-| `variant`    | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'`  | Button variant                                    |
-| `type`       | `'button' \| 'submit' \| 'reset'`                            | `'button'` | Inner-button type; invalid values become `button` |
-| `disabled`   | `boolean`                                                    | `false`    | Disabled state                                    |
-| `loading`    | `boolean`                                                    | `false`    | Loading spinner                                   |
-| `full`       | `boolean`                                                    | `false`    | Full width                                        |
-| `icon`       | `boolean`                                                    | `false`    | Icon-only mode                                    |
-| `size`       | `string`                                                     | `''`       | Size format `height` or `heightxwidth`            |
-| `aria-label` | `string`                                                     | —          | Accessible label (delegated to inner button)      |
+| Attribute    | Type                                                         | Default    | Description                                                             |
+| ------------ | ------------------------------------------------------------ | ---------- | ----------------------------------------------------------------------- |
+| `variant`    | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'`  | Button variant                                                          |
+| `type`       | `'button' \| 'submit' \| 'reset'`                            | `'button'` | Inner-button type; invalid values become `button`                       |
+| `disabled`   | `boolean`                                                    | `false`    | Disabled state                                                          |
+| `loading`    | `boolean`                                                    | `false`    | Loading spinner; with `icon`, the spinner replaces the icon content     |
+| `full`       | `boolean`                                                    | `false`    | Full width                                                              |
+| `icon`       | `boolean`                                                    | `false`    | Icon-only mode                                                          |
+| `size`       | `string`                                                     | `''`       | Button height in px (icon mode: also sets min-width for square default) |
+| `aria-label` | `string`                                                     | —          | Accessible label (delegated to inner button)                            |
 
 **Events:** standard `click`
 
@@ -471,6 +603,21 @@ form-associated control when external form submission behavior is required.
 
 Disabled and loading states 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.
+
+**CSS Custom Properties:**
+
+| Property                 | Default       | Description                             |
+| ------------------------ | ------------- | --------------------------------------- |
+| `--wui-button-width`     | `max-content` | Button width                            |
+| `--wui-button-px`        | `12px`        | Horizontal padding                      |
+| `--wui-button-gap`       | `8px`         | Gap between prefix/default/suffix slots |
+| `--wui-button-color`     | variant-based | Button text color                       |
+| `--wui-button-bg`        | variant-based | Button background color                 |
+| `--wui-button-bg-hover`  | variant-based | Button hover background                 |
+| `--wui-button-bg-active` | variant-based | Button active background                |
+
 #### `<web-ui-button-group>`
 
 Button group that manages child button layout and direction.
@@ -481,7 +628,7 @@ Button group that manages child button layout and direction.
 
 **Slots:** `default` (project `<web-ui-button>` elements)
 
-Propagates `direction` attribute to child buttons.
+Applies the direction to the grouped button layout without changing child button attributes.
 
 ---
 
@@ -491,41 +638,105 @@ Propagates `direction` attribute to child buttons.
 
 Modal dialog using native `<dialog>` with `showModal()`.
 
-| Attribute           | Type      | Default | Description                         |
-| ------------------- | --------- | ------- | ----------------------------------- |
-| `open`              | `boolean` | `false` | Dialog visibility                   |
-| `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 |
+| Attribute           | Type      | Default | Description                                                                    |
+| ------------------- | --------- | ------- | ------------------------------------------------------------------------------ |
+| `open`              | `boolean` | `false` | Dialog visibility                                                              |
+| `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                                            |
+| `controlled`        | `boolean` | `false` | Escape and backdrop only request `open=false`; the consumer must update `open` |
 
-**Events:** `open-change` (`CustomEvent<{ open: boolean }>`)
+**Events:** `open-change` (`CustomEvent<{ open: boolean }>`). With `controlled`, Escape and backdrop clicks only request `open=false` and the dialog stays open until the consumer writes `open=false`. Programmatic APIs (`showModal()`, `close()`, assigning `open`) stay direct and never emit. Native dialog closure (e.g. form `method="dialog"`) is restored to the controlled open state and re-emits the request.
 
 **Slots:** `body`, `title`, `default`, `footer`
 
 **Methods:** `showModal()`, `close()`
 
-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.
+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.
+
+**CSS Custom Properties:**
+
+| Property                  | Default                            | Description                                                    |
+| ------------------------- | ---------------------------------- | -------------------------------------------------------------- |
+| `--wui-dialog-max-width`  | `360px`                            | Dialog max width                                               |
+| `--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)` |
 
 #### `<web-ui-drawer>`
 
-Side drawer using native `<dialog>` with closing animation.
+Side drawer using native `<dialog>` with closing animation. In non-headless mode the drawer renders as a floating rounded card inset from all viewport edges (matching the layout sidebar's card language), so elastic drag distances read as margin changes rather than gaps.
 
-| Attribute           | Type                                     | Default   | Description                               |
-| ------------------- | ---------------------------------------- | --------- | ----------------------------------------- |
-| `open`              | `boolean`                                | `false`   | Drawer visibility                         |
-| `placement`         | `'right' \| 'left' \| 'top' \| 'bottom'` | `'right'` | Slide-in direction                        |
-| `heading`           | `string`                                 | `''`      | Title text (fallback when no header slot) |
-| `closable`          | `boolean`                                | `false`   | Show 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            |
+| Attribute           | Type                                     | Default   | Description                                                                       |
+| ------------------- | ---------------------------------------- | --------- | --------------------------------------------------------------------------------- |
+| `open`              | `boolean`                                | `false`   | Drawer visibility                                                                 |
+| `placement`         | `'right' \| 'left' \| 'top' \| 'bottom'` | `'right'` | Slide-in direction                                                                |
+| `heading`           | `string`                                 | `''`      | Title text (fallback when no header slot)                                         |
+| `closable`          | `boolean`                                | `false`   | Show 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                                                    |
+| `controlled`        | `boolean`                                | `false`   | User close actions only request `open=false`; the consumer must update `open`     |
+| `headless`          | `boolean`                                | `false`   | Keep only overlay behavior and render the default slot without built-in drawer UI |
+| `dialog-label`      | `string`                                 | `''`      | Accessible name for the internal native dialog; required in headless mode         |
+| `draggable`         | `boolean`                                | `false`   | Show a drag bar on the inner edge for drag-to-close gestures                      |
 
-**Events:** `open-change` (`CustomEvent<{ open: boolean }>`)
+**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`
+**Slots:** `header`, `default`, `footer` — with `headless`, only the `default` slot is rendered.
 
 **Methods:** `show()`, `close()`
 
-Closing keeps the native dialog in the top layer until the `--wui-duration-drawer` transition completes (280ms by default), then calls `dialog.close()`. Escape always follows this close path; `no-backdrop-close` controls backdrop clicks only.
+`headless` keeps the native dialog, backdrop, placement animation, Escape/backdrop close behavior, and scroll locking. It does not render the built-in glass body, header, close button, or footer; style the default-slot content completely in the consumer.
+
+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.
+
+**Drag to close:** With `draggable`, a gray capsule drag bar 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. Dragging follows the pointer in real time (backdrop fades proportionally); releasing past ~1/3 of the drawer size or with a fast closing flick springs the drawer shut, otherwise it springs back open. The close direction is placement-aware. With `controlled`, release past the threshold only emits `open-change(false)`; the drawer holds at the closed position briefly (120ms write-back window) and springs 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 snaps instantly without spring animation.
+
+**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`     | `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                                                          |
+
+---
+
+### In-flow Disclosure
+
+#### `<web-ui-collapse>`
+
+In-flow expand/collapse container with animated height (or width) transition. Single element with two slots; no portal, no scroll lock, no focus management.
+
+| Attribute      | Type      | Default | Description                                                                                                              |
+| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `open`         | `boolean` | `false` | Expanded state; self-managed on interaction, `open-change` emits only for user-originated toggles                        |
+| `disabled`     | `boolean` | `false` | Ignores trigger clicks and sets `aria-disabled` on the trigger element; expanded content is kept                         |
+| `horizontal`   | `boolean` | `false` | Animate width instead of height                                                                                          |
+| `keep-mounted` | `boolean` | `false` | Closed state keeps the content in the 0fr track with `inert` (scroll position and layout measurable) instead of `hidden` |
+
+**Events:** `open-change` (`CustomEvent<{ open: boolean }>`). Emitted only for user-originated toggles (trigger click). Programmatic writes (`open`, `show()`, `close()`, `toggle()`) never emit. Nested collapses: an inner `open-change` bubbles through the outer root (composed event); distinguish by `event.target`.
+
+**Slots:** `default` (trigger) + `content` (collapsible content)
+
+**Methods:** `show()`, `close()`, `toggle()`
+
+```html
+<web-ui-collapse>
+  <button type="button">Toggle me</button>
+  <div slot="content">Collapsible content</div>
+</web-ui-collapse>
+```
+
+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.
+
+**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.
+
+**Known limitations:** the `horizontal` animation reflows content while width changes.
 
 ---
 
@@ -553,6 +764,8 @@ Popover overlay anchored to trigger element.
 
 Hover mode uses `pointerenter`/`pointerleave` with delay. Click mode toggles on trigger click. Manual mode only responds to imperative `show()`/`close()`.
 
+**Trigger ARIA:** open/close state is written back to the trigger element: `aria-expanded` and `aria-controls` (pointing at the panel) are set on the first assigned element in the `trigger` slot (the wrapper retains them for backward compatibility). Put an interactive element (native button, `web-ui-button`) in the trigger slot.
+
 #### `<web-ui-tooltip>`
 
 Tooltip overlay using pointer/focus triggers.
@@ -573,7 +786,14 @@ Tooltip overlay using pointer/focus triggers.
 
 **Slots:** `default` (trigger), `content` (tooltip panel)
 
-`open` is a controlled visibility property. Pointer/focus triggers update it, and direct updates synchronize the local or portal panel. Adjacent tooltips open immediately after the first tooltip is visible; pointer/focus triggers otherwise use delay timers.
+`open` is a self-managed visibility property. Pointer/focus triggers update it, and direct property writes synchronize the local or portal panel; `open-change` emits only for user-originated open/close. Adjacent tooltips open immediately after the first tooltip is visible; pointer/focus triggers otherwise use delay timers.
+
+**CSS Custom Properties:**
+
+| Property                  | Default | Description       |
+| ------------------------- | ------- | ----------------- |
+| `--wui-tooltip-max-width` | `240px` | Tooltip max width |
+| `--wui-tooltip-font-size` | `13px`  | Tooltip font size |
 
 #### `<web-ui-context-menu>`
 
@@ -592,6 +812,8 @@ Right-click context menu.
 
 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, 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.
+
 ---
 
 ### Menu
@@ -617,6 +839,8 @@ Dropdown menu with multi-level submenu support.
 
 Items: `<web-ui-dropdown-item>`, `<web-ui-dropdown-divider>`, `<web-ui-dropdown-header>`. Submenus via `submenu` attribute on `<web-ui-dropdown-item>`. Full keyboard navigation (Arrow keys, Home, End, Enter, Space, Escape).
 
+**Trigger ARIA:** `aria-haspopup="menu"`, `aria-expanded` and `aria-controls` (pointing at the root menu panel) are written back to the first assigned element in the `trigger` slot. Put an interactive element in the trigger slot.
+
 #### `<web-ui-dropdown-item>`
 
 Menu item for dropdown or context-menu.
@@ -687,6 +911,17 @@ Empty state placeholder.
 
 **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) |
+
 #### `<web-ui-icon>`
 
 Icon renderer using Iconify data objects.
@@ -705,6 +940,12 @@ import { lucideLoaderCircle } from '@greypan/web-ui/icons'
 html`<web-ui-icon .icon=${lucideLoaderCircle} spin />`
 ```
 
+**CSS Custom Properties:**
+
+| Property           | Default   | Description |
+| ------------------ | --------- | ----------- |
+| `--wui-icon-color` | `inherit` | Icon color  |
+
 #### `<web-ui-spinner>`
 
 Loading spinner.
@@ -737,14 +978,43 @@ WebUiSpinner.hide() // hide
 
 #### `<web-ui-layout>`
 
-Page layout grid.
+Responsive page layout with an optional full-width banner, a collapsible desktop sidebar, and a headless-drawer mobile sidebar. The page itself scrolls; the desktop sidebar and header stick to the viewport after the banner scrolls away.
+
+| Attribute           | Type      | Default   | Description                                                                                        |
+| ------------------- | --------- | --------- | -------------------------------------------------------------------------------------------------- |
+| `sidebar-collapsed` | `boolean` | `false`   | Controlled desktop sidebar collapsed state                                                         |
+| `sidebar-open`      | `boolean` | `false`   | Controlled mobile sidebar drawer open state                                                        |
+| `header-glow`       | `boolean` | `false`   | Decorative Header background glow behind slot content                                              |
+| `sidebar-width`     | `string`  | `'240px'` | Expanded desktop and mobile sidebar width                                                          |
+| `collapsed-width`   | `string`  | `'72px'`  | Collapsed desktop sidebar width                                                                    |
+| `sidebar-resizable` | `boolean` | `false`   | Enable drag-to-resize on the desktop sidebar edge                                                  |
+| `sidebar-min-width` | `string`  | —         | Resize lower bound (px); falls back to `collapsed-width`                                           |
+| `sidebar-max-width` | `string`  | —         | Resize upper bound (px); clamped to half the viewport, which always wins over the configured value |
+
+**Events:** `sidebar-collapsed-change` (`CustomEvent<{ collapsed: boolean }>`) requests a desktop collapse-state update. `sidebar-open-change` (`CustomEvent<{ open: boolean }>`) requests a mobile drawer open-state update. `sidebar-width-change` (`CustomEvent<{ width: string }>`) requests a sidebar width update after a resize drag ends. Consumers must write the requested value back to the corresponding controlled property.
+
+**Sidebar resize:** With `sidebar-resizable`, a resize handle appears on the desktop sidebar's right edge (hidden while collapsed). Hovering or dragging shows a 3px accent vertical line with a `col-resize` cursor. Dragging updates the width in real time (transition suppressed, clamped to `[min, max]` and the viewport); releasing emits `sidebar-width-change` with the final pixel width and returns control to the `sidebar-width` property once the consumer writes it back. `pointercancel` restores the property-controlled width without emitting. The handle is keyboard-operable (WAI-ARIA splitter pattern): focus it and use ←/→ to step by 16px (Shift for 64px), Home/End to jump to min/max, Enter to commit via the same `sidebar-width-change` request, and Escape to revert an uncommitted adjustment. The mobile drawer always supports drag-to-close via its built-in `draggable` drawer.
+
+| Slot      | Description                                                                               |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `banner`  | Optional full-width banner above the layout body                                          |
+| `header`  | Sticky content-area header                                                                |
+| `sidebar` | Sidebar-card content. The consumer owns its internal fixed regions and scroll containers. |
+| `default` | Main content                                                                              |
+| `tabbar`  | Bottom tab bar                                                                            |
+
+`web-ui-layout` constrains the sidebar card and owns the desktop toggle area, but does not create a sidebar scrollport. To make only part of the sidebar scroll, make the `sidebar` slot root a `height: 100%; min-height: 0` flex column and apply `overflow-y: auto` to the intended child. This keeps consumer-defined headers and footers fixed without adding extra public slots.
+
+At `640px` and below, the sidebar becomes a headless `web-ui-drawer`. The consumer content is rendered in the same rounded sidebar card; 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`.
 
-| Slot      | Description     |
-| --------- | --------------- |
-| `header`  | Sticky top bar  |
-| `default` | Main content    |
-| `sidebar` | Side navigation |
-| `tabbar`  | Bottom tab bar  |
+`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`).
+
+**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           |
 
 #### `<web-ui-back-top>`
 
@@ -761,10 +1031,21 @@ Scroll-to-top button.
 
 **Methods:** `toTop()`
 
-**Positioning:** With `scrollTarget` as `window`, the button is fixed to the viewport corner. With `scrollTarget` as an `HTMLElement`, place the element inside that container and the button floats at the container's bottom corner via `position: sticky`. Offsets follow the `--web-ui-back-top-top/right/bottom/left` CSS variables.
+**Positioning:** With `scrollTarget` as `window`, the button is fixed to the viewport corner. With `scrollTarget` as an `HTMLElement`, place the element inside that container and the button floats at the container's bottom corner via `position: sticky`. Offsets follow the `--wui-back-top-top/right/bottom/left` CSS variables.
 
 Role: `button`, keyboard Enter scrolls to top.
 
+**CSS Custom Properties:**
+
+| Property                  | Default                          | Description   |
+| ------------------------- | -------------------------------- | ------------- |
+| `--wui-back-top-position` | `fixed`                          | CSS position  |
+| `--wui-back-top-z-index`  | `var(--wui-layer-auxiliary, 20)` | Z-index       |
+| `--wui-back-top-top`      | `auto`                           | Top offset    |
+| `--wui-back-top-right`    | `20px`                           | Right offset  |
+| `--wui-back-top-bottom`   | `20px`                           | Bottom offset |
+| `--wui-back-top-left`     | `auto`                           | Left offset   |
+
 #### `<web-ui-svg-draw-lines>`
 
 SVG line drawing animation using `stroke-dashoffset`. Animates geometry in-place — no cloning, no DOM manipulation.
@@ -793,7 +1074,84 @@ Theme provider defining CSS custom property tokens.
 
 **Methods:** `getOverlayRoot()` — returns the portal overlay container
 
-Defines `--wui-color-*`, `--wui-shadow-*`, `--wui-layer-*`, and motion tokens. Motion tokens are stable and may be overridden per theme scope: `--wui-duration-press`, `--wui-duration-feedback`, `--wui-duration-trigger`, `--wui-duration-focus`, `--wui-duration-menu-enter`, `--wui-duration-menu-exit`, `--wui-duration-overlay-enter`, `--wui-duration-overlay-exit`, `--wui-duration-drawer-enter`, `--wui-duration-drawer-exit`, `--wui-ease-enter`, `--wui-ease-slide`, and `--wui-scale-enter`. `motion="system"` follows `prefers-reduced-motion`; use `motion="reduced"` to reduce animation in a scope or `motion="full"` in a nested theme to restore the normal token values. System appearance follows `prefers-color-scheme`.
+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`.
+
+**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                            |
+
+**Layer tokens:**
+
+| 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    |
+| `--wui-layer-banner`         | `30`    | Banners                      |
+| `--wui-layer-tabbar`         | `40`    | Tab bars                     |
+| `--wui-layer-sidebar`        | `50`    | Sidebars                     |
+| `--wui-layer-menu`           | `100`   | Menus and floating panels    |
+| `--wui-layer-menu-nested`    | `110`   | Nested menus                 |
+| `--wui-layer-toast`          | `200`   | Toasts                       |
+| `--wui-layer-loading`        | `300`   | Blocking loading surfaces    |
+
+**Motion tokens:** duration defaults are `--wui-duration-press: 80ms`, `--wui-duration-feedback: 100ms`, `--wui-duration-trigger: 160ms`, `--wui-duration-focus: 200ms`, `--wui-duration-menu-enter: 140ms`, `--wui-duration-menu-exit: 100ms`, `--wui-duration-overlay-enter: 180ms`, `--wui-duration-overlay-exit: 140ms`, `--wui-duration-drawer-enter: 280ms`, `--wui-duration-drawer-exit: 240ms`, `--wui-duration-drawer-nested: 450ms`, `--wui-duration-collapse-enter: 200ms`, `--wui-duration-collapse-exit: 160ms`, `--wui-duration-layout: 200ms`. Easing tokens are `--wui-ease-enter` and `--wui-ease-slide`; enter scale is `--wui-scale-enter: 0.97`. Hover/active background feedback switches instantly with no transition; checked/pressed/focus and overlay enter/exit transitions are unaffected.
+
+**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(30 30 32 / 0.92)`                                       | 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-segmented`    | `#e5e5ea`                                                    | `#3a3a3c`                                                    | Segmented track surface         |
+| `--wui-color-surface-selected`     | `#fff`                                                       | `#5c5c5e`                                                    | Segmented selected indicator    |
+| `--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.08)`                                    | `rgb(255 255 255 / 0.2)`                                     | Glass corner sheen on border    |
+| `--wui-color-glass-shade`          | `rgb(0 0 0 / 0.06)`                                          | `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           |
+
+**Shadow tokens:**
+
+| Property               | Light default                    | Dark default                    | Description                 |
+| ---------------------- | -------------------------------- | ------------------------------- | --------------------------- |
+| `--wui-shadow-overlay` | `2px 16px 40px rgb(0 0 0 / 0.4)` | `0 18px 48px rgb(0 0 0 / 0.48)` | Modal and drawer shadow     |
+| `--wui-shadow-panel`   | `0 3px 9px rgb(0 0 0 / 0.27)`    | `0 4px 16px rgb(0 0 0 / 0.32)`  | Small floating panel shadow |
+| `--wui-shadow-glass`   | four-layer diffuse shadow        | `0 8px 24px rgb(0 0 0 / 0.08)`  | Base liquid glass shadow    |
+
+**Glass effect tokens:** `--wui-glass-brightness` is `1.06` in light mode and `1.02` in dark mode. `--wui-glass-corner-radius` defaults to `32px`; glass components set it from their own corner radius so the diagonal border lighting aligns with their shape.
+
+**Internal tokens:** variables prefixed `--wui-internal-*` are private wiring between shadow DOM parts; they are not part of the public token API and must not be overridden by consumers.
 
 ---
 
@@ -847,6 +1205,13 @@ toast.updateMessage(id, { message: 'Upload 60% complete', heading: 'Uploading' }
 
 Hover pauses auto-close timer (uses `pointerenter`/`pointerleave`). Batch-mounts toasts created in the same microtask.
 
+**CSS Custom Properties:**
+
+| Property                        | Default | Description                                        |
+| ------------------------------- | ------- | -------------------------------------------------- |
+| `--wui-toast-viewport-gap`      | `16px`  | Visible distance between toasts and viewport edges |
+| `--wui-toast-container-padding` | `40px`  | Container padding reserved for diffuse shadows     |
+
 ---
 
 ### Sub-items
@@ -866,6 +1231,12 @@ Selection option for `<web-ui-select>`.
 
 Not form-associated (child of select, not independent submit).
 
+**CSS Custom Properties:**
+
+| Property                     | Default | Description                                   |
+| ---------------------------- | ------- | --------------------------------------------- |
+| `--wui-option-check-display` | `block` | Display mode of the selection check indicator |
+
 #### `<web-ui-segmented-trigger>`
 
 Segment trigger for `<web-ui-segmented>`.
@@ -879,3 +1250,11 @@ Segment trigger for `<web-ui-segmented>`.
 **Events:** `change`
 
 Not form-associated (child of segmented, not independent submit).
+
+**CSS Custom Properties:**
+
+| Property                            | Default                          | Description               |
+| ----------------------------------- | -------------------------------- | ------------------------- |
+| `--wui-segmented-trigger-px`        | `12px`                           | Horizontal padding        |
+| `--wui-segmented-trigger-bg-hover`  | `--wui-color-state-layer-hover`  | Trigger hover background  |
+| `--wui-segmented-trigger-bg-active` | `--wui-color-state-layer-active` | Trigger active background |