@keyfunc/keybricks-ds 1.0.3 → 2.1.1

package/readme.md

@@ -1,151 +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）体系。
-cicd test
+- `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.

package/readme.zh-CN.md

@@ -0,0 +1,120 @@
+# Keybricks 设计系统
+
+[English](readme.md) · 中文
+
+> 本文是 `readme.md` 的完整中文版，两者逐条对应。如有出入，以英文版为准。
+
+Keybricks 是面向财务团队的企业绩效管理（EPM）平台：文档与报表、商业智能、数据集成、对账、合并报表，以及管理套件（建模、工作流、权限、系统迁移、业务逻辑、任务管理、校验规则、控制中心）。其标志性界面是基于节点的**数据管道编辑器**（"适配器"，如 *Oracle Adapter*），用户在点状网格画布上依次连接 数据源 → 关联 → 转换 → 合并 → 输出 节点。
+
+## 产品范围
+单一产品：Keybricks 网页应用（桌面端，设计尺寸约 1512×860）。核心界面：首页仪表盘 · 文档中心 · 管道编辑器 · 系统迁移向导。
+
+## 内容规范
+- **语气**：简洁、技术化、动词开头。按钮用祈使句："Run Test"、"Submit"、"Save Settings"、"Continue to Confirmation"、"Mark as New"、"Skip Selected"。
+- **大小写**：导航、标题、按钮、表头用词首大写（Title Case），如 "Import History"、"Custom Parameters"；辅助说明文字用句首大写（sentence case），如 "Import and manage configuration migrations across systems"、"Click to upload or drag and drop"、"JSON files only"。
+- **人称**：不使用"我 / 我们 / 你"——文案客观、以系统为中心。唯一的人性化表达是仪表盘问候语 "Good evening, Felix" 加完整日期 "Monday, April 21, 2026"。
+- **术语**：精确的 EPM/ETL 领域词汇——Detail Sheet、Dimension、Model、Association Match、Multi-Condition Judge、Group Calculation、Concat Merge、Reconciliation、Consolidation。配置代码用等宽字体、全大写下划线格式（"FIN_CURRENCY_DEFAULT"）。
+- **数字与元信息**：计数写作 "1 document"、"2 items"；相对时间写作 "2 hours ago"；日志行写作 "[14:30] Task started: Import"。
+- **状态文案**：状态标签带圆点前缀，如 "• Editing"；步骤用名词命名（"Upload & Parse"、"Comparison"、"Confirmation"、"Execution"、"Results"）。
+- **Emoji**：从不使用。所有装饰性表达交给图标。
+- **本地化**：内容容忍中英混排——名为"财务分析"的文档可以与英文名并列；界面框架文案保持英文。
+
+## 视觉基础
+- **色彩**：近乎单色的中性界面（neutral 色阶 #FAFAFA→#0A0A0A），只有**一个**操作蓝（#155DFC）。色彩只用于表达含义：节点分类色相（数据源绿 #009966、关联蓝 #155DFC、转换橙 #FF6900、合并紫 #9810FA、输出青 #009689，各配一个 100 档浅色底块）、反馈色（成功 #00BC7D、危险 #FB2C36、警告 #FFB900）、图表色（`--series-1…8`，见 `tokens/charts.css`）。背景：应用层 #FAFAFA，表面层白色。除图表区域的渐变填充（蓝 → 透明）外不使用渐变。
+  体系分为**三层**，只有中间一层是对外 API：
+  1. **调色板层** —— `--<色相>-<档位>`，统一的 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%）。两套主题取值相同，只供第二层引用。
+  2. **语义角色层** —— `--bg-*`、`--text-*`、`--border-*`、`--action-*`、`--overlay-*`，以及 `--success/warning/danger/info` 四组反馈色（含 `-bg`/`-text` 配对）。按用途命名，负责深色模式切换。**组件与业务设计只允许引用这一层。**
+  3. **组件层** —— `--cat-*`、`--tooltip-bg`、`--dropzone-border-hover`：只属于某个组件的某个部位，仅在第二层确实没有合适角色时才新增。
+
+  不可打破的规则：400 及更浅的档位不得在白底上承载正文（它们是表面色、边框色、禁用态图标色）；饱和填充之上的前景色只能用 `--on-accent`（#FFFFFF），**两套主题都是**；标签色相按机械规则取值（浅色 = 100 档底 + 700 档字，深色 = 950 档底 + 300 档字），新增分类无需主观判断；色相表达*分类*，四组反馈色表达*严重程度*。对比度目标：正文 4.5:1，18px 以上或加粗文字及界面边界 3:1。Colors 分组下三张卡片给出全部色值：Palette（完整色阶）、Schemes（可搭配使用的配色组合）、Transparency（透明度阶）。
+- **字体**：只用 Inter（300 用于统计数字，400 正文，500 界面中等字重，600 标题与表头），采用 14px 字号阶梯——12 说明文字 · 14 正文与控件 · 16 区块标题 · 20 页面标题；24px 只用于问候语和统计数字（字重 300）；11px 只用于图表刻度。14px 起使用负字距（-.15 到 -.54px），12px 字距为 0。数据 / 代码 / 日志用 Menlo，与所在行同字号，使用等宽数字。中文、日文、韩文（`lang="zh|ja|ko"`）：字号不变，500 字重改为 600，字距为 0，不做大写转换。
+- **间距**：实际采用 4px 体系（2/4/6/8/10/12/16/24/32）；页面内边距 24×32；卡片内边距 21（紧凑型 17）；区块间距 24。工具栏内的间距由尺寸层级决定：组内 8，组间 12/16/24，卡片边缘到第一个控件 12/16。
+- **尺寸层级**：每个区域只用一档——`data-size="sm" | "md" | "lg"` 对应 24 / 32 / 36px 控件、12 / 14 / 14px 控件文字、32 / 40 / 44px 行高；区域内所有控件自动继承，可交互元素不小于 24px，同一行内绝不混用高度或字号。md 是应用默认，对话框为 lg，密集表格为 sm。
+- **圆角**：4 小型控件 · 8 按钮 / 输入框 / 导航 / 标签 · 10 卡片 / 搜索框 / 上传区 · 14 组件面板图标块 · 16 画布节点 · 端口 / 步骤圆点 / 胶囊用全圆角。
+- **边框**：全局使用发丝级细边框——卡片 rgba(229,229,229,.6)；控件 #e5e5e5；行分隔线 #f5f5f5；复选框 #d1d5db 1.5px；端口 #d4d4d4 2px；上传区虚线 #d4d4d4 2px。
+- **阴影**：几乎全平面。只有画布节点有阴影：`0 1px 3px rgba(0,0,0,.1), 0 1px 2px -1px rgba(0,0,0,.1)`；选中态 = blue-400 边框 + 2px blue-100 光环；徽标带 2px 白色描边。其余一律靠边框区分层次。
+- **背景与图像**：不用摄影图，不用插画。管道画布为 #fafafa 底配淡淡的点状 / 曲线网格；图表区域用柔和的蓝色渐变填充。唯一的位图是立方体 Logo。
+- **交互状态**：每个可交互元素在静默态之外都有五种状态。**悬停**让填充加深一档（幽灵按钮类元素用 `--bg-hover`，实心按钮用 `--action-primary-hover`，浅色底按钮用 `--soft-hover`）；颜色写在内联样式里的控件，悬停效果来自 `tokens/hover.css` 中的悬停钩子。**按下**再加深一档：Button 与 IconButton 使用专门的 token（`--action-primary-active`、`--action-dark-active`、`--bg-press`、`--soft-active`、`--danger-active`、`--danger-soft-active`），并通过 `data-press="own"` 退出全局层；其余所有控件——导航行、树节点、菜单项、标签、标签页、列表行、选项行、面板磁贴——由 `tokens/interaction.css` 中的一条全局规则提供按下态（`:active` 时加上 `filter: var(--press-filter)`，在悬停底色之上再叠加一档，深色模式下方向为提亮）。不做缩放，不改阴影；纯文字按钮改为降到 70% 不透明度。**键盘聚焦**同样是全局的：仅在 `:focus-visible` 时绘制 2px `--focus-border` 描边（偏移 2px），鼠标点击不会出现。**选中 / 激活**是持续态而非瞬时态：激活的导航项 = `--bg-active` 胶囊 + 标题字重；选中的节点 = 蓝色边框 + 光环。**禁用**为 55% 不透明度（图标按钮 50%），使用默认光标。
+- **动效**：刻意克制（见下方"动效"一节）——悬停 / 选中 120–160ms 缓出，不弹跳，不大幅位移。
+- **布局框架**：左侧边栏 240px（可收起为 64px 图标栏）；顶栏 56px（左侧搜索，右侧铃铛 + 黑色 "AI Assistant" 胶囊）；可选的 240px 二级面板（文档树、管道组件面板）；右侧配置面板 400px；底部数据预览抽屉 250px。
+- **卡片**：白底、10px 圆角、细边框、21px 内边距、14px / 500 字重标题——从不使用投影抬高。
+- **密度**：高密度；表格行高 32（sm）· 40（md）· 44（lg）；表头与单元格同字号、字重 600、句首大写；等宽单元格与所在行同字号。
+
+## 图标系统
+- 产品图标是 **Lucide** 线性图标集（16/14px，实际描边约 1.33px，颜色为 `currentColor`）。我们提供 `components/icons/Icon.jsx`，内嵌产品用到的每个图形的 Lucide 原始路径数据。用法：`<Icon name="search" size={16}/>`。
+- 图标颜色跟随文字颜色（默认框架色 #525252，弱化态 #a1a1a1，彩色图标块内为对应分类色）。
+- 彩色图标块是标志性元素：40×40 圆角 14（组件面板）、48×48 圆角 16（节点）、32×32 圆角 8 带细边框（列表行）——100 档浅色底 + 600 档分类色图标。
+- 从不用 emoji 或 unicode 字符充当图标。
+- **扩展图标库**：全部 287 个 Feather 图标（同为 24 网格、2px 描边风格）已通过 `components/icons/feather-paths.js` 并入 `Icon`——重名时以核心集为准。Unicons 线性风格（1,206 个）通过 `components/icons/Unicon.jsx` 从 Unicons 官方 CDN 字体渲染——这是替代方案：SVG 图标集没有放在本地，所以 `Unicon` 需要联网。搜索用的关键词索引：`assets/icons/icon-index.json`（核心集 + Feather）和 `assets/icons/unicons-index.json`；可在两张 Icon Gallery 卡片中浏览（每个图标都附关键词）。
+- **图标来源**：Feather —— github.com/feathericons/feather（`icons/*.svg`，关键词来自 `src/tags.json`），MIT 许可；Unicons —— github.com/Iconscout/unicons（`json/line.json`），Apache-2.0 许可。最近同步 2026-08-15。
+- 徽标：13–20px 圆形（错误红、警告琥珀、待处理灰、调试红），带 2px 白色描边，叠在父元素的角上。
+
+## 设计令牌与字体
+- `tokens/colors.css`（基础色 + 语义别名）、`tokens/colors-extended.css`（九条 50–950 强调色阶 + 语义标签色对）、`tokens/alpha.css`（透明度阶与叠加层）、`tokens/typography.css`（14px 字号阶梯、CJK 规则）、`tokens/layout.css`（圆角、阴影、框架尺寸、尺寸层级、层级 z-index）、`tokens/motion.css`、`tokens/charts.css`（序列色板与绘图配件）、`tokens/interaction.css`（全局按下态与键盘聚焦层）、`tokens/hover.css`（悬停钩子）、`tokens/fonts.css`、`tokens/dark.css`。
+- `styles.css` 引入除 `hover.css` 以外的所有 token 文件；`keybricks.css` 引入 `styles.css` + `hover.css`，npm 路径 `@keyfunc/keybricks-ds/styles.css` 实际指向它。
+
+## 深色模式
+- 在 `<html>` 上加 `data-theme="dark"` 即可；所有组件只读取语义别名，其他什么都不用改。可在 UI kit 的顶栏或侧边栏 **Dark Mode** 项实时切换（持久化到 `localStorage("kb-theme")`）。应用启动时调用 `applyStoredTheme()` 恢复。
+- **深色模式主色**：在 #0a0a0a 画布上，浅色主题的蓝色显得浑浊，而更亮的 #2b7fff 又无法承载 14px 白色文字（3.8:1，未达 AA）。因此深色模式使用 **`#1f6feb`**——与画布对比 4.3:1，白色文字对比 4.6:1，均达 AA，与浅色主题同属约 214° 色相，亮度低一档。浅色主题保持 `#155dfc`。
+- **其他差异**：四级表面层次（#0a0a0a 应用层 / #161616 表面层 / #1d1d1d 浮起层 / #1f1f1f 内嵌层）；边框 `rgba(255,255,255,.09)`；深色 "AI Assistant" 胶囊反转为浅底深字（`--action-dark-fg`）；分类色与状态色变为同色相的低透明度色块；提示气泡反色；阴影加深而不是发光。
+- **填充色上的前景色**：位于饱和色填充之上的文字与图标使用 `--on-accent`，两套主题下都是白色；中性色的 "AI Assistant" 胶囊使用 `--action-dark-fg`，随主题反转。这里绝不能用 `--text-inverse`——它是正文颜色的反色，在深色背景上会变成近黑色。
+- **成熟度**：深色调色板是从浅色体系独立推导而来的，做过对比度验证，但并非照搬现成的深色设计稿。正式上线前，请与团队预期的深色规范核对。
+- **开发规范**：组件中绝不直接引用 `--neutral-*` / `--blue-*`。一律使用语义层（`--bg-surface`、`--bg-raised`、`--text-body`、`--border-card`、`--track`、`--soft-bg`、`--info-bg`、`--on-accent`、`--port-border`、`--dropzone-border`、`--ring-surface`、`--tooltip-bg` 等），这样两套主题自动生效。
+
+## 动效
+- `tokens/motion.css` 定义了克制的时长阶梯：80/120/160/240/360ms，缓动 `--ease-out cubic-bezier(.2,.8,.3,1)`。预设：`--t-hover`（悬停与按下）、`kb-rise`（菜单、对话框）、`kb-toast-in`、`kb-pulse`（骨架屏）、`kb-spin`（加载中——匀速旋转，这是行业内不定时长加载图标的通行做法）。全局遵循 `prefers-reduced-motion`。不弹跳，位移不超过 8px。
+- **字体说明**：Inter 通过 Google Fonts 加载。Menlo 没有网页字体——在非 Mac 平台上，等宽字体栈会回退到 ui-monospace / SF Mono / Consolas；如需精确还原，请提供正版字体文件。
+
+## 目录索引
+
+**开发团队接入入口**
+- `DESIGN.md` —— 给 AI 编程代理读的规则文件：绝对数值、交互状态、明确的"禁止"清单、文案语气。让 Claude Code / Cursor / Copilot 在生成界面前先读它。
+- `INTEGRATION.md` —— 接入指南：三步跑通首屏、全部 117 个组件的清单与引入路径、token 速查、深色模式、交互状态、版本策略。
+- `DEPLOY.md` —— 在 GitLab 上运行本系统：包里发布什么、什么留在 Pages 上、入口点、发布流程、各消费方需要的构建配置。
+- `index.html` · `gallery.html` —— 文档站：可浏览的系统主页与可筛选的缩略图网格，均由 CI 部署到 GitLab Pages。
+- `package.json` · `.gitlab-ci.yml` · `_scripts/` —— 让本系统成为可安装的包：打版本 tag 即发布到 GitLab Package Registry，默认分支更新即重新部署文档站，生成的 token 或入口文件与源码不一致时 `npm run check` 会让流水线失败。
+
+**其他文件**
+- `styles.css` —— 全局 CSS 入口（引入所有 token 文件）；`keybricks.css` —— 包的样式入口（token + 悬停钩子）。
+- `assets/` —— keybricks-logo.png 与图标关键词索引。
+- `guidelines/` —— 基础规范展示卡片（Design System 标签页）。
+- `ui_kits/keybricks-app/` —— 可交互的产品复刻：首页、文档、管道编辑器、系统迁移。
+- `SKILL.md` —— Agent 技能入口文件。
+
+## 组件清单
+- `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/` —— 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 种图表：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。
+
+## 主动补充的内容
+以下内容是对原始清单的扩展——每一项都是这个产品明显需要的标准能力，且只用已提取的基础规范搭建（不引入新的颜色、圆角或字号）：
+- `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` —— 配置摘要与迁移确认步骤中反复出现的"标签 / 值"与"变更前 → 变更后"写法。
+- **企业级扩展包**（参考 IBM Carbon、SAP Fiori、Salesforce Lightning、Workday Canvas 的通用组件清单；只用既有 token）：
+  - `Spreadsheet` —— Excel 式电子表格：公式栏（名称框 + fx）、冻结的字母 / 数字表头、点击与 Shift 点击范围选择、双击编辑、`=SUM()/AVERAGE()` 公式实时计算、工作表标签、Sum/Avg/Count 状态栏。
+  - `SmartTable` —— Notion / Airtable / Coda 式数据库表格：带类型图标的字段头（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）体系。

package/tokens/charts.css

@@ -1,16 +1,19 @@
 /* Keybricks chart tokens — series palette + plot furniture.
-   Series are theme-aware: saturated mid steps on white, 300-step tints on #0a0a0a.
+   Series palette (2.1.1, "Option A"): eight hues in one lightness band with a chroma floor — every adjacent
+   pair ΔE ≥ 8 under CVD simulation, ≥ 15 normal vision, ≥ 3:1 on the surface; the first three pass all pairs.
+   No green or red in the sequence: those stay reserved for --chart-pos / --chart-neg and status. Slots 9–10
+   are greys for "other" / overflow. Dark values are tuned for #161616, not derived from the light ramps.
    Components reference ONLY --series-* / --chart-* here, never raw ramps. */
 :root{
 --series-1:var(--chart-blue);
---series-2:var(--teal-600);
---series-3:var(--purple-600);
---series-4:var(--orange-500);
---series-5:var(--emerald-600);
---series-6:var(--pink-600);
---series-7:var(--cyan-600);
---series-8:var(--amber-400);
---series-9:var(--red-500);
+--series-2:#e16c10;
+--series-3:#079a94;
+--series-4:#8254c4;
+--series-5:#b98705;
+--series-6:#bc378d;
+--series-7:#7a8d30;
+--series-8:#2f99c0;
+--series-9:var(--neutral-500);
 --series-10:var(--neutral-400);
 --chart-grid:var(--neutral-100);
 --chart-axis:var(--neutral-300);
@@ -26,14 +29,14 @@
 }
 [data-theme="dark"]{
 --series-1:#51a2ff;
---series-2:var(--teal-300);
---series-3:var(--purple-300);
---series-4:var(--orange-300);
---series-5:var(--emerald-300);
---series-6:var(--pink-300);
---series-7:var(--cyan-300);
---series-8:var(--amber-300);
---series-9:var(--red-300);
+--series-2:#ee8545;
+--series-3:#35c6b9;
+--series-4:#a07cdb;
+--series-5:#e4ad3c;
+--series-6:#db6baf;
+--series-7:#9bb054;
+--series-8:#54b8e1;
+--series-9:#8f8f8f;
 --series-10:var(--neutral-500);
 --chart-grid:#1f1f1f;
 --chart-axis:#3f3f3f;

package/tokens/colors.css

@@ -19,7 +19,7 @@
 --danger:#fb2c36;--danger-bg:#fef2f2;--danger-text:#c10007;
 --warning:#ffb900;--warning-bg:#fff7ed;--warning-text:#ca3500;
 /* ── Semantic aliases: the ONLY layer components may reference ── */
---bg-app:var(--neutral-50);--bg-surface:var(--neutral-0);--bg-raised:var(--neutral-0);--bg-inset:var(--neutral-50);--bg-hover:var(--neutral-100);--bg-active:var(--neutral-100);--bg-scrim:rgba(10,10,10,.32);
+--bg-app:var(--neutral-50);--bg-surface:var(--neutral-0);--bg-raised:var(--neutral-0);--bg-inset:var(--neutral-50);--bg-table-header:var(--neutral-100);--bg-hover:var(--neutral-100);--bg-active:var(--neutral-100);--bg-scrim:rgba(10,10,10,.32);
 --text-primary:var(--neutral-950);--text-heading:var(--neutral-900);--text-strong:var(--neutral-700);--text-body:var(--neutral-600);--text-secondary:var(--neutral-500);--text-muted:var(--neutral-400);--text-inverse:#ffffff;
 /* Foreground ON a saturated fill — always light, in BOTH themes */
 --on-accent:#ffffff;
@@ -28,7 +28,7 @@
 --border-card:rgba(229,229,229,.6);--border-control:var(--neutral-200);--border-subtle:var(--neutral-100);--border-strong:var(--neutral-300);
 --action-primary:var(--blue-600);--action-primary-hover:var(--blue-700);--action-primary-active:#1039c4;--action-dark:var(--neutral-900);--action-dark-hover:var(--neutral-800);--action-dark-active:var(--neutral-950);
 /* Press (active) fills — one step past the hover value in each family */
---bg-press:var(--neutral-200);--soft-active:var(--blue-200);--danger-active:var(--red-800);--danger-soft-active:var(--red-200);
+--bg-press:var(--neutral-200);--soft-active:var(--blue-200);--danger-active:var(--red-800);--danger-soft-hover:var(--red-100);--danger-soft-active:var(--red-200);
 --focus-ring:var(--blue-100);--focus-border:var(--blue-500);--selected-border:var(--blue-400);
 --soft-bg:var(--blue-50);--soft-border:var(--blue-500);--soft-hover:var(--blue-100);
 --info-bg:var(--blue-50);--info-fg:var(--blue-600);

package/tokens/dark.css

@@ -15,7 +15,7 @@
 [data-theme="dark"]{
 color-scheme:dark;
 /* Surfaces — 4 steps, each ~+6% luminance, so nesting reads without borders */
---bg-app:#0a0a0a;--bg-surface:#161616;--bg-raised:#1d1d1d;--bg-inset:#1f1f1f;--bg-hover:#262626;--bg-active:#2e2e2e;--bg-scrim:rgba(0,0,0,.6);
+--bg-app:#0a0a0a;--bg-surface:#161616;--bg-raised:#1d1d1d;--bg-inset:#1f1f1f;--bg-table-header:#1f1f1f;--bg-hover:#262626;--bg-active:#2e2e2e;--bg-scrim:rgba(0,0,0,.6);
 /* Text */
 --text-primary:#fafafa;--text-heading:#f5f5f5;--text-strong:#e5e5e5;--text-body:#d4d4d4;--text-secondary:#a1a1a1;--text-muted:#737373;--text-inverse:#0a0a0a;
 --on-accent:#ffffff;--action-dark-fg:#0a0a0a;
@@ -24,7 +24,7 @@ color-scheme:dark;
 /* Actions */
 --action-primary:#1f6feb;--action-primary-hover:#2b7fff;--action-primary-active:#1a5ec9;--action-dark:#fafafa;--action-dark-hover:#e5e5e5;--action-dark-active:#d4d4d4;
 /* Press (active) fills — one step past the hover value in each family */
---bg-press:#3a3a3a;--soft-active:rgba(43,127,255,.32);--danger-active:#c10007;--danger-soft-active:rgba(251,44,54,.26);
+--bg-press:#3a3a3a;--soft-active:rgba(43,127,255,.32);--danger-active:#c10007;--danger-soft-hover:rgba(251,44,54,.2);--danger-soft-active:rgba(251,44,54,.26);
 --focus-ring:rgba(43,127,255,.32);--focus-border:#2b7fff;--selected-border:#51a2ff;
 --soft-bg:rgba(43,127,255,.14);--soft-border:#2b7fff;--soft-hover:rgba(43,127,255,.24);
 --info-bg:rgba(43,127,255,.14);--info-fg:#8ab8ff;

package/tokens/hover.css

@@ -0,0 +1,32 @@
+/* ── Hover hooks ── state signals read by component inline styles; these are not design tokens. */
+/* Hover for controls whose rest colours are inline. Two hooks, both set a custom property that the
+   component's own inline style reads, so focus, error and selected colours (written as plain values)
+   always win over hover without !important:
+   data-field — a bordered field box (Input, Textarea, Select, Combobox, MultiSelect, DatePicker,
+     SearchInput, NumberStepper): the border steps from --border-control to --border-strong.
+   data-wash — a borderless segment inside a control (stepper − / +, pagination items): the
+     surface steps to --bg-hover, the same step as an outline or ghost Button.
+   Each hook resets itself so a hovered parent never lights a nested control. */
+[data-field]{--field-border:initial}
+[data-field]:hover{--field-border:var(--border-strong)}
+[data-wash]{--wash:initial}
+[data-wash]:hover:not(:disabled){--wash:var(--bg-hover)}
+[data-wash="strong"]:hover:not(:disabled){--wash:var(--bg-press)} /* a control already on --bg-active */
+/* data-ink — a text-only control (inactive tab, legend item, clear ×, copy): the ink steps to --text-heading.
+   data-check — a checkbox label: the empty box's border steps to --text-muted, like Radio.
+   data-link — an inline action link: underline appears, or thickens if it is already drawn.
+   data-thumb — a slider track: the thumb picks up the focus-ring halo.
+   Switch tracks carry their colour in --sw-track; hover mixes it one step toward the ink colour,
+   which darkens in light mode and lightens in dark. */
+[data-row]{--row-wash:initial}
+[data-row]:hover{--row-wash:var(--bg-inset)}
+[data-ink]{--ink:initial;--ink-op:initial}
+[data-ink]:hover:not(:disabled){--ink:var(--text-heading);--ink-op:1}
+[data-check]{--check-border:initial}
+[data-check]:hover{--check-border:var(--text-muted)}
+[data-link]{--link-line:initial;--link-thick:initial}
+[data-link]:hover{--link-line:underline;--link-thick:2px}
+[data-thumb]{--thumb-ring:initial}
+[data-thumb]:hover{--thumb-ring:0 0 0 4px var(--focus-ring),0 1px 2px rgba(0,0,0,.15)}
+[role="switch"]:not([aria-disabled="true"]):not([aria-busy="true"]):hover,
+[data-sw]:hover>[role="switch"]:not([aria-disabled="true"]):not([aria-busy="true"]){--sw-bg:color-mix(in srgb,var(--sw-track) 86%,var(--text-primary))}