@icen.ai/ui 0.10.0 → 0.11.0

package/dist/vue.d.mts

@@ -1,22 +1,22 @@
-import { AiClient, AiAuditor } from './behaviors/ai-provider.js';
+import { AiClient, AiAuditor } from './behaviors/ai-provider.mjs';
 import * as vue from 'vue';
 import { PropType, Ref } from 'vue';
-import { IcenEventMap } from './behaviors/events.js';
-import { ChartSpec } from './behaviors/charts.js';
-export { ChartHandle } from './behaviors/charts.js';
-import { TableOptions } from './behaviors/datatable.js';
-export { TableColumn, TableHandle } from './behaviors/datatable.js';
-import { AiMessageModel } from './behaviors/ai-chat.js';
-export { AiMessageHandle } from './behaviors/ai-chat.js';
-import { AiProviderOption, AiComposerCurrentModel, AiComposerBindOpts } from './behaviors/ai-composer.js';
-export { AiContent, AiContentPart, AiStatus, AiToolCallModel, AiUsage } from './behaviors/ai-core.js';
-import './behaviors/mentions.js';
-import './behaviors/suggestions.js';
-import './behaviors/kb-core.js';
-import './behaviors/icons.js';
-import './behaviors/popover.js';
-import './behaviors/ai-panel.js';
-import './behaviors/context-menu.js';
+import { IcenEventMap } from './behaviors/events.mjs';
+import { ChartSpec } from './behaviors/charts.mjs';
+export { ChartHandle } from './behaviors/charts.mjs';
+import { TableOptions } from './behaviors/datatable.mjs';
+export { TableColumn, TableHandle } from './behaviors/datatable.mjs';
+import { AiMessageModel } from './behaviors/ai-chat.mjs';
+export { AiMessageHandle } from './behaviors/ai-chat.mjs';
+import { AiProviderOption, AiComposerCurrentModel, AiComposerBindOpts } from './behaviors/ai-composer.mjs';
+export { AiContent, AiContentPart, AiStatus, AiToolCallModel, AiUsage } from './behaviors/ai-core.mjs';
+import './behaviors/mentions.mjs';
+import './behaviors/suggestions.mjs';
+import './behaviors/kb-core.mjs';
+import './behaviors/icons.mjs';
+import './behaviors/popover.mjs';
+import './behaviors/ai-panel.mjs';
+import './behaviors/context-menu.mjs';
 
 type MaybeRef<T> = T | Ref<T | null>;
 type Cleanup = (() => void) | void;

package/dist/vue.mjs

@@ -168,6 +168,7 @@ var ICEN_LOCALE_ZH_CN = {
   "aiChat.roleTool": "\u5DE5",
   "aiChat.roleUser": "\u6211",
   "aiChat.thinking": "\u601D\u8003 {p0}",
+  "aiChat.thinkingNow": "\u6B63\u5728\u601D\u8003\u2026",
   /* ── aiComposer ── */
   "aiComposer.attachAgent": "\u4EE3\u7406",
   "aiComposer.library": "\u6DFB\u52A0\u4E0A\u4E0B\u6587\u4E0E\u547D\u4EE4",
@@ -1215,7 +1216,8 @@ function withChrome(el, opts, hasLegend, paint, state, extras) {
     emitIcen(el, "icen:chart-legend-visibility", { visible: hidden ? false : true });
   });
   syncEye();
-  head.append(title, eye);
+  if (hasLegend) head.append(title, eye);
+  else head.append(title);
   el.append(head, body);
   paint(body);
 }
@@ -1316,7 +1318,7 @@ function renderVBar(el, opts) {
       wrap.appendChild(track);
     }
     body.append(wrap, labelsRow(labelsUsed));
-    if (seriesList.length > 1) body.appendChild(toggleLegend(seriesList.map((s, si) => ({ key: s.name, label: s.name, tone: s.tone ?? (si === 0 ? opts.tone : void 0), si })), wrap));
+    if (seriesList.length > 1) body.appendChild(toggleLegend(seriesList.map((s, si) => ({ key: `${si}:${s.name}`, label: s.name, tone: s.tone ?? (si === 0 ? opts.tone : void 0), si })), wrap));
   });
   attachChartInteraction(el, "vbar");
   return el;
