Repowise UI 组件库实战指南：用 `@repowise-dev/ui` 构建代码智能可视化界面

本篇指南面向需要在 Repowise Dashboard（packages/web）之外渲染引擎产物，或在自有应用中复用 Repowise 可视化组件的开发者，系统讲解@repowise-dev/ui组件库的目录布局、Subpath 消费方式、设计 Token 体系与六大共享原语（ResponsiveTable、AdaptivePanel、Toaster、ErrorBoundary、EmptyState、健康分颜色词汇）。读完你可以直接在自己的 Next.js 应用中接入该包，理解其"纯展示组件 + 宿主注入路由"的约束，并掌握健康分 Band 颜色体系与源码级实现细节。

组件库定位：Dashboard 与下游消费者共享的可视化层

@repowise-dev/ui是 Repowise 的共享可视化组件包，其正式定位（见 packages/ui/README.md）是"为 Repowise dashboard（packages/web）以及任何想渲染同一引擎产物的下游消费者提供的共享可视化组件"。

从源码结构看，它覆盖了 Repowise 引擎的几乎全部产物形态：

• 代码健康：health/（文件表、标记、分数徽章）、coverage/（覆盖率环、新鲜度表）、dashboard/（健康分环、注意力面板、总览磁贴）
• Git 智能：git/（热点表、所有权表/树图、变更可视化）、commits/（提交探索表与详情）
• 架构可视化：graph/（基于 Sigma 的 graph-flow、工具栏、图例、面板）、graph-primitives/、c4/（C4 架构视图 + 移动端布局原语）
• 代码库分析：dead-code/（摘要条、发现列表）、decisions/（决策表、证据抽屉、验证徽章）、docs/（文档树、文档导航、读者画像）、files/（文件实体页）、symbols/（符号表、符号抽屉、符号页）
• 协作与运维：chat/（聊天界面、产物面板、chat-markdown）、jobs/（生成进度、任务日志）、workspace/（多仓库表格与摘要）、owners/（所有者目录与档案）、security/（发现表）、onboarding/（首次运行界面）
• 成本：costs/（LLM 成本分解）

组件库的核心设计哲学可以概括为一句：引擎产物由后端算出来，UI 组件只负责把同一份数据渲染得一致、好看、可响应。因此组件保持"纯展示"——不发起数据请求、不直接做路由跳转，把路由与数据获取的职责留给宿主应用。

目录布局：领域分目录 + 共享原语 + 设计 Token

仓库实际源码目录与 README 的 Layout 描述一一对应，可直接按需深入：

packages/ui/ src/ blast-radius/ PR 影响分析外壳 c4/ C4 架构视图（+ 移动端布局原语） chat/ chat-interface、artifact-panel、chat-markdown 等 commits/ commit 探索表 + 详情 costs/ LLM 成本分解 coverage/ coverage-donut、freshness-table dashboard/ health-score-ring、attention-panel、概览磁贴等 dead-code/ summary-bar、findings 外壳 decisions/ decisions-table、evidence drawer、verification badge docs/ docs-tree、doc-nav、reader-persona files/ 文件实体页（doc/health/history/coverage/graph 标签页） git/ hotspot-table、ownership-table/treemap、churn 可视化等 graph/ graph-flow（Sigma）、工具栏、图例、面板（+ sigma/） graph-primitives/ health/ file-table、markers、score tokens hooks/ use-debounce 等 jobs/ generation-progress、job-log modules/ module health 详情 onboarding/ 首次运行界面 owners/ owner 目录 + 档案 security/ 发现表 settings/ general-form shared/ 原语：responsive-table、adaptive-panel、toast、 error-boundary、empty-state、api-error、metric-card、 entity links/hover cards、context-drawer、owl-loader symbols/ symbol-table、symbol-drawer、symbol-page、graph/git 面板 ui/ Radix-CVA 原语 wiki/ wiki-markdown、code-block、ToC、git-history、backlinks workspace/ 多仓库表格 + 摘要 styles/ globals.css 设计 Token 权威定义（Tailwind v4 @theme）

值得注意的一点是根入口 src/index.ts 几乎是空的（只有export {}），其注释明确说明：消费者应当通过 Subpath 导入（如@repowise-dev/ui/graph），根入口仅用于让 IDE 与工具链能干净地解析包。这与 README 的"按需导入切片，而非整包引入"的建议完全一致。

消费方式：Subpath 导入、transpilePackages 与样式继承

按 Subpath 导入，避免整包引入

README 给出的标准导入方式是"导入你需要的切片，而不是 barrel"：

import { HotspotTable } from "@repowise-dev/ui/git"; import { GraphFlow } from "@repowise-dev/ui/graph"; import { ResponsiveTable, AdaptivePanel, Toaster, toast } from "@repowise-dev/ui/shared";

