@icen.ai/ui 0.10.0 → 0.11.1

package/docs/spec/charts-scale-a11y.md

@@ -0,0 +1,115 @@
+# 图表：数据规模、无障碍与手势（spec）
+
+面向实现者与评审。现状事实源：`src/behaviors/charts.ts`（统一 ChartSpec + renderChart）、`src/components/charts.css`。本文件给出规模分级、渲染策略、读屏语义、键盘与手势模型、性能预算与测试策略。已落地项标注 ✅（含验证方式），接口草案标注 🔵（未实现，类型即合同）。
+
+## 1. 数据规模分级与渲染策略
+
+| 级别 | 规模 | 渲染策略 | 现状 |
+| --- | --- | --- | --- |
+| S | ≤1e3 点 | 纯 SVG/DOM 直渲，无抽样 | ✅ 默认路径 |
+| M | 1e3–1e5 | SVG + LTTB 降采样（默认阈值 1000，`spec.downsample`）| ✅ `lttb()` 纯函数 + `downsampleView`；抽样时头部行提示「已抽样 N→M 点」（诚实呈现，不静默） |
+| L | 1e5–1e6 | LTTB + 视窗（zoom/append 窗口切片后才对视图抽样）| ✅ zoom 窗与 `append(maxPoints)` 头部淘汰已落地 |
+| XL | ≥1e6 | 分层混合：Canvas  raster 层 + SVG 交互层（热点/游标/焦点环）| 🔵 接口草案见 §7；当前 SVG 上限实测见 §6 |
+
+降采样算法选择：**LTTB**（保形状特征，极值不丢）为默认；min-max 分桶适合密度热力预览但不保峰形，作为 🔵 `sampling.method: 'minmax'` 草案保留；时序流式场景用 `append` 的窗口淘汰而非重抽样。
+
+渲染器选择原则：SVG 保交互与 a11y（每点是真实节点，可挂 title/焦点）；Canvas 只在 XL 级引入且必须叠加 SVG 交互层——读屏语义与键盘游标不因渲染器切换而退步。
+
+## 2. 长列表 / 表格 / 树的虚拟滚动
+
+| 组件 | 现状 | 方案 |
+| --- | --- | --- |
+| datatable | ✅ `virtual: true` 固定行高窗口化（`rowHeight` 可调，与分页互斥） | 万级行流畅；动态行高 🔵（测量缓存 + 预估高度 + 滚动锚定，见下） |
+| table | 静态展示组件 | 数据量大时用 datatable；table 不引入虚拟化（职责分离） |
+| tree | 无虚拟化 | 🔵 同 datatable 窗口化；展开/收起时以「首个可见节点的 key + 偏移」做滚动锚定 |
+
+动态行高草案（🔵）：`virtual: { estimatedRowHeight: number; measure?: true }`——IntersectionObserver-free，渲染后测量真实高并写回缓存，滚动锚定 = 记录锚点 key 与其在行内的偏移，重渲后恢复。滚动锚定同样适用于 prepend（聊天/日志流）。
+
+## 3. 屏幕阅读器语义
+
+每个图形的语义三层（✅ 已落地，`tests/dom/charts-a11y.test.ts` 7 项）：
+
+1. **可访问名**：`role="img"` + `aria-label` = 标题（图型）或图型（既有行为，axe 债已清）。
+2. **自动摘要**：sr-only `<p>` 经 `aria-describedby` 挂载——系列数、类目范围、最值及其类目、首系列趋势（升/降/平）；scatter 播报 x/y 范围。`spec.a11y.summary: false` 可关。
+3. **数据表替代视图**：`spec.a11y.table: true` 追加 sr-only `<table>`（caption + thead 系列名 + tbody 类目/值行；scatter 为 x/y 两列）。读屏器按表格语义逐格导航，复制导出同源。
+
+各图型语义矩阵：
+
+| 图型 | role/label | 摘要 | 键盘游标 |
+| --- | --- | --- | --- |
+| line/area | img + describedby ✅ | ✅ 范围/最值/趋势 | ✅ 点级（系列×点） |
+| vbar/hbar | DOM 容器 img + describedby ✅ | ✅ | ✅ 柱条级 |
+| scatter | img + describedby ✅ | ✅ x/y 范围 | ✅ 点级 |
+| donut/radar | img ✅ | ✅ 最值 | 🔵（段导航） |
+| heatmap/calendar | aria-label 网格 ✅ | ✅ 最值 | 🔵（格导航） |
+| gauge/sparkline | img ✅ | ✅ 单值退化 | —（单值无导航必要） |
+| graph/map | img ✅ | 🔵 节点/边计数 | 🔵 |
+
+**不只靠颜色**：多系列折线的区分 = 颜色 + 图例文本 + tooltip/播报中的系列名 + 标记点形状（marks）；键盘游标与播报完全不依赖颜色。纹理/虚线族（stroke-dasharray 轮换）作为 🔵 增强项保留（打印/单色场景）。
+
+## 4. 键盘导航模型与 live region
+
+✅ 已落地（`spec.a11y.keyboard` 默认开）：
+
+- 图形可聚焦（`tabindex=0` + `:focus-visible` 环）；**←/→** 逐点、**↑/↓** 切系列（多系列）、**Home/End** 跳首尾、**Esc** 重置缩放窗。
+- 游标视觉：SVG 点圆放大加粗（`r` 几何属性 + stroke-width；不支持 `r` 的浏览器退化为描边），DOM 柱条用 accent 轮廓环。
+- 播报：单个 `aria-live="polite"` region 随图表存活，播报「系列 · 类目：值，第 i/n 点」；先清空再写入保证同值重报。
+- 与 tooltip/事件族正交：键盘导航不触发 hover 事件，避免双通道噪音。
+
+## 5. 交互手势
+
+现状（✅）：`spec.zoom: 'x'|'brush'` 指针拖选缩放（统一 pointer 事件，位移 <5px 视为点击；pointercancel 按 pointerup 收口）；头部 chip 与双击 plot 复原；`icen:chart-zoom {chart,from,to}` 广播。
+
+本分支补齐（✅）：**触屏冲突**——zoom 启用时 plot 的 `touch-action`：`'x'` 为 `pan-y`（垂直留给页面滚动，水平拦拖选），`'brush'` 为 `none`（自由框选接管）。惯性不做（类目语义图表的惯性滚动会造成定位歧义，有意拒绝）。
+
+键盘等价：方向键游标 = 平移/浏览等价；Esc = 重置等价；双指缩放的键盘等价 🔵（`+`/`-` 以游标为中心缩放，接口预留）。
+
+触屏替代：tooltip 已有点击语义；游标类在触屏上不显示（无焦点）。
+
+## 6. 性能预算与基准
+
+预算（验收口径，桌面中端机 Chrome；首绘 = renderChart 同步返回 + 一帧）：
+
+| 指标 | 预算 | 量级依据 |
+| --- | --- | --- |
+| LTTB 1e6→1000 | <10ms JS | 实测 5.25ms（bun，本机） |
+| normalizeChartSpec 1e5 类目 | <10ms JS | 实测 3.27ms |
+| renderChart line 1e4（抽样开） | <100ms JS（happy-dom 口径） | 实测 63.9ms；浏览器 DOM 低于此 |
+| 交互帧（游标/图例切换） | <16ms | 类切换 + 单点重绘 |
+| 内存 | 视图点数 ≤ 抽样阈值 + 窗口 | LTTB 输出 ≤1000 点 |
+
+基准方法：`bun scripts/bench-charts.mjs`（可重复，口径写在脚本头注释：JS 侧耗时，不含绘制/合成；绘制预算由 e2e 视觉舱与人工 DevTools Performance 抽样验收）。数字为量级参考，随硬件变——评审看量级与回归趋势，不比绝对值。
+
+## 7. 接口草案（🔵 未实现，类型即合同）
+
+```ts
+/** XL 级（≥1e6）分层渲染：Canvas raster + SVG 交互层。a11y 层语义不因渲染器切换而退步。 */
+interface ChartCanvasRenderer {
+  /** 绘制视窗内点云（OffscreenCanvas 可迁移 Worker） */
+  paint(view: ChartSpec, window: { from: number; to: number }): void;
+  /** 命中测试交给 SVG 交互层（分桶索引），本层只管画 */
+  destroy(): void;
+}
+
+/** Worker 降采样池：大数据 LTTB 移出主线程；返回 Promise，不阻塞首绘 */
+interface ChartSamplingWorker {
+  sample(points: readonly { x: number; y: number }[], threshold: number): Promise<readonly number[]>;
+  terminate(): void;
+}
+
+/** 声音化（可选增强，默认关）：逐点音高映射值域，键盘游标移动时发声 */
+interface ChartSonifyOptions {
+  enabled: boolean;          // 默认 false；开启需用户动作（音频上下文策略）
+  rangeHz?: [number, number]; // 默认 [220, 880]
+}
+```
+
+落地顺序建议：Worker 降采样 > Canvas 层 > sonification。每一层都必须先过 a11y 回归（摘要/表格/键盘游标不降级）。
+
+## 8. 测试策略
+
+- ✅ DOM 测试 `tests/dom/charts-a11y.test.ts`：摘要内容、describedby 接线、数据表结构、键盘全键位、边界 clamp、update 后游标保持、destroy 解绑。
+- ✅ 既有 axe 基线（`tests/e2e/a11y.pw.ts` + a11y-baseline.json）覆盖组件页；本层新增的 sr-only 节点不改变像素（视觉基线无漂移）。
+- ✅ LTTB 单元测试（`tests/unit/charts-lttb.test.ts`）。
+- 手测矩阵（发布前人工）：NVDA + Chrome（摘要/表格/游标播报）、VoiceOver + Safari（macOS/iOS 各一）、键盘-only 全流程（焦点可见、无键盘陷阱）、200% 缩放与 Windows 高对比（forced-colors 已有滚动条/焦点环兜底）。
+- 视觉回归：游标类只在键盘聚焦时出现，默认截图不含；`a11y.table` 的 sr-only 表格不渲染进位图。

