BoardUI 与 HeroUI Pro：交付机制、设计原语与 Agent 开发体验

AI 参与说明（Agent：Codex）：本文由 Codex 根据官方文档、发布记录与 HeroUI Pro MCP 整理、校验；核验日期为 2026-09-07。模型 gpt-6-astra，reasoning effort ultra；执行入口 Codex Desktop，CLI 版本 0.153.4，提供方 openai。文中的选型建议是基于交付机制与接口边界的工程判断。

本次表达修订（2026-09-07，Agent：Codex）：根据已有官方引用，以完整英文陈述交付机制，中文解释维护差异。运行记录：模型 gpt-6-astra，reasoning effort ultra，Codex Desktop，提供方 openai，CLI 0.153.4。

BoardUI adds component source files to your project; HeroUI Pro distributes components through @heroui-pro/react. BoardUI Installation、HeroUI Pro Installation

这个交付差别决定了后续从哪里修改组件：BoardUI 的实现源码由项目维护；HeroUI Pro 通常通过公开 API、组件组合与主题扩展。两种方式都能定制 UI，但升级与维护责任落在不同的位置。

当项目已经采用当前 HeroUI Pro 时，默认继续把它作为统一 UI 基础更合适。BoardUI 值得额外评估的条件，是需要直接修改组件内部实现，或某套 Agent / Dashboard 页面与目标产品高度契合。仅为了让 Agent 更会写 UI，没有必要立即引入第二套组件体系：两边都已提供 MCP 与 Skills。

本文比较 BoardUI 当前 React 方案与基于 HeroUI v3 的 @heroui-pro/react。旧版 HeroUI Pro v2 的购买权益不能直接等同新版；官方说明有单独的升级安排，具体可用范围还取决于授权和 Updates Window。HeroUI Pro Licensing

四个维度的结论

交付机制依据两边的 Installation / Install HeroUI Pro；Agent 能力依据 BoardUI MCP / HeroUI Pro MCP。

使用机制：源码进入项目，还是依赖进入项目

BoardUI 的 init 建立主题、排版、global styles 与 cx 工具；add 把指定组件及内部依赖写到项目，并安装缺少的 npm 包。业务代码引用本地模块，例如 @/components/base/buttons/button。它仍依赖 React Aria 等运行时库；“源码交付”不代表没有依赖。BoardUI Installation、Button

修改本地实现后，上游更新需要审阅差异。BoardUI 文档给出的更新方式是重新 add 并使用 --overwrite，商业许可也明确没有保证更新与用户修改无冲突。更新前应保存本地修改，再取得上游版本比较差异；--overwrite 会重新写入文件，不会自动合并本地修改。BoardUI License

HeroUI Pro CLI 则把 @heroui-pro/react 加入项目，按授权下载 artifacts，并处理 peer dependencies。应用通常从包或组件 subpath 导入；定制优先通过公开 API、CSS 与组合完成。CI 重新安装时涉及 HEROUI_AUTH_TOKEN 和 postinstall 下载，不应把本机一次登录当作 CI 已具备安装条件。HeroUI Pro Installation

包升级更新组件实现，但不会自动迁移应用已经改过的模板或页面代码。核验当天，Pro 发布页仍把 1.0.0-beta.8 列为最新组件版本；HeroUI OSS 的 v3 状态不能替代 Pro 自身的版本判断。HeroUI Pro Releases

最小接入流程

