@keyfunc/keybricks-ds

Keybricks 设计系统

English · 中文

本文是 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"），显示为代码标签：Menlo 12px、浅灰底。配置代码用等宽字体、全大写下划线格式（"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"）统一一条规则：14px 以下比西文大一号（12 → 13，11 → 12，任何 CJK 文字都不小于 12px）；500 和 600 字重都改为 500（同样的数字，中日韩文字看起来比字母粗；sm 区域内中等字重改为 400，因为小字号加粗会让笔画粘连）；字距为 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" 对应 28 / 32 / 40px 控件、12 / 14 / 14px 控件文字（CJK 为 13 / 14 / 14）、36 / 40 / 48px 行高；区域内所有控件自动继承，可交互元素不小于 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、句首大写；金额单元格与所在行同字号、同字体，只加等宽数字（tabular figures）；配置代码用 12px 代码标签。等宽字体只用于代码。

图标系统

• 产品图标是 Lucide 线性图标集（16/14px，实际描边约 1.33px，颜色为 currentColor）。我们提供 components/icons/Icon.jsx，内嵌产品用到的每个图形的 Lucide 原始路径数据。用法：<Icon name="search" size={16}/>。
• Keybricks 自绘图标：为 Keybricks 自行绘制的 13 个图标与 Lucide 图标一起放在核心集中——AI 类（ai、ai-sparkles）、模块类（reconciliation、consolidation、journal、event、view-tree）和操作类（drilldown、add-below、copy-data、task-execution、time-future、time-restatement）。新画图标之前，先在图标库里搜索：hierarchy 其实就是 layers，change 就是 repeat。
• 绘制规范（所有核心图标，以及今后新增的图标）：24×24 网格；路径限制在 2–22 范围内，描边后四周留 1px 边距；描边 2，圆头圆角，无填充，currentColor；坐标取整数；相互独立的元素之间至少留 2px 空隙；矩形圆角 rx 2，8px 及以下的小矩形用 rx 1。新增图标前，先在 14px 和 16px 下检查。
• 图标颜色跟随文字颜色（默认框架色 #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 标签页）。
• 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）体系。