package/docs/spec/design-philosophy.md

@@ -47,11 +47,11 @@ GitHub Primer 的语义色纪律、Radix Colors 的阶梯尺、Stripe 的"深档
 ### 2.1 圆角六档职责
 | 档 | 现代默认值（随 design-radius 联动） | 职责 |
 |---|---|---|
-| `xs` | 4px | 微型件内角：芯片、徽标、小标签 |
-| `sm` | 8px | 控件内嵌：按钮、输入框、小卡 |
-| `md` | 10px | 默认容器：卡片、面板、浮层 |
-| `lg` | 16px | 大容器：modal、工作台卡 |
-| `xl` | 24px | 页面级容器/展示面 |
+| `xs` | 5px | 微型件内角：复选框、菜单项、日期格、小标签 |
+| `sm` | 8px | 控件：按钮、输入框、选择器 |
+| `md` | 10px | 内嵌块、大控件 |
+| `lg` | 14px | 卡片、面板、菜单与 popover |
+| `xl` | 20px | 弹窗与页面级展示面 |
 | `full` | 999px | **胶囊语义专用**（跑道形） |
 
 ### 2.2 同心圆法则（Concentric Corners，取法 Apple HIG）

package/docs/spec/design-primitives.md

@@ -22,7 +22,7 @@
 
 1. **作者种子** `--icen-design-*`：品牌色、表面、文字、几何、节奏、字体、材料参数。
 2. **语义映射**：推导已有 `--icen-token-* / --icen-radius-* / --icen-density-*`，让现有组件受益。
