@icen.ai/ui 0.11.0 → 0.11.2

package/dist/vue.mjs

@@ -351,6 +351,19 @@ var ICEN_LOCALE_ZH_CN = {
   "charts.noData": "\u6682\u65E0\u6570\u636E",
   "charts.resetZoom": "\u91CD\u7F6E\u7F29\u653E",
   "charts.sampled": "\u5DF2\u62BD\u6837 {p0}\u2192{p1} \u70B9",
+  "charts.a11y.keyboardHint": "\u65B9\u5411\u952E\u9010\u70B9\u6D4F\u89C8\uFF0CHome/End \u8DF3\u9996\u5C3E\uFF0CEsc \u91CD\u7F6E\u7F29\u653E",
+  "charts.a11y.max": "\u6700\u5927 {p0}\uFF08{p1}\uFF09",
+  "charts.a11y.min": "\u6700\u5C0F {p0}\uFF08{p1}\uFF09",
+  "charts.a11y.point": "{p0}\uFF1A{p1}\uFF0C\u7B2C {p2}/{p3} \u70B9",
+  "charts.a11y.pointSeries": "{p0} \xB7 {p1}\uFF1A{p2}\uFF0C\u7B2C {p3}/{p4} \u70B9",
+  "charts.a11y.range": "\u7C7B\u76EE {p0} \u81F3 {p1}",
+  "charts.a11y.scatterRange": "x \u8303\u56F4 {p0}\u2013{p1}\uFF0Cy \u8303\u56F4 {p2}\u2013{p3}",
+  "charts.a11y.seriesCount": "{p0} \u4E2A\u7CFB\u5217",
+  "charts.a11y.tableCaption": "{p0} \u6570\u636E\u8868",
+  "charts.a11y.trend": "\u9996\u7CFB\u5217\u8D8B\u52BF{p0}",
+  "charts.a11y.trendDown": "\u4E0B\u964D",
+  "charts.a11y.trendFlat": "\u6301\u5E73",
+  "charts.a11y.trendUp": "\u4E0A\u5347",
   "charts.type.area": "\u9762\u79EF\u56FE",
   "charts.type.donut": "\u73AF\u5F62\u56FE",
   "charts.type.gauge": "\u4EEA\u8868\u76D8",
@@ -2243,6 +2256,14 @@ function normalizeChartSpec(raw) {
   }
   if (s.zoom === "x" || s.zoom === "brush") spec.zoom = s.zoom;
   if (typeof s.loading === "boolean") spec.loading = s.loading;
+  if (s.a11y && typeof s.a11y === "object") {
+    const a = s.a11y;
+    const a11y = {};
+    if (typeof a.summary === "boolean") a11y.summary = a.summary;
+    if (typeof a.table === "boolean") a11y.table = a.table;
+    if (typeof a.keyboard === "boolean") a11y.keyboard = a.keyboard;
+    if (Object.keys(a11y).length > 0) spec.a11y = a11y;
+  }
   if (Array.isArray(s.marks)) {
     const marks = [];
     for (const raw2 of s.marks) {
@@ -2598,6 +2619,81 @@ function paintVBarChartMarks(root, view, spec, marks, formatValue, warned) {
 function chartAriaLabel(title, typeName) {
   return title ? `${typeName}\uFF1A${title}` : typeName;
 }
+function summarizeChart(view, type, fmt2) {
+  const series = view.series && view.series.length > 0 ? view.series : [{ name: "", values: view.values ?? [] }];
+  const parts = [];
+  if (series.length > 1) parts.push(t("charts.a11y.seriesCount", { p0: series.length }));
+  if (type === "scatter") {
+    const pts = view.points ?? [];
+    if (pts.length > 0) {
+      const xs = pts.map((p) => p.x);
+      const ys = pts.map((p) => p.y);
+      parts.push(t("charts.a11y.scatterRange", { p0: fmt2(Math.min(...xs)), p1: fmt2(Math.max(...xs)), p2: fmt2(Math.min(...ys)), p3: fmt2(Math.max(...ys)) }));
+    }
+    return parts.join("\uFF1B");
+  }
+  const labels = view.labels ?? [];
+  if (labels.length > 1) parts.push(t("charts.a11y.range", { p0: labels[0], p1: labels[labels.length - 1] }));
+  let min = Infinity;
+  let max = -Infinity;
+  let minAt = "";
+  let maxAt = "";
+  for (const s of series) {
+    s.values.forEach((v, i) => {
+      if (v < min) {
+        min = v;
+        minAt = labels[i] ?? String(i + 1);
+      }
+      if (v > max) {
+        max = v;
+        maxAt = labels[i] ?? String(i + 1);
+      }
+    });
+  }
+  if (Number.isFinite(min) && Number.isFinite(max)) {
+    parts.push(t("charts.a11y.min", { p0: fmt2(min), p1: minAt }));
+    parts.push(t("charts.a11y.max", { p0: fmt2(max), p1: maxAt }));
+  }
+  const first = series[0]?.values ?? [];
+  if (first.length > 1) {
+    const d = first[first.length - 1] - first[0];
+    const key = Math.abs(d) < 1e-9 ? "charts.a11y.trendFlat" : d > 0 ? "charts.a11y.trendUp" : "charts.a11y.trendDown";
+    parts.push(t("charts.a11y.trend", { p0: t(key) }));
+  }
+  return parts.join("\uFF1B");
+}
+function buildChartTable(view, spec, type, fmt2) {
+  const table = document.createElement("table");
+  table.className = "icen-chart-table";
+  const caption = document.createElement("caption");
+  caption.textContent = t("charts.a11y.tableCaption", { p0: spec.title ?? String(type) });
+  table.appendChild(caption);
+  const addRow = (target, cells, head) => {
+    const tr = document.createElement("tr");
+    for (const c of cells) {
+      const cell = document.createElement(head ? "th" : "td");
+      if (head) cell.scope = target.tagName === "THEAD" ? "col" : "row";
+      cell.textContent = c;
+      tr.appendChild(cell);
+    }
+    target.appendChild(tr);
+  };
+  const thead = table.createTHead();
+  const tbody = table.createTBody();
+  if (type === "scatter") {
+    addRow(thead, ["x", "y"], true);
+    for (const p of view.points ?? []) addRow(tbody, [fmt2(p.x), fmt2(p.y)], false);
+    return table;
+  }
+  const series = view.series && view.series.length > 0 ? view.series : [{ name: "", values: view.values ?? [] }];
+  const labels = view.labels ?? [];
+  addRow(thead, ["", ...series.map((s, i) => s.name || String(i + 1))], true);
+  const n = Math.max(labels.length, ...series.map((s) => s.values.length));
+  for (let i = 0; i < n; i++) {
+    addRow(tbody, [labels[i] ?? String(i + 1), ...series.map((s) => fmt2(s.values[i] ?? 0))], false);
+  }
+  return table;
+}
 function svgDimsOf(svg) {
   const vb = (svg.getAttribute("viewBox") ?? "").split(/\s+/).map(Number);
   const w = Number.isFinite(vb[2]) && (vb[2] ?? 0) > 0 ? vb[2] : CHART_LINE_W;
@@ -2938,6 +3034,7 @@ function renderChart(el, raw) {
     if (!isZoomableType(t2) || fullLength() < 2) return;
     const plot = t2 === "vbar" ? root.querySelector(".icen-chart-vbar") : root.querySelector(".icen-chart-line svg");
     if (!plot) return;
+    plot.style.touchAction = current2.zoom === "x" ? "pan-y" : "none";
     const on = (type, fn) => {
       plot.addEventListener(type, fn);
     };
@@ -2993,6 +3090,149 @@ function renderChart(el, raw) {
       render();
     });
   };
+  const KB_TYPES = /* @__PURE__ */ new Set(["line", "area", "vbar", "hbar", "scatter"]);
+  const kbCursor = { si: 0, i: 0, active: false };
+  let liveRegion = null;
+  let a11ySeq = 0;
+  const a11yOf = () => ({
+    summary: current2.a11y?.summary !== false,
+    table: current2.a11y?.table === true,
+    keyboard: current2.a11y?.keyboard !== false
+  });
+  const seriesViewOf = (view) => view.series && view.series.length > 0 ? view.series : [{ name: "", values: view.values ?? [] }];
+  const kbPointCount = (view) => typeOf() === "scatter" ? view.points?.length ?? 0 : Math.max(0, ...seriesViewOf(view).map((s) => s.values.length), view.labels?.length ?? 0);
+  const kbCursorEl = () => {
+    const t2 = typeOf();
+    const view = viewOf();
+    const series = seriesViewOf(view);
+    const n = kbPointCount(view);
+    if (n < 1) return null;
+    const si = clampNum(kbCursor.si, 0, Math.max(0, series.length - 1));
+    const i = clampNum(kbCursor.i, 0, n - 1);
+    if (t2 === "line" || t2 === "area") {
+      const svg = root.querySelector(".icen-chart-line svg");
+      if (!svg) return null;
+      const dots = svg.querySelectorAll("circle");
+      let base = 0;
+      for (let k = 0; k < si; k++) base += Math.min(series[k].values.length, n);
+      return dots.item(base + i) ?? null;
+    }
+    if (t2 === "scatter") return root.querySelector(".icen-chart-scatter svg")?.querySelectorAll("circle").item(i) ?? null;
+    if (t2 === "vbar") return root.querySelectorAll(".icen-chart-vbar-bar").item(series.length > 1 ? i * series.length + si : i) ?? null;
+    if (t2 === "hbar") return root.querySelectorAll(".icen-chart-hbar-bar").item(i) ?? null;
+    return null;
+  };
+  const announceKb = (text) => {
+    if (!liveRegion || !liveRegion.isConnected) {
+      liveRegion = document.createElement("div");
+      liveRegion.className = "icen-chart-live";
+      liveRegion.setAttribute("aria-live", "polite");
+      root.appendChild(liveRegion);
+    }
+    liveRegion.textContent = "";
+    liveRegion.textContent = text;
+  };
+  const applyKbCursor = () => {
+    for (const el2 of root.querySelectorAll(".icen-chart-kb-focus")) el2.classList.remove("icen-chart-kb-focus");
+    if (!kbCursor.active) return;
+    kbCursorEl()?.classList.add("icen-chart-kb-focus");
+  };
+  const announceCursor = () => {
+    const view = viewOf();
+    const series = seriesViewOf(view);
+    const n = kbPointCount(view);
+    if (n < 1) return;
+    const si = clampNum(kbCursor.si, 0, Math.max(0, series.length - 1));
+    const i = clampNum(kbCursor.i, 0, Math.max(0, n - 1));
+    const fmt2 = chartFormatValue(current2.format);
+    if (typeOf() === "scatter") {
+      const p = view.points?.[i];
+      if (!p) return;
+      announceKb(t("charts.a11y.point", { p0: `x ${fmt2(p.x)}`, p1: `y ${fmt2(p.y)}`, p2: i + 1, p3: n }));
+      return;
+    }
+    const label = view.labels?.[i] ?? String(i + 1);
+    const value = series[si]?.values[i] ?? 0;
+    if (series.length > 1) announceKb(t("charts.a11y.pointSeries", { p0: series[si].name || String(si + 1), p1: label, p2: fmt2(value), p3: i + 1, p4: n }));
+    else announceKb(t("charts.a11y.point", { p0: label, p1: fmt2(value), p2: i + 1, p3: n }));
+  };
+  const onKbKeydown = (e) => {
+    const conf = a11yOf();
+    if (!conf.keyboard || !KB_TYPES.has(typeOf())) return;
+    const g = root.querySelector("[data-icen-chart-kb]");
+    if (!g || e.target !== g) return;
+    if (e.key === "Escape") {
+      if (zoomWindow) {
+        zoomWindow = null;
+        kbCursor.active = false;
+        render();
+      }
+      return;
+    }
+    const view = viewOf();
+    const series = seriesViewOf(view);
+    const n = kbPointCount(view);
+    if (n < 1) return;
+    const siMax = Math.max(0, series.length - 1);
+    let moved = true;
+    switch (e.key) {
+      case "ArrowRight":
+        kbCursor.i = clampNum(kbCursor.i + 1, 0, n - 1);
+        break;
+      case "ArrowLeft":
+        kbCursor.i = clampNum(kbCursor.i - 1, 0, n - 1);
+        break;
+      case "ArrowDown":
+        kbCursor.si = clampNum(kbCursor.si + 1, 0, siMax);
+        break;
+      case "ArrowUp":
+        kbCursor.si = clampNum(kbCursor.si - 1, 0, siMax);
+        break;
+      case "Home":
+        kbCursor.i = 0;
+        break;
+      case "End":
+        kbCursor.i = n - 1;
+        break;
+      default:
+        moved = false;
+    }
+    if (!moved) return;
+    e.preventDefault();
+    kbCursor.active = true;
+    applyKbCursor();
+    announceCursor();
+  };
+  root.addEventListener("keydown", onKbKeydown);
+  const applyChartA11yPlus = (view, spec, type, formatValue) => {
+    const conf = a11yOf();
+    const graphic = root.querySelector('[role="img"]');
+    if (!graphic) return;
+    const body = root.querySelector(".icen-chart-body") ?? graphic.parentElement ?? root;
+    const summaryParts = [];
+    if (conf.summary) summaryParts.push(summarizeChart(view, type, formatValue));
+    if (conf.keyboard && KB_TYPES.has(type)) summaryParts.push(t("charts.a11y.keyboardHint"));
+    const summaryText = summaryParts.filter(Boolean).join("\uFF1B");
+    if (summaryText) {
+      const p = document.createElement("p");
+      p.className = "icen-chart-summary";
+      p.id = `icen-chart-a11y-${++a11ySeq}`;
+      p.textContent = summaryText;
+      body.appendChild(p);
+      graphic.setAttribute("aria-describedby", p.id);
+    } else {
+      graphic.removeAttribute("aria-describedby");
+    }
+    if (conf.keyboard && KB_TYPES.has(type)) {
+      graphic.setAttribute("tabindex", "0");
+      graphic.setAttribute("data-icen-chart-kb", "");
+    } else {
+      graphic.removeAttribute("tabindex");
+      graphic.removeAttribute("data-icen-chart-kb");
+    }
+    if (conf.table) body.appendChild(buildChartTable(view, spec, type, formatValue));
+    applyKbCursor();
+  };
   const render = () => {
     if (!current2.type) current2 = { ...current2, type: inferChartType(current2) };
     const spec = current2;
@@ -3073,6 +3313,7 @@ function renderChart(el, raw) {
       }
     }
     if (loading) return;
+    applyChartA11yPlus(view, spec, type, formatValue);
     paintChartMarks(root, view, spec, formatValue, warnedMarks);
     bindZoomGesture();
   };
@@ -3154,6 +3395,7 @@ function renderChart(el, raw) {
       releaseFluidWidth(root);
       hiddenLegendKeys.delete(root);
       zoomDragCleanup?.();
+      root.removeEventListener("keydown", onKbKeydown);
       root.textContent = "";
       root.classList.remove("is-loading");
       unbindEvents();

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icen.ai/ui",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Icen Design System — 设计 tokens（6 主题 × 4 原语 × 明暗）+ 无框架组件 CSS/行为 JS + AI 原生组件族（7 态状态机/多模态/定价审计）+ 图表通用层（ChartSpec 纯 JSON）+ AI 工具体系",
   "repository": {
     "type": "git",
@@ -62,6 +62,7 @@
     "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",