@keyfunc/keybricks-ds 1.0.4 → 2.1.1

package/components/tabs/Tabs.jsx

@@ -1,14 +1,14 @@
 import React from "react";
 
-/** Underline tabs on a hairline baseline (Import/Export). Active = blue text + 2px blue underline. */
-export function Tabs({ tabs = [], active, onChange, style }) {
+/** Underline tabs on a hairline baseline (Import/Export). Active = blue text + 2px blue underline. The bar is the region's bar height (sm 32 · md 40 · lg 44) with the tier's control text; omit `size` to inherit. */
+export function Tabs({ tabs = [], active, onChange, size, style }) {
   return (
-    <div style={{ display: "flex", gap: 4, borderBottom: "1px solid var(--border-control)", ...style }}>
+    <div role="tablist" data-size={size} style={{ display: "flex", gap: 4, borderBottom: "1px solid var(--border-control)", ...style }}>
       {tabs.map((t) => {
         const is = t === active;
         return (
-          <button key={t} type="button" onClick={() => onChange && onChange(t)}
-            style={{ background: "transparent", border: "none", cursor: "pointer", padding: "9px 16px", marginBottom: -1, borderBottom: is ? "2px solid var(--action-primary)" : "2px solid transparent", fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--text-base)", lineHeight: "var(--leading-base)", letterSpacing: "var(--tracking-base)", color: is ? "var(--action-primary)" : "var(--text-body)" }}>
+          <button key={t} type="button" role="tab" aria-selected={is} data-ink={is ? undefined : ""} onClick={() => onChange && onChange(t)}
+            style={{ background: "transparent", border: "none", cursor: "pointer", height: "var(--bar-h)", boxSizing: "border-box", padding: "0 var(--control-px)", marginBottom: -1, borderBottom: is ? "2px solid var(--action-primary)" : "2px solid transparent", fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: is ? "var(--action-primary)" : "var(--ink, var(--text-body))", whiteSpace: "nowrap" }}>
             {t}
           </button>
         );
@@ -17,15 +17,15 @@ export function Tabs({ tabs = [], active, onChange, style }) {
   );
 }
 
-/** Compact panel tabs (Node Info · Calc Rules · Output Fields · SQL Preview), 12px. */
-export function PanelTabs({ tabs = [], active, onChange, style }) {
+/** Panel tabs (Node Info · Calc Rules · Output Fields · SQL Preview): a lighter underline tab bar at the region's bar height with regular-weight control text. Put the panel in an sm region for the compact 32px/12px look. */
+export function PanelTabs({ tabs = [], active, onChange, size, style }) {
   return (
-    <div style={{ display: "flex", borderBottom: "1px solid var(--border-subtle)", ...style }}>
+    <div role="tablist" data-size={size} style={{ display: "flex", borderBottom: "1px solid var(--border-subtle)", ...style }}>
       {tabs.map((t) => {
         const is = t === active;
         return (
-          <button key={t} type="button" onClick={() => onChange && onChange(t)}
-            style={{ background: "transparent", border: "none", cursor: "pointer", padding: "8px 12px", marginBottom: -1, borderBottom: is ? "2px solid var(--action-primary)" : "2px solid transparent", fontFamily: "var(--font-sans)", fontSize: "var(--text-sm)", lineHeight: "var(--leading-sm)", color: is ? "var(--action-primary)" : "var(--text-secondary)" }}>
+          <button key={t} type="button" role="tab" aria-selected={is} data-ink={is ? undefined : ""} onClick={() => onChange && onChange(t)}
+            style={{ background: "transparent", border: "none", cursor: "pointer", height: "var(--bar-h)", boxSizing: "border-box", padding: "0 var(--control-px)", marginBottom: -1, borderBottom: is ? "2px solid var(--action-primary)" : "2px solid transparent", fontFamily: "var(--font-sans)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: is ? "var(--action-primary)" : "var(--ink, var(--text-secondary))", whiteSpace: "nowrap" }}>
             {t}
           </button>
         );
@@ -34,15 +34,15 @@ export function PanelTabs({ tabs = [], active, onChange, style }) {
   );
 }
 
-/** Text pill filter tabs (For Review · To be Submitted · For Approval). Active = #f5f5f5 pill. */
-export function PillTabs({ tabs = [], active, onChange, style }) {
+/** Text pill filter tabs (For Review · To be Submitted · For Approval). Active = tinted pill. Pills are control-height (sm 24 · md 32 · lg 36); omit `size` to inherit. */
+export function PillTabs({ tabs = [], active, onChange, size, style }) {
   return (
-    <div style={{ display: "flex", gap: 8, ...style }}>
+    <div role="tablist" data-size={size} style={{ display: "flex", gap: "var(--control-gap)", ...style }}>
       {tabs.map((t) => {
         const is = t === active;
         return (
-          <button key={t} type="button" onClick={() => onChange && onChange(t)}
-            style={{ background: is ? "var(--bg-active)" : "transparent", border: "none", cursor: "pointer", height: 28, padding: "0 11px", borderRadius: "var(--radius-md)", fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--text-sm)", lineHeight: "var(--leading-sm)", color: is ? "var(--text-heading)" : "var(--text-secondary)" }}>
+          <button key={t} type="button" role="tab" aria-selected={is} data-ink={is ? undefined : ""} data-wash={is ? undefined : ""} onClick={() => onChange && onChange(t)}
+            style={{ background: is ? "var(--bg-active)" : "var(--wash, transparent)", border: "none", cursor: "pointer", height: "var(--control-h)", padding: "0 var(--control-px)", borderRadius: "var(--radius-md)", fontFamily: "var(--font-sans)", fontWeight: "var(--weight-medium)", fontSize: "var(--control-text)", lineHeight: "var(--control-leading)", letterSpacing: "var(--control-tracking)", color: is ? "var(--text-heading)" : "var(--ink, var(--text-secondary))", whiteSpace: "nowrap" }}>
             {t}
           </button>
         );

package/components/tabs/Tabs.vue

@@ -1,11 +1,11 @@
 <script setup>
-// Underline tabs on a hairline baseline (Import/Export). Active = blue text + 2px blue underline.
-defineProps({ tabs: { type: Array, default: () => [] }, active: String, style: Object })
+// Underline tabs on a hairline baseline (Import/Export). Active = blue text + 2px blue underline. The bar is the region's bar height (sm 32 · md 40 · lg 44) with the tier's control text; omit `size` to inherit.
+defineProps({ tabs: { type: Array, default: () => [] }, active: String, size: String, style: Object })
 const emit = defineEmits(['change'])
 </script>
 <template>
-  <div :style="{ display: 'flex', gap: 4, borderBottom: '1px solid var(--border-control)', ...style }">
-    <button v-for="t in tabs" :key="t" type="button" @click="emit('change', t)"
-      :style="{ background: 'transparent', border: 'none', cursor: 'pointer', padding: '9px 16px', marginBottom: -1, borderBottom: t === active ? '2px solid var(--action-primary)' : '2px solid transparent', fontFamily: 'var(--font-sans)', fontWeight: 'var(--weight-medium)', fontSize: 'var(--text-base)', lineHeight: 'var(--leading-base)', letterSpacing: 'var(--tracking-base)', color: t === active ? 'var(--action-primary)' : 'var(--text-body)' }">{{ t }}</button>
+  <div role="tablist" :data-size="size" :style="{ display: 'flex', gap: '4px', borderBottom: '1px solid var(--border-control)', ...style }">
+    <button v-for="t in tabs" :key="t" type="button" role="tab" :aria-selected="t === active" :data-ink="t === active ? undefined : ''" @click="emit('change', t)"
+      :style="{ background: 'transparent', border: 'none', cursor: 'pointer', height: 'var(--bar-h)', boxSizing: 'border-box', padding: '0 var(--control-px)', marginBottom: '-1px', borderBottom: t === active ? '2px solid var(--action-primary)' : '2px solid transparent', fontFamily: 'var(--font-sans)', fontWeight: 'var(--weight-medium)', fontSize: 'var(--control-text)', lineHeight: 'var(--control-leading)', letterSpacing: 'var(--control-tracking)', color: t === active ? 'var(--action-primary)' : 'var(--ink, var(--text-body))', whiteSpace: 'nowrap' }">{{ t }}</button>
   </div>
 </template>

package/components/tabs/ViewToggle.d.ts

@@ -1,7 +1,9 @@
 import * as React from "react";
-/** list/grid segmented icon toggle (26px, r4, active #f5f5f5). */
+/** list/grid icon toggle — two IconButtons at the region's tier (sm 24 · md 32 · lg 36), active gets the tinted wash. */
 export interface ViewToggleProps {
   value?: "list" | "grid";
+  /** Size tier. Omit to inherit the enclosing region's tier (the default). */
+  size?: "sm" | "md" | "lg";
   onChange?: (v: "list" | "grid") => void;
   style?: React.CSSProperties;
 }

package/components/tabs/ViewToggle.jsx

@@ -1,12 +1,12 @@
 import React from "react";
 import { IconButton } from "../buttons/IconButton.jsx";
 
-/** Two-state list/grid icon toggle (palette header). */
-export function ViewToggle({ value = "grid", onChange, style }) {
+/** Two-state list/grid icon toggle (palette header). Two IconButtons at the region's tier; omit `size` to inherit. */
+export function ViewToggle({ value = "grid", onChange, size, style }) {
   return (
-    <div style={{ display: "inline-flex", gap: 2, ...style }}>
-      <IconButton icon="list" size="sm" active={value === "list"} onClick={() => onChange && onChange("list")} label="List view" />
-      <IconButton icon="layout-grid" size="sm" active={value === "grid"} onClick={() => onChange && onChange("grid")} label="Grid view" />
+    <div data-size={size} style={{ display: "inline-flex", gap: 2, ...style }}>
+      <IconButton icon="list" active={value === "list"} onClick={() => onChange && onChange("list")} label="List view" />
+      <IconButton icon="layout-grid" active={value === "grid"} onClick={() => onChange && onChange("grid")} label="Grid view" />
     </div>
   );
 }

package/components/tabs/ViewToggle.vue

@@ -1,12 +1,12 @@
 <script setup>
 import IconButton from '../buttons/IconButton.vue'
-// Two-state list/grid icon toggle (palette header).
-defineProps({ modelValue: { type: String, default: 'grid' }, style: Object })
+// Two-state list/grid icon toggle (palette header). Two IconButtons at the region's tier; omit `size` to inherit.
+defineProps({ modelValue: { type: String, default: 'grid' }, size: String, style: Object })
 const emit = defineEmits(['update:modelValue'])
 </script>
 <template>
-  <div :style="{ display: 'inline-flex', gap: 2, ...style }">
-    <IconButton icon="list" size="sm" :active="modelValue === 'list'" label="List view" @click="emit('update:modelValue', 'list')" />
-    <IconButton icon="layout-grid" size="sm" :active="modelValue === 'grid'" label="Grid view" @click="emit('update:modelValue', 'grid')" />
+  <div :data-size="size" :style="{ display: 'inline-flex', gap: '2px', ...style }">
+    <IconButton icon="list" :active="modelValue === 'list'" label="List view" @click="emit('update:modelValue', 'list')" />
+    <IconButton icon="layout-grid" :active="modelValue === 'grid'" label="Grid view" @click="emit('update:modelValue', 'grid')" />
   </div>
 </template>

package/components/tabs/tabs.prompt.md

@@ -1,4 +1,4 @@
-Tab systems: `Tabs` (13px underline — page level), `PanelTabs` (12px underline — config panel), `PillTabs` (pill filters), `ViewToggle` (list/grid icons).
+Tab systems: `Tabs` (underline — page level), `PanelTabs` (lighter underline — config panel, put the panel in an sm region), `PillTabs` (pill filters), `ViewToggle` (list/grid icons). All read the region's size tier: bars are 32 / 40 / 44px, pills 24 / 32 / 36px.
 
 ```jsx
 <Tabs tabs={["Import","Export"]} active={tab} onChange={setTab}/>

package/keybricks.css

@@ -0,0 +1,4 @@
+/* Consumer entry: tokens + the hover hooks that component inline styles read.
+   (hover.css stays outside styles.css so the design-system compiler does not register its state signals as tokens.) */
+@import './styles.css';
+@import './tokens/hover.css';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@keyfunc/keybricks-ds",
-  "version": "1.0.4",
-  "description": "Keybricks design system — 334 design tokens and 118 UI components in React and Vue 3, source-only.",
+  "version": "2.1.1",
+  "description": "Keybricks design system — 352 design tokens, three size tiers and 117 UI components in React and Vue 3, source-only.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": [
@@ -13,7 +13,8 @@
       "default": "./components/index.js"
     },
     "./vue": "./components/_vue/index.mjs",
-    "./styles.css": "./styles.css",
+    "./styles.css": "./keybricks.css",
+    "./keybricks.css": "./keybricks.css",
     "./tokens": {
       "types": "./tokens/tokens.d.ts",
       "default": "./tokens/tokens.js"
@@ -31,7 +32,9 @@
     "assets",
     "_scripts",
     "styles.css",
+    "keybricks.css",
     "readme.md",
+    "readme.zh-CN.md",
     "DESIGN.md",
     "INTEGRATION.md",
     "DEPLOY.md",

package/readme.md

@@ -1,150 +1,118 @@
 # Keybricks Design System
 
+English · [中文](readme.zh-CN.md)
+
 Keybricks is an enterprise performance-management (EPM) platform for finance teams: documents & reporting, business intelligence, data integration, reconciliation, consolidation, and a management suite (modeling, workflow, security, system migration, business logic, tasks, validation rules, control center). Its signature surface is a node-based **data-pipeline editor** ("adapters" like *Oracle Adapter*) where users wire Data Source → Join → Transformation → Merge → Output nodes on a dotted canvas.
-（Keybricks 是面向财务团队的企业绩效管理（EPM）平台：文档与报表、商业智能、数据集成、对账、合并报表，以及管理套件（建模、工作流、权限、系统迁移、业务逻辑、任务管理、校验规则、控制中心）。其标志性界面是基于节点的**数据管道编辑器**（如「Oracle Adapter」），用户在点状网格画布上依次连接数据源 → 关联 → 转换 → 合并 → 输出节点。）
 
-## Products represented / 产品范围
+## Products represented
 One product: the Keybricks web app (desktop, 1512×~860 design size). Key surfaces: Home dashboard · Documents · Pipeline editor · System Migration wizard.
-（单一产品：Keybricks 网页应用（桌面端，设计尺寸约 1512×860）。核心界面：首页仪表盘、文档中心、管道编辑器、系统迁移向导。）
 
-## CONTENT FUNDAMENTALS / 内容规范
-- **Voice / 语气**: terse, technical, verb-first. Buttons are imperative: "Run Test", "Submit", "Save Settings", "Continue to Confirmation", "Mark as New", "Skip Selected".
-  （简洁、技术化、动词开头。按钮用祈使句：「Run Test」「Submit」「Save Settings」「Continue to Confirmation」「Mark as New」「Skip Selected」。）
-- **Casing / 大小写**: Title Case for nav, headings, buttons, table headers ("Import History", "Custom Parameters"); sentence case for helper copy ("Import and manage configuration migrations across systems", "Click to upload or drag and drop", "JSON files only").
-  （导航、标题、按钮、表头用词首大写（Title Case）；辅助说明文字用句首大写（sentence case）。）
-- **Person / 人称**: no "I/we/you" — labels are objective and system-centric. Personal touch is limited to the dashboard greeting "Good evening, Felix" + full date "Monday, April 21, 2026".
-  （不使用「我/我们/你」——文案客观、以系统为中心。唯一的人性化表达是仪表盘问候语「Good evening, Felix」及完整日期。）
-- **Terminology / 术语**: domain-precise EPM/ETL vocabulary — Detail Sheet, Dimension, Model, Association Match, Multi-Condition Judge, Group Calculation, Concat Merge, Reconciliation, Consolidation. Config codes render in mono ALL_CAPS_SNAKE ("FIN_CURRENCY_DEFAULT").
-  （精确的 EPM/ETL 领域术语；配置代码用等宽字体全大写下划线格式，如「FIN_CURRENCY_DEFAULT」。）
-- **Numbers & meta / 数字与元信息**: counts as "1 document", "2 items", relative time "2 hours ago", log lines "[14:30] Task started: Import".
-  （计数如「1 document」「2 items」；相对时间如「2 hours ago」；日志行如「[14:30] Task started: Import」。）
-- **Status language / 状态文案**: "• Editing" dot-prefixed state chip; steps named as nouns ("Upload & Parse", "Comparison", "Confirmation", "Execution", "Results").
-  （状态用圆点前缀，如「• Editing」；步骤用名词命名，如「Upload & Parse」「Comparison」「Confirmation」「Execution」「Results」。）
+## Content fundamentals
+- **Voice**: terse, technical, verb-first. Buttons are imperative: "Run Test", "Submit", "Save Settings", "Continue to Confirmation", "Mark as New", "Skip Selected".
+- **Casing**: Title Case for nav, headings, buttons, table headers ("Import History", "Custom Parameters"); sentence case for helper copy ("Import and manage configuration migrations across systems", "Click to upload or drag and drop", "JSON files only").
+- **Person**: no "I/we/you" — labels are objective and system-centric. Personal touch is limited to the dashboard greeting "Good evening, Felix" + full date "Monday, April 21, 2026".
+- **Terminology**: domain-precise EPM/ETL vocabulary — Detail Sheet, Dimension, Model, Association Match, Multi-Condition Judge, Group Calculation, Concat Merge, Reconciliation, Consolidation. Config codes render in mono ALL_CAPS_SNAKE ("FIN_CURRENCY_DEFAULT").
+- **Numbers & meta**: counts as "1 document", "2 items", relative time "2 hours ago", log lines "[14:30] Task started: Import".
+- **Status language**: "• Editing" dot-prefixed state chip; steps named as nouns ("Upload & Parse", "Comparison", "Confirmation", "Execution", "Results").
 - **Emoji**: never. Icons carry all decoration.
-  （从不使用 emoji，所有装饰性表达交给图标。）
-- **Localization note / 本地化说明**: content is bilingual-tolerant — a document named 财务分析 sits beside English names; UI chrome stays English.
-  （内容本身容忍中英混排——如「财务分析」这样的文档名可与英文文档名并列；界面框架文案本身保持英文。）
+- **Localization**: content is bilingual-tolerant — a document named 财务分析 sits beside English names; UI chrome stays English.
 
-## VISUAL FOUNDATIONS / 视觉基础
-- **Color / 色彩**: near-monochrome neutral UI (neutral ramp #FAFAFA→#0A0A0A) with ONE action blue (#155DFC). Color is reserved for meaning: node-category hues (source green #009966, join blue #155DFC, transform orange #FF6900, merge purple #9810FA, output teal #009689, each with a 100-tint tile bg), feedback (success #00BC7D, danger #FB2C36, warning #FFB900), charts (#3B82F6). Backgrounds: app #FAFAFA, surfaces white. No gradients except chart-area fills (blue → transparent).
+## Visual foundations
+- **Color**: near-monochrome neutral UI (neutral ramp #FAFAFA→#0A0A0A) with ONE action blue (#155DFC). Color is reserved for meaning: node-category hues (source green #009966, join blue #155DFC, transform orange #FF6900, merge purple #9810FA, output teal #009689, each with a 100-tint tile bg), feedback (success #00BC7D, danger #FB2C36, warning #FFB900), charts (`--series-1…8`, see `tokens/charts.css`). Backgrounds: app #FAFAFA, surfaces white. No gradients except chart-area fills (blue → transparent).
   The system is organized in **three tiers**, and only the middle one is public API:
   1. **Palette** — `--<hue>-<step>` on a fixed 50→950 lightness scale (neutral + blue extracted from the source file; red/orange/amber/emerald/teal/cyan/purple/pink generated in OKLCH on one shared lightness/chroma curve so every family reads as part of the same system rather than a public library's defaults — steps other tokens point to byte-for-byte, like `--danger`/`--warning`/`--success`/`--cat-*`, are pinned to those exact source-verified values; cyan and pink have no source anchor, so their hue angles were chosen to complete an evenly spaced wheel alongside the anchored hues and the brand blue), plus the transparency ramps `--neutral-alpha-*` (2→80%, black in light / white in dark) and `--brand-alpha-*` (8→32%). Identical in both themes; referenced only by tier 2.
   2. **Semantic role** — `--bg-*`, `--text-*`, `--border-*`, `--action-*`, `--overlay-*`, and the feedback families `--success/warning/danger/info` with `-bg`/`-text` pairs. Named by job, flips for dark mode. **Components and consuming designs reference these and nothing else.**
   3. **Component** — `--cat-*`, `--tooltip-bg`, `--dropzone-border-hover`: one part of one component, added only when no tier-2 role fits.
+
   Rules that don't bend: step 400 and lighter never carry body text on white (they are surfaces, borders, disabled glyphs); `--on-accent` (#FFFFFF) is the only foreground allowed on a saturated fill, in **both** themes; label hues are mechanical (light = 100-step bg + 700-step text, dark = 950-step bg + 300-step text) so a new category needs no judgement; hue means *category*, the four feedback roles mean *severity*. Contrast targets: 4.5:1 body text, 3:1 for 18px+/bold and for UI boundaries. Three Colors cards carry the values: Palette (every ramp), Schemes (sets that work together), Transparency (the alpha scale).
-  （近乎单色的中性界面（neutral 色阶 #FAFAFA→#0A0A0A），仅有一个强调蓝 #155DFC。色彩只用于表达含义：节点分类色相、状态色、图表色。背景：应用层 #FAFAFA，卡片层白色。除图表区域渐变填充外不使用渐变。
-  体系分为**三层**，其中只有中间一层对外开放：① **调色板层** `--<色相>-<档位>`，统一 50→950 明度阶（neutral 与 blue 提取自源文件；red/orange/amber/emerald/teal/cyan/purple/pink 用 OKLCH 在同一条明度/彩度曲线上生成，让每个色系读起来像同一套体系，而非某个公共库的默认值——凡是其他 token 需要逐字节对应的档位（如 `--danger`/`--warning`/`--success`/`--cat-*`）都锁定为源文件验证过的原值；cyan 与 pink 没有源文件锚点，其色相角度经过挑选，与已锚定的色相及品牌蓝共同组成一个分布均匀的色轮），另含透明度阶 `--neutral-alpha-*`（2→80%，浅色模式为黑、深色模式为白）与 `--brand-alpha-*`（8→32%）；两套主题取值相同，仅供第二层引用。② **语义角色层** `--bg-*`、`--text-*`、`--border-*`、`--action-*`、`--overlay-*`，以及 `--success/warning/danger/info` 四组反馈色（含 `-bg`/`-text` 配对）；按用途命名，负责深色模式的切换，**组件与业务设计只允许引用这一层**。③ **组件层** `--cat-*`、`--tooltip-bg` 等，仅在第二层确实无对应角色时新增。
-  不可打破的规则：400 及更浅的档位不得在白底上承载正文（它们是表面色、边框色、禁用态图标色）；饱和填充之上的前景色只能用 `--on-accent`（#FFFFFF），**两套主题皆是**；标签色相是机械规则（浅色 = 100 档底 + 700 档字，深色 = 950 档底 + 300 档字），新增分类无需主观判断；色相表达**分类**，四组反馈色表达**严重程度**。对比度目标：正文 4.5:1，18px+/加粗及界面边界 3:1。Colors 分组下三张卡片给出全部色值：Palette（完整色阶）、Schemes（可直接套用的配色组合）、Transparency（透明度阶）。）
-- **Type / 字体**: Inter only (300 stat numerals, 400 body, 500 UI-medium, 600 titles) at small sizes — 13px is the default UI size; 10–15px covers almost everything; 20/24px only for the greeting + stat numbers (weight 300). Negative tracking on ≥13px (-.076 to -.449px), positive on ≤11px. Menlo for data/code/logs.
-  （全局仅用 Inter；13px 为默认界面字号，10–15px 覆盖绝大多数场景，20/24px 仅用于问候语和统计数字（细体 300）。≥13px 用负字距，≤11px 用正字距。数据/代码/日志用 Menlo。）
-- **Spacing / 间距**: 4-px family in practice (2/4/6/8/10/12/16/24/32); page padding 24×32; card padding 21 (dense 17); section gap 24. Fractional heights (35.5, 31.5, 61.5, 19.5 line-heights) come from line-height math — keep them.
-  （实际以 4px 为基础的间距族；页面内边距 24×32；卡片内边距 21（密集型 17）；区块间距 24。带小数的高度值来自行高计算，需保留，不要取整。）
-- **Radii / 圆角**: 4 small controls · 8 buttons/inputs/nav/chips · 10 cards/search/dropzone · 14 palette tiles · 16 canvas nodes · full circles for ports/steps/pills.
-  （4px 用于小型控件；8px 用于按钮/输入框/导航/标签；10px 用于卡片/搜索框/上传区；14px 用于组件面板图标块；16px 用于画布节点；端口/步骤圆点/胶囊用全圆角。）
-- **Borders / 边框**: hairline everywhere — cards rgba(229,229,229,.6); controls #e5e5e5; row separators #f5f5f5; checkbox #d1d5db 1.5px; ports #d4d4d4 2px; dropzone dashed #d4d4d4 2px.
-  （全局使用发丝级细边框。）
-- **Shadows / 阴影**: nearly flat. Canvas nodes only: `0 1px 3px rgba(0,0,0,.1), 0 1px 2px -1px rgba(0,0,0,.1)`; selection = blue-400 border + 2px blue-100 ring; badges get a 2px white ring. Everything else relies on borders.
-  （几乎全平面化设计。仅画布节点有轻阴影；选中态为蓝色边框+浅蓝光环；徽标带 2px 白色描边。其余元素依赖边框区分层次。）
-- **Backgrounds/imagery / 背景与图像**: no photography, no illustration. The pipeline canvas is #fafafa with a subtle dot/curve grid; chart areas use soft blue gradient fills. Only bitmap: the cube logo.
-  （不使用摄影图或插画。管道画布为浅灰底配点状网格；图表区域用柔和蓝色渐变填充。唯一位图资源是立方体 Logo。）
-- **States / 交互状态**: every interactive element carries five states beyond rest. **Hover** moves the fill one step (`--bg-hover` wash on ghost items, `--action-primary-hover` on solid buttons, `--soft-hover` on tinted ones). **Press** moves it a second step: Button and IconButton use explicit tokens (`--action-primary-active`, `--action-dark-active`, `--bg-press`, `--soft-active`, `--danger-active`, `--danger-soft-active`) and opt out of the global layer with `data-press="own"`; every other control — nav rows, tree items, menu items, chips, tabs, list rows, option rows, palette tiles — gets press from the one global rule in `tokens/interaction.css` (`filter: var(--press-filter)` on `:active`, which multiplies whatever wash hover is already showing, and brightens rather than darkens in dark mode). No scale transforms, no shadow shifts; text-only buttons drop to 70% opacity instead. **Keyboard focus** is also global: a 2px `--focus-border` outline at 2px offset on `:focus-visible` only, so a mouse click never draws it. **Selected/active** is persistent, not transient: active nav = `--bg-active` pill + heading-weight text; selected node = blue border + ring. **Disabled** is 55% opacity (50% on icon buttons) with the default cursor.
-  （每个可交互元素在静默态之外都有五种状态：悬停加深一档；按下再加深一档——Button 与 IconButton 使用专门的 `--*-active` / `--bg-press` token 并以 `data-press="own"` 退出全局层，其余所有控件（导航行、树节点、菜单项、标签页、列表行、选项行、面板磁贴等）由 `tokens/interaction.css` 中的单条全局规则提供按压态（`:active` 时叠加 `filter: var(--press-filter)`，在悬停底色之上再加深一档，深色模式下方向为提亮）；不做缩放或阴影变化，纯文字按钮改为降至 70% 透明度。键盘聚焦同样是全局的：仅在 `:focus-visible` 时绘制 2px `--focus-border` 描边（偏移 2px），鼠标点击不显示。选中态是持续态而非瞬时态；禁用态约 55% 透明度（图标按钮 50%）并使用默认光标。）
-- **Motion / 动效**: kept minimal by design (see Motion section below) — 120–160ms ease-out on hover/selection, nothing bouncy or far-traveling.
-  （动效克制（详见下方“动效”一节）——悬停/选中约 120–160ms 缓出，无弹跳、无大位移。）
-- **Layout chrome / 布局框架**: left sidebar 240px (collapsible to a 64px icon rail), 56px top bar (search left, bell + black "AI Assistant" pill right), optional 240px secondary panel (Documents tree, pipeline palette), 400px right config panel, 250px bottom data-preview drawer.
-  （左侧边栏 240px（可收起为 64px 图标栏）；顶栏 56px（左搜索，右铃铛+黑色「AI Assistant」胶囊）；可选二级面板 240px；右侧配置面板 400px；底部数据预览抽屉 250px。）
-- **Cards / 卡片**: white, radius 10, hairline border, 21px padding, 13px/500 title — never elevated.
-  （白底、10px 圆角、细边框、21px 内边距、13px/中等字重标题——不使用投影堆叠层级。）
-- **Density / 密度**: high; tables 29–51px rows; mono 11px for data cells.
-  （高密度界面；表格行高 29–51px；数据单元格用 11px 等宽字体。）
+- **Type**: Inter only (300 stat numerals, 400 body, 500 UI-medium, 600 titles and table headers) on the 14px scale — 12 captions · 14 body and controls · 16 section titles · 20 page titles; 24px only for the greeting + stat numbers (weight 300); 11px for chart ticks and nothing else. Negative tracking from 14px up (-.15 to -.54px), 0 at 12px. Menlo for data/code/logs at the row's own size with tabular figures. Chinese, Japanese and Korean (`lang="zh|ja|ko"`): same sizes, weight 500 → 600, tracking 0, never caps.
+- **Spacing**: 4-px family in practice (2/4/6/8/10/12/16/24/32); page padding 24×32; card padding 21 (dense 17); section gap 24. Inside a bar the gaps come from the size tier: 8 inside a group, 12/16/24 between groups, 12/16 from a card edge to the first control.
+- **Size tiers**: one tier per region — `data-size="sm" | "md" | "lg"` gives 24 / 32 / 36px controls, 12 / 14 / 14px control text and 32 / 40 / 44px rows; every control inside inherits, nothing interactive is below 24px, and heights or text sizes are never mixed in one row. md is the app default; dialogs are lg; dense grids are sm.
+- **Radii**: 4 small controls · 8 buttons/inputs/nav/chips · 10 cards/search/dropzone · 14 palette tiles · 16 canvas nodes · full circles for ports/steps/pills.
+- **Borders**: hairline everywhere — cards rgba(229,229,229,.6); controls #e5e5e5; row separators #f5f5f5; checkbox #d1d5db 1.5px; ports #d4d4d4 2px; dropzone dashed #d4d4d4 2px.
+- **Shadows**: nearly flat. Canvas nodes only: `0 1px 3px rgba(0,0,0,.1), 0 1px 2px -1px rgba(0,0,0,.1)`; selection = blue-400 border + 2px blue-100 ring; badges get a 2px white ring. Everything else relies on borders.
+- **Backgrounds & imagery**: no photography, no illustration. The pipeline canvas is #fafafa with a subtle dot/curve grid; chart areas use soft blue gradient fills. Only bitmap: the cube logo.
+- **States**: every interactive element carries five states beyond rest. **Hover** moves the fill one step (`--bg-hover` wash on ghost items, `--action-primary-hover` on solid buttons, `--soft-hover` on tinted ones); controls whose colours are inline get it from the hover hooks in `tokens/hover.css`. **Press** moves it a second step: Button and IconButton use explicit tokens (`--action-primary-active`, `--action-dark-active`, `--bg-press`, `--soft-active`, `--danger-active`, `--danger-soft-active`) and opt out of the global layer with `data-press="own"`; every other control — nav rows, tree items, menu items, chips, tabs, list rows, option rows, palette tiles — gets press from the one global rule in `tokens/interaction.css` (`filter: var(--press-filter)` on `:active`, which multiplies whatever wash hover is already showing, and brightens rather than darkens in dark mode). No scale transforms, no shadow shifts; text-only buttons drop to 70% opacity instead. **Keyboard focus** is also global: a 2px `--focus-border` outline at 2px offset on `:focus-visible` only, so a mouse click never draws it. **Selected/active** is persistent, not transient: active nav = `--bg-active` pill + heading-weight text; selected node = blue border + ring. **Disabled** is 55% opacity (50% on icon buttons) with the default cursor.
+- **Motion**: kept minimal by design (see Motion below) — 120–160ms ease-out on hover/selection, nothing bouncy or far-traveling.
+- **Layout chrome**: left sidebar 240px (collapsible to a 64px icon rail), 56px top bar (search left, bell + black "AI Assistant" pill right), optional 240px secondary panel (Documents tree, pipeline palette), 400px right config panel, 250px bottom data-preview drawer.
+- **Cards**: white, radius 10, hairline border, 21px padding, 14px/500 title — never elevated.
+- **Density**: high; table rows 32 (sm) · 40 (md) · 44 (lg); header cells the same size as body cells in weight 600, sentence case; mono cells at the row's size.
 
-## ICONOGRAPHY / 图标系统
+## Iconography
 - The product's icons are the **Lucide** stroke set (16/14px at 1.33px effective stroke, `currentColor`). We ship `components/icons/Icon.jsx`, embedding the exact Lucide path data for every glyph the product uses. Usage: `<Icon name="search" size={16}/>`.
-  （产品图标采用 **Lucide** 线性图标集（16/14px，约 1.33px 描边，随文字颜色变化）。已封装为 `components/icons/Icon.jsx`，内含产品实际用到的全部图形路径。用法：`<Icon name="search" size={16}/>`。）
 - Icon color follows text color (#525252 default chrome, #a1a1a1 muted, category hue inside tinted tiles).
-  （图标颜色跟随文字色：默认 #525252，弱化态 #a1a1a1，分类色块内为对应分类色。）
 - Tinted icon tiles are a signature motif: 40×40 r14 (palette), 48×48 r16 (nodes), 32×32 r8 hairline-bordered (list rows) — 100-tint bg + 600-hue glyph.
-  （彩色图标块是标志性视觉元素：40×40/r14（组件面板）、48×48/r16（节点）、32×32/r8 细边框（列表行）——浅色底 + 深色分类图标。）
-- Emoji/unicode-as-icon: never.
-  （从不用 emoji 或 unicode 符号充当图标。）
-- **Extended icon libraries / 扩展图标库**: all 287 Feather icons (same 24-grid stroke-2 dialect) are merged into `Icon` via `components/icons/feather-paths.js` — core names win on overlap. Unicons line style (1,206 glyphs) renders through `components/icons/Unicon.jsx` from the official Unicons CDN webfont — a substitution: the SVG set is not vendored locally, so `Unicon` needs network access. Keyword indexes for search: `assets/icons/icon-index.json` (core + Feather) and `assets/icons/unicons-index.json`; browse both in the two Icon Gallery cards (every icon carries keywords).
-  （扩展图标库：287 个 Feather 图标（与核心集同为 24 网格描边风格）已全部并入 `Icon` 组件，重名时以核心集为准；Unicons 线性风格 1,206 个图标通过 `Unicon` 组件从 Unicons 官方 CDN 字体渲染（替代方案：SVG 未本地化，需联网）。两份关键词索引位于 `assets/icons/`，可在两张 Icon Gallery 卡片中按关键词搜索，每个图标均附关键词。）
+- Emoji or unicode-as-icon: never.
+- **Extended icon libraries**: all 287 Feather icons (same 24-grid stroke-2 dialect) are merged into `Icon` via `components/icons/feather-paths.js` — core names win on overlap. Unicons line style (1,206 glyphs) renders through `components/icons/Unicon.jsx` from the official Unicons CDN webfont — a substitution: the SVG set is not vendored locally, so `Unicon` needs network access. Keyword indexes for search: `assets/icons/icon-index.json` (core + Feather) and `assets/icons/unicons-index.json`; browse both in the two Icon Gallery cards (every icon carries keywords).
+- **Icon sources**: Feather — github.com/feathericons/feather (`icons/*.svg`, keywords from `src/tags.json`), MIT licence; Unicons — github.com/Iconscout/unicons (`json/line.json`), Apache-2.0 licence. Last synced 2026-08-15.
 - Badges: 13–20px circles (error red, warning amber, pending gray, debug red) with 2px white ring, overlapping the parent's corner.
-  （徽标为 13–20px 圆形，叠加在父元素角上，带 2px 白色描边。）
 
-## Tokens & fonts / 设计令牌与字体
-- `tokens/colors.css`（基础色 + 语义别名）、`tokens/colors-extended.css`（九条 50–950 强调色阶 + 语义标签色对）、`tokens/alpha.css`（透明度阶与叠加层）、`tokens/typography.css`、`tokens/layout.css`（圆角/阴影/布局尺寸/层级）、`tokens/motion.css`、`tokens/interaction.css`（全局按压态与键盘聚焦层）、`tokens/fonts.css`、`tokens/dark.css`。
+## Tokens & fonts
+- `tokens/colors.css` (base colors + semantic aliases), `tokens/colors-extended.css` (nine 50–950 accent ramps + semantic label pairs), `tokens/alpha.css` (transparency ramps and overlays), `tokens/typography.css` (14px scale, CJK rules), `tokens/layout.css` (radii, shadows, chrome sizes, size tiers, z-index), `tokens/motion.css`, `tokens/charts.css` (series palette and plot furniture), `tokens/interaction.css` (global press and keyboard-focus layer), `tokens/hover.css` (hover hooks), `tokens/fonts.css`, `tokens/dark.css`.
+- `styles.css` imports every token file except `hover.css`; `keybricks.css` imports `styles.css` + `hover.css` and is what the npm path `@keyfunc/keybricks-ds/styles.css` resolves to.
 
-## Dark mode / 深色模式
+## Dark mode
 - Apply with `<html data-theme="dark">`; every component reads semantic aliases only, so nothing else changes. Toggle it live in the UI kit from the top bar or the sidebar's **Dark Mode** item (persisted to `localStorage("kb-theme")`). `applyStoredTheme()` restores it at app start.
-  （在 `<html>` 上加 `data-theme="dark"` 即可全局切换；所有组件只读取语义别名，无需改动组件本身。可在 UI kit 顶栏或侧边栏「Dark Mode」项实时切换，并持久化到 `localStorage("kb-theme")`；应用启动时调用 `applyStoredTheme()` 恢复。）
-- **Primary blue in dark / 深色模式主色**: on the #0a0a0a canvas the light-theme blue reads murky, and a brighter #2b7fff cannot carry white 13px type (3.8:1, below AA). Dark mode therefore uses **`#1f6feb`** — 4.3:1 against the canvas, 4.6:1 for its white label, both passing AA, in the same hue family (~214°) one step lower in luminance. The light theme keeps `#155dfc`.
-  （在 #0a0a0a 画布上，浅色主题的品牌蓝显得沉闷，而更亮的 #2b7fff 无法承载 13px 白色文字（对比度 3.8:1，未达 AA）。因此深色模式使用 **`#1f6feb`**：与画布对比 4.3:1、白色文字对比 4.6:1，均达 AA 标准，色相与浅色主题同属约 214°，亮度低一档。浅色主题仍为 `#155dfc`。）
-- Other shifts / 其他差异: four surface steps (#0a0a0a app / #161616 surface / #1d1d1d raised / #1f1f1f inset); borders `rgba(255,255,255,.09)`; the dark "AI Assistant" pill inverts to light-on-dark (`--action-dark-fg`); category and status tints become low-alpha washes of the same hues; tooltips invert; shadows deepen rather than glow.
-  （四级表面层次；边框为半透明白；深色「AI Assistant」胶囊反转为浅底深字；分类色与状态色为同色相的低透明度色块；提示气泡反色；阴影加深而非发光。）
-- **Foreground on filled surfaces / 填充色上的前景色**: text and icons sitting on a saturated fill use `--on-accent`, which stays white in both themes; the neutral "AI Assistant" pill uses `--action-dark-fg`, which inverts with the theme. Never use `--text-inverse` for this — it is the inverse of body text and flips to near-black on dark backgrounds.
-  （位于饱和色填充之上的文字与图标使用 `--on-accent`，在两套主题下恒为白色；中性色的「AI Assistant」胶囊使用 `--action-dark-fg`，随主题反转。此场景不得使用 `--text-inverse`，它是正文颜色的反色，在深色背景上会变为近黑色。）
-- **Status / 规范成熟度**: the dark palette is an original derivation of the light one, validated for contrast rather than copied from a dark-theme design. Confirm it against your intended dark spec before production use.
-  （深色调色板基于浅色体系推导而来，已做对比度验证，但并非直接来自现成的深色设计稿。正式用于生产前，建议与团队预期的深色规范核对。）
-- Authoring rule / 开发规范: never reference `--neutral-*` / `--blue-*` directly in a component. Use the semantic layer (`--bg-surface`, `--bg-raised`, `--text-body`, `--border-card`, `--track`, `--soft-bg`, `--info-bg`, `--on-accent`, `--port-border`, `--dropzone-border`, `--ring-surface`, `--tooltip-bg`, …) so both themes work for free.
-  （组件中禁止直接引用 `--neutral-*`/`--blue-*` 等基础色变量，一律使用语义层变量，这样浅色/深色两套主题自动生效，无需额外适配。）
+- **Primary blue in dark**: on the #0a0a0a canvas the light-theme blue reads murky, and a brighter #2b7fff cannot carry white 14px type (3.8:1, below AA). Dark mode therefore uses **`#1f6feb`** — 4.3:1 against the canvas, 4.6:1 for its white label, both passing AA, in the same hue family (~214°) one step lower in luminance. The light theme keeps `#155dfc`.
+- **Other shifts**: four surface steps (#0a0a0a app / #161616 surface / #1d1d1d raised / #1f1f1f inset); borders `rgba(255,255,255,.09)`; the dark "AI Assistant" pill inverts to light-on-dark (`--action-dark-fg`); category and status tints become low-alpha washes of the same hues; tooltips invert; shadows deepen rather than glow.
+- **Foreground on filled surfaces**: text and icons sitting on a saturated fill use `--on-accent`, which stays white in both themes; the neutral "AI Assistant" pill uses `--action-dark-fg`, which inverts with the theme. Never use `--text-inverse` for this — it is the inverse of body text and flips to near-black on dark backgrounds.
+- **Status**: the dark palette is an original derivation of the light one, validated for contrast rather than copied from a dark-theme design. Confirm it against your intended dark spec before production use.
+- **Authoring rule**: never reference `--neutral-*` / `--blue-*` directly in a component. Use the semantic layer (`--bg-surface`, `--bg-raised`, `--text-body`, `--border-card`, `--track`, `--soft-bg`, `--info-bg`, `--on-accent`, `--port-border`, `--dropzone-border`, `--ring-surface`, `--tooltip-bg`, …) so both themes work for free.
 
-## Motion / 动效
-- `tokens/motion.css` defines a restrained scale: 80/120/160/240/360ms with `--ease-out cubic-bezier(.2,.8,.3,1)`. Recipes: `--t-hover`（悬停/按压通用）、`kb-rise`（菜单、弹窗）、`kb-toast-in`、`kb-pulse`（骨架屏）、`kb-spin`（加载中）。`prefers-reduced-motion` 全局生效。动效克制：不弹跳，位移不超过 8px。
-- **Font caveat / 字体说明**: Inter is loaded from Google Fonts. Menlo has no webfont — the mono stack falls back to ui-monospace/SF Mono/Consolas on non-mac platforms.
-  （Inter 通过 Google Fonts 加载；Menlo 无网页字体可用，非 Mac 平台会回退到 ui-monospace/SF Mono/Consolas，如需精确还原请提供正版字体文件。）
+## Motion
+- `tokens/motion.css` defines a restrained scale: 80/120/160/240/360ms with `--ease-out cubic-bezier(.2,.8,.3,1)`. Recipes: `--t-hover` (hover and press), `kb-rise` (menus, dialogs), `kb-toast-in`, `kb-pulse` (skeletons), `kb-spin` (loading — constant-speed rotation, the industry norm for indeterminate spinners). `prefers-reduced-motion` is honoured globally. Nothing bounces; nothing travels more than 8px.
+- **Font caveat**: Inter is loaded from Google Fonts. Menlo has no webfont — the mono stack falls back to ui-monospace/SF Mono/Consolas on non-mac platforms; supply licensed font files if exact rendering matters.
 
-## Index / 目录索引
+## Index
 
-**For developers integrating this system / 开发团队接入入口**
-- `DESIGN.md` — the rules file for AI coding agents: absolute token values, interaction states, an explicit “do not” list, and voice. Point Claude Code / Cursor / Copilot at this before they generate UI.（给 AI 编程代理读的规则文件：绝对数值、交互状态、明确的禁止事项、文案语气。让 AI 写 UI 前先读它。）
-- `INTEGRATION.md` — the integration guide: three steps to first paint, the full 118-component index with import paths, token reference, dark mode, interaction states, versioning.（接入指南：三步跑通、全部组件清单与引入路径、token 速查、深色模式、交互状态、版本策略。）
-- `DEPLOY.md` — running the system on GitLab: what ships in the package and what stays on Pages, the entry points, the release flow, and the bundler config each consumer needs.（在 GitLab 上运行本系统：包里发什么、Pages 上留什么、入口点、发布流程、消费方需要的构建配置。）
-- `index.html` · `gallery.html` — the documentation site: the browsable system and the filterable thumbnail grid, both deployed to GitLab Pages by CI.（文档站：可浏览的系统主页与可筛选缩略图网格，由 CI 部署到 GitLab Pages。）
-- `package.json` · `.gitlab-ci.yml` · `_scripts/` — makes the system an installable package: a version tag publishes to the GitLab Package Registry, the default branch redeploys the docs site, and `npm run check` fails the pipeline if the generated tokens or barrels drift from source.（使设计系统成为可 `npm install` 的包：打 tag 发包，主分支重部文档站，`npm run check` 在生成产物与源码不一致时让流水线失败。）
+**For developers integrating this system**
+- `DESIGN.md` — the rules file for AI coding agents: absolute token values, interaction states, an explicit "do not" list, and voice. Point Claude Code / Cursor / Copilot at this before they generate UI.
+- `INTEGRATION.md` — the integration guide: three steps to first paint, the full 117-component index with import paths, token reference, dark mode, interaction states, versioning.
+- `DEPLOY.md` — running the system on GitLab: what ships in the package and what stays on Pages, the entry points, the release flow, and the bundler config each consumer needs.
+- `index.html` · `gallery.html` — the documentation site: the browsable system and the filterable thumbnail grid, both deployed to GitLab Pages by CI.
+- `package.json` · `.gitlab-ci.yml` · `_scripts/` — makes the system an installable package: a version tag publishes to the GitLab Package Registry, the default branch redeploys the docs site, and `npm run check` fails the pipeline if the generated tokens or barrels drift from source.
 
-- `styles.css` — 全局 CSS 入口（汇总所有 tokens）。
-- `assets/` — keybricks-logo.png。
-- `guidelines/` — 基础规范展示卡片（Design System 标签页）。
-- `ui_kits/keybricks-app/` — 交互式产品复刻：首页、文档、管道编辑器、系统迁移。
-- `SKILL.md` — Agent 技能入口文件。
+**Other files**
+- `styles.css` — global CSS entry (imports all token files); `keybricks.css` — the package's stylesheet entry (tokens + hover hooks).
+- `assets/` — keybricks-logo.png and the icon keyword indexes.
+- `guidelines/` — foundation showcase cards (Design System tab).
+- `ui_kits/keybricks-app/` — interactive product recreation: Home, Documents, Pipeline editor, System Migration.
+- `SKILL.md` — agent skill entry file.
 
-## Components / 组件清单
-- `components/icons/` — Icon（+ ICON_PATHS 图形数据 + feather-paths.js 全量 Feather 回退）、Unicon（Unicons CDN 字体）。
-- `components/buttons/` — Button、IconButton、ActionChip。
-- `components/forms/` — Field、Input、Textarea、Select、SearchInput、Checkbox、NumberStepper、Dropzone、Switch、Radio、RadioGroup、Combobox、MultiSelect、DatePicker、Slider。
-- `components/tabs/` — Tabs、PanelTabs、PillTabs、ViewToggle、SegmentedControl。
-- `components/display/` — Card、StatCard、Badge、StatusBadge、IconTile、ProgressBar、Donut、AreaChart、MiniBars、Avatar、AvatarGroup、Tag、Divider、Kbd。
-- `components/feedback/` — Stepper、ContextMenu、ActivityItem、DotActivity、LogViewer、Tooltip、Modal、Toast、ToastStack、Alert、EmptyState、Skeleton、Spinner、Menu、Accordion、Banner、Drawer、Timeline。
-- `components/data/` — DataTable、ListRow、Pagination、KeyValue、KeyValueList、DiffValue、CodeBlock、Spreadsheet、SmartTable、FilterBar。
-- `components/navigation/` — Sidebar（+ KEYBRICKS_NAV)、TopBar、PageToolbar、PageHeading、DocTree、Breadcrumb、Tree、ThemeToggle（+ applyStoredTheme）。
-- `components/pipeline/` — NodeCard、Port、PortLabel、PaletteItem、PaletteListItem、PalettePanel（+ PIPELINE_CATALOG）、PipelineCanvas、DataPreview、ConfigPanel、ZoomControls。
-- `components/brand/` — BrandVisual（品牌视觉：7 个生成式母题，统一 1200×400 画布，可裁切填充任意尺寸；恒为深色，不随主题变化）。
-- `components/charts/` — 图表模块（27 种）：Sparkline、LineChart、BarChart、BarList、DonutChart、ScatterChart、HeatmapChart、WaterfallChart、BulletChart、GaugeChart、FunnelChart、TreemapChart、RadarChart、Histogram、BoxPlot、ParetoChart、CandlestickChart、SankeyChart、ChordChart、SunburstChart、WorldMap、GanttChart，以及 3D 系列 Surface3D、Scatter3D、Bar3D、Pie3D、Ribbon3D（SVG 画家算法渲染，拖拽旋转；+ ChartKit 共享图例/提示，`tokens/charts.css` 序列色与绘图配件）。三个尺寸层级：统计卡内微型、卡片内交互中型、整页分析大型；每种图表在任何尺寸都保留悬停读数。WorldMap 使用真实 Natural Earth 地理数据，需页面加载固定版本的 d3 与 topojson。
+## Components
+- `components/icons/` — Icon (+ ICON_PATHS glyph data + feather-paths.js, the full Feather fallback), Unicon (Unicons CDN webfont).
+- `components/buttons/` — Button, IconButton, ActionChip.
+- `components/forms/` — Field, Input, Textarea, Select, SearchInput, Checkbox, NumberStepper, Dropzone, Switch, Radio, RadioGroup, Combobox, MultiSelect, DatePicker, Slider.
+- `components/tabs/` — Tabs, PanelTabs, PillTabs, ViewToggle, SegmentedControl.
+- `components/display/` — Card, StatCard, Badge, StatusBadge, IconTile, ProgressBar, Donut, AreaChart, MiniBars, Avatar, AvatarGroup, Tag, Divider, Kbd.
+- `components/feedback/` — Stepper, ContextMenu, ActivityItem, DotActivity, LogViewer, Tooltip, Modal, Toast, ToastStack, Alert, EmptyState, Skeleton, Spinner, Menu, Accordion, Banner, Drawer, Timeline.
+- `components/data/` — Table, ListRow, Pagination, KeyValue, KeyValueList, DiffValue, CodeBlock, Spreadsheet, SmartTable, FilterBar.
+- `components/navigation/` — Sidebar (+ KEYBRICKS_NAV), TopBar, PageToolbar, PageHeading, DocTree, Breadcrumb, Tree, ThemeToggle (+ applyStoredTheme).
+- `components/pipeline/` — NodeCard, Port, PortLabel, PaletteItem, PaletteListItem, PalettePanel (+ PIPELINE_CATALOG), PipelineCanvas, DataPreview, ConfigPanel, ZoomControls.
+- `components/charts/` — 27 chart types: Sparkline, LineChart, BarChart, BarList, DonutChart, ScatterChart, HeatmapChart, WaterfallChart, BulletChart, GaugeChart, FunnelChart, TreemapChart, RadarChart, Histogram, BoxPlot, ParetoChart, CandlestickChart, SankeyChart, ChordChart, SunburstChart, WorldMap, GanttChart, and the 3D set Surface3D, Scatter3D, Bar3D, Pie3D, Ribbon3D (SVG painter's-algorithm rendering, drag to rotate; + ChartKit shared legend/tooltip, `tokens/charts.css` series colors and plot furniture). Three scales: micro inside stat tiles, interactive mid-size inside cards, full-page analysis; every chart keeps its hover read-out at every scale. WorldMap uses real Natural Earth geography and needs the page to load pinned d3 and topojson.
 
-## Intentional additions / 主动补充的内容
+## Intentional additions
 These extend the original inventory — each is a standard need this product clearly has, built only from the extracted foundations (no new colors, radii, or type sizes):
-（以下为在原始素材基础上主动补充的内容——均为该产品明显需要、但原始设计未直接给出的标准能力，且仅使用已提取的基础规范搭建，不引入新的颜色/圆角/字号：）
-- `Icon` — 图标封装组件。
-- `Switch`、`Radio`/`RadioGroup` — 设置项开关与单选场景。
-- `SegmentedControl` — 视图/范围切换（对已有 `ViewToggle` 的泛化）。
-- `Tooltip`、`Modal`、`Toast`/`ToastStack` — 确认与通知场景。
-- `Alert`、`EmptyState`、`Skeleton`、`Spinner` — 空状态/加载态/报错态。
-- `Breadcrumb` — 面包屑导航（导航层级可达三级，如 Management → System Migration → Import）。
-- `Pagination` — 表格分页。
-- `Avatar`/`AvatarGroup` — 头像组件；无真实头像图时以着色首字母代替，传入 `src` 即可使用真实图片。
-- `ThemeToggle` + `applyStoredTheme` — 驱动深色模式。
-- `KeyValue`/`KeyValueList`、`DiffValue` — 归纳配置摘要与迁移确认步骤中反复出现的「标签/值」与「变更前→变更后」写法。
-- **Enterprise pack / 企业级扩展包**（参考 IBM Carbon、SAP Fiori、Salesforce Lightning、Workday Canvas 的通用清单补充；仅使用既有 token）：
-  - `Spreadsheet` — Excel 式电子表格：公式栏（名称框 + fx）、字母/数字冻结表头、点击 + Shift 点击范围选择、双击编辑、`=SUM()/AVERAGE()` 等公式实时计算、工作表标签、Sum/Avg/Count 状态栏。
-  - `SmartTable` — Notion/Airtable/Coda 式智能表格（database grid）：带类型图标的字段头（text/number/select/multiSelect/date/person/checkbox/url/progress）、主题自适应的彩色选项胶囊（`--hue-*`）、行悬停 + 展开按钮、双击内联编辑、“+ New” 加行与加字段列、列尾 COUNT/SUM/AVG 聚合、视图工具栏（Hide fields/Filter/Group/Sort/搜索）。
-  - `FilterBar` — Fiori 风格列表报表筛选栏（变体名 + 展开/收起 + Adapt Filters (n) + Go）。
-  - `Combobox` — 输入即筛选的单选下拉；`MultiSelect` — 多选下拉（标签 + "+n" 溢出 + 一键清空）。
-  - `DatePicker` — 日历弹层日期选择；`Slider` — 滑杆（拖动气泡 + 最值标签）。
-  - `Drawer` — 右侧滑出详情面板；`Banner` — 页面级通知条（区别于卡片内 Alert 与浮动 Toast）；`Timeline` — 垂直活动时间线；`Tree` — 通用嵌套树（级联勾选、异步加载、搜索高亮、拖入文件夹、键盘导航）。
-- `Tag`、`Divider`、`Kbd` — 归纳筛选标签、分隔线、快捷键提示等在界面中反复手写的小元素。
-- `Menu`（挂载于触发元素下方的下拉菜单，区别于按点击位置弹出的 `ContextMenu`）、`Accordion`（通用可折叠区块，区别于专用于工作流文档的 `ListRow`）。
-- `CodeBlock` — 带复制按钮的等宽代码块，用于 SQL Preview 与导出 JSON 预览。
-- `ZoomControls` — 管道画布的缩放控件；源文件隐含平移/缩放交互，但未给出对应控件。
-- `StatCard`/`Donut`/`ProgressBar`/`AreaChart`/`MiniBars` 内置的图表小工具，免去引入图表库。
-- Token 补充：`tokens/motion.css`、层级（z-index）体系。
+- `Icon` — icon wrapper component.
+- `Switch`, `Radio`/`RadioGroup` — settings toggles and single choice.
+- `SegmentedControl` — view/range switching (a generalisation of the existing `ViewToggle`).
+- `Tooltip`, `Modal`, `Toast`/`ToastStack` — confirmation and notification.
+- `Alert`, `EmptyState`, `Skeleton`, `Spinner` — empty, loading and error states.
+- `Breadcrumb` — breadcrumb navigation (hierarchy reaches three levels, e.g. Management → System Migration → Import).
+- `Pagination` — table paging.
+- `Avatar`/`AvatarGroup` — avatars; tinted initials when no photo exists, pass `src` for a real image.
+- `ThemeToggle` + `applyStoredTheme` — drive dark mode.
+- `KeyValue`/`KeyValueList`, `DiffValue` — the "label / value" and "before → after" patterns that recur in config summaries and the migration confirmation step.
+- **Enterprise pack** (drawn from the common inventory of IBM Carbon, SAP Fiori, Salesforce Lightning and Workday Canvas; existing tokens only):
+  - `Spreadsheet` — Excel-style sheet: formula bar (name box + fx), frozen letter/number headers, click and Shift-click range selection, double-click editing, live `=SUM()/AVERAGE()` formulas, sheet tabs, Sum/Avg/Count status bar.
+  - `SmartTable` — Notion/Airtable/Coda-style database grid: field headers with type icons (text/number/select/multiSelect/date/person/checkbox/url/progress), theme-aware colored option pills (`--hue-*`), row hover + expand button, double-click inline editing, "+ New" row and field columns, COUNT/SUM/AVG footer aggregates, view toolbar (Hide fields/Filter/Group/Sort/search).
+  - `FilterBar` — Fiori-style list-report filter bar (variant name + expand/collapse + Adapt Filters (n) + Go).
+  - `Combobox` — type-to-filter single-select dropdown; `MultiSelect` — multi-select dropdown (tags + "+n" overflow + clear all).
+  - `DatePicker` — calendar popover date picker; `Slider` — slider (drag bubble + min/max labels).
+  - `Drawer` — right-hand slide-out detail panel; `Banner` — page-level notification (distinct from in-card Alert and floating Toast); `Timeline` — vertical activity timeline; `Tree` — general nested tree (cascading checks, async loading, search highlight, drag into folder, keyboard navigation).
+- `Tag`, `Divider`, `Kbd` — filter tags, separators and shortcut hints that were hand-built over and over in the UI.
+- `Menu` (dropdown anchored under its trigger, distinct from `ContextMenu`, which opens at the click point), `Accordion` (general collapsible section, distinct from `ListRow`, which is specific to workflow documents).
+- `CodeBlock` — mono code block with a Copy button, for SQL Preview and exported-JSON previews.
+- `ZoomControls` — zoom controls for the pipeline canvas; the source implied pan/zoom but gave no control for it.
+- `StatCard`/`Donut`/`ProgressBar`/`AreaChart`/`MiniBars` — built-in chart widgets, so small dashboards need no chart library.
+- Token additions: `tokens/motion.css` and the z-index scale.