@keyfunc/keybricks-ds 1.0.4 → 2.1.1

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))}

package/tokens/interaction.css

@@ -1,5 +1,5 @@
 /* ── Universal interaction layer ──
-   Rest, hover and selected states live in each component's own styles.
+   Rest, hover and selected states live in each component's own styles; field boxes and segments read the hover hooks below.
    Press and keyboard focus are delivered here so EVERY control carries them
    uniformly: `filter` and `outline` are never set inline, so these rules
    compose on top of whatever background a component is showing at the time.
@@ -30,6 +30,8 @@ summary:active,
 [role="treeitem"]:active,
 [role="gridcell"]:active{filter:var(--press-filter)}
 
+/* Hover hooks live in tokens/hover.css (state signals, not tokens). */
+
 /* Keyboard focus — visible on :focus-visible only, so a mouse click never draws it.
    `outline` is used (not box-shadow) so component shadows stay intact. */
 button:focus-visible,

package/tokens/layout.css

@@ -1,9 +1,9 @@
-/* Keybricks spacing / radii / borders / shadows / chrome sizes */
+/* Keybricks spacing / radii / borders / shadows / chrome sizes / size tiers */
 :root{
-/* Radii */
---radius-sm:4px;   /* steppers, dropdown selects, small toggles, checkbox */
---radius-md:8px;   /* buttons, inputs, nav items, chips, 32px icon tiles */
---radius-lg:10px;  /* cards, dropzone, large buttons, search fields */
+/* Radii — picked by element type, identical at every size tier */
+--radius-sm:4px;   /* checkbox, small toggles */
+--radius-md:8px;   /* buttons, inputs, selects, search, steppers, segmented controls, pagination items, nav items, chips, 32px icon tiles */
+--radius-lg:10px;  /* cards, dropzone, menus */
 --radius-tile:14px;/* 40px palette icon tiles */
 --radius-node:16px;/* canvas node cards + their 48px icon tiles */
 --radius-full:9999px;
@@ -16,8 +16,26 @@
 --ring-focus:0 0 0 2px var(--bg-surface),0 0 0 4px var(--focus-border);
 /* Chrome sizes */
 --sidebar-w:240px;--rail-w:64px;--topbar-h:56px;--panel-w:400px;--drawer-h:250px;
-/* Control heights */
---h-button:32px;--h-button-sm:30px;--h-input:36px;--h-nav-item:35.5px;--h-subnav-item:31.5px;--h-tree-item:30px;
+--h-nav-item:36px;--h-subnav-item:32px;--h-tree-item:32px;
+/* Size tiers — one scale that every control reads. A region (app root, toolbar, filter bar, form, table,
+   dialog, drawer) declares data-size="sm" | "md" | "lg"; everything inside inherits these values, so controls
+   that share a row can never disagree. md is the default; the rules below the :root block switch the tier.
+   sm 24 · md 32 · lg 36 for controls; bars and rows are 8px taller; a bar inside a bordered card 16px taller. */
+--control-h:32px;                                                                         /* buttons, inputs, selects, search, steppers, segmented controls, chips, pagination items */
+--control-text:var(--text-base);--control-leading:var(--leading-base);--control-tracking:var(--tracking-base); /* text inside controls and their labels */
+--control-icon:16px;                                                                      /* icon inside a control */
+--control-px:12px;                                                                        /* horizontal padding inside a text control or button */
+--control-gap:8px;                                                                        /* gap inside one group: label → its control, button → button */
+--group-gap:16px;                                                                         /* gap between groups in one bar: field → next field */
+--bar-h:40px;                                                                             /* toolbar, filter bar, tab bar, table row, list row */
+--bar-card-h:48px;                                                                        /* a bar inside a bordered card (table toolbar, pagination): keeps 8px from the card edge */
+--edge-pad:16px;                                                                          /* card edge → first control or cell */
+--cell-px:12px;                                                                           /* horizontal padding of a table cell */
+--check-size:16px;                                                                        /* checkbox and radio box */
+--tag-h:24px;                                                                             /* Tag */
+--switch-w:36px;--switch-h:20px;                                                          /* Switch track */
+/* Compatibility aliases — superseded by the tier tokens above */
+--h-button:var(--control-h);--h-input:var(--control-h);--h-button-sm:24px;
 /* Page rhythm */
 --page-pad-y:24px;--page-pad-x:32px;--section-gap:24px;--card-pad:21px;--card-pad-sm:17px;
 /* Stacking */
@@ -28,3 +46,7 @@
 --z-toast:80; /* @kind other */
 --z-tooltip:100; /* @kind other */
 }