@@ -1411,8 +1413,10 @@ function renderDonut(el, opts) {
       "stroke-width": "14"
     }));
     let offset = 0;
+    const gap = opts.segments.length > 1 ? 2.5 : 0;
     opts.segments.forEach((seg, segIndex) => {
-      const dash = seg.value / total * circumference;
+      const arcLength = Math.max(0, seg.value / total * circumference);
+      const dash = arcLength - Math.min(gap, arcLength * 0.1);
       const arc = svgEl("circle", {
         cx: "60",
         cy: "60",
@@ -1426,7 +1430,7 @@ function renderDonut(el, opts) {
       });
       setMarkData(arc, { index: segIndex, label: seg.label, value: seg.value });
       svg.appendChild(arc);
-      offset += dash;
+      offset += arcLength;
     });
     const legend = document.createElement("div");
     legend.className = "icen-chart-legend";
@@ -1461,8 +1465,9 @@ function renderLine(el, opts) {
     const svg = svgEl("svg", { viewBox: `0 0 ${width} ${height}`, role: "img", "aria-label": chartAriaLabel(opts.title, t("charts.type.line")) });
     const defs = svgEl("defs", {});
     for (let i = 0; i < 4; i++) {
-      const y = pad + i * (height - pad * 2) / 3;
+      const y = Math.round(pad + i * (height - pad * 2) / 3) + 0.5;
       svg.appendChild(svgEl("line", {
+        class: i === 3 ? "icen-chart-grid icen-chart-baseline" : "icen-chart-grid",
         x1: String(pad),
         x2: String(width - pad),
         y1: String(y),
@@ -1546,7 +1551,7 @@ function renderLine(el, opts) {
     if (defs.firstChild) svg.insertBefore(defs, svg.firstChild);
     wrap.append(svg, pointLabelsRow(labelsUsed, width, pad));
     body.appendChild(wrap);
-    if (seriesList.length > 1) body.appendChild(toggleLegend(seriesList.map((s, si) => ({ key: s.name, label: s.name, tone: s.tone ?? (si === 0 ? opts.tone : void 0), si })), wrap));
+    if (seriesList.length > 1) body.appendChild(toggleLegend(seriesList.map((s, si) => ({ key: `${si}:${s.name}`, label: s.name, tone: s.tone ?? (si === 0 ? opts.tone : void 0), si })), wrap));
   });
   if (el.dataset.icenChartBody == null) observeFluidWidth(el, () => renderLine(el, opts));
   attachChartInteraction(el, "line");
@@ -1653,7 +1658,7 @@ function renderRadar(el, opts) {
         setMarkData(dot, { index: i, seriesIndex: si, seriesName: s.name || void 0, label: axes[i] ?? "", value: s.values[i] ?? 0 });
         svg.appendChild(dot);
       }
-      legendItems.push({ key: s.name || t("charts.seriesName", { p0: si + 1 }), label: s.name || t("charts.seriesName", { p0: si + 1 }), tone: s.tone, si });
+      legendItems.push({ key: `${si}:${s.name || t("charts.seriesName", { p0: si + 1 })}`, label: s.name || t("charts.seriesName", { p0: si + 1 }), tone: s.tone, si });
     });
     wrap.appendChild(svg);
     body.appendChild(wrap);
@@ -1675,6 +1680,11 @@ function niceCeil(v) {
   else nice = 10;
   return nice * base;
 }
+function tickPrecision(min, max, steps) {
+  const span = Math.abs(max - min);
+  if (!Number.isFinite(span) || span <= 0) return 0;
+  return Math.max(0, Math.ceil(-Math.log10(span / steps)));
+}
 function isoDate(d) {
   const m = String(d.getMonth() + 1).padStart(2, "0");
   const day = String(d.getDate()).padStart(2, "0");
@@ -1770,7 +1780,8 @@ function renderSparkline(el, opts) {
     const tone = toneVar(opts.tone);
     const points = values.map((value, i) => ({
       x: values.length <= 1 ? width / 2 : pad + i / (values.length - 1) * (width - pad * 2),
-      y: height - pad - value / max * (height - pad * 2),
+      /* 负值钳到基线（与折线图同口径）：viewBox 仅 28 高，反向射出更刺眼 */
+      y: height - pad - Math.max(0, value) / max * (height - pad * 2),
       value
     }));
     const line = points.map((p, i) => `${i === 0 ? "M" : "L"}${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(" ");
@@ -1895,6 +1906,7 @@ function renderCalendar(el, opts) {
       weekdayRow.appendChild(s);
     });
     const max = maxOf(entries.map((e) => e.value));
+    entries.sort((a, b) => a.date.localeCompare(b.date));
     const pad = padFirstWeek(grid, entries[0].date, weekStart);
     let lastMonth = -1;
     entries.forEach((entry, i) => {
@@ -1953,8 +1965,9 @@ function renderScatter(el, opts) {
     const xAt = (x) => pad + (x - xMin) / (xMax - xMin) * (width - pad * 2);
     const yAt = (y) => height - pad - (y - yMin) / (yMax - yMin) * (height - pad * 2);
     for (let i = 0; i <= 3; i++) {
-      const y = pad + i * (height - pad * 2) / 3;
+      const y = Math.round(pad + i * (height - pad * 2) / 3) + 0.5;
       svg.appendChild(svgEl("line", {
+        class: i === 3 ? "icen-chart-grid icen-chart-baseline" : "icen-chart-grid",
         x1: String(pad),
         x2: String(width - pad),
         y1: String(y),
@@ -1970,12 +1983,13 @@ function renderScatter(el, opts) {
         "font-size": "8",
         fill: "var(--icen-token-text-faint)"
       });
-      txt.textContent = fmt(opts, Math.round(tv * 10) / 10);
+      txt.textContent = fmt(opts, +tv.toFixed(tickPrecision(yMin, yMax, 3)));
       svg.appendChild(txt);
     }
     for (let i = 0; i <= 4; i++) {
-      const x = pad + i * (width - pad * 2) / 4;
+      const x = Math.round(pad + i * (width - pad * 2) / 4) + 0.5;
       svg.appendChild(svgEl("line", {
+        class: i === 0 ? "icen-chart-grid icen-chart-grid--v icen-chart-axis" : "icen-chart-grid icen-chart-grid--v",
         x1: String(x),
         x2: String(x),
         y1: String(pad),
@@ -1992,7 +2006,7 @@ function renderScatter(el, opts) {
         "font-size": "8",
         fill: "var(--icen-token-text-faint)"
       });
-      txt.textContent = fmt(opts, Math.round(tv * 10) / 10);
+      txt.textContent = fmt(opts, +tv.toFixed(tickPrecision(xMin, xMax, 4)));
       svg.appendChild(txt);
     }
     if (opts.yLabel) {
@@ -2356,6 +2370,7 @@ function renderChartSkeleton(body) {
   body.appendChild(box);
 }
 var CHART_MARK_ACCENT = "var(--icen-token-accent)";
+var CHART_MARK_ACCENT_TEXT = "var(--icen-token-accent-text)";
 function markToneVar(tone) {
   switch (tone) {
     case "success":
@@ -2491,7 +2506,7 @@ function paintSvgChartMarks(root, view, marks, formatValue, warned) {
         y: String(clampNum(y - 10, 8, CHART_LINE_H - 4)),
         "text-anchor": "middle",
         "font-size": "8",
-        fill: CHART_MARK_ACCENT
+        fill: CHART_MARK_ACCENT_TEXT
       });
       label.textContent = mark.text ?? mark.label;
       g.appendChild(label);
@@ -3049,6 +3064,12 @@ function renderChart(el, raw) {
       const graphic = root.querySelector('[role="img"]');
       if (graphic && !graphic.getAttribute("aria-label")) {
         graphic.setAttribute("aria-label", spec.title ? `${spec.title}\uFF08${type}\uFF09` : type);
+      } else if (!graphic) {
+        const dom = root.querySelector(".icen-chart-vbar, .icen-chart-hbar");
+        if (dom) {
+          dom.setAttribute("role", "img");
+          dom.setAttribute("aria-label", spec.title ? `${spec.title}\uFF08${type}\uFF09` : type);
+        }
       }
     }
     if (loading) return;
@@ -3761,7 +3782,13 @@ function onKeyDown2(e) {
 
 // src/behaviors/datatable.ts
 function defaultCompare(a, b) {
-  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "number" && typeof b === "number") {
+    if (Number.isNaN(a) || Number.isNaN(b)) {
+      if (Number.isNaN(a) && Number.isNaN(b)) return 0;
+      return Number.isNaN(a) ? 1 : -1;
+    }
+    return a - b;
+  }
   return String(a ?? "").localeCompare(String(b ?? ""), "zh-CN", { numeric: true });
 }
 function toNum2(v) {
@@ -4050,11 +4077,13 @@ function createTable(el, opts) {
   const body = document.createElement("div");
   body.className = "icen-dt-body";
   body.setAttribute("role", "rowgroup");
-  const summaryEl = document.createElement("div");
-  summaryEl.className = "icen-dt-row icen-dt-row--summary";
-  summaryEl.setAttribute("role", "row");
-  summaryEl.hidden = true;
-  canvas.append(head, body, summaryEl);
+  const summaryEl = opts.summaryRow ? document.createElement("div") : null;
+  if (summaryEl) {
+    summaryEl.className = "icen-dt-row icen-dt-row--summary";
+    summaryEl.setAttribute("role", "row");
+    summaryEl.hidden = true;
+  }
+  canvas.append(head, body, ...summaryEl ? [summaryEl] : []);
   scroll.appendChild(canvas);
   root.appendChild(scroll);
   const foot = document.createElement("div");
@@ -4868,6 +4897,7 @@ function createTable(el, opts) {
     return wrap;
   }
   function renderSummary() {
+    if (!summaryEl) return;
     summaryEl.textContent = "";
     summaryEl.hidden = true;
     const cfg = opts.summaryRow;
@@ -5064,9 +5094,9 @@ function createTable(el, opts) {
     }
   }
   let currentTotal = 0;
-  function visibleRange(total) {
+  function visibleRange(total, avail) {
     if (!virtual) {
-      if (opts.remote || opts.pagination === false) return [0, total];
+      if (opts.remote || opts.pagination === false) return [0, Math.min(total, avail)];
       const start2 = (page - 1) * pageSize;
       return [start2, Math.min(total, start2 + pageSize)];
     }
@@ -5081,6 +5111,10 @@ function createTable(el, opts) {
     const rows = pipeline();
     const entries = groupFn ? flatEntries() : null;
     const total = entries ? entries.length : opts.remote ? opts.totalCount ?? data.length : rows.length;
+    if (!opts.remote && opts.pagination !== false) {
+      const pages = Math.max(1, Math.ceil(total / pageSize));
+      if (page > pages) page = pages;
+    }
     navTotal = entries ? entries.length : rows.length;
     currentTotal = total;
     const keepTop = virtual ? scroll.scrollTop : 0;
@@ -5109,7 +5143,7 @@ function createTable(el, opts) {
       renderSummary();
       return;
     }
-    const [start, end] = visibleRange(total);
+    const [start, end] = visibleRange(total, rows.length);
     const frag = document.createDocumentFragment();
     const offsets = frozenOffsets();
     if (virtual && start > 0) {
@@ -5172,11 +5206,21 @@ function createTable(el, opts) {
     const pages = Math.ceil(total / pageSize);
     const pager = document.createElement("nav");
     pager.className = "icen-dt-pager";
-    pager.setAttribute("aria-label", t("datatable.paginationAria"));
+    {
+      const base = t("datatable.paginationAria");
+      const used = /* @__PURE__ */ new Set();
+      for (const el2 of document.querySelectorAll(".icen-dt-pager[aria-label]")) {
+        if (!root.contains(el2)) used.add(el2.getAttribute("aria-label") ?? "");
+      }
+      let label = base, n = 2;
+      while (used.has(label)) label = `${base} ${n++}`;
+      pager.setAttribute("aria-label", label);
+    }
     const sizeSel = document.createElement("select");
     sizeSel.className = "icen-dt-page-size";
     sizeSel.setAttribute("aria-label", t("datatable.pageSizeAria"));
-    for (const s of pageSizes) {
+    const sizeOptions = pageSizes.includes(pageSize) ? pageSizes : [...pageSizes, pageSize].sort((a, b) => a - b);
+    for (const s of sizeOptions) {
       const o = document.createElement("option");
       o.value = String(s);
       o.textContent = t("pagination.pageSize", { p0: s });
@@ -5268,6 +5312,7 @@ function createTable(el, opts) {
     if (destroyed) return;
     renderHead();
     renderBody();
+    syncFrozenWidths();
   }
   rekey();
   renderAll();
@@ -5288,12 +5333,52 @@ function createTable(el, opts) {
     opts.onPageChange?.(page, pageSize);
     renderAll();
   }
+  function hasFluidFrozen() {
+    return cols().some((c) => frozenSide(c) != null && !/^(\d+(?:\.\d+)?)px/.test(colWidths.get(c.key) ?? c.width ?? ""));
+  }
+  function syncFrozenWidths() {
+    if (!hasFluidFrozen()) return;
+    const visible = cols();
+    const headCells = Array.from(headRow.children);
+    const lead = headCells.length - visible.length;
+    const left = /* @__PURE__ */ new Map();
+    const right = /* @__PURE__ */ new Map();
+    let acc = headCells.slice(0, lead).reduce((s, c) => s + c.offsetWidth, 0);
+    for (let i = 0; i < visible.length; i++) {
+      const c = visible[i];
+      if (frozenSide(c) === "left") left.set(c.key, acc);
+      acc += headCells[lead + i]?.offsetWidth ?? 0;
+    }
+    let accR = 0;
+    for (let i = visible.length - 1; i >= 0; i--) {
+      const c = visible[i];
+      if (frozenSide(c) === "right") right.set(c.key, accR);
+      accR += headCells[lead + i]?.offsetWidth ?? 0;
+    }
+    const rows = [headRow, ...summaryEl ? [summaryEl] : [], ...Array.from(body.querySelectorAll(".icen-dt-row"))];
+    for (const row of rows) {
+      const cells = Array.from(row.children);
+      if (cells.length !== headCells.length) continue;
+      cells.forEach((cell, i) => {
+        const col = i >= lead ? visible[i - lead] : void 0;
+        if (!col) return;
+        const l = left.get(col.key);
+        if (l != null && cell.classList.contains("icen-dt-cell--frozen")) cell.style.left = `${l}px`;
+        const r = right.get(col.key);
+        if (r != null && cell.classList.contains("icen-dt-cell--frozen-right")) cell.style.right = `${r}px`;
+      });
+    }
+  }
   return {
     setPage,
     setPageSize,
     setData(next) {
       if (editing) cancelEdit(true);
       data = next;
+      if (typeof opts.rowKey !== "function" && typeof opts.rowKey !== "string" && selected.size > 0) {
+        selected.clear();
+        emitSelection();
+      }
       rekey();
       invalidate();
       page = 1;
@@ -5536,6 +5621,15 @@ function svgIcon(svg) {
   return parseSvg(svg);
 }
 
+// src/behaviors/url-safety.ts
+function safeUrl(uri) {
+  const s = uri.replace(/[\t\n\r\0-\x1f\x7f]/g, "").trim().toLowerCase();
+  if (!s) return void 0;
+  if (s.startsWith("javascript:") || s.startsWith("vbscript:")) return void 0;
+  if (/^data:\s*text\/html/.test(s)) return void 0;
+  return uri;
+}
+
 // src/behaviors/ai-chat.ts
 var ICON_COPY = iconHTML("copy");
 var ICON_RETRY = iconHTML("refresh");
@@ -5563,6 +5657,8 @@ function createAiStream(el) {
   el.setAttribute("aria-busy", "true");
   if (reasoning) {
     reasoning.classList.add("is-streaming");
+    const timeEl = reasoning.querySelector(".icen-ai-reasoning-time");
+    if (timeEl) timeEl.textContent = t("aiChat.thinkingNow");
     setReasoningOpen(reasoning, true);
     const head = reasoning.querySelector(".icen-ai-reasoning-head");
     if (head && head.dataset.icenReasoningStart == null) head.dataset.icenReasoningStart = String(startedAt);
@@ -5650,10 +5746,9 @@ var ROLE_AVATAR = {
   system: t("aiChat.roleSystem"),
   tool: t("aiChat.roleTool")
 };
-function safeHref(uri) {
-  const s = uri.trim().toLowerCase();
-  if (s.startsWith("javascript:") || s.startsWith("data:text/html")) return void 0;
-  return uri;
+function safeContentUrl(part) {
+  const src = aiContentUrl(part);
+  return src ? safeUrl(src) : void 0;
 }
 function renderAiContentPart(part) {
   if (part.type === "text") {
@@ -5663,7 +5758,7 @@ function renderAiContentPart(part) {
     return span;
   }
   if (part.type === "image") {
-    const src = aiContentUrl(part);
+    const src = safeContentUrl(part);
     if (!src) return void 0;
     const img = document.createElement("img");
     img.className = "icen-ai-msg-media icen-ai-msg-media--image";
@@ -5673,7 +5768,7 @@ function renderAiContentPart(part) {
     return img;
   }
   if (part.type === "audio") {
-    const src = aiContentUrl(part);
+    const src = safeContentUrl(part);
     if (!src) return void 0;
     const audio = document.createElement("audio");
     audio.className = "icen-ai-msg-media icen-ai-msg-media--audio";
@@ -5682,7 +5777,7 @@ function renderAiContentPart(part) {
     return audio;
   }
   if (part.type === "video") {
-    const src = aiContentUrl(part);
+    const src = safeContentUrl(part);
     if (!src) return void 0;
     const video = document.createElement("video");
     video.className = "icen-ai-msg-media icen-ai-msg-media--video";
@@ -5694,7 +5789,7 @@ function renderAiContentPart(part) {
   if (part.type === "file") {
     const chip = h("span", "icen-ai-msg-file");
     chip.appendChild(h("span", "ai-msg-file-name", part.filename ?? t("aiChat.file")));
-    const href2 = part.url ? safeHref(part.url) : void 0;
+    const href2 = part.url ? safeUrl(part.url) : void 0;
     if (href2 && /^(https?:|data:)/i.test(href2)) {
       const a2 = document.createElement("a");
       a2.className = "icen-ai-msg-file-link";
@@ -5707,7 +5802,7 @@ function renderAiContentPart(part) {
   }
   const a = document.createElement("a");
   a.className = "icen-ai-msg-link";
-  const href = safeHref(part.uri);
+  const href = safeUrl(part.uri);
   if (href) a.href = href;
   a.textContent = part.name ?? part.uri;
   a.title = part.uri;
@@ -5769,7 +5864,7 @@ function renderAiMessage(scrollEl, model) {
       errEl.textContent = message;
     },
     stream() {
-      const span = h("span", "ai-msg-stream-text");
+      const span = h("span", "icen-ai-msg-text ai-msg-stream-text");
       body.appendChild(span);
       return createAiStream(span);
     }

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/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.0",
+  "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,22 @@
     "dtcg": "bun scripts/dtcg.mjs",
     "design-tokens": "bun scripts/design-tokens.mjs",
     "guard": "bun scripts/guard/index.ts",
+    "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 +85,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",