Hexclave Dashboard 设计规范实践指南:design-components 组件体系与 UI 开发标准
Hexclave Dashboard 设计规范实践指南:design-components 组件体系与 UI 开发标准
本文基于 apps/dashboard/DESIGN-GUIDE.md 编写,并结合
apps/dashboard/src/components/design-components与packages/dashboard-ui-components的源码实现进行验证与扩充。
Hexclave Dashboard 的前端 UI 由一份面向「人类与 AI Agent 双读者」的设计规范约束:所有页面必须优先使用 design-components 组件体系,禁止临时发明视觉原语。本文带你完整梳理这份规范——从核心原则、快速决策树、颜色/排版/间距/动效系统,到每一个组件的 Props 契约、DataGrid 数据表格用法、路由级指引与反模式清单,并以源码佐证各组件的真实行为,让你在新页面开发或旧页面迁移时有一份可直接落地的参考手册。
1) 核心原则(不可妥协)
apps/dashboard/DESIGN-GUIDE.md 的第一条原则是:
Always prefer components from
apps/dashboard/src/components/design-components.
具体含义如下:
- 不要自建视觉原语:如果
design-components里已有对应组件,就不要再写自定义的GlassCard、ChartCard、徽章 pill、pill 切换器、列表行等。 - 优先扩展而非重造:如果想要的 UI 可以通过「调整 / 定制 / 扩展」一个 design-components 组件实现,就不要创建页面局部的替代组件。
- 兜底顺序:只有完全无法用 design-components 实现时,才允许非 design-components 方案;
@/components/ui/*原语仅在没有 design-components 等价物、或 design-components 组件本身就是对该原语的包装时才可使用。 - 行为对齐:新代码必须与既有 design-components 行为保持一致,包括:
- hover-exit 过渡(
transition-* duration-150 hover:transition-none); - 合适的 glassmorphic(毛玻璃)表面;
- alert/badge 的语义化 variant;
- 通过 design-components 原语提供的「异步安全」点击处理(见下文
DesignButton对 asynconClick的支持)。
- hover-exit 过渡(
该原则的直接证据在于目录结构与依赖关系:design-components/index.ts 中 export * from "@hexclave/dashboard-ui-components",即组件大部分实现沉淀在独立包 packages/dashboard-ui-components(版本 1.0.126,见 package.json),而 Dashboard 内还有 analytics-card.tsx、editable-grid.tsx 等本地扩展。
2) 快速决策树
实现新页面时,先按这张决策树走,避免「凭感觉造轮子」:
| 场景 | 组件 |
|---|---|
| 需要区块容器 / 卡片 | DesignCard;图表密集型分析面(尤其 Recharts tooltip/溢出)用 DesignAnalyticsCard |
| 需要面向用户的状态/信息/警告/错误提示 | DesignAlert |
| 需要小的语义标签(sent、failed、queued、active) | DesignBadge |
| 需要用户操作按钮,尤其异步操作 | DesignButton |
| 需要文本输入 / 下拉选择 | DesignInput、DesignSelectorDropdown |
| 需要分段 / pill 切换器 | DesignPillToggle |
| 需要带计数徽章的类别 Tab | DesignCategoryTabs |
| 需要带操作按钮 / 菜单的行或列表项 | DesignListItemRow(用户行用 DesignUserList) |
| 需要设置 / 属性网格编辑器 | DesignEditableGrid |
| 需要可交互、可排序、可搜索的数据表格 | DataGrid + useDataSource + createDefaultDataGridState(来自 @hexclave/dashboard-ui-components) |
| 需要下拉操作 / 选择 / 切换菜单 | DesignMenu |
| 需要焦点陷阱模态框(确认、富内容、tester、表单) | DesignDialog |
3) 允许的基础 UI 使用
@/components/ui/* 仍然可以在没有 design-components 等价物的情况下使用:
- 确认流程辅助组件
ActionDialog/FormDialog(它们包装了onClick/ 表单提交生命周期,仅需一个装饰好的确认/提交提示时仍然有用); - 侧滑面板 / popover(
Sheet、Popover等); - design-components 未提供的复杂布局容器;
- 高度专业化的编辑器内部实现。
但对任何通用模态表面(富内容详情对话框、tester 界面、数据对话框、以模态呈现的设置 popover),一律使用 DesignDialog,而不是手工拼接 Dialog + DialogContent + DialogHeader 等——DesignDialog 是 Dashboard 的规范毛玻璃模态表面(见 4.14)。
直接使用原语时还要注意:视觉风格与 design-components 表面兼容;不要在本地区重复一个 design-components 组件的 API;优先考虑创建/扩展 design-components 组件而不是重复本地模式。
3.1) 最佳实践(始终适用)
- 先用 design-components 原语搭建,再加最小化的页面级样式。
- 保持组件可组合:通过 props 传数据/配置,而不是把展示逻辑硬编码。
- 偏好语义化 API(
variant、color、gradient),避免逐处写死 class。 - 使用无障碍默认值:纯图标控件要有清晰 label;键盘焦点可见性(
focus-visible:*);适用场景使用语义 role。 - 保持行为确定性:每个屏幕一种视觉语言;所有路由共用一套状态色映射;每种控件类型只有一种交互模式。
3.2) 颜色系统(浅色 + 深色主题)
主题 token 使用优先级
- 组件 variant(
DesignAlert、DesignBadge、DesignCard的 gradient、tab/toggle 的 gradient)。 - 语义 Tailwind token(
bg-background、text-foreground、text-muted-foreground、border-border)。 - 用于微妙表面的透明度层(如
bg-foreground/[0.03])。
表面与文本规则
- 主表面:
bg-background+ 微弱的 ring/border。 - 次级/弱化表面:低透明度 foreground 覆盖层。
- 主文本:
text-foreground。 - 次级文本:
text-muted-foreground。 - 应用 UI 文本/表面绝不使用写死的纯黑/纯白 utility 值。
语义状态色
| 状态 | 颜色 | 组件用法 |
|---|---|---|
| 成功 | 绿/emerald | DesignAlert variant="success"、DesignBadge color="green" |
| 错误 | 红 | DesignAlert variant="error"、DesignBadge color="red" |
| 警告 | 橙/amber | DesignAlert variant="warning"、DesignBadge color="orange" |
| 信息 | 蓝/cyan | DesignAlert variant="info"、DesignBadge color="blue" 或 "cyan" |
浅色与深色指引
- 每个自定义颜色都要保证深色模式下的可读性。
- 深色模式中减少高对比填充,改用低透明度色调 + ring。
- 文本保持高对比,非关键 chrome 保持中对比。
从 badge.tsx 的 badgeStyles 映射可以看到这套语义色在底层是如何落地的:每种颜色都是「亮色下深色文字 + 低透明度底 + ring」的组合,例如 green 对应 text-emerald-700 dark:text-emerald-400 bg-emerald-500/20 dark:bg-emerald-500/10 ring-1 ring-emerald-500/30,天然满足双主题对比要求。
3.3) 字体系统
排版保持简洁一致,优先使用既有 design-components / header 模式。
推荐字号与用途
| 用途 | 样式 |
|---|---|
| 页面标题 | text-xl sm:text-2xl font-semibold tracking-tight |
| 区块标题 | text-xs font-semibold uppercase tracking-wider |
| 正文 / 默认控件文本 | text-sm |
| 次级元数据 | text-xs text-muted-foreground |
| 微标签 / 徽章 | text-[10px] 到 text-[11px] |
排版规则
- 大写 + tracking 只用于区块标签和紧凑元数据标题。
- 已有字号能满足需求时,不要引入新的任意字号。
- 卡片与 alert 内保持短行宽,便于扫读。
- 数值/统计值需要时使用表格数字(tabular numerals)。
这与源码实现一致:DesignCard 的标题统一为 text-xs font-semibold uppercase tracking-wider(见 card.tsx 第 174 行),DesignAnalyticsCardHeader 同样使用该组合(见 analytics-card.tsx)。
3.4) 间距与布局指南
采用紧凑、可重复的间距节奏。
间距节奏(gap)
| 值 | 用途 |
|---|---|
gap-1(4px) |
紧密的图标/文本耦合 |
gap-2(8px) |
紧凑控件间距 |
gap-3(12px) |
标准行间距 |
gap-4(16px) |
区块内部间距 |
gap-5(20px) |
更大区块分组 |
内边距节奏(padding)
p-2/px-3 py-2:紧凑控件p-3:标准紧凑块p-4到p-5:卡片内容 / 主要区块
布局规则
- 主要容器/卡片用
rounded-2xl。 - 控件(输入框、切换器、小卡片)用
rounded-xl。 - 保持视觉层级:页面间距 > 区块间距 > 控件间距。
- 单个组件内不要混用无关的间距刻度。
3.5) 动画与微交互
动效应即时、细微、有信息量。
核心动效规则
- 无 hover-enter 延迟过渡。
- 使用 hover-exit 过渡:
transition-* duration-150 hover:transition-none。 - 交互过渡保持短而微妙。
- 密集型后台界面避免大幅度动画位移。
时长指引
| 时长 | 用途 |
|---|---|
| 50ms–100ms | 非常小的图标反馈 |
| 150ms | 标准 hover/focus/press 恢复 |
| 200ms–300ms | 布局/状态过渡(面板折叠、sheet 式展开) |
| >300ms | 仅用于环境/非关键效果 |
微交互模式
- Hover:文字微微变亮;ring/阴影微妙增强。
- Press:即时反馈(无延迟按压动画)。
- Focus:所有可交互元素都有可见的
focus-visiblering。 - Loading:使用 design-components 内置加载态(
DesignButton、带 async 的 tabs/toggles);绝不在无反馈的情况下冻结 UI。
动效无障碍
- 非必要效果尊重
prefers-reduced-motion。 - 微交互不依赖动画也能被理解。
源码佐证:DesignCard 的毛玻璃表面类就是 transition-all duration-150 hover:transition-none + ring 强弱变化(见 card.tsx 第 136-141 行);DesignPillToggle 的滑动指示器使用 transform 200ms ease-out, width 200ms ease-out(见 pill-toggle.tsx),恰在 200ms–300ms 的标准布局过渡区间内。
3.6) 最佳实践清单(视觉 + UX)
- [ ] 在自定义 wrapper 之前先使用 design-components 原语。
- [ ] 使用语义 variant/颜色而非自定义状态样式。
- [ ] 浅色和深色主题下都可读、对比度合适。
- [ ] 使用规范的排版字号与层级。
- [ ] 使用一致的间距节奏(
gap-2/3/4、p-3/4/5)。 - [ ] 使用干脆的 hover-exit 过渡和清晰的 focus ring。
- [ ] 提供清晰的 loading/disabled/empty/error 状态。
4) 组件逐一契约
本节是强制性的:什么场景用什么组件、用什么 props。
4.1 DesignCard
文件:packages/dashboard-ui-components/src/components/card.tsx(经 apps/dashboard/src/components/design-components/card.tsx 再导出)。
用途:页面区块、分组控件、分析面板、列表容器、邮件/项目页面里的毛玻璃块。
最常用的 props:
title、icon(可选subtitle)用于区块头;gradient:"blue" | "cyan" | "purple" | "green" | "orange" | "default";glassmorphic(可选显式覆盖);contentClassName用于内容间距覆盖。
重要行为(均有源码印证):
- 如果给了
title,类型上强制要求icon(card.tsx 的判别式联合类型WithTitleProps要求icon: React.ElementType)。 - 布局自动推导:
title + subtitle→ 完整 header;仅title→ 紧凑 header;无 title → 纯 body 卡片。对应源码中的variant = "header" | "compact" | "bodyOnly"。 useGlassmorphicDefault()让嵌套组件默认继承毛玻璃行为:组件内部通过DesignCardNestingContext提供上下文,useGlassmorphicDefault(explicit)在未显式传值glassmorphic时回退到「是否在 DesignCard 内部」。
默认建议:Dashboard 区块默认用 glassmorphic 风格(显式或通过嵌套上下文);除非有语义原因需要彩色色调,否则用 gradient="default"。
4.1.1 DesignAnalyticsCard(及图表辅助)
文件:apps/dashboard/src/components/design-components/analytics-card.tsx。
用途:overview 和指标面中的图表密集型分析壳;图表 tooltip 需要逃逸裁剪/堆叠问题的卡片;替代此前重复的玻璃分析包装(ChartCard、GlassCard 克隆)。
导出:DesignAnalyticsCard、DesignAnalyticsCardHeader、DesignChartLegend、useInfiniteListWindow、DesignInfiniteScrollList。
DesignAnalyticsCard 的 props:
gradient:"blue" | "cyan" | "purple" | "green" | "orange" | "slate";className;- 另支持
chart?: DesignAnalyticsChartConfig,内部会渲染到data-analytics-*属性上,供图表/样式层读取图表类型、tooltip 类型、高亮模式与平均线配置。
规则:
- overview/分析卡片优先
DesignAnalyticsCard而非本地图表 wrapper。 - 图表实现保持局部(Recharts 配置、数据转换),但 shell/legend/列表管道共享。
- 布局匹配时用
DesignChartLegend而非手写点+标签图例行。 - 分析/列表 tab 中增量滚动列表用
useInfiniteListWindow。
源码中的关键实现细节(analytics-card.tsx):
- 它默认不裁剪溢出(不带
overflow:hidden),并带analytics-card-tooltip-escapeCSS 逃逸层,让 Recharts 的绝对定位 tooltip 不被卡片裁剪;hover:z-10保证 hover 卡片的 tooltip 浮在相邻卡片之上。 useInfiniteListWindow基于IntersectionObserver实现增量渲染:初始渲染INFINITE_LIST_BATCH_SIZE(12 条),哨兵元素进入滚动容器视口时追加下一批,rootMargin: "120px 0px"提供预加载;支持resetKey(如切换 tab 时重置)和enabled开关。
4.2 DesignAlert
文件:apps/dashboard/src/components/design-components/alert.tsx(后端实现在 packages/dashboard-ui-components/src/components/alert.tsx)。
用途:保存成功/失败、警告状态(如 SMTP/provider 配置警告)、信息性通知。
props:variant("default" | "success" | "error" | "warning" | "info")、title、description、glassmorphic(渲染在玻璃表面上时)。
规则:用语义 variant 而不是自定义 alert 类组合;标题保持简短可行动;更长说明放 description。
4.3 DesignBadge
文件:packages/dashboard-ui-components/src/components/badge.tsx(经 design-components 再导出)。
用途:状态 chip(sent、failed、queued、draft、active);header 和列表中的小语义标签。
props:
label;color:"blue" | "cyan" | "purple" | "green" | "orange" | "red";icon(可选,组件类型而非已渲染节点);size:"sm" | "md";contentMode:"both" | "text" | "icon"。
规则:
- 按含义选色,不按喜好选色。
- 仅当提供了
icon时才用contentMode="icon";源码中该组合缺失 icon 会直接抛错("DesignBadge contentMode 'icon' requires the icon prop to be provided.")。 - 纯图标徽章的无障碍已由
aria-label处理。
额外源码事实:sm 尺寸为 px-2 py-0.5 text-[10px],md 为 px-2.5 py-1 text-[11px];iconClassName 可用于传入如 animate-spin 之类表示进行中状态的类。
4.4 DesignButton
文件:packages/dashboard-ui-components/src/components/button.tsx。
用途:Dashboard 表面的所有主/次操作;异步 submit/save/delete 操作。
props:
variant:"default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "plain";size:"default" | "sm" | "lg" | "icon";onClick(可以是 async);loading(可选受控模式);loadingStyle:"spinner" | "disabled";asChild(与链接/触发器组合时)。
规则:
- 异步行为与一致的 loading 语义上,优先
DesignButton而非基础Button。 - 标准按钮操作不要手写 spinner。
源码事实(button.tsx):async onClick 经由 useAsyncCallback 包装,promise 未完成时自动显示 spinner(或 loadingStyle="disabled" 的禁用态);错误通过 runAsynchronouslyWithAlert 抛给 alert 感知的异步工具链,避免吞掉异步错误——这正是规范第 7 节「async 错误不得被吞掉」的实现基础。
4.5 DesignInput
文件:apps/dashboard/src/components/design-components/input.tsx。
用途:design-components 表面内的文本字段;紧凑过滤字段与内联设置输入。
props:size("sm" | "md" | "lg")、prefixItem(固定前缀 UI)、leadingIcon(前置图标的输入框),以及常规 input props(placeholder、value、onChange、disabled 等)。
规则:前缀值(域名/路径/货币符号)用 prefixItem;搜索或查询字段用 leadingIcon。
4.6 DesignSelectorDropdown
文件:apps/dashboard/src/components/design-components/select.tsx。
用途:Dashboard 设置与过滤器中标准单选下拉。
props:value、onValueChange、options: { value, label, disabled? }[]、placeholder、size("sm" | "md" | "lg")、disabled。
规则:除非需要自定义行为,功能页面优先用它而不是裸 Select。
4.7 DesignPillToggle
文件:packages/dashboard-ui-components/src/components/pill-toggle.tsx。
用途:分段控件、视口切换器、紧凑模式切换。
props:options: { id, label, icon? }[]、selected、onSelect(可为 async)、size("sm" | "md" | "lg")、gradient、showLabels(纯图标控件设为 false)、glassmorphic。
规则:适用时不要自建内联 pill 切换组件;showLabels={false} 仅在图标清晰且带 tooltip 式标签时使用。源码显示隐藏标签时 hover 会显示 Tooltip 承载的标签文本。
4.8 DesignCategoryTabs
文件:packages/dashboard-ui-components/src/components/tabs.tsx。
用途:带可选计数徽章的顶层分类切换。
props:categories: { id, label, count?, badgeCount? }[]、selectedCategory、onSelect、showBadge、size("sm" | "md")、gradient、glassmorphic。
规则:用于分类级导航,而非微切换;若无分类计数且控件很小,DesignPillToggle 可能更合适。
4.9 DesignMenu
文件:apps/dashboard/src/components/design-components/menu.tsx。
用途:标准行/卡片操作菜单;选择器菜单(radio group);切换菜单(checkbox 项)。
三种 variant 及必填 props:
variant="actions"+items;variant="selector"+options、value、onValueChange;variant="toggles"+options、onToggleChange。
公共共享 props:trigger("button" | "icon")、triggerLabel、triggerIcon、align、label、withIcons。
规则:常见操作菜单优先用它而不是本地 DropdownMenu wrapper。
4.10 DesignListItemRow 与 DesignUserList
文件:apps/dashboard/src/components/design-components/list.tsx。
用途:带可选行内操作的结构化列表行;用户活动/用户列表行。
DesignListItemRow props:title、可选 subtitle、icon、size("sm" | "lg")、buttons(直接操作或菜单操作)、onClick。
DesignUserList props:users: { name, email, time, color? }[]、onUserClick、showAvatar、gradient("blue-purple" | "cyan-blue" | "none")。
规则:密集列表用 size="sm";卡片式列表项用 size="lg";除非布局真正独一无二,否则用它们替换自定义 row/card 列表项。
4.11 DesignEditableGrid
文件:apps/dashboard/src/components/design-components/editable-grid.tsx。
用途:键/值设置编辑器;混合类型设置控件;延迟保存/放弃模式。
props:
items(类型化联合:text、boolean、dropdown、custom-dropdown、custom-button、custom);- 共享项元数据:
itemKey、icon、name、可选description与tooltip; columns:1 | 2;size:"sm" | "md";deferredSave、hasChanges、onSave、onDiscard;externalModifiedKeys。
规则:
- 基于行且行内可编辑的配置表单优先用它。
- 布局是扁平的 label/value 网格(无逐字段卡片);浅色模式下可编辑值使用白色控件。
- 多字段需一起提交时使用延迟保存模式。
- 文本值进入显式编辑态;Enter 保存,Escape 取消。
- 省略
onUpdate或设readOnly得到不可编辑的值。 description用于持久上下文,tooltip仅用于次要细节。custom-dropdown拥有自己的 popover;需同时提供triggerContent与popoverContent。- 类型化联合之外的页面局部可编辑触发器,复用
designEditableGridControlClassName/designEditableGridPopoverClassName(二者由 design-tokens.ts 导出,提供 h-9 触发器与毛玻璃 popover 表面的完整样式串)。
4.12 DataGrid + useDataSource + createDefaultDataGridState
包:@hexclave/dashboard-ui-components(源码位于 packages/dashboard-ui-components/src/components/data-grid)。
用途:可交互、可排序、可搜索的数据表格;超过约 20 行、需要分页、列可见性、快速搜索或 CSV 导出的表格。
规范用法(取自文档原文,可直接复制):
import { DataGrid, useDataSource, createDefaultDataGridState, type DataGridColumnDef } from "@hexclave/dashboard-ui-components";
const columns: DataGridColumnDef<MyRow>[] = [
{ id: "name", header: "Name", accessor: "name", width: 200, type: "string" },
{ id: "status", header: "Status", accessor: "status", width: 120, type: "singleSelect",
valueOptions: [{ value: "active", label: "Active" }, { value: "inactive", label: "Inactive" }],
renderCell: ({ value }) => <DesignBadge label={String(value)} color={value === "active" ? "green" : "red"} size="sm" /> },
];
const [gridState, setGridState] = useState(() => createDefaultDataGridState(columns));
const gridData = useDataSource({
data: myRows,
columns,
getRowId: (row) => row.id,
sorting: gridState.sorting,
quickSearch: gridState.quickSearch,
pagination: gridState.pagination,
paginationMode: "client",
});
<DataGrid
columns={columns}
rows={gridData.rows}
getRowId={(row) => row.id}
totalRowCount={gridData.totalRowCount}
isLoading={gridData.isLoading}
state={gridState}
onChange={setGridState}
toolbar={false} // set to false to hide; omit for default toolbar
onRowClick={(row) => handleClick(row)}
maxHeight={400}
/>
关键 props:
columns(DataGridColumnDef[]):列定义,含id、header、accessor、type,可选renderCell、cellOverflow;rows(TRow[]):永远传gridData.rows(useDataSource的输出),绝不传原始数组——网格自身不做排序/过滤/分页;getRowId((row) => RowId):唯一行标识(RowId为string);state/onChange:完全受控的网格状态(排序、分页、搜索、可见性);totalRowCount:分页显示所需总行数;toolbar:false隐藏,省略则默认,或传渲染函数自定义;onRowClick:可选行点击处理器;maxHeight:滚动前的最大像素高度;rowHeight:数字(默认 44)固定高度,或"auto"动态行测量;estimatedRowHeight:rowHeight="auto"时虚拟化器估算的行高(默认 44)。
单元格溢出:
cellOverflow: "truncate"(默认):单行 + text-overflow 省略号。cellOverflow: "wrap":内容自然换行;rowHeight="auto"时行高自适应。- 徽章列表、权限 chip、多行文本用
"wrap";UUID、邮箱、日期、单行文本用默认 truncate。
const columns: DataGridColumnDef<MyRow>[] = [
{ id: "userId", header: "User ID", width: 130 }, // truncates (default)
{ id: "auth", header: "Auth methods", width: 150, cellOverflow: "wrap", // badges wrap, row grows
renderCell: ({ row }) => (
<div className="flex flex-wrap gap-1">
{row.authTypes.map((t) => <Badge key={t}>{t}</Badge>)}
</div>
),
},
];
<DataGrid columns={columns} rowHeight="auto" estimatedRowHeight={48} ... />
规则:
- 始终用
createDefaultDataGridState(columns)初始化状态——绝不要手工拼装 state 对象。源码 state.ts 会从列定义推导columnWidths/columnOrder,默认pageSize: 50、paginationMode由调用方决定。 - 始终用
useDataSource处理数据——网格不自作排序/过滤/分页。 - 列必须跨渲染稳定(组件外定义或
useMemo包裹)。 renderCell必须是纯函数——内部不得使用 React hooks。- 完整铁律与高级用法阅读
DataGrid组件的 JSDoc。
源码补充:状态模块还内置了 CSV 导出(exportToCsv,带 UTF-8 BOM 以保证 Excel 正确识别编码)、相对/绝对日期格式化(formatGridDate)、默认排序比较器与跨列大小写不敏感快速搜索(applyQuickSearch / defaultMatchRow),这些能力都由 useDataSource 在 paginationMode: "client" 时自动串联。
4.13 CursorBlastEffect
文件:apps/dashboard/src/components/design-components/cursor-blast-effect.tsx(实际实现位于 packages/dashboard-ui-components/src/components/cursor-blast-effect.tsx)。
用途:可选的高反馈交互(playground/内部原型)。
props:blastLifetimeMs、maxActiveBlasts、rageClickThreshold、rageClickWindowMs、rageClickRadiusPx、containerRef。
规则:仅作为可选增强,不是必备 UX;生产关键流程中避免分散注意力的过度使用。
4.14 DesignDialog
文件:packages/dashboard-ui-components/src/components/dialog.tsx(经 @/components/design-components 再导出)。
用途:Dashboard 中任何焦点陷阱模态(确认框、富内容详情对话框、tester 界面、以模态呈现的设置表单);替代手写 Dialog + DialogContent + DialogHeader 组合。
最常用的 props:
trigger:包在DialogTrigger中的元素;通过open/onOpenChange/defaultOpen外部控制时省略。size:"sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl" | "full"(默认"lg")。源码中每种尺寸映射到max-w-*,如2xl→max-w-2xl。variant:"glassmorphic"(默认)或"plain"。玻璃变体应用 Dashboard 的模糊表面 + 变暗遮罩(源码中为bg-white/95 backdrop-blur-2xl ring-1 ring-black/[0.08]+bg-black/50 backdrop-blur-smoverlay)。icon:Phosphor 图标组件(或传null跳过 chip)。title/description:标准头部文本。title自动接入DialogTitle以支持无障碍。headerContent:渲染在 icon/title 块下方的富内容——用于 header 内的内嵌摘要卡片、指标磁贴或状态 pill。customHeader:完全覆盖 header 区域。此时你负责渲染可访问的DialogTitle。footer:渲染在带样式底部栏中的 footer 节点。关闭按钮包在DesignDialogClose asChild中(同一模块再导出)。noBodyPadding:禁用默认px-6 py-4内边距,用于全出血 body 内容。hideTopCloseButton:隐藏DialogContent渲染的右上角 "X",用于完全自定义关闭方式。bodyClassName/headerClassName/footerClassName/overlayClassName/className:各区域的细粒度类覆盖。
再导出(从同一模块导入,同一个 dialog 不要混用 @hexclave/ui):
DesignDialogClose(DialogClose别名);DesignDialogTrigger(DialogTrigger别名);DesignDialogTitle/DesignDialogDescription;DesignDialogRoot(Dialog别名),用于罕见的需要裸Dialog.Root语义的场景。
规则:
- 构建整页模态时不要直接写
Dialog+DialogContent+DialogHeader+DialogBody+DialogFooter,用DesignDialog。 - 重构既有 dialog 时,通过
headerContentprop 保留任何摘要卡片、sparkline 或统计磁贴,而不是从头写customHeader。 - Footer 插槽已提供边框 + 背景 + 响应式 flex,不要重复添加同样式的包裹 div。
- 用能容纳内容的最小
size:确认框用md/lg,带摘要卡片的详情对话框用2xl/3xl,tester/表单用5xl+。
常用形态(原文代码):
// Confirmation
<DesignDialog
trigger={<DesignButton size="sm">Open</DesignButton>}
icon={InfoIcon}
title="Heads up"
description="You're about to do something."
footer={
<DesignDialogClose asChild>
<DesignButton variant="secondary" size="sm">Close</DesignButton>
</DesignDialogClose>
}
>
<p className="text-sm">Body content.</p>
</DesignDialog>
// Rich modal with summary card
<DesignDialog
open={open}
onOpenChange={setOpen}
size="2xl"
icon={PulseIcon}
title="Rule trigger history"
description="3 total triggers"
headerContent={<SummaryCard />}
footer={
<DesignDialogClose asChild>
<DesignButton variant="secondary" size="sm">Close</DesignButton>
</DesignDialogClose>
}
>
{/* recent triggers list */}
</DesignDialog>
// Wide tester / form
<DesignDialog
trigger={<DesignButton size="sm">Open tester</DesignButton>}
size="5xl"
icon={FlaskIcon}
title="Test sign-up rules"
description="Simulate a sign-up request."
footer={
<>
<DesignDialogClose asChild>
<DesignButton variant="secondary" size="sm">Cancel</DesignButton>
</DesignDialogClose>
<DesignButton size="sm">Run test</DesignButton>
</>
}
>
<TesterForm />
</DesignDialog>
5) 路由级指引(Project + Email 表面)
参考表面:
apps/dashboard/src/app/(main)/(protected)/projects/[projectId]apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/emailsapps/dashboard/src/app/(main)/(protected)/projects/[projectId]/email-draftsapps/dashboard/src/app/(main)/(protected)/projects/[projectId]/email-templatesapps/dashboard/src/app/(main)/(protected)/projects/[projectId]/email-themes
这些页面目前的实现常使用自定义 card/header/pill 组件。新增与重构代码应按下述方案标准化到 design-components 原语。
5.0 /projects/[projectId]/(overview) 分析表面
用:图表/列表壳 DesignAnalyticsCard;紧凑图表头 DesignAnalyticsCardHeader;堆叠图例 DesignChartLegend;增量列表渲染 useInfiniteListWindow(或适用的 DesignInfiniteScrollList)。
避免:页面局部 ChartCard wrapper;每个卡片重复的 IntersectionObserver 列表窗口逻辑。
5.1 /projects/[projectId]/emails
用:区块容器 DesignCard(title、icon、可选 subtitle、gradient);提示 DesignAlert(按状态选 variant);状态 chip DesignBadge(sent 用 green,failed 用 red);操作 DesignButton;表格 DataGrid + useDataSource + createDefaultDataGridState。
避免:自定义 GlassCard;自定义状态徽章组件;除非特殊组合需要否则不用裸 Alert。
5.2 /projects/[projectId]/email-drafts(列表)
用:列表容器 DesignCard;行项 DesignListItemRow(卡片行 size="lg"、密集列表 size="sm");行菜单 DesignMenu variant="actions";空态操作 DesignButton。
避免:用于标准列表行行为时自定义 DraftCard。
5.3 /projects/[projectId]/email-drafts/[draftId](编辑器)
用:状态/同步提示 DesignAlert;scope/状态 chip DesignBadge;编辑器侧边控件按需 DesignButton、DesignSelectorDropdown、DesignInput。
保留:design-components 无等价物的专用编辑器布局系统。
5.4 /projects/[projectId]/email-templates
用:模板项容器 DesignCard(按语义区块选 gradient);提示/警告 DesignAlert;操作 DesignButton;模板行操作菜单 DesignMenu。
避免:为每个模板卡片内联重复玻璃样式块。
5.5 /projects/[projectId]/email-templates/[templateId]
用:保存/错误提示 DesignAlert;顶部操作 DesignButton;需要处状态标签 DesignBadge。
5.6 /projects/[projectId]/email-themes
用:区块容器 DesignCard;视口/设备选择器 DesignPillToggle;状态消息 DesignAlert;主题状态徽章 DesignBadge;操作 DesignButton、DesignMenu。
避免:DesignPillToggle 已支持相同行为时自定义 ViewportSelector。
5.7 /projects/[projectId]/email-themes/[themeId]
用:状态反馈 DesignAlert;操作 DesignButton;可选分段控件 DesignPillToggle。
6) 语义映射规则
所有页面保持一致的状态色/variant 映射:
| 语义 | Alert variant | Badge color |
|---|---|---|
| 成功/完成/已发送 | success |
green |
| 错误/失败 | error |
red |
| 警告/需注意 | warning |
orange |
| 信息/中性更新 | info |
blue 或 cyan |
卡片/Tab/切换器的 gradient 映射:
| 颜色 | 语义 |
|---|---|
| Blue | 主导航/状态 |
| Cyan | 分析/活动 |
| Purple | 模板/主题或创意工具 |
| Green | 成功/完成 |
| Orange | 警告/谨慎 |
| Default | 中性/系统区块 |
7) 交互与动效规则
以下规则必须在自定义样式与覆盖中保留:
- 无 hover-enter 延迟;
- 用 hover-exit 过渡:
transition-* duration-150 hover:transition-none; - 控件保持干脆可读;
- 密集型后台工作流避免重度动画。
异步操作:
- 优先使用已处理 async/loading 的 design-components 原语;
- 不要吞掉异步错误;通过 design-components 原语使用现有的 alert 感知异步工具(见 4.4 中
runAsynchronouslyWithAlert的调用链)。
8) AI 可读的实现清单
提交 Dashboard UI PR 前过一遍:
- [ ] 将临时卡片替换为
DesignCard(可能时)。 - [ ] 将临时 alert 替换为
DesignAlert。 - [ ] 将临时徽章/状态 pill 替换为
DesignBadge。 - [ ] 将临时分段控件替换为
DesignPillToggle或DesignCategoryTabs。 - [ ] 将临时 row/card 列表项替换为
DesignListItemRow或DesignUserList。 - [ ] 异步操作使用
DesignButton。 - [ ] 标准字段控件使用
DesignSelectorDropdown/DesignInput。 - [ ] 交互式表格使用
DataGrid+useDataSource+createDefaultDataGridState。 - [ ] 没有为 design-components 中已有的组件引入重复的本地 wrapper。
- [ ] hover/motion 行为与本指南一致。
9) 规范代码片段(Canonical)
区块卡片
<DesignCard
title="Email Log"
subtitle="View and manage email sending history"
icon={Envelope}
gradient="default"
>
{/* content */}
</DesignCard>
语义 Alert
<DesignAlert
variant="error"
title="Failed to send email"
description="Please verify provider configuration and try again."
/>
状态徽章
<DesignBadge
label="Sent"
color="green"
icon={CheckCircle}
size="sm"
/>
视口切换
<DesignPillToggle
options={[
{ id: "desktop", label: "Desktop", icon: Desktop },
{ id: "tablet", label: "Tablet", icon: DeviceTablet },
{ id: "mobile", label: "Mobile", icon: DeviceMobile },
]}
selected={viewport}
onSelect={setViewport}
size="sm"
gradient="default"
/>
分类 Tab
<DesignCategoryTabs
categories={[
{ id: "all", label: "All", count: 42 },
{ id: "failed", label: "Failed", count: 3 },
]}
selectedCategory={category}
onSelect={setCategory}
gradient="blue"
/>
10) 反模式(不要引入)
- 创建本地
GlassCard/ChartCard组件替代DesignCard或DesignAnalyticsCard。 - 创建本地状态 pill 替代
DesignBadge。 - 创建本地分段/pill 选择器替代
DesignPillToggle。 - 在标准 Dashboard 表面用裸
Alert/Button而应使用DesignAlert/DesignButton。 - 用
DesignDataTable或裸DataTable替代DataGrid+useDataSource+createDefaultDataGridState。DesignDataTable已废弃,所有新建与迁移表格使用DataGrid(注意:table.tsx 中DesignDataTable仍存在,但它是对旧@tanstack/react-tableDataTable的封装,规范明确不再用于新表格)。 - 为常见 design-components 模式重复大段内联 class 字符串。
11) 既有 Email 表面的迁移优先级
触碰既有 email/project 页面时按此顺序迁移:
- 卡片/表面(
DesignCard,图表密集型壳用DesignAnalyticsCard)。 - 提示(
DesignAlert)。 - 徽章(
DesignBadge)。 - 切换/tab(
DesignPillToggle/DesignCategoryTabs)。 - 行/列表(
DesignListItemRow)。 - 按钮/菜单(
DesignButton/DesignMenu)。 - 表格/表单(
DataGrid、DesignInput、DesignSelectorDropdown、DesignEditableGrid)。
该顺序先获得最大的一致性收益。
12) 维护规则
每当在 Dashboard 功能中引入新的可复用视觉模式时:
- 先添加或扩展一个 design-components 组件;
- 然后在本文档中记录组件契约与推荐用法;
- 避免引入与 design-components 行为重复的永久性页面局部 UI 原语。
这条「先沉淀、后使用、再文档化」的闭环,保证了设计系统的长期演进不会被页面临时 hack 侵蚀——也是 DESIGN-GUIDE.md 作为「真相之源」(source of truth)被同时写给人类开发者和 AI Agent 的根本原因:任何 AI 在生成或重构 Dashboard UI 代码时,都能以同一份契约产出风格一致、语义正确、异步安全的结果。