-3. **材料角色**：content / chrome / floating，共享边缘、模糊和阴影配方。
+3. **材料角色**：content / chrome / floating，共享边缘、实面和阴影配方。
 4. **组件适配**：按钮、输入、分段选择、菜单、弹窗等，处理仅靠变量无法表达的细节。
 
 现代主题为中性瓷白＋冷蓝，独立校准，不继承其它主题的配色。
@@ -40,12 +40,12 @@
 | 角色 | 背景 | 光与影 | 用途 |
 | --- | --- | --- | --- |
 | content | 不透明 | 轻边界，不投影 | 阅读与编辑 |
-| chrome | 条件启用透光 | 顶部微光 | 导航与操作 |
-| floating | 条件启用透光 | 接触影＋环境影＋顶部微光 | 临时面板 |
+| chrome | 不透明 | 顶部微光 | 导航与操作 |
+| floating | 不透明 | 接触影＋环境影＋顶部微光 | 临时面板 |
 
 布局、定位和内边距归业务页面。材料不携带固定宽高，不强行让所有内容成为卡片。`data-icen-material` 的通用外轮廓使用 lg 圆角；需要贴边的站栏可由布局覆盖。
 
-透明度只在支持 backdrop-filter 的浏览器中启用，否则自动使用不透明表面。`prefers-reduced-transparency: reduce` 与 `<html data-icen-transparency="reduced">` 都强制不透明。透明表面的实际对比度依赖背后内容，仍需实屏验证。
+modern 的内容、操作与临时面板始终使用不透明表面，不启用背景模糊。`glass-*` 参数保留供自有材料和既有品牌配方兼容使用；不会让 modern 的标准操作面变成玻璃。`prefers-reduced-transparency: reduce` 与 `<html data-icen-transparency="reduced">` 继续提供跨原语的实面降级。
 
 ## 修改与新增品牌
 