对照 package.json 的exports字段，可以确认这套 Subpath 映射是完整且精细的：除了./graph、./git、./shared这样的目录级入口，还暴露了大量细粒度入口，例如：

• ./health/tokens→src/health/tokens.ts（健康分颜色词汇，后文详述）
• ./docs/doc-nav、./docs/reader-persona→ 对应的纯函数模块
• ./workspace/system-map、./workspace/dsm→ 依赖结构矩阵等子模块
• ./lib/cn、./lib/format、./lib/errors、./lib/confidence等工具函数
• ./ui/*→ Radix-CVA 基础原语（按钮、对话框等）

根入口"."同样指向./src/index.ts，保证包能被工具链解析。

关键配置：transpilePackages

由于包内组件是Tailwind v4 + TypeScript 源码原样发布、没有预编译步骤，Next.js 消费者必须在next.config.ts中加入：

transpilePackages: ["@repowise-dev/ui", "@repowise-dev/types"]

@repowise-dev/types一并列出，是因为组件 props 大量引用了它（如HealthBand、HealthFileMetric）。这个配置在仓库自身已经验证过——packages/web/next.config.ts 实际配置为：

transpilePackages: ["@repowise-dev/ui", "@repowise-dev/types", "@repowise-dev/api-client"]

继承设计 Token：一次导入样式

要继承规范的设计 Token，在应用根部导入一次样式表即可：

@import "@repowise-dev/ui/styles.css";

styles/globals.css是规范设计 Token 的唯一定义处，使用 Tailwind v4 的@theme机制。其语义 Token 体系（浅色/深色两套）从源码可见，例如：

• 语义色板：--color-error、--color-warning、--color-caution、--color-success
• 层级 Token：--z-modal: 40、--z-toast: 60（见 styles/globals.css）

这些 Token 采用"语义命名"策略：组件不直接引用裸色值，而是引用语义变量，因此同一套组件在明暗两种主题下自动正确渲染。README 特别强调消费者若想自定义主题，可以在导入该文件后声明自己的@theme块覆盖。

共享原语（Shared Primitives）详解

shared/是所有列表型页面应共同依赖的基础层，README 列出的原语在 src/shared/index.ts 中均可找到对应导出（还包括VirtualizedTable、PageShell、MetricCard、StatGrid、OwlLoader、ThemeToggle等未在 README 逐条展开的补充组件）。

ResponsiveTable：带列优先级的表格原语

README 对它的定义是"每个列表页面都应该建立在它之上的表格原语"，三条核心规则：

• 每列声明priority：1 永远可见；2 在md（768px）以下隐藏；3 在lg（1024px）以下隐藏；
• 外层永远回退到overflow-x-auto，保证内容不被裁切；
• stacked模式下，表格在手机端折叠为卡片列表。

对照源码 responsive-table.tsx，可以印证更多实现细节：

export type ColumnPriority = 1 | 2 | 3; export interface ResponsiveColumn<T> { key: string; // 稳定标识，同时作为 onSort 的排序键 header: React.ReactNode; mobileLabel?: string; // 卡片模式的短标签，缺省回退到 header 字符串 align?: "left" | "right" | "center"; priority?: ColumnPriority; sortable?: boolean; render: (row: T) => React.ReactNode; mobileRender?: (row: T) => React.ReactNode; // 卡片内覆写渲染（如去掉图标、缩短文本） hideInCard?: boolean; // 卡片模式完全跳过该列 }

优先级通过max-md:hidden/max-lg:hidden这类 Tailwind 响应式类实现（见源码PRIORITY_CELL_CLS）。折叠成卡片时，第一条 priority-1 列渲染为卡片标题，其余列以"标签/值"行呈现（优先mobileRender，否则render）。

源码还揭示了 README 之外的重要能力：

• 排序：sortable列配合sortField/sortOrder/onSort，表头按钮点击触发排序，并用aria-sort标注当前方向，箭头图标来自 lucide-react；
• 虚拟化：传入virtualize对象即开启窗口化渲染（行与折叠卡片两棵树都会开窗），默认阈值 60 行以下不虚拟化、低于该阈值渲染全部，默认估高：行 44px、卡片 76px，滚动视口最大 600px。非虚拟化路径通过count: 0传入useVirtualRows来实现"完全不打补丁"；
• 可点击行：clickableRowProps()让行保持原生<tr>语义（不覆写 role），同时可 Tab 聚焦、Enter/Space 激活；CLICKABLE_ROW_CLS提供聚焦环样式；
• 可访问性：支持caption（仅屏幕阅读器可见的表格标题）与onRowHover（指针悬停回调，供配对视图高亮；README 源注释提醒它只是指针事件，不能作为唯一的信息入口，必须与onRowClick配对）；
• 空态：rows为空且有empty时直接渲染empty，且 README 规定空态必须用EmptyState。

AdaptivePanel：一组件覆盖桌面侧栏与移动底部抽屉

README 定义它为一个统一的覆盖层表面：桌面端为右侧滑入面板，移动端为可下滑关闭的底部抽屉。ContextDrawer与聊天的ArtifactPanel都构建在它之上。

源码 adaptive-panel.tsx 给出了完整参数与默认值：

export interface AdaptivePanelProps { open: boolean; onOpenChange: (open: boolean) => void; title: React.ReactNode; // 可访问名称；渲染在头部 eyebrow?: React.ReactNode; // 标题上方的小号大写标签（如实体类型） children: React.ReactNode; widthClassName?: string; // 桌面宽度，默认 md:max-w-[520px] sheetHeightClassName?: string; // 移动抽屉最大高度，默认 max-h-[85dvh] hideHeader?: boolean; // 传自定义头部时隐藏标准头部 modal?: boolean; // false 时桌面端页面保持可交互（无焦点陷阱，仅移动端有遮罩），默认 true onInteractOutside?: (event: Event) => void; className?: string; }

实现要点：

• 基于 Radix Dialog 构建，始终发射DialogTitle以保证屏幕阅读器可访问；
• 移动端手势：拖拽把手区域通过onTouchStart/Move/End跟踪触摸位移，向下拖动超过SWIPE_DISMISS_PX = 80px阈值即触发onOpenChange(false)，拖动过程中实时translateY跟随手指；
• 层级：遮罩与面板使用z-[var(--z-modal)]；
• 非modal模式下桌面端不渲染遮罩，仅移动端显示轻遮罩（点击关闭）。

Toaster / toast：Token 主题化的 Sonner 通知

README 说明：这是token 主题化的 sonner toaster，使用--z-toast层级；在应用外壳挂载一次Toaster，由宿主传入解析好的主题。

源码 toast.tsx 与此完全对应：

export interface ToasterProps { theme?: "light" | "dark"; // 默认 "dark" position?: ...; // 默认 "bottom-right" }

其关键设计是框架中立：组件本身不读取主题（不从 next-themes 直接取），而是由宿主应用把解析后的theme传进来，从而让包可被任何 React 宿主使用。Toast 的样式直接绑定语义 Token（背景--color-bg-elevated、边框--color-border-default、文字--color-text-primary），toast从 sonner 再导出。

ErrorBoundary：可恢复的渲染错误边界

README：可恢复的渲染错误边界，默认回退是带重置重试的ApiError。

源码 error-boundary.tsx 是一个 class 组件，通过getDerivedStateFromError捕获错误，componentDidCatch转发给可选onError回调；reset把 state 清空以重挂载子树。支持自定义fallback(error, reset)，默认回退调用ApiError并附toFriendlyMessage(error)（来自 src/lib/errors.ts）与重试按钮。

EmptyState：唯一被认可的空态渲染

README 规定得很明确："唯一被认可的空态渲染，不允许裸<p>占位"。

源码 empty-state.tsx 提供icon、title、description、action与titleAs（h2/h3，默认h3；文件页标签页作为整面板空态时传h2，以保持标题层级 h1→h2→h3 不跳级）。外观为虚线边框卡片 + 渐变暖色 wash 背景。

其他值得注意的 shared 导出

从 shared/index.ts 还可看到：VirtualizedTable/useVirtualRows（ResponsiveTable 虚拟化的底层）、PageShell、MetricCard、StatGrid/StatTile、ViewTabs、TableSkeleton/CardSkeleton/PageSkeleton等骨架屏、ThemeToggle、use-theme-tokens.ts的resolveToken/useThemeVersion，以及entity/子目录（entity-link、entity-hover-card、entity-header、routes）——README 提到的"entity links/hover cards"就落在shared/entity/下。

健康分颜色词汇：唯一的 Band 语义色表

README 用一整段强调健康分颜色体系：分数颜色来自health/tokens.ts，建立在@repowise-dev/types/health的唯一 Band 词汇表上。

Band 词汇表（单一事实来源）

packages/types/src/health.ts 定义了五个绝对健康分档（其注释明确这是 Python 端grading.py的 TypeScript 镜像，由两端 parity 测试同步，禁止在任何地方硬编码档位阈值）：

关键语义：Excellent 与 Good 共享同一绿色，靠词本身区分（"the word carries the difference"）。此外还提供bandForScore(score)纯函数、formatScore（向下取整到 1 位小数，避免四舍五入跨档位边界造成"6.98 显示为 7.0 却标注 Fair"的矛盾）等工具。

tokens.ts 的颜色解析函数

packages/ui/src/health/tokens.ts 是"健康面颜色唯一真源"，保证文件行的分数胶囊、发现卡片的严重度徽章、KPI 卡片文字颜色三者永远一致。README 指定的使用函数：

• 已有 band 时：healthBandSoftBadgeClass(band)/healthBandTextColor(band)
• 已有 score 时：scoreBadgeClass(score)（带边框的分数胶囊，用于表格行）、scoreTextColor(score)、healthInk(score10)（canvas 墨色与内联样式）
• 全部解析到语义 Token（--color-error/warning/caution/success），从而自动适配明暗主题

源码中还可看到同族的补充函数：healthBandColor（返回 CSS 变量名）、scoreSoftBadgeClass（无边框、用于行文内联）、healthBand100/healthInk100（0-100 刻度换算）、healthBandNodeFill/healthNodeFill（canvas 节点用的独立五档渐变色--color-node-*，因为密集填充的图形无法带词，必须按数值区分 Excellent/Good）、HEALTH_BAND_FILL（散点图 SVG fill 类）、HEALTH_BAND_BAR（分布条形图填充，Good 用 55% 透明度绿色以便与 Excellent 相邻时保持可读）、coverageColor/coverageBand/coverageTextColor（覆盖率四档色带：<30 Thin/error、<60 Partial/warning、<80 Solid/caution、≥80 Strong/success）、deltaColor/formatDelta（变化量颜色与格式化，注意四舍五入决定符号）、formatHealthImpact（扣分格式化，区分"无扣分"与"扣分小到不显示"两种零）等。

README 特意提醒表结构的一个实现约束：所有映射表必须逐条写全，因为 Tailwind 只会读取源码中能字面识别的类名（运行时拼出的类名会被树摇掉）——这也是这些表全部以Record<HealthBand, string>显式展开的原因。

Peer Dependencies 与"纯展示"约束

README 明确指出组件包的 peer deps 只有：

react react-dom next-themes （仅用于主题解析）

（package.json 中 peerDependencies 还包含swr，配合@repowise-dev/api-client使用。）

随之而来的四条工程约束（README 原文要点）：

1. 组件保持 client-pure 或纯展示——不直接调用next/navigation或next/link；
2. 需要路由时通过 props 或 context 注入：renderLinkrender props、LinkComponent、buildHref，让消费者接自己的路由方案；
3. 新组件不得读取window.location——初始状态通过 props 到达；
4. 主题解析由宿主完成并传入（如Toaster的themeprop），组件包本身不直接依赖 next-themes 运行时读取。

这解释了为什么shared/entity/下有routes.ts（路由构造被抽成纯函数交给消费者拼接），以及为什么 package.json 将next-themes同时列为 peer dep（消费方）与 dev dep（测试用），但组件运行时代码保持框架中立。

质量保障：类型检查、测试与发布门禁

package.json 的 scripts 提供了完整质量链路：

• type-check:tsc --noEmit
• test:vitest run（对应packages/ui/__tests__/下的组件测试，例如brand.test.ts、token-drift.test.ts、types-alias-parity.test.ts、z-layering.test.ts以及shared/、health/等各领域测试）
• gates:bash ./scripts/ui-gates.sh，并暴露三个 bin：repowise-ui-gates、repowise-ui-no-raw-hex（禁止裸十六进制色值，强制走 Token 体系，脚本见 scripts/no-raw-hex-check.sh）、repowise-ui-contrast-check（对比度检查，scripts/contrast-check.py）

发布配置为publishConfig（GitHub Packages 私有 registry，access: restricted），files仅包含src、styles、scripts，sideEffects声明仅 CSS 文件有副作用，保证打包器可以正确摇树。

实战建议小结

1. 优先 Subpath 导入，例如@repowise-dev/ui/git、@repowise-dev/ui/shared，避免根 barrel；需要健康分颜色时直接@repowise-dev/ui/health/tokens。
2. Next.js 消费者必须配置transpilePackages: ["@repowise-dev/ui", "@repowise-dev/types"]（这是 TS 源码原样发布的硬性前提），并在应用根部@import "@repowise-dev/ui/styles.css"一次。
3. 列表一律基于ResponsiveTable：用priority控制响应式可见性、stacked处理手机折叠、virtualize处理长列表、EmptyState处理空态。
4. 覆盖层一律基于AdaptivePanel：桌面侧栏 + 移动底部抽屉一套搞定，注意modal={false}时桌面端可保持页面交互。
5. 颜色永远走语义 Token：健康分用health/tokens.ts提供的函数，禁止在业务代码里硬编码色值（有no-raw-hex门禁兜底）。
6. 遵守纯展示约束：路由经renderLink/LinkComponent/buildHref注入，不读window.location，从而让组件包可在任意 React 路由方案下复用。

如需继续深入，建议从这些文件入手：packages/ui/README.md（本文依据）、packages/ui/src/shared/responsive-table/responsive-table.tsx、packages/ui/src/shared/adaptive-panel.tsx、packages/ui/src/health/tokens.ts、packages/types/src/health.ts 与 packages/ui/styles/globals.css。