以下 Bash 命令供两个独立的、已配置 React 19 与 Tailwind CSS v4 的项目分别使用；本次仅与官方文档核对，未执行安装。BoardUI 还需配置 @/* 路径别名；HeroUI Pro 需具备相应授权并先配置 OSS。

BoardUI：

npx boardui@latest init
npx boardui@latest add button

随后按 CLI 输出将生成的 global stylesheet 接入应用入口。预期结果是项目中出现可编辑的组件、样式和工具文件。

HeroUI Pro：

npx heroui-pro@latest login
npx heroui-pro@latest install

在主 CSS 文件中按顺序加载：

@import "tailwindcss";
@import "@heroui/styles";
@import "@heroui-pro/react/css";

预期结果是项目安装 Pro 包与所需依赖，并能引用授权组件。上述接入步骤与 CSS 顺序见各自安装文档；已有项目应合并 stylesheet，避免覆盖原有样式。

组件库：比较任务覆盖与抽象层级

BoardUI 目录把基础控件与更具体的 Blocks 分开，后者包括 Composer、Agent Progress、Agent Limits、Web Search 等。HeroUI Pro 同样覆盖 AI 界面，包含 PromptInput、ChatMessage、ChatTool、ChatSource、ChainOfThought，以及 DataGrid、Sidebar、Agenda、Kanban 等业务组件。BoardUI Components、HeroUI Pro Components

从这些目录可以做出一个有边界的判断：BoardUI 的部分 Blocks 已经预设了具体产品场景，适合快速采用其交互结构；HeroUI Pro 的 AI 组件提供了较多可组合的消息、输入、工具和引用元素。两者都有基础组件与成套页面，不能绝对归类成“素材库”和“底层库”。

两个例子能更准确地体现差别：

对应依据：BoardUI Data Table、HeroUI DataGrid、HeroUI PromptInput。表格排序、编辑与虚拟化的实际表现仍应在相同数据集上验证；这里没有据组件名称做性能排名。

Agent UI 的组件名称也不能证明已经包含 Agent 执行系统。例如输入框的提交和生成状态，需要应用连接到实际服务。BoardUI 的免费 Chat Starter 是一个更具体的例外：它提供服务端 streaming route，但默认历史保存在浏览器，不能据此推断已解决数据库持久化或完整 Agent 编排。BoardUI Chat Starter

设计原语：行为、视觉与组合需要分开看

行为层的共同点比首页给人的感觉更多。两者的交互基础都使用 React Aria，并采用 Tailwind CSS v4；图表也存在 Recharts 等依赖重叠。实际差异主要来自如何组织样式、状态与组件接口，而不是购买了另一套完全不同的交互底层。

BoardUI 的视觉层从 palette primitives 映射到 semantic tokens，名称细分到文本、前景、背景、边框与状态，并与 Figma 的变量路径对应。交互主色使用 accent ramp，数据和状态颜色另行组织。这使它既能整体换色，也能维持某套具体设计的细节。BoardUI Color

BoardUI 默认通过手动 .dark 切换并在 localStorage 保存选择，不读取系统主题；产品需要跟随系统时，应在应用层补齐这一策略。BoardUI Dark mode

排版也有明确约束：text-body-medium 这样的复合类同时定义字号、行高、字距和字重，颜色单独设置；cx 有配套的合并规则。Agent 如果随意换成普通 class 合并工具，或新增复合排版类却不更新相应配置，就可能破坏预期结果。BoardUI Typography

HeroUI 的视觉层围绕 --accent、--surface、--foreground、--field-* 等语义变量，通过 Tailwind 的 @theme 映射到 utilities，再用 BEM classes 表达组件、子元素、变体和状态。OSS 与 Pro 共享主题基础；调整品牌样式不必直接编辑包的内部文件。HeroUI Theming

Pro 的 Design Systems 还能管理颜色、字体、圆角、阴影与组件覆盖，并在文档中预览和导出 CSS。主题可以改变组件质感，不能把 HeroUI 的默认外观理解为它唯一能实现的视觉语言。HeroUI Pro Theming

在组合层，HeroUI 许多组件使用 Sheet.Trigger、Sheet.Content 等 compound API，并提供 render 等扩展方式；具体 anatomy 要逐组件查询。DataGrid 是高级 props API 的例外，Sidebar 又有局部 Sidebar.Provider，所以“无需全局 HeroUI Provider”不意味着所有组件都无 Provider。Composition、Sidebar

由此可见，二者都拥有设计原语，但它们的 token 命名、排版、组件结构和状态接口不是同一份协议。直接混装源码时，必须处理这些差异；共享 React Aria 不会自动完成适配。

Agent 开发友好度：能发现、能理解，还要知道能改哪里

接口依据：BoardUI MCP、BoardUI Skills、HeroUI Pro MCP、HeroUI Design Taste。本次实际调用了 HeroUI MCP 的目录与组件文档；BoardUI MCP 的能力依据官方接口说明，未运行其安装工具。

BoardUI 的优势是 Agent 能沿着“发现组件 → 取用例和源码 → 安装 → 直接修改”完成工作。代价也随之落到本地：内部实现、依赖差异与上游更新需要维护；规则文件能提供约束，但不能保证 Agent 一定遵守。

HeroUI Pro 则适合让 Agent 围绕统一的组件 API 与主题约定工作。MCP 提供当前组件与参数资料，Design Taste 为间距、层级和语义颜色提供规则，设计系统导出补足品牌与产品上下文。其局限是 Pro 实现不能经 MCP 任意查看或重写；遇到公开接口之外的需求，要采用包装、组合或单独实现。HeroUI Skills

一个更有效的任务约定是：先查当前目录，再查实际会使用的组件文档和主题；完成后验证交互与视觉。在 HeroUI 中尤其要避免把旧 v2 API 写到 v3 项目；在 BoardUI 中要保持生成的 tokens、复合排版与 cx 约定一致。

这里讨论的是编码 Agent 的开发体验。官网另有名为 HeroUI Agents 的产品，它是面向最终用户的 hosted agent，目前标为 invite-only beta，与 Pro MCP 的职责不同。HeroUI Agents

已有 HeroUI Pro 时如何决定

• 长期业务产品，重视统一主题与持续维护：优先复用现有 HeroUI OSS / Pro，并让 Agent 同时获得 MCP、开发 Skill 和 Design Taste。需要专属外观时先调整 Design Systems，再评估缺失组件。
• 全新 Agent / Dashboard 项目，目标界面与 BoardUI 很接近：可用免费基础组件与 Blocks 验证源码交付方式；只有具体 Pro 组件确实减少了定制工作，才有明确的额外购买理由。
• 确实需要反复修改组件内部逻辑：BoardUI 的本地源码是实质优势，同时要接受自行合并更新。它是否更省时间，取决于修改深度，而非宣传中的组件数量。

例如产品需要任务进度、来源列表和可停止的输入框时，应先检查现有 HeroUI 的输入、消息、工具与来源组件能否组合出目标行为。只有结构性缺口仍然存在，才值得评估另一套实现。参考公开页面的交互思路与直接搬入组件源码，是维护成本不同的两种选择。

关联阅读

• Frontend 文档导航
• TanStack 文档导航：本文涉及 BoardUI Data Table 对 TanStack Table 的使用。