@@ -115,9 +115,9 @@ setDesign(brand.name);
 | success / warning / error / info | 明暗各有独立值，见源码 | 语义色 |
 | radius | 10px | 六档轮廓的共同起点 |
 | space | 4px | 布局节奏单位 |
-| control-height | 40px | 标准操作高度 |
-| font-size / font | 14px / 系统无衬线 | 界面阅读基准 |
-| glass-opacity / glass-blur | 82% / 20px；88% / 20px | 操作层材料 |
+| control-height | 34px | 标准操作高度（density compact 28 / comfortable 38） |
+| font-size / font | 13px / 系统无衬线 | 界面阅读基准；中文下限 12px |
+| glass-opacity / glass-blur | 84% / 24px；90% / 24px | 自有材料的兼容参数，modern 标准组件不消费模糊 |
 | shadow-color / shadow-strength | 中性灰 11%；黑 28% | 接触影与环境影 |
 | light / highlight-strength | 白 70%；白 9% | 表面边缘光 |
 | edge-strength | 12% / 14% | 材料边界 |
@@ -128,8 +128,8 @@ CSS 作者可以直接覆盖全部种子；类型 API 暴露常用旋钮，并
 ## 现代的具体判断
 
 - **文字**：界面系统无衬线；代码单独等宽；数据才使用 tabular-nums。取消全局 Numeric Math 混排。正文阅读可在业务排版中提高到 16px。
-- **几何**：xs/sm/md/lg/xl 从共同控件半径推导；贴合内外轮廓同心，独立控件保留自身半径。分段选择内角扣掉外壳 padding 与边框。
-- **密度**：normal / compact / comfortable 改变间距和控件高度，不缩小文字；嵌套密度可恢复 normal。触摸环境控件至少 44px。
+- **几何**：xs/sm/md/lg/xl 为 5/8/10/14/20px，从共同基准推导。控件 8px、卡片与面板 14px、弹窗 20px；贴合内外轮廓同心，独立控件保留自身半径。分段选择内角扣掉外壳 padding 与边框。
+- **密度**：normal / compact / comfortable 改变间距和控件高度，不缩小文字；嵌套密度可恢复 normal。触摸环境控件至少 44px。KB 行内操作使用 `--icen-density-item-height`（normal 28 / compact 24 / comfortable 32px），嵌套密度重新计算字号角色。
 - **反馈**：hover 以中性变化为主，主要动作用品牌色；键盘焦点始终明确。按压轻缩放，减少位置漂移。
 - **选择**：分段选择使用中性表面和接触影，不把每次选择都变成品牌强调。
 - **光照**：暗色保留遮挡阴影，降低高光并重新设置边缘，避免照搬亮色投影。
@@ -149,7 +149,7 @@ CSS 作者可以直接覆盖全部种子；类型 API 暴露常用旋钮，并
 
 运行时使用 `setPrimitive("pixel")`；自建原语先 `registerPrimitive("brand-shape")`，再用 `[data-icen-style="brand-shape"]` 覆盖几何、字体、光影参数。主题仍单独由 setTheme({preset:...}) 选择。
 
