OpenBot UI 设计系统完全指南:Kobalte + Lucide 组件规范与 Token 体系
OpenBot UI 设计系统完全指南:Kobalte + Lucide 组件规范与 Token 体系
OpenBot 是一个本地优先(local-first)的桌面工作台,用于管理 Codex、Claude、Grok 等 AI 队友。它的界面之所以看起来统一、克制且一致,靠的是一套严谨的 UI 设计系统:以 Kobalte 作为无头行为引擎、Lucide 作为统一图标库,再用一份"唯一事实来源"的 CSS Token 体系贯穿桌面端、Web 端与移动端。本文面向新手开发者,带你快速读懂 OpenBot 的组件库规范与 Token 设计,看完即可安全地在项目中扩展界面。
为什么要先有设计系统
大型桌面应用如果让每个功能各自写颜色和间距,几个月后就会出现"同一个按钮三种圆角"的灾难。OpenBot 的做法是三条硬规则:
| 规则 | 说明 | 落地位置 |
|---|---|---|
| Token 唯一声明处 | 所有 --openbot-* 变量只在一个文件里声明 |
tokens.css |
| 组件唯一出口 | 功能代码只能从 @openbot/ui 导入组件,禁止直接使用 Kobalte / Lucide |
packages/ui/ |
| 规范机器检查 | bun run check:ui 拦截颜色字面量、手搓弹窗/菜单等违规写法 |
ui-foundation-check.ts |
这套设计文档的完整说明见 docs/ui-foundation.md。
Token 体系:一个文件管住三端
OpenBot 的 Token 体系核心是一个文件:packages/brand/src/tokens.css。桌面渲染进程、公开 Web 应用、移动端都只 @import 它,谁也不许再声明自己的 Token——这正是该文件头注释里强调的"唯一声明处(the only declaration site)"。
颜色:语义化命名,而不是裸色值
Token 按"用途"命名,而不是按"色相"命名。举几个典型例子:
--openbot-bg-canvas: #1a1a1a; /* 主画布 */
--openbot-bg-surface: #212121; /* 卡片表面 */
--openbot-text-muted: #979797; /* 弱化文字 */
--openbot-accent: #007cf7; /* 强调色,色相 210 刻意对齐参考 UI */
--openbot-danger: #fd2f3b; /* 全产品只有一种红 */
值得注意的是文件里那些"考古式"注释:比如 danger 颜色曾存在 4 个近似红色家族,最终统一为单一 --openbot-danger 加五个"角色变体"(实心、hover、浅色填充、ring、border);绿色 --openbot-success 则经过 OKLCH 明度/饱和度测算,把色彩饱和度控制在渲染器不会裁切的可用范围内。颜色是决策,不是随手填的值。
深浅主题:只改值,不声明
- 深色是默认值,写在 tokens.css;
- 浅色主题 tokens-light.css 在根元素带
data-openbot-color-scheme="light"时生效,只改变数值、从不新增 Token; - 移动端另有 tokens-native.css 走同样的"只改值"原则。
尺寸 Token:紧凑的控件比例尺
OpenBot 采用一套非常克制的控件尺寸:--openbot-control-xs 24px(辅助元素)、sm 28px(工具栏)、md 32px(标准)、lg 36px(重要操作)。文字字号只有六级(12/13/14/16/18/24px),圆角、间距、动画时长、阴影、z-index 层叠(--openbot-layer-dropdown → tooltip 240)全部 Token 化。这样任何一处 UI 的视觉参数都"有据可查",且被检查脚本强制约束。
组件库 @openbot/ui:一实现,三端复用
packages/ui/ 是内部 SolidJS 组件库,桌面端、公开 Web 端、Storybook 共用同一份实现,通过 index.ts 统一导出。它的定位很清晰:独立于应用上下文(不碰 Electron、存储、鉴权、网络客户端),数据与回调一律走类型化 props。
公开 API 速查
| 组件 | 用途 | 选用建议 |
|---|---|---|
Button / IconButton |
有标签的操作 / 纯图标操作 | 一个上下文里只保留一个 default 主按钮;ghost 用于工具栏 |
Badge |
短状态与分类标签 | 不要拿它当按钮用 |
Input / Textarea / NativeSelect |
统一解剖结构的原生控件 | 包一层 Field 自动接上 label、错误、aria-describedby |
Switch |
即时生效的二进制设置 | 需要"提交表单才生效"的选择请用 Checkbox 或 RadioGroup |
Card / Separator / Spinner / Skeleton |
表面、结构与加载反馈 | 进行中的持续反馈用 Spinner / Skeleton |
Dialog / AlertDialog / DropdownMenu / Tabs 等 |
复杂交互 | 不可逆确认必须用 AlertDialog;轻提示用 Tooltip 或 Popover |
以 Button 为例(源码 button.tsx),它用 class-variance-authority(cva)声明变体,而不是手写一堆条件 class:
const buttonVariants = cva("ui-button", {
variants: {
variant: {
default: "ui-button-variant-default",
secondary: "ui-button-variant-secondary",
ghost: "ui-button-variant-ghost",
destructive: "ui-button-variant-destructive",
link: "ui-button-variant-link",
// …
},
size: { default: "…", icon: "…", "icon-lg": "…" },
},
});
变体名只是 class 映射,真正的视觉全部落在 primitives.css 的 .ui-button-* 规则里,且只使用 Token 变量——样式与行为分离,改主题不改组件。
Kobalte:行为引擎,而非公开 API
这是 OpenBot 设计系统里最关键的一条架构决策:Kobalte 是被禁止直接导入的。
docs/ui-foundation.md 明确写道:"Kobalte is a behaviour engine, not the application's public API(Kobalte 是行为引擎,不是应用的公开 API)"。功能层想做一个弹窗?导入 @openbot/ui 导出的 Dialog,而不是 @kobalte/core/dialog。这带来两个直接好处:
- 可无痛升级:版本锁死在
@kobalte/core@2.0.0-alpha.0(见根目录 package.json),上游结构怎么变,功能代码不用动; - 焦点行为可修补:集中补丁全部收口在 complex.tsx 这一组"精选适配器"里。
complex.tsx 里最有代表性的补丁是焦点恢复:alpha 版 Kobalte 在 dialog / menu / popover 关闭后会丢失焦点,OpenBot 在 focusRestoreHandler 中自行记录打开前的 activeElement,关闭时经两帧 requestAnimationFrame 后安全地把焦点归还触发器——但只在"焦点确实属于该弹层"时才归还,避免打扰正在编辑 composer 的用户。这类细节正是"封装一层"的价值:上游的坑被填掉,功能层永远拿到干净的 API。
配合锁定 Kobalte 的,还有 patches/ 下由 Bun 维护的 Solid 2 RC 兼容补丁(如 @kobalte%2Fcore@2.0.0-alpha.0.patch)。文档约定:等 Kobalte 出稳定 API 后,先删补丁、再验证封装层行为不变。
Lucide:图标也走统一出口
图标同样不许裸用。全部 160+ 个 Lucide 图标经 icons.ts 统一再导出(export { default as Copy } from "lucide-solid/icons/copy"),功能代码只 import { Copy } from "@openbot/ui"。
Token 文件里还有一个和 Lucide 深度联动的细节——图标描边 Token:
/* Lucide 图标 viewBox="0 0 24 24",CSS stroke-width 按用户单位解析:
字面 1px 在 16px 尺寸下实际只画 0.67 物理像素,发虚。
1.5 用户单位才是设计稿要的"1px"。 */
--openbot-icon-stroke: 1.5;
这条注释揭示了团队对细节的执着:描边粗细直接由 SVG viewBox 的坐标比例决定,写错 0.5 整个产品图标就会集体变糊。图标尺寸同样是六级 Token(--openbot-icon-xs 12px 到 lg 20px)。而 Logo、头像、产品插画则刻意留在 OpenBot 自己的品牌资产里(packages/brand/src/ 中的 AppLogo、ProviderLogo 等),不混入 Lucide。
机器检查:规范不是贴在墙上的
再好的规范也需要"强制执行器"。OpenBot 的答案是 bun run check:ui(脚本 scripts/ui-foundation-check.ts),它扫描渲染进程的全部样式表与 TSX 内联声明,拦截:
- 🚫 原生
<button>/<input type="switch">绕过组件库; - 🚫 手搓的 dialog / menu / tabs / listbox(复合 ARIA role 只能来自 UI 层);
- 🚫 UI 层之外直接
import "@kobalte/core"或lucide-solid; - 🚫 颜色字面量——全仓库唯一允许写死颜色的地方就是 tokens.css;
- 🚫 未 Token 化的字号、圆角、过渡时长。
所有"迁移预算"都是零,连 data-testid 也不例外。这意味着规范不是靠 Code Review 的自觉,而是 CI 层面的硬门禁。
如何上手扩展 OpenBot 的 UI
给想贡献代码的新手一份最短路径:
- 先读规范:docs/ui-foundation.md 与 packages/ui/README.md,30 分钟建立全局观;
- 找参考实现:所有基础组件都在 packages/ui/src/,样式在 packages/ui/src/styles/primitives.css——复制"写法"而不是复制"值";
- 只用 Token:颜色写
var(--openbot-*),字号/圆角/时长同样查 Token; - 交互组件走
@openbot/ui:需要弹窗、菜单、下拉?导入现成适配器,不要碰@kobalte/core; - 本地验证:
bun run check:ui通过后再提交;孤立组件的 Storybook 故事(Foundations分组)要覆盖 default / hover / focus-visible / active / disabled 各状态,并保留 a11y 故事——无障碍是全局 Storybook 门禁(test: "error")。
小结
OpenBot 的 UI 设计系统可以浓缩成三句话:
一份 Token 文件(tokens.css)定义产品所有视觉参数,深浅主题只改值不声明;一个组件库(packages/ui/)作为唯一公开 API,把 Kobalte 行为引擎与 Lucide 图标封装在内部;一个检查脚本(ui-foundation-check.ts)把规范变成 CI 门禁。
对于正在做桌面/多端 AI 产品的团队,这套"Token 唯一源 + 无头库封装 + 机器检查"的组合,是一份非常值得参考的工程化范本。

