@greypan/web-ui 3.0.1 → 5.0.0

package/README.CN.md

@@ -31,6 +31,29 @@ import '@greypan/web-ui'
 
 ## 框架集成
 
+### 跨框架 API 约定
+
+`web-ui-*` 元素暴露三面 API，**DOM / JavaScript API 是事实来源**：Property 使用 camelCase，Attribute 使用
+kebab-case，Event 使用 kebab-case。
+
+| 表面      | 命名       | 示例                                          |
+| --------- | ---------- | --------------------------------------------- |
+| Property  | camelCase  | `open`、`sidebarCollapsed`、`noScrollLock`    |
+| Attribute | kebab-case | `open`、`sidebar-collapsed`、`no-scroll-lock` |
+| Event     | kebab-case | `open-change`、`sidebar-collapsed-change`     |
+
+- **布尔 Attribute** 遵循原生 HTML 存在语义：不存在 → `false`，存在 → `true`。框架绑定写入的
+  `disabled="false"` 是字符串 `"false"`，会被视为 true——**动态布尔必须绑定 Property**（camelCase），
+  才能把 `false` 写成真实 property。
+- **Vue**：动态绑定必须走 **Property**，使用 camelCase 属性名（`:sidebarCollapsed="x"`、`:open="x"`）。
+  kebab-case 绑定（`:sidebar-collapsed="x"`）会被写成字符串 attribute，无法表达 `false`，请使用 camelCase
+  property。`.prop` 修饰符只在 camelCase 属性名下有效（`:sidebarCollapsed.prop="x"`）。String/Number 值可
+  保留 kebab-case attribute（`:max-height="120"`）。带值控件（`web-ui-input`、`web-ui-select`、
+  `web-ui-autocomplete` 等）支持 `v-model`，编译为元素的 `value` property + `input` 事件。
+- **React**：React 19 对 custom element 的 props 直接写 DOM property，因此使用 camelCase props
+  （`open={open}`、`noScrollLock`、`value={value}`）。**不要把复杂数据（对象、数组）放进 attribute 字符串**，
+  一律绑定为 property。kebab-case JSX prop 在 custom element 上会写成 attribute。
+
 ### React
 
 需要 `@types/react >= 19` 作为可选 peer 依赖。
@@ -127,6 +150,20 @@ import '@greypan/web-ui/types/vue'
 </template>
 ```
 
+Boolean 属性必须用 **camelCase 属性名**绑定，而不是 kebab-case attribute。Vue 会把 attribute 绑定写成字符串，
+而布尔 attribute 遵循「存在即 true」的语义——所以 `:sidebar-collapsed="false"` 会写出字符串 `"false"`，被当作 true。
+改用 camelCase 属性名（`:sidebarCollapsed="false"`，或 `.prop` 修饰符）会让 Vue 直接写 DOM property：
+
+```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 事件类型零 cast：带值组件上的 `@input`/`@change` 解析到组件 emit，`$event.target` 即为组件实例，
 `value`/`checked` 直接读取；kebab-case 事件（如 `open-change`）的 `$event.detail` 保持 `CustomEvent` 载荷类型。
 命名 handler 用 `WebUiEvent<WebUiXxx, 'change'>` 标注；当变量或泛型表示事件名时，使用
@@ -143,45 +180,79 @@ ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而
 `click`、`input`、`change` 等浏览器 composed 原生事件仍是主要交互 API。`open-change` 等 kebab-case 自定义事件
 仅描述用户操作导致的组件状态变化；程序化赋值 property 不会触发它们。
 
+### Cursor 行为
+
+交互控件使用原生箭头光标，而不是手型光标；disabled 控件使用 `not-allowed`。Slider、Switch 和 Segmented 在
+hover 与按压反馈阶段保持箭头光标，仅在真实拖拽进行中切换为 `grabbing`。专用拖拽把手和 resize 控件保留各自
+的专用光标。Cursor 样式位于 Shadow DOM 内，应用层普通选择器无法覆盖。
+
+### 受控状态语义
+
+`web-ui-*` 元素没有单一的「受控」契约；按交互性质分成三套状态模型，各组件族取其一。不要假设不同组件上的
+`controlled` 含义相同。
+
+**仅用户来源事件（所有 `open` 类组件：collapse、popover、dropdown、tooltip、dialog、drawer、back-top）。**
+`*-change` 事件（`open-change` 等）只在用户来源的切换时派发；程序化赋值（`el.open = true`）或命令式调用
+（`show()`、`close()`、`toggle()`）从不派发。组件**自管理**自己的 `open` 值，除非你在外部协调——你可以监听事件
+并写回自己的状态，但组件不要求、也不等待这个写回。
+
+**请求-写回模式（仅 dialog 与 drawer 的 `controlled`）。**
+`controlled=true` 时，用户关闭操作（Escape、backdrop、内置关闭、拖拽释放）只*请求* `open=false`；组件不改自己的
+状态，保持打开，直到消费者写回 `open=false`。这是模态确认语义——关对话框/抽屉通常是需要消费者批准的操作（未保存
+表单、需确认），与即时开合不同，不能由组件自行提交。只有这两个模态组件使用该模式；即时开合家族（collapse、popover、
+dropdown、tooltip）不需要它。
+
+**原生表单模型（input、textarea、input-number、select、checkbox、radio、switch、autocomplete）。**
+控件内部自管理 value/checked 状态；用户交互立即翻转，然后派发原生 `input`/`change` 事件。程序化赋值
+（`el.checked = true`）覆盖内部状态。这与原生 `<input type="checkbox">` 一致——**没有 `controlled` prop 是因为
+值总是可读可写**，React/Vue 层自备受控包装。若翻转的持久化需要外部往返（例如开关应只有 API 调用成功后保持开启），
+使用**乐观更新**路径：立即翻转、监听 `change`、请求期间设 `loading`（阻断后续交互并显示 spinner），失败后回写
+property（`el.checked = false`）并提示 toast。翻转先于批准的窗口被接受；不提供「批准前不翻转」的 `controlled` prop。
+
+### 表单关联控件
+
+所有表单控件均参与原生 `FormData`、约束校验、`form.reset()` 和浏览器表单状态恢复。控件会在**首次连接且声明式属性完成初始化后**捕获一次重置默认值；之后的运行时 property 更新不会改写该默认值。祖先 `fieldset` 的禁用状态会禁用交互和校验，但不会改写控件公开的 `disabled` 属性。对于 checkbox/radio group，父 group 是提交、重置和状态恢复的唯一所有者；被管理的子项不会独立提交或恢复状态。
+
 ## 所有组件
 
