holaOS 共享 UI 库 @holaboss/ui 实战指南:为 Agent 构建的应用统一视觉层的 Primitives、布局与 CSS 设计令牌
holaOS 共享 UI 库 @holaboss/ui 实战指南:为 Agent 构建的应用统一视觉层的 Primitives、布局与 CSS 设计令牌
holaOS 以"让企业自行构建 agentic workspace"为核心,其中由 Agent(而非人手)搭建的应用仪表盘往往风格各异,容易产生"dashboard drift"(仪表盘视觉漂移)。@holaboss/ui 正是为解决这一问题而设计的共享 UI 库:它以 shadcn 风格的基础组件(primitives)为骨架、以设计令牌(tokens)统一颜色与圆角,再补上页面外壳(page chrome)、空态、加载骨架、数据表密度等组合层,让工作区里每个由 Agent 构建的仪表盘都像出自同一个产品。读完本文,你将掌握该库的安装与样式挂载方式、Primitives 与布局组件的完整清单、最小可运行示例、设计令牌体系,以及面向 npm 的发布与版本管理流程。
一、背景与定位:为什么 holaOS 需要一个共享 UI 层
@holaboss/ui 在仓库中的定位,可以从 packages/ui/package.json 的 description 看出端倪:"Shared UI library for holaOS — primitives, layouts, and tokens used by app-builder-sdk dashboards"(holaOS 共享 UI 库,由 app-builder-sdk 仪表盘使用的 primitives、布局与令牌)。
README 给出了其设计动因:设计令牌(tokens)已经让颜色(colors)和圆角(radii)跨应用保持同步,但仅有令牌还不够——本库补上的是组合层(composition layer):页面 chrome、空态(empty states)、加载骨架(loading skeletons)、数据表密度(data-table density)等。其核心目标是"visual consistency across agent-built apps":让 Agent 在 workspace 里搭建的每个仪表盘,看起来都属于同一个产品。
在仓库中,该库的消费方主要是 packages/app-builder-sdk 的参考应用(reference dashboards),例如 content-calendar 参考应用在其 README.md 中明确写道:"No second component library. Everything from @holaboss/ui"(不引入第二套组件库,一切组件都来自 @holaboss/ui)。
二、安装与依赖
@holaboss/ui 以独立 npm 包形式分发,支持三大主流包管理器:
bun add @holaboss/ui
# 或:npm install @holaboss/ui
# 或:pnpm add @holaboss/ui
Peer 依赖:react ^19、react-dom ^19——要求消费应用运行在 React 19 上。从 package.json 看,包的运行依赖(dependencies)包括:
@base-ui/react ^1.3.0—— 无头组件基础层,所有 primitives 构建于其上;class-variance-authority、clsx、tailwind-merge—— 变体管理与类名合并;lucide-react—— 图标;cmdk、input-otp、date-fns、react-day-picker、embla-carousel-react、react-resizable-panels、recharts、sonner、vaul、next-themes—— 支撑 Command、InputOTP、日历、轮播、可调整面板、图表、Toast 抽屉、主题等扩展组件。
三、样式挂载:一条 import 覆盖全部
在应用根部(例如 routes/__root.tsx)只需一行:
import "@holaboss/ui/styles.css";
这一条 import 即涵盖三件事:设计令牌(design tokens)、默认主题(default theme),以及库内 primitives 与布局组件用到的每一个 Tailwind 工具类。这些工具类在构建期已由 Tailwind CLI 预编译进 styles.css,因此消费应用不需要把 @holaboss/ui 加入自己的 Tailwind @source 列表。
如果只想引入原始令牌、不要内置的工具类集合,逃生舱写法是:
import "@holaboss/ui/tokens.css";
import "@holaboss/ui/themes/holaos.css";
但 README 明确推荐单一 styles.css 导入路径。
源码佐证(构建机制):packages/ui/tsdown.config.ts 的 build:done hook 做了两件事——先把 src/tokens/tokens.css 与 src/tokens/themes/holaos.css 原样复制到 dist/(对应 tokens.css 与 themes/holaos.css 两个导出入口),再执行 bunx @tailwindcss/cli 将 src/styles.css 编译为单个 dist/styles.css。也就是说"预编译好的工具类"确实在发布包里。
而 src/styles.css 顶部即:
@import "tailwindcss";
@source "./primitives";
@source "./layouts";
@import "./tokens/tokens.css";
@import "./tokens/themes/holaos.css";
@source 指令让 Tailwind 扫描本包自己的源码,从而在构建时产出 primitives/layouts 实际用到的全部工具类。package.json 的 exports 字段也印证了这四个入口:.(JS + 类型)、./styles.css、./tokens.css、./themes/holaos.css。
两个值得注意的样式层细节(来自 styles.css 源码注释):
border默认色修复:Tailwind v4 把裸border工具类的默认颜色从 v3 的固定灰改成了currentColor,导致按 v3 习惯写<div class="border">会出现近黑色发丝线。该库在@layer utilities中把默认边框色重置为--border令牌,同时利用 utilities 是级联最后一层的特性,避免与各应用自身重复引入的 preflight 冲突。- 行内字体粗细上限:针对 Agent 偶尔写
style={{ fontWeight: 700 }}等行内样式的情况,styles.css 用属性选择器把这些声明钳制到 530,防止任何内容渲染得比设计系统允许的加粗档位更粗。
四、Primitives:锁定 holaOS 规范的 shadcn 风格组件
Primitives 是"开箱即用"的 shadcn 风格组件,构建在 @base-ui/react 之上,样式与 holaOS 桌面端的规范风格完全一致。README 列出的核心清单:
Alert · Badge · Button · Card(含 CardHeader/Title/Description/Content/Footer/Action)· DropdownMenu 家族 · EmptyState · Input · Kbd · Label · Popover 家族 · Select 家族 · StatusDot · Switch · Tabs 家族 · Tooltip 家族
源码佐证(导出结构):packages/ui/src/index.ts 是包的唯一入口(tsdown 以 src/index.ts 为 entry),它显式命名导出了上述组件,并用 export * 展开完整的 shadcn(base-ui)目录——包括 accordion、alert-dialog、avatar、breadcrumb、calendar、carousel、chart、checkbox、dialog、drawer、field、menubar、navigation-menu、pagination、resizable、sidebar、skeleton、sonner、table 等 50+ 个组件文件(见 packages/ui/src/primitives 目录)。
值得注意的两个设计决策:
ScrollArea被有意省略:源码注释说明,按设计策略改用原生overflow-y-auto,不引入滚动区域组件;- 上游同步策略:
export *使每个组件的具名导出清单与源文件保持规范一致,shadcn 上游新增子组件时能自动落到包里。
五、Layouts:解决仪表盘漂移的组合层
Layouts 是 README 强调的"真正解决 dashboard-drift 问题的组合层"——与其每个仪表盘手搓相似结构,不如直接使用这些组合原语:
| 组件 | 职责 |
|---|---|
DashboardShell |
吸顶头部(sticky-header)chrome + 可滚动内容区 |
PageHeader |
标题 + 描述 + 操作按钮行 |
Section |
标题 + 描述,包住一块内容 |
FilterBar |
搜索输入 + 筛选 chip 插槽 + 操作区 |
DataTable |
类型化列、可选行点击、内置加载与空态 |
StatPill |
小型指标(label + value + tone + 可选趋势/图标) |
LoadingState |
骨架屏变体:rows / list / card |
ErrorState |
错误展示,可带重试按钮 |
源码状态说明:以当前仓库快照为准,packages/ui/src 下直接可见的实现以 primitives/、tokens/ 与 lib/utils.ts 为主(README 所描述的布局组件属于该包规划的组成层,使用方式以文档为准);styles.css 中 @source "./layouts" 的声明表明构建流程已为布局源码预留扫描入口。hack 时请以发布到 npm 的实际包形态为准。
六、工具函数:cn()
cn(...inputs) 用 clsx + tailwind-merge 实现类名合并,是组合组件类名的标准工具。实现非常精简(packages/ui/src/lib/utils.ts):
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
tailwind-merge 保证后传入的 Tailwind 类能覆盖前者的冲突类(如同一个元素同时出现 p-2 与 p-4 时取后者),这是构建可覆写样式组件的关键。
七、最小示例:一个完整的 Issues 仪表盘
README 提供了一个可直接复制的完整示例,把 DashboardShell、PageHeader、FilterBar、Section、StatPill、DataTable、Badge、Button 串起来,是理解该库组合方式的最佳起点:
import {
Badge,
Button,
DashboardShell,
DataTable,
FilterBar,
PageHeader,
Section,
StatPill,
type DataTableColumn,
} from "@holaboss/ui";
const columns: DataTableColumn<Issue>[] = [
{ id: "title", header: "Title", cell: (row) => row.title },
{ id: "status", header: "Status", width: "120px", cell: (row) => <Badge>{row.status}</Badge> },
];
export default function Dashboard() {
return (
<DashboardShell
header={
<>
<PageHeader
title="Issues"
description="GitHub issues synced into the workspace"
actions={<Button size="sm">Refresh</Button>}
/>
<FilterBar search={search} onSearchChange={setSearch} />
</>
}
>
<Section title="Overview">
<div className="grid grid-cols-3 gap-3">
<StatPill label="Open" value={open} tone="positive" />
<StatPill label="In progress" value={inProgress} />
<StatPill label="Closed" value={closed} />
</div>
</Section>
<Section title="Issues">
<DataTable
columns={columns}
rows={rows}
rowKey={(r) => String(r.id)}
isLoading={isLoading}
emptyTitle="No issues yet"
/>
</Section>
</DashboardShell>
);
}
几个要点:
DataTableColumn<T>是类型化列定义:id用于标识列、header是表头文本、width可指定列宽(如"120px")、cell是渲染函数;StatPill的tone支持语义色调(如positive),value直接渲染指标数字;DataTable的isLoading与emptyTitle是内置的加载/空态,无需额外手写骨架屏;DashboardShell的header插槽承载页面头部与筛选栏,内容区自动可滚动。
八、设计令牌体系:视觉一致性的地基
"Tokens already keep colors and radii in sync"是 README 的一句关键表述,而令牌的具体内容集中在 packages/ui/src/tokens/tokens.css。这份文件是"一切视觉的单一事实来源",通过 Tailwind v4 的 @theme inline 把 CSS 变量映射成工具类(如 bg-background、text-foreground、bg-primary),并定义了:
- 字体:
--font-sans: "Inter Variable"、--font-mono: "Geist Mono Variable"等; - 圆角阶梯:以 8px 为基准(
--radius: 0.5rem),派生sm(4px)到4xl(20px),并注明"按钮/菜单项用 6px、卡片/输入框用 8px、popover 用 10px"; - 字重策略:整体比 Tailwind 默认轻约 25~40,且
semibold及更重档位全部钳制到 530,防止"vibe-coded"应用渲染出过重的字; - 紧凑字号阶梯:比 Tailwind 默认密约 10~20%(
--text-base: 0.875rem等); - 分层阴影:
--shadow-2xs到--shadow-2xl,其中sm是 Linear/Stripe 风格的多层堆叠,深色模式通过--hairline-alpha/--shadow-alpha反转极性(见.dark规则); - 语义 z-index:sticky 100 / chrome 200 / panel 300 / popover 500 / tooltip 600 / modal 700 / overlay 800 / toast 900 / splash 1000;
- 动效令牌:
--duration-fast: 120ms到--duration-slow: 360ms,以及--ease-standard、--ease-emphasized等缓动曲线与两个入场动画; @property注册:将--background、--foreground、--primary等注册为可插值颜色,使主题切换时整块画布平滑过渡而非硬切;- 前景混合阶梯:
--fg-2到--fg-92用color-mix把前景色按百分比混合进背景,配合bg-fg-3这类工具类实现"前景染色表面"。
主题文件 packages/ui/src/tokens/themes/holaos.css 则通过 [data-theme="*"] 属性覆盖 --background、--foreground、--primary 等核心变量——这正是"主题是 workspace 级别"这一设计边界的实现机制。
九、边界:这个库不是什么
README 用一节专门划清边界,值得所有接入方先读:
- 不是 Tailwind 的替代品:库期望消费应用自带 Tailwind(令牌编译在 Tailwind 的 CSS 变量层之上);
- 不是主题系统:主题是 workspace 级别的,单个应用不做主题切换;
- 不是"原版 shadcn"直发:primitives 被锁定到 holaOS 规范版本——如果 shadcn 上游变化,是
@holaboss/ui这个包先更新,而不是每个消费应用各自跟进。
十、发布与版本管理
@holaboss/ui 虽住在 holaOS monorepo 的 packages/ui 下,但作为独立 npm 包发布,发布走仓库共享的 publish-sdk.yml 工作流。
一次性环境设置
GitHub 仓库 → Settings → Environments → npm-publish → Environment secrets:
NPM_TOKEN—— 对@holaboss/*具备 read+write 权限的 npm Granular Access Token;- 可选:开启 Required reviewers,让每次发布在任务继续前需人工审批。
基于 tag 的常规发布(推荐)
# 1. 提升版本
cd sdk/ui
# 编辑 package.json:"version": "0.1.x" → "0.1.x+1"
# (或 `npm version patch | minor | major` 自动提升并写回)
# 2. 提交并推送到发布分支
cd ../..
git add sdk/ui/package.json
git commit -m "release(ui): bump @holaboss/ui to 0.1.x+1"
git push
# 3. 给刚推送的提交打 tag 并推送
git tag @holaboss/ui@0.1.x+1
git push upstream @holaboss/ui@0.1.x+1
tag 命名是 monorepo 约定:Git tag 是仓库级的,因此包名被写进 tag 字符串(@holaboss/ui@版本号)。工作流按 @holaboss/ui@* tag 过滤,validate 任务从 tag 中解析出包名与版本号。
CI 随后执行如下流水线:
validate (~5s)
├─ 从 tag 解析 package=ui, version=0.1.x+1
└─ 校验 sdk/ui/package.json 版本与 tag 一致
test (~30s)
└─ bun install + bun run test (tsc --noEmit)
build (~1min)
├─ bun run build(tsdown + Tailwind CLI 产出 dist/styles.css)
├─ 校验 package.json exports 中每个路径都存在于 dist/
└─ npm pack --dry-run(预览 tarball 内容)
publish (~10s,可能因环境审批暂停)
└─ npm publish --access public --provenance
--provenance 标志借助 GitHub Actions OIDC 生成可验证的 npm provenance 声明——对应版本在 npm 页面上会显示"Built and signed on GitHub Actions"徽章并链接到工作流运行记录。
手动触发(workflow_dispatch)
适用于发布前干跑,或 npm 仓库异常时重试。GitHub 仓库 → Actions → Publish SDK → Run workflow:
| 输入项 | 值 |
|---|---|
| Package to publish | ui |
| Dry run | ☐ 不勾选 = 真实发布 · ☑ 勾选 = 仅 npm pack --dry-run |
dry-run 路径会与真实发布一样执行 validate / test / build,但跳过最终 npm publish。新分支首次发布或配置有较大改动后,建议先走一次 dry-run。
本地发布(逃生通道)
仅当 CI 不可用时使用。注意:本地发布不会生成 provenance(npm 要求 OIDC,只能在受支持的 CI 环境工作):
cd sdk/ui
npm publish --access public
# 按提示输入 2FA OTP
本地发布不会自动产生 Git tag,完成后记得手动打 tag 并推送,保持 CI 历史一致。
SemVer 策略
| 变更 | 版本提升 |
|---|---|
| 新增 primitive / 新增 layout / 新增可选 prop | minor(0.x.y → 0.x+1.0) |
| 令牌默认值微调 / 样式修复 / bug 修复 | patch(0.x.y → 0.x.y+1) |
| 移除 prop / 重命名导出 / 移除 primitive | major(0.x.y → 1.0.0) |
在 1.0.0 之前,0.x 版本允许携带破坏性变更——但一旦发生,应提升到新的 minor(如 0.1.x → 0.2.0)。
常见问题排查
code EUSAGE: Automatic provenance generation not supported for provider: null—— 在本地运行npm publish且publishConfig中设置了provenance: true。provenance 只在受支持的 CI 环境生效。本包已在publishConfig中移除该字段(CI 通过 CLI 标志传--provenance),可执行npm publish --provenance=false规避;404 Not Found - PUT https://registry.npmjs.org/@holaboss/ui——@holabossscope 在 npm 上不存在,或 token 缺少写入权限;- 首次发布新包时
403 Forbidden—— scoped 包默认私有,首次发布需要--access public(已写入本包publishConfig与工作流); - Tag 指向错误的 commit / 版本号错误 —— 删除并重建 tag:
若 CI 已经发布过该版本,npm 上无法撤下同一版本,应提升版本发布新的 patch。git tag -d @holaboss/ui@0.1.x git push upstream :refs/tags/@holaboss/ui@0.1.x # 然后给正确的 commit 重新打 tag 并推送
十一、真实消费示例:content-calendar 参考应用
要观察该库在真实 app-builder-sdk 仪表盘中的用法,content-calendar 参考应用是最直接的样本(packages/app-builder-sdk/reference/content-calendar):
- 其 README.md 明确"一切组件来自
@holaboss/ui"; - playground/package.json 以
"@holaboss/ui": "workspace:*"方式在 monorepo 内引用; - playground/src/main.tsx 入口即
import "@holaboss/ui/styles.css"; - playground/vite.config.ts 在 Vite 预构建/别名层对
@holaboss/ui及其styles.css做了显式映射——这说明消费端工程化配置中需要让打包器正确解析该包的 CSS 子路径导出。
结语
@holaboss/ui 的核心理念可以概括为一句话:让 Agent 写的 UI 与产品团队定的规范一致。设计令牌统一了色彩、圆角、字重、阴影与动效的底层语义;primitives 提供了锁定 holaOS 规范的交互组件;布局组件(按 README 规划)则解决仪表盘最容易漂移的页面结构问题;而"预编译样式 + 单条 import"的交付方式,让 Agent 生成的应用无需维护任何 Tailwind 配置即可获得完整外观。对希望在企业工作区里产出风格统一、可直接上线仪表盘的开发者和 Agent 而言,这是一套低接入成本、高一致收益的共享 UI 方案。本包以 Apache-2.0 协议开源,详见仓库根目录 LICENSE。