Hexclave Dashboard 设计规范实践指南:design-components 组件体系与 UI 开发标准

原创2026-10-08 13:45:011,849 阅读
文章标签:后端认证鉴权前端MCP 服务

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 对 async onClick 的支持)。

该原则的直接证据在于目录结构与依赖关系: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 使用优先级

  1. 组件 variant(DesignAlert、DesignBadge、DesignCard 的 gradient、tab/toggle 的 gradient)。
  2. 语义 Tailwind token(bg-background、text-foreground、text-muted-foreground、border-border)。
  3. 用于微妙表面的透明度层(如 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-visible ring。
  • 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-escape CSS 逃逸层,让 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-sm overlay)。
  • 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 时,通过 headerContent prop 保留任何摘要卡片、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]/emails
  • apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/email-drafts
  • apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/email-templates
  • apps/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-table DataTable 的封装,规范明确不再用于新表格)。
  • 为常见 design-components 模式重复大段内联 class 字符串。

11) 既有 Email 表面的迁移优先级

触碰既有 email/project 页面时按此顺序迁移:

  1. 卡片/表面(DesignCard,图表密集型壳用 DesignAnalyticsCard)。
  2. 提示(DesignAlert)。
  3. 徽章(DesignBadge)。
  4. 切换/tab(DesignPillToggle / DesignCategoryTabs)。
  5. 行/列表(DesignListItemRow)。
  6. 按钮/菜单(DesignButton / DesignMenu)。
  7. 表格/表单(DataGrid、DesignInput、DesignSelectorDropdown、DesignEditableGrid)。

该顺序先获得最大的一致性收益。

12) 维护规则

每当在 Dashboard 功能中引入新的可复用视觉模式时:

  • 先添加或扩展一个 design-components 组件;
  • 然后在本文档中记录组件契约与推荐用法;
  • 避免引入与 design-components 行为重复的永久性页面局部 UI 原语。

这条「先沉淀、后使用、再文档化」的闭环,保证了设计系统的长期演进不会被页面临时 hack 侵蚀——也是 DESIGN-GUIDE.md 作为「真相之源」(source of truth)被同时写给人类开发者和 AI Agent 的根本原因:任何 AI 在生成或重构 Dashboard UI 代码时,都能以同一份契约产出风格一致、语义正确、异步安全的结果。

登录后查看全文
hexclave