-| 分类            | 组件                                                      |
-| --------------- | --------------------------------------------------------- |
-| **表单控件**    | [`<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)             |
-| **按钮**        | [`<web-ui-button>`](#web-ui-button)                       |
-|                 | [`<web-ui-button-group>`](#web-ui-button-group)           |
-| **浮层 / 模态** | [`<web-ui-dialog>`](#web-ui-dialog)                       |
-|                 | [`<web-ui-drawer>`](#web-ui-drawer)                       |
-| **浮动**        | [`<web-ui-popover>`](#web-ui-popover)                     |
-|                 | [`<web-ui-tooltip>`](#web-ui-tooltip)                     |
-|                 | [`<web-ui-context-menu>`](#web-ui-context-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)     |
-| **数据展示**    | [`<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)                     |
-| **布局与工具**  | [`<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)                         |
-| **通知**        | [`<web-ui-toast>`](#web-ui-toast)                         |
-| **子项**        | [`<web-ui-option>`](#web-ui-option)                       |
-|                 | [`<web-ui-segmented-trigger>`](#web-ui-segmented-trigger) |
+| 分类                  | 组件                                                      |
+| --------------------- | --------------------------------------------------------- |
+| **表单控件**          | [`<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)             |
+| **按钮**              | [`<web-ui-button>`](#web-ui-button)                       |
+|                       | [`<web-ui-button-group>`](#web-ui-button-group)           |
+| **浮层 / 模态**       | [`<web-ui-dialog>`](#web-ui-dialog)                       |
+|                       | [`<web-ui-drawer>`](#web-ui-drawer)                       |
+| **文档流 Disclosure** | [`<web-ui-collapse>`](#web-ui-collapse)                   |
+| **浮动**              | [`<web-ui-popover>`](#web-ui-popover)                     |
+|                       | [`<web-ui-tooltip>`](#web-ui-tooltip)                     |
+|                       | [`<web-ui-context-menu>`](#web-ui-context-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)     |
+| **数据展示**          | [`<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)                     |
+| **布局与工具**        | [`<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)                         |
+| **通知**              | [`<web-ui-toast>`](#web-ui-toast)                         |
+| **子项**              | [`<web-ui-option>`](#web-ui-option)                       |
+|                       | [`<web-ui-segmented-trigger>`](#web-ui-segmented-trigger) |
 
 ## API 参考
 
@@ -193,46 +264,52 @@ ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而
 
 文本输入框，支持清除按钮和前后缀插槽。
 
-| 属性          | 类型      | 默认值   | 说明            |
-| ------------- | --------- | -------- | --------------- |
-| `value`       | `string`  | `''`     | 输入值          |
-| `type`        | `string`  | `'text'` | HTML input 类型 |
-| `placeholder` | `string`  | `''`     | 占位文本        |
-| `name`        | `string`  | `''`     | 表单字段名      |
-| `disabled`    | `boolean` | `false`  | 禁用状态        |
-| `readonly`    | `boolean` | `false`  | 只读状态        |
-| `required`    | `boolean` | `false`  | 必填校验        |
-| `clearable`   | `boolean` | `false`  | 显示清除按钮    |
-| `full`        | `boolean` | `false`  | 全宽            |
-| `borderless`  | `boolean` | `false`  | 无边框          |
-| `aria-label`  | `string`  | —        | 无障碍标签      |
+| 属性          | 类型      | 默认值   | 说明                                                                  |
+| ------------- | --------- | -------- | --------------------------------------------------------------------- |
+| `value`       | `string`  | `''`     | 输入值                                                                |
+| `type`        | `string`  | `'text'` | HTML input 类型                                                       |
+| `placeholder` | `string`  | `''`     | 占位文本                                                              |
+| `name`        | `string`  | `''`     | 表单字段名                                                            |
+| `disabled`    | `boolean` | `false`  | 禁用状态                                                              |
+| `readonly`    | `boolean` | `false`  | 只读状态                                                              |
+| `required`    | `boolean` | `false`  | 必填校验                                                              |
+| `clearable`   | `boolean` | `false`  | 显示清除按钮                                                          |
+| `full`        | `boolean` | `false`  | 全宽                                                                  |
+| `borderless`  | `boolean` | `false`  | ghost 形态：移除边框、背景与阴影；保留 padding、高度度量与 focus ring |
+| `aria-label`  | `string`  | —        | 无障碍标签                                                            |
 
 **事件：** `input`, `change`, `focus`, `blur`
 
 **插槽：** `prefix`, `default`, `suffix`
 
+**CSS 自定义属性：**
+
+| 属性                      | 默认值                           | 说明         |
+| ------------------------- | -------------------------------- | ------------ |
+| `--wui-input-clear-color` | `var(--wui-color-text-tertiary)` | 清除按钮颜色 |
+
 #### `<web-ui-textarea>`
 
 多行文本输入框，支持自动调整高度。
 
-| 属性              | 类型      | 默认值  | 说明                               |
-| ----------------- | --------- | ------- | ---------------------------------- |
-| `value`           | `string`  | `''`    | 输入值                             |
-| `placeholder`     | `string`  | `''`    | 占位文本                           |
-| `rows`            | `number`  | `3`     | 显示行数                           |
-| `name`            | `string`  | `''`    | 表单字段名                         |
-| `disabled`        | `boolean` | `false` | 禁用状态                           |
-| `readonly`        | `boolean` | `false` | 只读状态                           |
-| `required`        | `boolean` | `false` | 必填校验                           |
-| `clearable`       | `boolean` | `false` | 显示清除按钮                       |
-| `full`            | `boolean` | `false` | 全宽                               |
-| `borderless`      | `boolean` | `false` | 无边框                             |
-| `autosize`        | `boolean` | `false` | 自动调整高度                       |
-| `max-height`      | `number`  | `0`     | 自动高度上限（px），`0` 表示不限制 |
-| `minlength`       | `number`  | —       | 最小长度校验                       |
-| `maxlength`       | `number`  | —       | 最大长度校验                       |
-| `aria-label`      | `string`  | —       | 无障碍标签                         |
-| `aria-labelledby` | `string`  | —       | 无障碍标签引用                     |
+| 属性              | 类型      | 默认值  | 说明                                                                  |
+| ----------------- | --------- | ------- | --------------------------------------------------------------------- |
+| `value`           | `string`  | `''`    | 输入值                                                                |
+| `placeholder`     | `string`  | `''`    | 占位文本                                                              |
+| `rows`            | `number`  | `3`     | 显示行数                                                              |
+| `name`            | `string`  | `''`    | 表单字段名                                                            |
+| `disabled`        | `boolean` | `false` | 禁用状态                                                              |
+| `readonly`        | `boolean` | `false` | 只读状态                                                              |
+| `required`        | `boolean` | `false` | 必填校验                                                              |
+| `clearable`       | `boolean` | `false` | 显示清除按钮                                                          |
+| `full`            | `boolean` | `false` | 全宽                                                                  |
+| `borderless`      | `boolean` | `false` | ghost 形态：移除边框、背景与阴影；保留 padding、高度度量与 focus ring |
+| `autosize`        | `boolean` | `false` | 自动调整高度                                                          |
+| `max-height`      | `number`  | `0`     | 自动高度上限（px），`0` 表示不限制                                    |
+| `minlength`       | `number`  | —       | 最小长度校验                                                          |
+| `maxlength`       | `number`  | —       | 最大长度校验                                                          |
+| `aria-label`      | `string`  | —       | 无障碍标签                                                            |
+| `aria-labelledby` | `string`  | —       | 无障碍标签引用                                                        |
 
 **事件：** `input`, `change`, `focus`, `blur`
 
@@ -240,6 +317,13 @@ ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而
 
 **插槽：** `prefix`, `suffix`
 
+**CSS 自定义属性：**
+
+| 属性                         | 默认值                           | 说明         |
+| ---------------------------- | -------------------------------- | ------------ |
+| `--wui-textarea-width`       | `200px`                          | 文本域宽度   |
+| `--wui-textarea-clear-color` | `var(--wui-color-text-tertiary)` | 清除按钮颜色 |
+
 #### `<web-ui-input-number>`
 
 数字输入框，支持步进按钮和键盘操作。
@@ -282,32 +366,60 @@ ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值
 
 子 `<web-ui-option>` 通过 `option-register` / `option-unregister` 注册。支持 ArrowDown/ArrowUp/Enter/Escape 键盘导航。
 
+**CSS 自定义属性：**
+
+| 属性                      | 默认值                             | 说明                  |
+| ------------------------- | ---------------------------------- | --------------------- |
+| `--wui-select-max-width`  | `500px`                            | 下拉框最大宽度        |
+| `--wui-select-max-height` | `200px`                            | 下拉滚动区域最大高度  |
+| `--wui-overlay-min-width` | `200px`                            | 下拉框最小宽度        |
+| `--wui-select-bg-hover`   | `--wui-color-surface-glass-hover`  | Trigger 悬停背景      |
+| `--wui-select-bg-active`  | `--wui-color-surface-glass-active` | Trigger 按下/打开背景 |
+
+Portal 面板创建时会镜像 host 上解析后的这些变量；更新 host 后需重新打开 Portal 面板才会生效。
+
 #### `<web-ui-autocomplete>`
 
 可输入并过滤候选的单值选择器。
 
-| 属性               | 类型                               | 默认值       | 说明                                                    |
-| ------------------ | ---------------------------------- | ------------ | ------------------------------------------------------- |
-| `value`            | `string`                           | `''`         | 当前输入文本（表单值）                                  |
-| `selected-value`   | `string`                           | `''`         | 输入文本精确匹配 label 的 option 的 value（派生，只读） |
-| `placeholder`      | `string`                           | `''`         | 占位文本                                                |
-| `filter`           | `'none' \| 'prefix' \| 'contains'` | `'contains'` | 候选过滤模式（按 option label 匹配）                    |
-| `name`             | `string`                           | `''`         | 表单字段名                                              |
-| `disabled`         | `boolean`                          | `false`      | 禁用状态                                                |
-| `readonly`         | `boolean`                          | `false`      | 只读状态（不可输入、不可展开下拉）                      |
-| `required`         | `boolean`                          | `false`      | 必填校验                                                |
-| `portal`           | `boolean`                          | `false`      | 在主题浮层容器中渲染                                    |
-| `no-scroll-lock`   | `boolean`                          | `false`      | 打开时不锁定页面滚动                                    |
-| `overlayContainer` | `HTMLElement \| () => HTMLElement` | —            | 显式 Portal 容器                                        |
-| `aria-label`       | `string`                           | —            | 无障碍名称                                              |
-| `aria-labelledby`  | `string`                           | —            | 无障碍名称引用                                          |
+| 属性                 | 类型                               | 默认值       | 说明                                                                  |
+| -------------------- | ---------------------------------- | ------------ | --------------------------------------------------------------------- |
+| `value`              | `string`                           | `''`         | 当前输入文本（表单值）                                                |
+| `selected-value`     | `string`                           | `''`         | 输入文本精确匹配 label 的非禁用 option 的 value（派生，只读）         |
+| `placeholder`        | `string`                           | `''`         | 占位文本                                                              |
+| `borderless`         | `boolean`                          | `false`      | ghost 形态：移除边框、背景与阴影；保留 padding、高度度量与 focus ring |
+| `filter`             | `'none' \| 'prefix' \| 'contains'` | `'contains'` | 候选过滤模式（按 option label 匹配）                                  |
+| `name`               | `string`                           | `''`         | 表单字段名                                                            |
+| `disabled`           | `boolean`                          | `false`      | 禁用状态                                                              |
+| `readonly`           | `boolean`                          | `false`      | 只读状态（不可输入、不可展开下拉）                                    |
+| `required`           | `boolean`                          | `false`      | 必填校验                                                              |
+| `allow-custom-value` | `boolean`                          | `false`      | 允许 Enter 提交不在候选中的 custom value                              |
+| `portal`             | `boolean`                          | `false`      | 在主题浮层容器中渲染                                                  |
+| `no-scroll-lock`     | `boolean`                          | `false`      | 打开时不锁定页面滚动                                                  |
+| `overlayContainer`   | `HTMLElement \| () => HTMLElement` | —            | 显式 Portal 容器                                                      |
+| `aria-label`         | `string`                           | —            | 无障碍名称                                                            |
+| `aria-labelledby`    | `string`                           | —            | 无障碍名称引用                                                        |
 
 **事件：** `input`, `change`, `focus`, `blur`, `open-change` (`CustomEvent<{ open: boolean }>`)
 
-**插槽：** `default`（投影 `<web-ui-option>` 元素）
+**插槽：** `default`（投影 `<web-ui-option>` 元素）、`empty`（替换无匹配空态；默认回退为“无匹配选项”）
 
 键入时按 label 过滤候选（`contains` 或 `prefix`，`none` 关闭过滤）。选择 option 时文本回填为该项 label，`selected-value` 暴露该项的 value；`change` 在选择提交时触发。支持 ArrowDown/ArrowUp/Enter/Escape 键盘导航。
 
+启用 `allow-custom-value` 后，无匹配且无活动 option 时，Enter 会把当前输入原文作为 custom value 提交并关闭面板；`change` 会触发，`selected-value` 保持为空。组件不会自动创建 option，也不会 trim 原文。命中禁用 option 的文本不会绕过禁用语义，也不会派生为已选 option。
+
+通过 `<div slot="empty">…</div>` 自定义静态、非交互的空态内容。Portal 渲染时该节点会迁入浮层，关闭后恢复到宿主。
+
+**CSS 自定义属性：**
+
+| 属性                            | 默认值  | 说明                 |
+| ------------------------------- | ------- | -------------------- |
+| `--wui-autocomplete-max-width`  | `500px` | 下拉框最大宽度       |
+| `--wui-autocomplete-max-height` | `200px` | 下拉滚动区域最大高度 |
+| `--wui-overlay-min-width`       | `200px` | 下拉框最小宽度       |
+
+Portal 面板创建时会镜像 host 上解析后的这些变量；更新 host 后需重新打开 Portal 面板才会生效。
+
 #### `<web-ui-slider>`
 
 范围滑块，支持刻度标记和垂直方向。
@@ -330,6 +442,18 @@ ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值
 
 支持 ArrowLeft/Right/Up/Down、Home/End、PageUp/PageDown 键盘导航。使用 pointer capture 处理鼠标、触控笔和触摸交互。
 
+**CSS 自定义属性：**
+
+| 属性                           | 默认值                              | 说明         |
+| ------------------------------ | ----------------------------------- | ------------ |
+| `--wui-slider-width`           | `200px`                             | 滑块宽度     |
+| `--wui-slider-vertical-height` | `200px`                             | 垂直滑块高度 |
+| `--wui-slider-height`          | `var(--wui-slider-track-size, 6px)` | 轨道厚度     |
+| `--wui-slider-track-size`      | `6px`                               | 轨道尺寸     |
+| `--wui-slider-thumb-width`     | `30px`                              | 滑块宽度     |
+| `--wui-slider-thumb-height`    | `20px`                              | 滑块高度     |
+| `--wui-slider-marks-inset`     | `0`                                 | 刻度内缩     |
+
 #### `<web-ui-checkbox>`
 
 单个复选框。
@@ -442,16 +566,16 @@ ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值
 
 样式化按钮，支持多种变体和加载状态。
 
-| 属性         | 类型                                                         | 默认值     | 说明                                |
-| ------------ | ------------------------------------------------------------ | ---------- | ----------------------------------- |
-| `variant`    | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'`  | 按钮变体                            |
-| `type`       | `'button' \| 'submit' \| 'reset'`                            | `'button'` | 内部按钮类型；非法值回退为 `button` |
-| `disabled`   | `boolean`                                                    | `false`    | 禁用状态                            |
-| `loading`    | `boolean`                                                    | `false`    | 加载旋转动画                        |
-| `full`       | `boolean`                                                    | `false`    | 全宽                                |
-| `icon`       | `boolean`                                                    | `false`    | 纯图标模式                          |
-| `size`       | `string`                                                     | `''`       | 尺寸格式 `高度` 或 `高度x宽度`      |
-| `aria-label` | `string`                                                     | —          | 无障碍标签（委托给内部按钮）        |
+| 属性         | 类型                                                         | 默认值     | 说明                                                          |
+| ------------ | ------------------------------------------------------------ | ---------- | ------------------------------------------------------------- |
+| `variant`    | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'`  | 按钮变体                                                      |
+| `type`       | `'button' \| 'submit' \| 'reset'`                            | `'button'` | 内部按钮类型；非法值回退为 `button`                           |
+| `disabled`   | `boolean`                                                    | `false`    | 禁用状态                                                      |
+| `loading`    | `boolean`                                                    | `false`    | 加载旋转动画；与 `icon` 组合时 spinner 替换图标内容           |
+| `full`       | `boolean`                                                    | `false`    | 全宽                                                          |
+| `icon`       | `boolean`                                                    | `false`    | 纯图标模式                                                    |
+| `size`       | `string`                                                     | `''`       | 按钮高度（px）；icon 模式下同时设为 min-width，默认保持正方形 |
+| `aria-label` | `string`                                                     | —          | 无障碍标签（委托给内部按钮）                                  |
 
 **事件：** 标准 `click`
 
@@ -461,6 +585,20 @@ ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值
 
 禁用和加载状态阻止 `click` 事件。
 
+`icon` 与 `loading` 同时开启时，按钮只渲染 spinner，默认插槽图标不投影。默认 icon 几何保持正方形，`full` 或显式 width 除外。
+
+**CSS 自定义属性：**
+
+| 属性                     | 默认值        | 说明                   |
+| ------------------------ | ------------- | ---------------------- |
+| `--wui-button-width`     | `max-content` | 按钮宽度               |
+| `--wui-button-px`        | `12px`        | 水平内边距             |
+| `--wui-button-gap`       | `8px`         | 前缀/默认/后缀插槽间距 |
+| `--wui-button-color`     | 随 variant    | 按钮文字颜色           |
+| `--wui-button-bg`        | 随 variant    | 按钮背景颜色           |
+| `--wui-button-bg-hover`  | 随 variant    | 悬停背景颜色           |
+| `--wui-button-bg-active` | 随 variant    | 按下背景颜色           |
+
 #### `<web-ui-button-group>`
 
 按钮组，管理子按钮布局和方向。
@@ -471,7 +609,7 @@ ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值
 
 **插槽：** `default`（投影 `<web-ui-button>` 元素）
 
-向子按钮传递 `direction` 属性。
+以内部派生的视觉上下文控制按钮组方向，不改写子按钮属性。
 
 ---
 
@@ -481,41 +619,105 @@ ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值
 
 模态对话框，使用原生 `<dialog>` 的 `showModal()`。
 
-| 属性                | 类型      | 默认值  | 说明                 |
-| ------------------- | --------- | ------- | -------------------- |
-| `open`              | `boolean` | `false` | 对话框可见性         |
-| `no-scroll-lock`    | `boolean` | `false` | 打开时不锁定页面滚动 |
-| `no-backdrop-close` | `boolean` | `false` | 禁止点击遮罩关闭     |
-| `no-escape-close`   | `boolean` | `false` | 禁止按 Escape 关闭   |
+| 属性                | 类型      | 默认值  | 说明                                                      |
+| ------------------- | --------- | ------- | --------------------------------------------------------- |
+| `open`              | `boolean` | `false` | 对话框可见性                                              |
+| `no-scroll-lock`    | `boolean` | `false` | 打开时不锁定页面滚动                                      |
+| `no-backdrop-close` | `boolean` | `false` | 禁止点击遮罩关闭                                          |
+| `no-escape-close`   | `boolean` | `false` | 禁止按 Escape 关闭                                        |
+| `controlled`        | `boolean` | `false` | Escape 与遮罩仅请求 `open=false`，由 Consumer 回写 `open` |
 
-**事件：** `open-change` (`CustomEvent<{ open: boolean }>`)
+**事件：** `open-change` (`CustomEvent<{ open: boolean }>`)。启用 `controlled` 后，Escape 与遮罩点击仅请求 `open=false`，Consumer 写入 `open=false` 前对话框保持打开。程序化 API（`showModal()`/`close()`/直接赋值 `open`）不受影响，始终直通且不派发事件。原生 dialog 关闭（如表单 `method="dialog"`）会被恢复为受控打开状态并重新发出同一请求。
 
 **插槽：** `body`, `title`, `default`, `footer`
 
 **方法：** `showModal()`, `close()`
 
-使用原生 `<dialog>`，`@cancel` 阻止默认关闭行为。除非存在 `no-escape-close`，否则 Escape 调用 `close()`；除非存在 `no-backdrop-close`，否则点击遮罩关闭。
+使用原生 `<dialog>`，`@cancel` 阻止默认关闭行为。除非存在 `no-escape-close`，否则 Escape 调用 `close()`；除非存在 `no-backdrop-close`，否则点击遮罩关闭。启用 `controlled` 后，两者都只派发关闭请求而不自关闭。
+
+**CSS 自定义属性：**
+
+| 属性                      | 默认值                             | 说明                                             |
+| ------------------------- | ---------------------------------- | ------------------------------------------------ |
+| `--wui-dialog-max-width`  | `360px`                            | 对话框最大宽度                                   |
+| `--wui-dialog-overlay-bg` | `var(--wui-color-backdrop)`        | 遮罩背景色                                       |
+| `--wui-dialog-bg`         | `var(--wui-color-surface-overlay)` | 玻璃卡片背景色，回退到 `rgb(246 246 246 / 0.88)` |
 
 #### `<web-ui-drawer>`
 
-侧边抽屉，使用原生 `<dialog>` 并自带关闭动画。
+侧边抽屉，使用原生 `<dialog>` 并自带关闭动画。非 headless 模式下抽屉渲染为四周留边的浮动圆角卡片（与 layout sidebar 的卡片语言一致），弹性拖拽的位移表现为边距变化而非缺口。
 
-| 属性                | 类型                                     | 默认值    | 说明                             |
-| ------------------- | ---------------------------------------- | --------- | -------------------------------- |
-| `open`              | `boolean`                                | `false`   | 抽屉可见性                       |
-| `placement`         | `'right' \| 'left' \| 'top' \| 'bottom'` | `'right'` | 滑入方向                         |
-| `heading`           | `string`                                 | `''`      | 标题文字（无 header 插槽时显示） |
-| `closable`          | `boolean`                                | `false`   | 显示关闭按钮                     |
-| `no-scroll-lock`    | `boolean`                                | `false`   | 打开时不锁定页面滚动             |
-| `no-backdrop-close` | `boolean`                                | `false`   | 禁止点击遮罩关闭                 |
+| 属性                | 类型                                     | 默认值    | 说明                                                 |
+| ------------------- | ---------------------------------------- | --------- | ---------------------------------------------------- |
+| `open`              | `boolean`                                | `false`   | 抽屉可见性                                           |
+| `placement`         | `'right' \| 'left' \| 'top' \| 'bottom'` | `'right'` | 滑入方向                                             |
+| `heading`           | `string`                                 | `''`      | 标题文字（无 header 插槽时显示）                     |
+| `closable`          | `boolean`                                | `false`   | 显示关闭按钮                                         |
+| `no-scroll-lock`    | `boolean`                                | `false`   | 打开时不锁定页面滚动                                 |
+| `no-backdrop-close` | `boolean`                                | `false`   | 禁止点击遮罩关闭                                     |
+| `controlled`        | `boolean`                                | `false`   | 用户关闭仅请求 `open=false`，由 Consumer 回写 `open` |
+| `headless`          | `boolean`                                | `false`   | 仅保留 overlay 行为，默认插槽不渲染内置抽屉 UI       |
+| `dialog-label`      | `string`                                 | `''`      | 内部原生 dialog 的可访问名称；headless 模式必须提供  |
+| `draggable`         | `boolean`                                | `false`   | 打开时在抽屉内缘显示 drag bar，支持拖拽关闭手势      |
 
-**事件：** `open-change` (`CustomEvent<{ open: boolean }>`)
+**事件：** `open-change` (`CustomEvent<{ open: boolean }>`)。启用 `controlled` 后，Escape、遮罩、内置关闭按钮和拖拽松手仅请求 `open=false`；Consumer 写入 `open=false` 前抽屉保持打开。程序化 API（`show()`/`close()`/直接赋值 `open`）不受影响，始终直通且不派发事件。若原生 dialog 在请求等待期间关闭，组件会恢复其打开的 top layer 状态并发出同一关闭请求。嵌套 drawer 时，内层 `open-change` 会 composed 冒泡穿过外层根，按 `event.target` 区分。
 
-**插槽：** `header`, `default`, `footer`
+**插槽：** `header`, `default`, `footer`；启用 `headless` 时仅渲染 `default` 插槽。
 
 **方法：** `show()`, `close()`
 
-关闭时保留原生 dialog 的 top layer，待 `--wui-duration-drawer` 过渡完成（默认 280ms）后调用 `dialog.close()`。Escape 始终走此关闭路径；`no-backdrop-close` 仅控制遮罩点击。
+`headless` 保留原生 dialog、遮罩、placement 动画、Escape/遮罩关闭行为和滚动锁定，但不渲染内置 glass 主体、header、关闭按钮或 footer；Consumer 负责完整定义默认插槽内容的样式，并且必须提供 `dialog-label`，确保原生 dialog 具有可访问名称。
+
+关闭时保留原生 dialog 的 top layer，待退出过渡完成后调用 `dialog.close()`。Escape 始终走此关闭路径；`no-backdrop-close` 仅控制遮罩点击。
+
+**拖拽关闭：** 启用 `draggable` 后，打开的抽屉在内缘显示灰色胶囊 drag bar（`right` 在左缘、`left` 在右缘、`top` 在下缘、`bottom` 在上缘）。拖拽实时跟手（遮罩透明度按比例淡出）；松手时位移超过抽屉尺寸约 1/3 或快速甩动即弹簧关闭，否则弹回打开位，方向随 placement 适配。启用 `controlled` 后，超过阈值松手仅派发 `open-change(false)`；抽屉在闭合位短暂等待（120ms 回写窗口），Consumer 拒绝或超时未回写时弹回打开位。不支持拖拽打开——关闭态的抽屉在原生 dialog 之外没有任何渲染物。`prefers-reduced-motion` 下松手即时到位，不播放弹簧动画。
+
+**CSS 自定义属性：**
+
+| 属性                      | 默认值                             | 说明                                               |
+| ------------------------- | ---------------------------------- | -------------------------------------------------- |
+| `--wui-drawer-width`      | `320px`                            | 抽屉宽度                                           |
+| `--wui-drawer-height`     | `300px`                            | 抽屉高度（上/下）                                  |
+| `--wui-drawer-bg`         | `var(--wui-color-surface-overlay)` | 抽屉背景色                                         |
+| `--wui-drawer-radius`     | `28px`                             | 浮动卡片圆角（非 headless）                        |
+| `--wui-drawer-inset`      | `8px`                              | 浮动卡片视口留边（非 headless）；置 `0` 为贴边几何 |
+| `--wui-drawer-overlay-bg` | `rgb(0 0 0 / 0.12)`                | 遮罩背景色                                         |
+
+---
+
+### 文档流展开收起
+
+#### `<web-ui-collapse>`
+
+文档流内的展开收起容器，带高度（或宽度）过渡动画。单元素双插槽；无 portal、无滚动锁定、无焦点管理。
+
+| 属性           | 类型      | 默认值  | 说明                                                                                |
+| -------------- | --------- | ------- | ----------------------------------------------------------------------------------- |
+| `open`         | `boolean` | `false` | 展开状态；交互时自管理，`open-change` 仅用户来源时派发                              |
+| `disabled`     | `boolean` | `false` | 忽略 trigger 点击并在 trigger 元素上设 `aria-disabled`；已展开内容保持现状          |
+| `horizontal`   | `boolean` | `false` | 沿宽度而非高度动画                                                                  |
+| `keep-mounted` | `boolean` | `false` | 关闭稳态以 `inert` 保留在 0fr 轨道内（滚动位置与布局可测量），而非内部容器 `hidden` |
+
+**事件：** `open-change` (`CustomEvent<{ open: boolean }>`)。仅用户来源的切换（trigger 点击）派发；程序化写入（`open`、`show()`、`close()`、`toggle()`）不派发。嵌套时内层 `open-change` 会冒泡穿过外层根（composed 事件），按 `event.target` 区分。
+
+**插槽：** `default`（trigger）+ `content`（折叠内容）
+
+**方法：** `show()`、`close()`、`toggle()`
+
+```html
+<web-ui-collapse>
+  <button type="button">点击切换</button>
+  <div slot="content">折叠内容</div>
+</web-ui-collapse>
+```
+
+初始即带 `open` attribute 时直接落稳态，不播动画。支持嵌套 collapse。
+
+**trigger 语义：** 交互语义完全来自 default slot 放入的元素——原生 `<button>`、`<web-ui-button>` 或其他可交互元素原生提供 Enter/Space 激活与焦点。collapse 把 `aria-expanded` / `aria-controls`（指向内容轨道）与 `aria-disabled` 回写到 trigger slot 的首个 assigned element。trigger 请使用可交互元素：纯 `<span>` 可点击但没有键盘/焦点语义。
+
+**关闭稳态语义：** 消费者的 light DOM 永不移动或卸载。默认关闭稳态在内部内容容器上设 `hidden`；`keep-mounted` 时内部容器标记 `inert`，保留在收起轨道内可测量。
+
+**已知限制：** `horizontal` 动画期间内容随宽度变化 reflow。
 
 ---
 
@@ -543,6 +745,8 @@ ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值
 
 Hover 模式使用 `pointerenter`/`pointerleave` 加延迟控制。Click 模式点击切换。Manual 模式仅响应命令式调用。
 
+**trigger ARIA：** 开合状态回写到 trigger 元素：`aria-expanded` 与 `aria-controls`（指向面板）设在 `trigger` slot 的首个 assigned element 上（包装结构上的同名属性保留兼容）。trigger slot 请放入可交互元素（原生 button、`web-ui-button`）。
+
 #### `<web-ui-tooltip>`
 
 工具提示，支持指针和焦点触发。
@@ -563,7 +767,14 @@ Hover 模式使用 `pointerenter`/`pointerleave` 加延迟控制。Click 模式
 
 **插槽：** `default`（触发器）、`content`（提示面板）
 
-`open` 是受控可见性属性。指针/焦点触发会更新它，直接设置也会同步本地或 Portal 面板。第一个 Tooltip 显示后，相邻 Tooltip 会立即切换；其余 pointer/focus 触发使用延迟计时器。
+`open` 是自管理的可见性属性。指针/焦点触发会更新它，直接赋值 property 也会同步本地或 Portal 面板；`open-change` 仅用户来源的开关时派发。第一个 Tooltip 显示后，相邻 Tooltip 会立即切换；其余 pointer/focus 触发使用延迟计时器。
+
+**CSS 自定义属性：**
+
+| 属性                      | 默认值  | 说明         |
+| ------------------------- | ------- | ------------ |
+| `--wui-tooltip-max-width` | `240px` | 提示最大宽度 |
+| `--wui-tooltip-font-size` | `13px`  | 提示字号     |
 
 #### `<web-ui-context-menu>`
 
@@ -582,6 +793,8 @@ Hover 模式使用 `pointerenter`/`pointerleave` 加延迟控制。Click 模式
 
 通过 `contextmenu` 事件打开。菜单项：`web-ui-dropdown-item`、`web-ui-dropdown-divider`、`web-ui-dropdown-header`。支持键盘导航和子菜单 hover。
 
+菜单打开期间，消费者可以安全地使用条件渲染（如 Vue `v-if`）切换、移动或删除菜单项，无需重新插入到宿主元素；portal 内的变更会自动 reconcile，关闭时框架锚点随元素迁回宿主，保证后续框架更新正常。
+
 ---
 
 ### 菜单
@@ -607,6 +820,8 @@ Hover 模式使用 `pointerenter`/`pointerleave` 加延迟控制。Click 模式
 
 菜单项：`web-ui-dropdown-item`、`web-ui-dropdown-divider`、`web-ui-dropdown-header`。子菜单在 `web-ui-dropdown-item` 上通过 `submenu` 属性启用。完整键盘导航支持。
 
+**trigger ARIA：** `aria-haspopup="menu"`、`aria-expanded` 与 `aria-controls`（指向根菜单面板）回写到 `trigger` slot 的首个 assigned element。trigger slot 请放入可交互元素。
+
 #### `<web-ui-dropdown-item>`
 
 菜单项。
@@ -677,6 +892,17 @@ Hover 模式使用 `pointerenter`/`pointerleave` 加延迟控制。Click 模式
 
 **插槽：** `default`（标题，覆盖 `title` 属性）、`icon`、`description`、`action`
 
+**CSS 自定义属性：**
+
+| 属性                                | 默认值      | 说明               |
+| ----------------------------------- | ----------- | ------------------ |
+| `--wui-empty-min-height`            | `240px`     | 最小高度（medium） |
+| `--wui-empty-padding`               | `32px 24px` | 内边距（medium）   |
+| `--wui-empty-icon-size`             | `56px`      | 图标容器尺寸       |
+| `--wui-empty-content-width`         | `480px`     | 标题/描述最大宽度  |
+| `--wui-empty-title-font-size`       | `16px`      | 标题字号（medium） |
+| `--wui-empty-description-font-size` | `14px`      | 描述字号（medium） |
+
 #### `<web-ui-icon>`
 
 图标渲染组件。接受 Iconify 数据对象。
@@ -695,6 +921,12 @@ import { lucideLoaderCircle } from '@greypan/web-ui/icons'
 html`<web-ui-icon .icon=${lucideLoaderCircle} spin />`
 ```
 
+**CSS 自定义属性：**
+
+| 属性               | 默认值    | 说明     |
+| ------------------ | --------- | -------- |
+| `--wui-icon-color` | `inherit` | 图标颜色 |
+
 #### `<web-ui-spinner>`
 
 加载旋转器。
@@ -727,14 +959,43 @@ WebUiSpinner.hide() // 隐藏
 
 #### `<web-ui-layout>`
 
-页面布局网格。
+响应式页面布局：支持可选全宽 Banner、桌面端可折叠侧边栏，以及移动端 headless drawer。页面本身滚动；Banner 滚出后，桌面端 sidebar 和 header 固定在视口内。
+
+| 属性                | 类型      | 默认值    | 说明                                                           |
+| ------------------- | --------- | --------- | -------------------------------------------------------------- |
+| `sidebar-collapsed` | `boolean` | `false`   | 桌面端侧边栏受控折叠状态                                       |
+| `sidebar-open`      | `boolean` | `false`   | 移动端侧边栏 Drawer 受控打开状态                               |
+| `header-glow`       | `boolean` | `false`   | 在 header 插槽内容背后显示装饰性晕染                           |
+| `sidebar-width`     | `string`  | `'240px'` | 桌面端和移动端展开时的侧边栏宽度                               |
+| `collapsed-width`   | `string`  | `'72px'`  | 桌面端折叠时的侧边栏宽度                                       |
+| `sidebar-resizable` | `boolean` | `false`   | 启用桌面端侧边栏右边缘拖拽调整宽度                             |
+| `sidebar-min-width` | `string`  | —         | 拖拽调整的下限（px）；默认回退到 `collapsed-width`             |
+| `sidebar-max-width` | `string`  | —         | 拖拽调整的上限（px）；钳制在视口一半以内，内置上限优先于配置值 |
+
+**事件：** `sidebar-collapsed-change`（`CustomEvent<{ collapsed: boolean }>`）用于请求更新桌面端折叠状态；`sidebar-open-change`（`CustomEvent<{ open: boolean }>`）用于请求更新移动端 Drawer 打开状态；`sidebar-width-change`（`CustomEvent<{ width: string }>`）用于请求在拖拽调整结束后更新侧边栏宽度。Consumer 必须将请求值回写到对应的受控属性。
+
+**侧边栏调整宽度：** 启用 `sidebar-resizable` 后，桌面端侧边栏右边缘会出现调整手柄（折叠状态下隐藏）。悬停或拖拽时显示 3px 宽的强调色垂直线和 `col-resize` 光标。拖拽时实时更新宽度（禁止过渡动画，限制在 `[min, max]` 和视口范围内）；释放时触发 `sidebar-width-change` 事件并携带最终像素宽度，控制权交还给 `sidebar-width` 属性等待 Consumer 回写。`pointercancel` 会恢复属性控制的宽度且不触发事件。手柄同时支持键盘（WAI-ARIA splitter 模式）：聚焦后用 ←/→ 以 16px 步进调整（Shift 加速到 64px），Home/End 跳到 min/max，Enter 以同一 `sidebar-width-change` 请求提交，Escape 撤回未提交的调整。移动端 Drawer 始终通过其内置 `draggable` 抽屉支持拖拽关闭。
+
+| 插槽      | 说明                                                         |
+| --------- | ------------------------------------------------------------ |
+| `banner`  | 位于布局主体上方的可选全宽 Banner                            |
+| `header`  | 内容区的 sticky header                                       |
+| `sidebar` | 侧边栏卡片内容；内部固定区域与滚动容器均由 Consumer 自行定义 |
+| `default` | 主内容区                                                     |
+| `tabbar`  | 底部 tabbar                                                  |
+
+`web-ui-layout` 只约束侧边栏卡片的可用空间并管理桌面端 Toggle，不创建侧边栏 scrollport。若仅让侧边栏的一部分滚动，请将 `sidebar` 插槽根节点设为 `height: 100%; min-height: 0` 的 flex column，再将 `overflow-y: auto` 设置到目标子元素。这样 Consumer 可自行固定头部和底部，无需额外的公共 slot。
+
+在 `640px` 及以下，侧边栏会切换为 headless 模式的 `web-ui-drawer`。Consumer 内容仍渲染在相同的圆角侧边栏卡片中，移动端 Toggle 以 glass 变体位于 header 行内。其左缩进默认 `8px`，可通过 `--wui-layout-mobile-toggle-inset` 与 Consumer 自身的 header 内边距对齐。
 
-| 插槽      | 说明       |
-| --------- | ---------- |
-| `header`  | 顶部横幅   |
-| `default` | 主内容区   |
-| `sidebar` | 侧边栏     |
-| `tabbar`  | 底部标签栏 |
+`header-glow` 会在 header 插槽内容和移动端 Toggle 的背后添加 `pointer-events: none` 的装饰性晕染。它属于 Header 背景而非前景层，因此插槽内容始终位于其上方；可通过 `--wui-layout-header-glow-color` 覆盖颜色，默认值为 `--wui-color-page`。晕染浓度和范围由内部变量 `--wui-layout-header-glow-height`（默认 `150%`）控制；增大可加强覆盖，减小则更柔和。布局层级顺序为 Header（`10`）< Auxiliary（`20`）< Banner（`30`）< Tabbar（`40`）< Sidebar（`50`）。
+
+**CSS 自定义属性：**
+
+| 属性                               | 默认值 | 说明                                 |
+| ---------------------------------- | ------ | ------------------------------------ |
+| `--wui-layout-sidebar-radius`      | `24px` | 侧边栏卡片圆角（桌面端和移动端共用） |
+| `--wui-layout-mobile-toggle-inset` | `8px`  | 移动端 header Toggle 的左缩进        |
 
 #### `<web-ui-back-top>`
 
@@ -751,10 +1012,21 @@ WebUiSpinner.hide() // 隐藏
 
 **方法：** `toTop()`
 
-**定位：** `scrollTarget` 为 `window` 时按钮固定在视口角落；为 `HTMLElement` 时需将元素放置在容器内部，按钮通过 `position: sticky` 悬浮于容器底部角落。偏移量沿用 `--web-ui-back-top-top/right/bottom/left` CSS 变量。
+**定位：** `scrollTarget` 为 `window` 时按钮固定在视口角落；为 `HTMLElement` 时需将元素放置在容器内部，按钮通过 `position: sticky` 悬浮于容器底部角落。偏移量沿用 `--wui-back-top-top/right/bottom/left` CSS 变量。
 
 角色：`button`，键盘 Enter 触发回到顶部。
 
+**CSS 自定义属性：**
+
+| 属性                      | 默认值                           | 说明     |
+| ------------------------- | -------------------------------- | -------- |
+| `--wui-back-top-position` | `fixed`                          | CSS 定位 |
+| `--wui-back-top-z-index`  | `var(--wui-layer-auxiliary, 20)` | 层级     |
+| `--wui-back-top-top`      | `auto`                           | 上偏移   |
+| `--wui-back-top-right`    | `20px`                           | 右偏移   |
+| `--wui-back-top-bottom`   | `20px`                           | 下偏移   |
+| `--wui-back-top-left`     | `auto`                           | 左偏移   |
+
 #### `<web-ui-svg-draw-lines>`
 
 SVG 线条绘制动画，基于 `stroke-dashoffset`。直接在原元素上动画 —— 不克隆、不操作 DOM。
@@ -783,7 +1055,84 @@ SVG 线条绘制动画，基于 `stroke-dashoffset`。直接在原元素上动
 
 **方法：** `getOverlayRoot()` — 返回 Portal 浮层容器
 
-定义 `--wui-color-*`、`--wui-shadow-*`、`--wui-layer-*` 与 motion token。motion token 是稳定的主题契约，可在主题范围覆盖：`--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`、`--wui-scale-enter`。`motion="system"` 跟随 `prefers-reduced-motion`；使用 `motion="reduced"` 降低当前作用域动效，或在嵌套主题中使用 `motion="full"` 恢复默认 token。System 配色模式跟随 `prefers-color-scheme`。
+在其子树中定义基础、颜色、层级、阴影和动效 token。`motion="system"` 跟随 `prefers-reduced-motion`；使用 `motion="reduced"` 降低当前作用域动效，或在嵌套主题中使用 `motion="full"` 恢复默认 token。System 配色模式跟随 `prefers-color-scheme`。
+
+**基础 token：**
+
+| 属性                      | 默认值  | 说明                     |
+| ------------------------- | ------- | ------------------------ |
+| `--wui-font-size`         | `14px`  | 控件基础字号             |
+| `--wui-input-width`       | `200px` | 紧凑表单控件默认宽度     |
+| `--wui-control-size`      | `36px`  | 控件默认高度和方形最小宽 |
+| `--wui-overlay-min-width` | `200px` | 锚定浮层最小宽度         |
+| `--wui-focus-ring-width`  | `3px`   | Focus 指示器宽度         |
+
+**层级 token：**
+
+| 属性                         | 默认值 | 说明           |
+| ---------------------------- | ------ | -------------- |
+| `--wui-layer-base`           | `0`    | 基础内容       |
+| `--wui-layer-inline-overlay` | `1`    | 组件内部浮层   |
+| `--wui-layer-header`         | `10`   | 页面 Header    |
+| `--wui-layer-auxiliary`      | `20`   | 悬浮工具控件   |
+| `--wui-layer-banner`         | `30`   | Banner         |
+| `--wui-layer-tabbar`         | `40`   | Tab Bar        |
+| `--wui-layer-sidebar`        | `50`   | 侧边栏         |
+| `--wui-layer-menu`           | `100`  | 菜单/浮动面板  |
+| `--wui-layer-menu-nested`    | `110`  | 嵌套菜单       |
+| `--wui-layer-toast`          | `200`  | Toast          |
+| `--wui-layer-loading`        | `300`  | 阻塞式 Loading |
+
+**动效 token：** duration 默认值为 `--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 token 是 `--wui-ease-enter` 和 `--wui-ease-slide`；进入缩放是 `--wui-scale-enter: 0.97`。hover/active 背景反馈即时切换、无过渡动画；选中态、按压、focus 与 overlay 进出场过渡不受影响。
+
+**颜色 token：**
+
+| 属性                               | 浅色默认值                                                   | 深色默认值                                                   | 说明                   |
+| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------------------- |
+| `--wui-color-page`                 | `#fff`                                                       | `#242628`                                                    | 页面背景               |
+| `--wui-color-surface`              | `#fff`                                                       | `#2c2c2e`                                                    | 普通 表面              |
+| `--wui-color-surface-raised`       | `#f2f2f7`                                                    | `#2c2c2e`                                                    | 抬升表面               |
+| `--wui-color-surface-control`      | `#dfdfdf`                                                    | `#3a3a3c`                                                    | 中性可交互控件表面     |
+| `--wui-color-surface-track`        | `#e5e5ea`                                                    | `#444446`                                                    | Slider/Switch 轨道表面 |
+| `--wui-color-surface-menu`         | `rgb(246 246 246 / 0.82)`                                    | `rgb(30 30 32 / 0.92)`                                       | Menu 和浮动面板表面    |
+| `--wui-color-surface-glass`        | `rgb(250 250 250 / 0.34)`                                    | `rgb(44 44 46 / 0.42)`                                       | 液态玻璃表面           |
+| `--wui-color-surface-glass-hover`  | `color-mix(... text 6%, surface-glass)`                      | `color-mix(... text 6%, surface-glass)`                      | Glass 完整悬停背景     |
+| `--wui-color-surface-glass-active` | `color-mix(... text 15%, surface-glass)`                     | `color-mix(... text 15%, surface-glass)`                     | Glass 完整按下背景     |
+| `--wui-color-surface-overlay`      | `rgb(246 246 246 / 0.82)`                                    | `rgb(32 34 34 / 0.9)`                                        | 半透明浮层表面         |
+| `--wui-color-surface-segmented`    | `#e5e5ea`                                                    | `#3a3a3c`                                                    | Segmented 轨道表面     |
+| `--wui-color-surface-selected`     | `#fff`                                                       | `#5c5c5e`                                                    | Segmented 选中滑块表面 |
+| `--wui-color-text`                 | `#1b1b1b`                                                    | `#e9eaea`                                                    | 主要文本               |
+| `--wui-color-text-secondary`       | `#6a6a6a`                                                    | `#a1a1a6`                                                    | 次要文本               |
+| `--wui-color-text-tertiary`        | `color-mix(in srgb, var(--wui-color-text) 35%, transparent)` | `color-mix(in srgb, var(--wui-color-text) 42%, transparent)` | 三级文本和弱意图图标   |
+| `--wui-color-text-disabled`        | `color-mix(in srgb, var(--wui-color-text) 32%, transparent)` | `color-mix(in srgb, var(--wui-color-text) 38%, transparent)` | 禁用态前景文本         |
+| `--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)`  | 透明悬停层             |
+| `--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)` | 透明按下层             |
+| `--wui-color-border`               | `rgb(0 0 0 / 0.1)`                                           | `rgb(255 255 255 / 0.14)`                                    | 常规边框和分隔线       |
+| `--wui-color-glass-border`         | `transparent`                                                | `rgb(255 255 255 / 0.05)`                                    | Glass 边框色调         |
+| `--wui-color-glass-highlight`      | `rgb(255 255 255 / 0.9)`                                     | `rgb(255 255 255 / 0.1)`                                     | Glass 高光边缘         |
+| `--wui-color-glass-corner`         | `rgb(255 255 255 / 0.08)`                                    | `rgb(255 255 255 / 0.2)`                                     | Glass 边框角落光泽     |
+| `--wui-color-glass-shade`          | `rgb(0 0 0 / 0.06)`                                          | `rgb(0 0 0 / 0.5)`                                           | Glass 边框背光角压暗   |
+| `--wui-color-accent`               | `#08f`                                                       | `#0a84ff`                                                    | Accent 和输入焦点边框  |
+| `--wui-color-on-accent`            | `#fff`                                                       | `#fff`                                                       | Accent 上的前景色      |
+| `--wui-color-on-control`           | `#fff`                                                       | `#f2f2f7`                                                    | 控件内芯前景色         |
+| `--wui-color-success`              | `#16a34a`                                                    | `#30d158`                                                    | 成功                   |
+| `--wui-color-warning`              | `#d97706`                                                    | `#ff9f0a`                                                    | 警告                   |
+| `--wui-color-danger`               | `#dc2626`                                                    | `#ff453a`                                                    | 危险                   |
+| `--wui-color-info`                 | `#2563eb`                                                    | `#64d2ff`                                                    | 信息                   |
+| `--wui-color-backdrop`             | `rgb(0 0 0 / 0.12)`                                          | `rgb(0 0 0 / 0.48)`                                          | Modal 遮罩             |
+| `--wui-color-focus-ring`           | `rgb(0 136 255 / 0.4)`                                       | `rgb(10 132 255 / 0.62)`                                     | Focus 指示器颜色       |
+
+**阴影 token：**
+
+| 属性                   | 浅色默认值                       | 深色默认值                      | 说明              |
+| ---------------------- | -------------------------------- | ------------------------------- | ----------------- |
+| `--wui-shadow-overlay` | `2px 16px 40px rgb(0 0 0 / 0.4)` | `0 18px 48px rgb(0 0 0 / 0.48)` | Modal/Drawer 阴影 |
+| `--wui-shadow-panel`   | `0 3px 9px rgb(0 0 0 / 0.27)`    | `0 4px 16px rgb(0 0 0 / 0.32)`  | 小型浮动面板阴影  |
+| `--wui-shadow-glass`   | 四层扩散阴影                     | `0 8px 24px rgb(0 0 0 / 0.08)`  | 液态玻璃基础阴影  |
+
+**玻璃效果 token：** `--wui-glass-brightness` 浅色模式为 `1.06`，深色模式为 `1.02`。`--wui-glass-corner-radius` 默认值为 `32px`；玻璃组件会以自身的圆角半径覆盖它，使对角描边光影与形状对齐。
+
+**内部 token：** 以 `--wui-internal-*` 为前缀的变量是 Shadow DOM 内部接线变量，不属于公共 token API，消费方不应覆盖。
 
 ---
 
@@ -837,6 +1186,13 @@ toast.updateMessage(id, { message: '上传已完成 60%', heading: '正在上传
 
 悬停暂停自动关闭计时器（使用 `pointerenter`/`pointerleave`）。同一微任务中批量挂载 Toast。
 
+**CSS 自定义属性：**
+
+| 属性                            | 默认值 | 说明                       |
+| ------------------------------- | ------ | -------------------------- |
+| `--wui-toast-viewport-gap`      | `16px` | Toast 到视口边缘的可见距离 |
+| `--wui-toast-container-padding` | `40px` | 容器预留的扩散阴影绘制空间 |
+
 ---
 
 ### 子项
@@ -856,6 +1212,12 @@ toast.updateMessage(id, { message: '上传已完成 60%', heading: '正在上传
 
 非表单关联组件（父级 select 统一提交）。
 
+**CSS 自定义属性：**
+
+| 属性                         | 默认值  | 说明                      |
+| ---------------------------- | ------- | ------------------------- |
+| `--wui-option-check-display` | `block` | 选中勾选图标的 display 值 |
+
 #### `<web-ui-segmented-trigger>`
 
 `<web-ui-segmented>` 的分段按钮。
@@ -869,3 +1231,11 @@ toast.updateMessage(id, { message: '上传已完成 60%', heading: '正在上传
 **事件：** `change`
 
 非表单关联组件（父级 segmented 统一提交）。
+
+**CSS 自定义属性：**
+
+| 属性                                | 默认值                           | 说明             |
+| ----------------------------------- | -------------------------------- | ---------------- |
+| `--wui-segmented-trigger-px`        | `12px`                           | 水平内边距       |
+| `--wui-segmented-trigger-bg-hover`  | `--wui-color-state-layer-hover`  | Trigger 悬停背景 |
+| `--wui-segmented-trigger-bg-active` | `--wui-color-state-layer-active` | Trigger 按下背景 |