+/* The three tiers. Declared after :root so a tier set on <html> itself also wins. */
+[data-size="sm"]{--control-h:24px;--control-text:var(--text-xs);--control-leading:var(--leading-xs);--control-tracking:var(--tracking-xs);--control-icon:14px;--control-px:8px;--control-gap:8px;--group-gap:12px;--bar-h:32px;--bar-card-h:40px;--edge-pad:12px;--cell-px:8px;--check-size:14px;--tag-h:20px;--switch-w:28px;--switch-h:16px}
+[data-size="md"]{--control-h:32px;--control-text:var(--text-base);--control-leading:var(--leading-base);--control-tracking:var(--tracking-base);--control-icon:16px;--control-px:12px;--control-gap:8px;--group-gap:16px;--bar-h:40px;--bar-card-h:48px;--edge-pad:16px;--cell-px:12px;--check-size:16px;--tag-h:24px;--switch-w:36px;--switch-h:20px}
+[data-size="lg"]{--control-h:36px;--control-text:var(--text-base);--control-leading:var(--leading-base);--control-tracking:var(--tracking-base);--control-icon:16px;--control-px:16px;--control-gap:8px;--group-gap:24px;--bar-h:44px;--bar-card-h:52px;--edge-pad:16px;--cell-px:16px;--check-size:16px;--tag-h:28px;--switch-w:44px;--switch-h:24px}

package/tokens/tokens.d.ts

@@ -18,6 +18,8 @@ export type TokenName =
   | "--amber-800"
   | "--amber-900"
   | "--amber-950"
+  | "--bar-card-h"
+  | "--bar-h"
   | "--bg-active"
   | "--bg-app"
   | "--bg-hover"
@@ -26,6 +28,7 @@ export type TokenName =
   | "--bg-raised"
   | "--bg-scrim"
   | "--bg-surface"
+  | "--bg-table-header"
   | "--blue-100"
   | "--blue-200"
   | "--blue-300"
@@ -58,6 +61,7 @@ export type TokenName =
   | "--cat-source-bg"
   | "--cat-transform"
   | "--cat-transform-bg"
+  | "--cell-px"
   | "--chart-area-alpha"
   | "--chart-axis"
   | "--chart-blue"
@@ -74,7 +78,15 @@ export type TokenName =
   | "--chart-pos"
   | "--chart-total"
   | "--chart-track"
+  | "--check-size"
   | "--checkbox-border"
+  | "--control-gap"
+  | "--control-h"
+  | "--control-icon"
+  | "--control-leading"
+  | "--control-px"
+  | "--control-text"
+  | "--control-tracking"
   | "--cyan-100"
   | "--cyan-200"
   | "--cyan-300"
@@ -90,6 +102,7 @@ export type TokenName =
   | "--danger-active"
   | "--danger-bg"
   | "--danger-soft-active"
+  | "--danger-soft-hover"
   | "--danger-text"
   | "--dot-neutral"
   | "--drawer-h"
@@ -104,6 +117,7 @@ export type TokenName =
   | "--ease-in-out"
   | "--ease-out"
   | "--edge"
+  | "--edge-pad"
   | "--emerald-100"
   | "--emerald-200"
   | "--emerald-300"
@@ -119,6 +133,7 @@ export type TokenName =
   | "--focus-ring"
   | "--font-mono"
   | "--font-sans"
+  | "--group-gap"
   | "--h-button"
   | "--h-button-sm"
   | "--h-input"
@@ -273,8 +288,11 @@ export type TokenName =
   | "--success-bg"
   | "--success-strong"
   | "--success-text"
+  | "--switch-h"
+  | "--switch-w"
   | "--t-hover"
   | "--t-theme"
+  | "--tag-h"
   | "--teal-100"
   | "--teal-200"
   | "--teal-300"
@@ -353,6 +371,8 @@ export type TokenKey =
   | "amber800"
   | "amber900"
   | "amber950"
+  | "barCardH"
+  | "barH"
   | "bgActive"
   | "bgApp"
   | "bgHover"
@@ -361,6 +381,7 @@ export type TokenKey =
   | "bgRaised"
   | "bgScrim"
   | "bgSurface"
+  | "bgTableHeader"
   | "blue100"
   | "blue200"
   | "blue300"
@@ -393,6 +414,7 @@ export type TokenKey =
   | "catSourceBg"
   | "catTransform"
   | "catTransformBg"
+  | "cellPx"
   | "chartAreaAlpha"
   | "chartAxis"
   | "chartBlue"
@@ -409,7 +431,15 @@ export type TokenKey =
   | "chartPos"
   | "chartTotal"
   | "chartTrack"
+  | "checkSize"
   | "checkboxBorder"
+  | "controlGap"
+  | "controlH"
+  | "controlIcon"
+  | "controlLeading"
+  | "controlPx"
+  | "controlText"
+  | "controlTracking"
   | "cyan100"
   | "cyan200"
   | "cyan300"
@@ -425,6 +455,7 @@ export type TokenKey =
   | "dangerActive"
   | "dangerBg"
   | "dangerSoftActive"
+  | "dangerSoftHover"
   | "dangerText"
   | "dotNeutral"
   | "drawerH"
@@ -439,6 +470,7 @@ export type TokenKey =
   | "easeInOut"
   | "easeOut"
   | "edge"
+  | "edgePad"
   | "emerald100"
   | "emerald200"
   | "emerald300"
@@ -454,6 +486,7 @@ export type TokenKey =
   | "focusRing"
   | "fontMono"
   | "fontSans"
+  | "groupGap"
   | "hButton"
   | "hButtonSm"
   | "hInput"
@@ -608,8 +641,11 @@ export type TokenKey =
   | "successBg"
   | "successStrong"
   | "successText"
+  | "switchH"
+  | "switchW"
   | "tHover"
   | "tTheme"
+  | "tagH"
   | "teal100"
   | "teal200"
   | "teal300"