-Apple 研究参考：[Materials](https://developer.apple.com/design/human-interface-guidelines/materials)、[Meet Liquid Glass](https://developer.apple.com/videos/play/wwdc2025/219/)。现代实现以内容／操作分层、同心几何、文字可读性为准则；Web 材料不是系统 Liquid Glass 的光学模拟。
+现代实现以内容／操作分层、同心几何、文字可读性为准则；使用稳定实面、细边与接触影建立空间。
 
 ## 中式与苏式原语
 

package/docs/spec/motion-typography.md

@@ -0,0 +1,105 @@
+# 动效令牌与排版尺度（spec）
+
+面向实现者与评审。令牌定义在 `src/tokens/motion.css` 与 `src/tokens/typography.css`；运行时口径在 `src/behaviors/motion.ts`；DTCG 导出经 `scripts/dtcg.mjs`（`dist/tokens/dtcg.json`）。组件只消费令牌与语义别名，不写死时长、曲线、字号。
+
+## 1. 动效令牌
+
+### 1.1 时长阶梯
+
+| 令牌 | 值 | 场景 | 反例 |
+| --- | --- | --- | --- |
+| `--icen-motion-duration-instant` | 0ms | 像素原语全量；状态复位 | 用它"省掉"必要的过渡反馈 |
+| `--icen-motion-duration-fast` | 110ms | hover / press / 焦点环微反馈 | 浮层进出场（太短促） |
+| `--icen-motion-duration-base` | 180ms | 展开收起、淡入淡出、勾选 | 页面级转场 |
+| `--icen-motion-duration-slow` | 260ms | 浮层进出、modal、面板滑入 | 高频 hover 反馈（拖沓） |
+| `--icen-motion-duration-deliberate` | 420ms | 页面级转场、强调入场 | 常规控件（必须克制，>420ms 需评审） |
+
+消费口径：组件读语义别名 `--icen-duration-fast/normal/slow/deliberate`（design.css 映射 = 基值 × `--icen-design-motion`）；`instant` 同样有别名。新组件可直接读 `--icen-motion-duration-*` 基值（不缩放，用于设计工具对齐场景）。
+
+### 1.2 缓动集
+
+| 令牌 | 值 | 场景 | 反例 |
+| --- | --- | --- | --- |
+| `--icen-motion-ease-standard` | cubic-bezier(.45,0,.25,1) | 持续类状态变化（颜色、宽度） | 入场（缺加速初速感） |
+| `--icen-motion-ease-enter` | cubic-bezier(.16,1,.3,1) | 入场：快出慢归 | 离场（会显犹豫） |
+| `--icen-motion-ease-exit` | cubic-bezier(.4,0,1,1) | 离场：快进加速 | 入场（像被弹开） |
+| `--icen-motion-ease-emphasized` | cubic-bezier(.22,.8,.24,1) | 强调：长减速弧（hero、落板） | 高频微交互 |
+| `--icen-motion-ease-spring` | linear() 阻尼弹簧近似（过冲 ≈8%）；不支持 linear() 的浏览器回退 emphasized | 抽屉、卡片回弹 | 表单控件状态变化（过冲多余） |
+
+回退声明在 `motion.css` 的 `@supports (transition-timing-function: linear(0,1))` 块——可降级增强，不 polyfill。`linear()` / `steps()` 超出 DTCG 经典版标量，导出时明示跳过（`dtcg.json` 的 `ai.icen.skipped`）。
+
+### 1.3 幅度与编排
+
+| 令牌 | 值 | 场景 | 反例 |
+| --- | --- | --- | --- |
+| `--icen-motion-shift-sm` | 2px | 行内微移（列表项 hover） | 弹层入场（幅度不足） |
+| `--icen-motion-shift-md` | 6px | 浮层/气泡入场位移 | 抽屉 |
+| `--icen-motion-shift-lg` | 12px | 抽屉/面板入场位移 | 行内微移（晃眼） |
+| `--icen-motion-scale-enter` | .96 | 弹层入场起始缩放 | 大于 .96 的夸张缩放入场 |
+| `--icen-motion-scale-press` | .985 | 按下形变 | 持续缩放循环 |
+| `--icen-motion-stagger-step` | 24ms | 列表/卡片瀑布入场相邻延迟 | 超过 40ms 的排队（显卡顿） |
+| `--icen-motion-stagger-count` | 5 | 级联上限，超出同拍 | 全列表逐项延迟（长尾等待） |
+
+### 1.4 与预设、原语的联动
+
+- 配色预设（themes.json 六套）不动效：动效与色彩正交。
+- 原语：pixel 原语把 `--icen-motion-ease-*` 全部改写为 `steps(1, end)`，且 `--icen-design-motion: 0` 使时长归零（点阵逐帧美学）；chinese / soviet 沿用现代动效曲线，仅在其自有块覆盖排版与几何。
+- 明暗：不动效。
+
+## 2. reduced-motion 策略
+
+降级链（实现于 `base.css`，运行时口径 `behaviors/motion.ts`）：
+
+1. **默认遵循系统**：`@media (prefers-reduced-motion: reduce)` 时 `--icen-design-motion: 0` → 全部 `--icen-duration-*` 过渡瞬时完成；循环/环境动画（spinner、skeleton、脉冲）单次瞬时；平滑滚动关闭。（Chromium 实测：reduce 下 0s 被钳制为 0.01ms 序列化，语义等同瞬时，保证 transitionend 派发。）
+2. **手动覆盖**：`<html data-icen-motion="reduce">` 无需系统设置即可降级；`"full"` 在系统降级时显式恢复（演示机、用户显式选择）。属性优先级高于系统偏好。
+3. **降级而非移除**：状态变化仍然可见，只是瞬时完成；一次性的状态表达保留。组件编写约定：入场动画应同时含 opacity 与 transform——顺畅时是"移动+淡入"，降级时是瞬时呈现，不会出现"什么都没发生"。
+4. **JS 同口径**：`icenMotionReduced()` 读取与 CSS 相同的判定（属性 > 系统）；`onIcenMotionChange(cb)` 统一订阅 matchMedia 与属性改写，返回销毁函数；`setIcenMotion(mode|null)` 写覆盖。JS 驱动的视差、autoplay、canvas 循环必须走此口径停止运动、保留状态。
+
+反模式（守卫/评审拦截）：组件内写死 `transition-duration` 毫秒值；用 `!important` 自创降级块；JS 动画只读 matchMedia 不看手动覆盖。
+
+## 3. 排版尺度
+
+### 3.1 内容排版尺度（typography.css）
+
+模块比例 1.250（大三度），`clamp()` 流体插值；面向内容/文档排版。控件字号仍由 `--icen-density-font-size-*` 驱动——**两套尺度解耦：密度档只压缩控件，不挤压阅读**。
+
+| 令牌 | 区间（min→max） | 场景 |
+| --- | --- | --- |
+| `--icen-type-xs` | 11→12px | 角标、时间戳 |
+| `--icen-type-sm` | 12.5→14.4px | 辅助说明、表注 |
+| `--icen-type-md` | 14→16px | 正文基准 |
+| `--icen-type-lg` | 16→20px | 小节标题、导语 |
+| `--icen-type-xl` | 20→25px | 页标题 |
+| `--icen-type-2xl` | 25→31.25px | 区块主标 |
+| `--icen-type-3xl` | 31.25→39px | hero（克制使用） |
+
+行高：`--icen-leading-tight` 1.3（大标题）/ `-base` 1.6（正文，CJK 混排安全下限）/ `-loose` 1.8（长文）。字距：`--icen-tracking-tight` -.02em（大号拉丁标题）/ `-base` 0 / `-wide` .04em（眉标）。字重：`--icen-weight-regular/medium/semibold/bold` = 400/500/600/700。
+
+### 3.2 CJK 与拉丁混排
+
+- 字体栈：`--icen-font-cjk` 默认跟随标题字体，栈内含 PingFang SC / Hiragino Sans GB / Microsoft YaHei（design.css）；像素原语整体替换为点阵字体。
+- 标点挤压：`text-spacing-trim: trim-start` 渐进增强（Chrome 123+，`@supports` 守卫；不支持即浏览器默认，不 polyfill）。
+- 数字：数据密集区用 `font-variant-numeric: lining-nums tabular-nums`（`.icen-numeric` / `.icen-font-math` 已消费；新增 `--icen-feature-data` 令牌供新组件）。
+- CJK 字距一律 0（`--icen-tracking-tight` 仅拉丁大标题；不对 CJK 正文加字距）。
+
+### 3.3 紧凑密度
+
+`data-icen-density="compact|comfortable"` 只作用于 `--icen-density-*`（控件高度/间距/控件字号，style-profiles.css），不影响 `--icen-type-*` 内容尺度。数据密集界面应开密度档而不是缩小正文字号。
+
+## 4. DTCG 导出
+
+`bun run dtcg` 导出时长（duration）、缓动（cubicBezier）、位移（dimension）、缩放/行高/字重/级联数（number）各族；clamp()、`linear()`、`steps()`、font-feature-settings 字符串超出经典版标量，逐条记录在 `ai.icen.skipped` 并注明原因——不猜不静默。
+
+## 5. 文档页信息结构（tokens 页扩展建议）
+
+1. 动效族：时长阶梯演示条（同曲线五档并排播放）→ 缓动曲线卡（SVG 曲线 + 用途/反例）→ 幅度尺（shift/scale 对照）→ stagger 演示列表。
+2. 降级演示：开关 `data-icen-motion="reduce|full|系统"`（调 `setIcenMotion`），同一块动画区实时对照。
+3. 排版族：尺度阶梯表（实际渲染字号 + 区间）→ 行高/字距对照 → CJK 混排样张 → 密度档对照（控件 vs 内容）。
+4. 每令牌一行：名称 / 值 / 一句话场景 / 反例（与本 spec 表格同源）。
+
+## 验收
+
+- `bun run guard` 全绿（token 引用、meta、契约快照含新增变量与 motion.ts 导出）。
+- `bun test tests/unit/motion.test.ts` 5/5：覆盖优先级、订阅销毁、非法值回退。
+- `bun scripts/dtcg.mjs` 导出 motion-duration/motion-ease 等族，linear()/clamp() 记入 skipped。
+- reduced-motion e2e：系统 reduce 下 `--icen-duration-fast` 计算值 0ms；`data-icen-motion="full"` 恢复 110ms；手动 reduce 无需系统设置。

package/docs/spec/scrollbars.md

@@ -0,0 +1,46 @@
+# 滚动条
+
+全局使用原生滚动条，不替换滚动容器、不拦截滚轮、不模拟滑块。Chromium/WebKit 使用统一无箭头样式；Firefox 使用标准细滚动条，具体几何由浏览器和系统控制。浏览器、系统或强制颜色模式的可访问性设置可覆盖皮肤。
+
+标准 `scrollbar-color` / `scrollbar-width` 的非 auto 值会覆盖 WebKit 伪元素皮肤，因此支持伪元素的浏览器使用 auto 值以保留无箭头规则；其余浏览器使用标准属性回退。参考 [MDN scrollbar-color](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/scrollbar-color) 与 [WebKit 滚动条说明](https://webkit.org/blog/363/styling-scrollbars/)。
+
+全量引入 `@icen.ai/ui/ui.css` 即包含样式。按需引入时使用 `tokens.css` + `base.css`，再加需要的组件 CSS；`kit/scroll-area` 导出行为和容器样式，仍需上述全局底座。只引 CSS 时保持可见。启用闲置策略：
+
+```ts
+import { initScrollArea } from '@icen.ai/ui/behaviors/scroll-area';
+const dispose = initScrollArea(); // 文档委托，接管之后插入的原生滚动区与 portal
+// 或 initScrollArea({ root: element, idleDelay: 1200 })
+// 卸载时 dispose()：移除监听、清理定时器并恢复状态属性
+```
+
+| `data-icen-scrollbars` | 滚动时 | 悬停时 | 聚焦时 | 闲置后 |
+| --- | --- | --- | --- | --- |
+| `auto` | 显示 | 容器悬停时显示 | 显示 | 指针离开且失焦后隐藏 |
+| `scroll`（启用行为后的默认） | 显示 | 不唤醒 | 显示 | 未聚焦时隐藏 |
+| `visible` | 显示 | 显示 | 显示 | 显示 |
+| `hidden` | 隐藏 | 隐藏 | 隐藏 | 隐藏，仍可滚动 |
+
+策略在子树继承，嵌套组件可另设模式。默认 scroll 下，指针停在内容区不阻止闲置隐藏；菜单等需要悬停时保持可见的区域可显式使用 auto。文档根滚动条不因整页悬停一直亮起。无溢出时浏览器不绘制滑块。闲置策略只改变颜色，不反复增减宽度，因此停止滚动时不会造成内容跳动。`hidden` 会取消滚动条占位，适合已有其他导航提示的区域。需要持续位置提示时用 visible。需要直接键盘滚动的普通容器应提供 `tabindex="0"` 和名称。
+
+```html
+<div class="icen-scroll-area" tabindex="0" aria-label="运行日志"
+     data-icen-scrollbars="scroll" data-icen-scrollbar-delay="1200"
+     data-icen-scrollbar-gutter="stable"
+     style="max-height:20rem; --icen-token-scrollbar-size:10px">
+  …
+</div>
+```
+
+| 局部控制槽 | 默认 | 用途 |
+| --- | --- | --- |
+| `--icen-token-scrollbar-size` | 8px | 双轴尺寸；`--sm` 6px、`--lg` 12px |
+| `--icen-token-scrollbar-inset` | 2px | 滑块与槽边的透明内距 |
+| `--icen-token-scrollbar-track` | transparent | 轨道颜色 |
+| `--icen-token-scrollbar-thumb` / `-thumb-hover` | 当前主题墨色混合 | 默认/悬停滑块颜色 |
+| `--icen-token-scrollbar-idle-delay` | 900ms | 停止滚动多久后隐藏 |
+| `--icen-token-scrollbar-fade-duration` | normal 动效时长 | 支持原生滑块颜色过渡的浏览器使用；其他环境直接隐藏 |
+| `--icen-token-scrollbar-gutter` | auto | 原生留槽策略 |
+
+延时优先级：最近祖先的 `data-icen-scrollbar-delay`（毫秒）→ `idleDelay` 参数 → CSS token。运行时读取当前值，修改后下一次滚动生效。非法延时回退 900ms，范围限制为 0–60000ms。留槽也可用 `data-icen-scrollbar-gutter="auto|stable|both-edges"`，与是否显示滑块独立。
+
+减少动效时禁用颜色过渡，保留延时显示/隐藏；强制颜色模式恢复系统可见滚动条。原生控件内部、跨源 iframe 与 Shadow DOM 的封闭内部由其宿主控制；如需开放影子树内的滚动活动跟踪，应在内部容器单独初始化。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@icen.ai/ui",
-  "version": "0.10.0",
-  "description": "Icen Design System — 设计 tokens（8 主题 × 4 原语 × 明暗）+ 无框架组件 CSS/行为 JS + AI 原生组件族（7 态状态机/多模态/定价审计）+ 图表通用层（ChartSpec 纯 JSON）+ AI 工具体系",
+  "version": "0.11.1",
+  "description": "Icen Design System — 设计 tokens（6 主题 × 4 原语 × 明暗）+ 无框架组件 CSS/行为 JS + AI 原生组件族（7 态状态机/多模态/定价审计）+ 图表通用层（ChartSpec 纯 JSON）+ AI 工具体系",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/icen-ai/ui.git"
@@ -28,6 +28,10 @@
   "sideEffects": [
     "**/*.css"
   ],
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "bun@1.3.5",
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
@@ -58,14 +62,23 @@
     "dtcg": "bun scripts/dtcg.mjs",
     "design-tokens": "bun scripts/design-tokens.mjs",
     "guard": "bun scripts/guard/index.ts",
+    "meta": "bun scripts/meta.mjs",
+    "contracts": "bun scripts/contracts.ts --check",
+    "contracts:update": "bun scripts/contracts.ts --write",
+    "contracts:diff": "bun scripts/contracts.ts --diff",
+    "size": "bun scripts/size.ts",
+    "check:pkg": "bunx publint && bunx @arethetypeswrong/cli --pack . --ignore-rules no-resolution cjs-resolves-to-esm",
     "prepublishOnly": "bun run build",
     "pretest:e2e": "cd site && bun run build",
     "test": "bun test",
+    "test:coverage": "bun scripts/coverage.ts",
     "test:e2e": "playwright test",
-    "verify": "bunx tsc --noEmit && bun run guard && bun test && bun run build",
+    "test:e2e:update": "playwright test --update-snapshots",
+    "verify": "bunx tsc --noEmit && bun run guard && bun test && bun run build && bun run size",
     "colors": "bun scripts/theme-colors.mjs"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
     "@happy-dom/global-registrator": "^20.14.5",
     "@playwright/test": "^1.63.0",
     "@types/node": "^20.14.0",
@@ -73,6 +86,7 @@
     "@types/react-dom": "^19.3.0",
     "axe-core": "^4.14.0",
     "happy-dom": "^20.14.5",
+    "publint": "^0.3.25",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "tsup": "^8.3.0",