OpenBot UI 设计系统完全指南:Kobalte + Lucide 组件规范与 Token 体系

原创2026-10-30 14:18:171,757 阅读
文章标签:桌面应用AI Agent人工智能多智能体代码智能体浏览器控制本地部署MCP 服务

OpenBot UI 设计系统完全指南:Kobalte + Lucide 组件规范与 Token 体系

OpenBot 是一个本地优先(local-first)的桌面工作台,用于管理 Codex、Claude、Grok 等 AI 队友。它的界面之所以看起来统一、克制且一致,靠的是一套严谨的 UI 设计系统:以 Kobalte 作为无头行为引擎、Lucide 作为统一图标库,再用一份"唯一事实来源"的 CSS Token 体系贯穿桌面端、Web 端与移动端。本文面向新手开发者,带你快速读懂 OpenBot 的组件库规范与 Token 设计,看完即可安全地在项目中扩展界面。

OpenBot 深色主题对话线程界面:左侧为频道列表与成员徽章,右侧为 AI 队友生成的任务计划表格

为什么要先有设计系统

大型桌面应用如果让每个功能各自写颜色和间距,几个月后就会出现"同一个按钮三种圆角"的灾难。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 定时任务界面:右侧显示执行时间设置与 Run history 执行历史,左侧为消息气泡与已调用的 routine 列表

组件库 @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。这带来两个直接好处:

  1. 可无痛升级:版本锁死在 @kobalte/core@2.0.0-alpha.0(见根目录 package.json),上游结构怎么变,功能代码不用动;
  2. 焦点行为可修补:集中补丁全部收口在 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

给想贡献代码的新手一份最短路径:

  1. 先读规范:docs/ui-foundation.md 与 packages/ui/README.md,30 分钟建立全局观;
  2. 找参考实现:所有基础组件都在 packages/ui/src/,样式在 packages/ui/src/styles/primitives.css——复制"写法"而不是复制"值";
  3. 只用 Token:颜色写 var(--openbot-*),字号/圆角/时长同样查 Token;
  4. 交互组件走 @openbot/ui:需要弹窗、菜单、下拉?导入现成适配器,不要碰 @kobalte/core;
  5. 本地验证: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 唯一源 + 无头库封装 + 机器检查"的组合,是一份非常值得参考的工程化范本。

登录后查看全文
openbot