数据平台 UI 设计与视觉规范：从 M3 到可扩展的专业工作台

数据平台的界面需要帮助用户持续完成筛选、比较、批量操作、任务配置和结果复核。视觉规范既要让页面看起来一致，也要让用户看懂当前数据范围、任务状态与操作后果。

Data Flywheel 的设计讨论提出了两个明确诉求：一是按钮、字体、字号、颜色、层级和布局都有成熟依据，二是后续能够扩展视频时间轴、标注画布与插件面板。讨论后来收敛到偏好公开的 Material Design 3（M3） 视觉语言，并保留当前 React 组件实现的可控性。

本文结合 2026-09-06 阅读到的项目代码，讨论如何把这两个诉求落实为规范。代码已有 M3 风格的语义变量和基础组件，但这不等于已经完整实现或验证了全部 M3 规范。

1. 设计规范、组件库和页面模式是三层东西

shadcn/ui 强调将组件代码交给项目管理，Base UI 提供无预设样式的 React 交互基础。因此，它们提供实现自主权，也意味着团队需要维护视觉适配和组件回归。参见 shadcn 文档与 Base UI 介绍。

选择 M3 可以减少重复发明基础规则，但仍要设计领域工作流。一个成熟按钮不会自动决定视频预览该放哪、跨页选择应如何计数、验收驳回后应该提示什么。

2. M3、GM3 与 Cloudscape 怎样比较

本文以公开 Material Design 3 为可追踪的规范入口。聊天中的 GM3 用于指代 Google 产品中的 Material 3 相关落地；这个简称需要结合来源理解，不应假定它代表一套可直接安装、完整公开、适配当前 React 项目的独立组件包。

Cloudscape 的模式目录提供资源列表、分栏查看、筛选、详情和多步创建等指导，适合借鉴工作流组织。参见 Cloudscape Patterns。这不意味着需要让一半页面采用 Cloudscape 外观，另一半采用 M3。

对当前项目的建议是：保持一个视觉主规范，借鉴其他体系中合适的业务模式，并统一转译到现有组件。 如果未来更重视直接使用配套企业组件而非深入修改源码，则可以重新评估整体采用 Cloudscape；这属于取舍变化，而非设计水平排名。

还应区分设计规范与实现库的维护状态。截至本次核对，Google 的 Material Web 仓库注明处于维护模式。不能仅凭“M3 是 Google 的设计”就假定任意 Web 实现都具有同样的维护承诺。

3. 先建立语义变量，避免逐页调色

当前 apps/web/src/App.css 已使用如下映射。这里只摘取少量代码说明结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

:root {
  --md-sys-color-primary: #315da8;
  --md-sys-color-on-primary: #ffffff;
  --md-sys-color-surface-container-lowest: #ffffff;
  --md-sys-color-on-surface: #24272c;

  --primary: var(--md-sys-color-primary);
  --primary-foreground: var(--md-sys-color-on-primary);
  --card: var(--md-sys-color-surface-container-lowest);
  --card-foreground: var(--md-sys-color-on-surface);
}

primary 表达主要操作色，on-primary 表达其上的内容色；组件应消费成对语义，而不是在每个按钮上硬编码蓝色背景和白色文字。图表、表格和插件面板也应复用这些语义。

项目还定义了 success、warning 等业务状态变量。即使名字使用 md-sys 前缀，也不能因此视作 M3 官方标准角色；建议明确区分继承自规范的变量与平台新增语义，并记录用途。

数据状态不宜靠颜色猜测：运行中、成功、失败、暂停、排队应同时有文字或图标。主色主要服务操作与选择，避免所有 KPI、卡片边框和分类标签都抢占视觉注意力。

4. 字体、字号和密度要有清晰层级

以下是当前 CSS 中已有的文字层级，作为项目现状记录，不是宣称这些值都是 M3 唯一标准：

当前字体栈包括 Roboto、Noto Sans SC 和系统回退字体。声明字体名称不代表浏览器一定安装或加载了字体，中文回退、字重和离线部署都需要验证。

建议把间距也收敛为少量语义：字段内部、字段之间、容器内部、区块之间。例如使用 4、8、12、16、24、32 px 作为团队间距刻度，再映射到组件用途；这是一套建议起点，不应代替对长中文标签与复杂表单的检查。

当前事件表格行高为 52 px、表头为 56 px，偏向易读的默认密度。若后续需要紧凑模式，可通过统一 density 变量调整行高、单元格内边距和控件尺寸，而不是每页自行缩小字体。

5. 从标准页面到专业工作区

建议优先维护四种页面模板：

当前需求中心已有响应式列表和详情时间线，可以作为列表／详情模板的起点。视频检索更适合缩略图网格与详情分栏；精确标注则需要画布、快捷键、时间轴和撤销历史，不宜全部挤进普通卡片页。

列表需要明确“选中当前页”还是“选中全部符合条件的数据”。跨页批量操作显示范围摘要与数量；破坏性操作的确认文字应说明作用对象，不能统一写“确定吗”。

响应式不等于把所有区域缩窄：小屏下可以把列表与详情切为单栏，次要信息折叠。复杂标注工作区如果只支持桌面尺寸，应明确告知并保持基本浏览能力。

6. 把交互状态写入组件规范

当前 Button 基于 Base UI 与统一 variants，包含尺寸、焦点环、禁用态和状态层。需要进一步保证每个业务组件都有完整状态，而不是只有设计稿中的默认态。

项目的看板请求已有 isFallback 区分演示降级数据，401／403 不走该降级。生产产品应保持这种状态区分，并显著标记演示数据；模拟指标不能与真实运行结果混用。

对百分比进度，只有总量可定义且统计可靠时才显示确定百分比。不确定任务可以展示阶段、已处理数量和最近心跳，不能把耗时估计伪装成完成度。

7. 表格和插件也必须进入同一套规范

事件页面的 AG Grid 通过 themeQuartz.withParams 复用主色、表面色、文字色与边框变量，说明第三方组件可以接入统一视觉系统。但主题配色之外，还要检查表头、排序、选择、焦点、错误状态和密度。

插件扩展建议只使用平台公开的 Token、基础组件与布局插槽。插件可以声明动作、参数和结果类型，但不自行覆盖全局字体、主色与层级。需要特殊画布时允许领域设计，同时保留快捷键、焦点和操作反馈约定。

若允许不受信任的前端扩展，视觉一致性与执行隔离应分别设计。共享 CSS 变量不代表应共享全部页面执行权限，详见 Operator as Plugin。

8. 用验证维护规范

文字对比度可以使用 WCAG 2.2 的标准作为检查依据：一般文字至少 4.5:1，符合标准定义的大号文字至少 3:1；装饰、禁用等例外须按规范具体判断。参见 W3C 对比度说明。配色达标也不等于整个页面满足全部可访问性要求。

建议将验证固定在已有工程链路中：

• Storybook 展示基础组件、长中文、错误、禁用和加载状态。
• 组件测试验证行为，关键流程用 Playwright 验证导航与操作。
• 视觉检查覆盖窄屏、长文本、空数据、多条错误与高密度列表。
• 人工使用键盘走完表单、菜单、弹窗与退出流程，确认焦点恢复。
• 动效尊重减少运动偏好；颜色变化、图标和声音均不作为唯一反馈。

当前项目已引入相关工具，但工具存在不证明所有页面已覆盖。新增组件时，应把规范、实现、示例与验证一起维护。

M3 可以成为稳定的视觉基础；数据平台特有的时间轴、检索与工作流需要逐步沉淀为领域组件。技术框架怎样承接这些责任，见 前后端技术框架选型。