holaOS 共享 UI 库 @holaboss/ui 实战指南:为 Agent 构建的应用统一视觉层的 Primitives、布局与 CSS 设计令牌

原创2026-10-02 10:53:421,935 阅读
文章标签:AI AgentAgent 框架AI 应用人工智能桌面应用MCP 服务本地部署多智能体前端工作流自动化插件系统AI 技能

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 源码注释):

  1. border 默认色修复:Tailwind v4 把裸 border 工具类的默认颜色从 v3 的固定灰改成了 currentColor,导致按 v3 习惯写 <div class="border"> 会出现近黑色发丝线。该库在 @layer utilities 中把默认边框色重置为 --border 令牌,同时利用 utilities 是级联最后一层的特性,避免与各应用自身重复引入的 preflight 冲突。
  2. 行内字体粗细上限:针对 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 —— @holaboss scope 在 npm 上不存在,或 token 缺少写入权限;
  • 首次发布新包时 403 Forbidden —— scoped 包默认私有,首次发布需要 --access public(已写入本包 publishConfig 与工作流);
  • Tag 指向错误的 commit / 版本号错误 —— 删除并重建 tag:
    git tag -d @holaboss/ui@0.1.x
    git push upstream :refs/tags/@holaboss/ui@0.1.x
    # 然后给正确的 commit 重新打 tag 并推送
    
    若 CI 已经发布过该版本,npm 上无法撤下同一版本,应提升版本发布新的 patch。

十一、真实消费示例: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。

登录后查看全文
holaOS