12 KiB
12 KiB
WishForge 设计规范与设计令牌 (Design Tokens & Component Rules)
适用范围:WishForge 前端 (
apps/web)
设计语言与基调:工程严谨、数据透彻、零冗余装饰、轻盈沉稳。以最简文案规范(参考 droboticflowcopy-guidelines.md)为底座。
1. 颜色系统 (Color Tokens)
将原本分散、硬编码的 131 种颜色统一归纳为高辨识度、高无障碍对比度(WCAG AA/AAA,文字对比度 ≥ 4.5:1)的语义化色板。
1.1 品牌色与中性色 (Brand & Neutrals)
| 语义变量名 | Hex 建议值 | 对比度与用途 | 迁移映射说明 |
|---|---|---|---|
--wf-brand-primary |
#0f766e (Teal-700) |
核心主动作 (CTA)、主要链接、关键高亮。比老旧 #168574 更温润且稳健 |
替换老 --teal 及相关变体 |
--wf-brand-hover |
#0d625b (Teal-800) |
主动作 hover / active 态 | 替换老 --teal-dark |
--wf-brand-surface |
#f0fdfa (Teal-50) |
选中卡片浅底、高亮徽标背景 | 替换老 --teal-pale、#eaf5f1 |
--wf-brand-border |
#ccfbf1 (Teal-100) |
品牌浅色边框 | 替换分散的浅绿色边框 |
--wf-navy-dark |
#0f172a (Slate-900) |
侧边栏底色、深色终端背景、强强调文字 | 替换老 --navy: #102031 |
--wf-bg-app |
#f8fafc (Slate-50) |
控制台主背景、灰底卡片槽位 | 保持并规范 --bg |
--wf-bg-surface |
#ffffff |
面板卡片、模态弹窗、下拉菜单纯白背景 | 替换 --surface |
--wf-bg-subtle |
#f1f5f9 (Slate-100) |
表头背景、代码块背景、弱卡片背景 | 替换 #f6f8fb、#fbfcfe、#edf2f6 |
--wf-border-subtle |
#e2e8f0 (Slate-200) |
卡片常规描边、表格行分割线 | 替换老 --border: #e1e7ef、#d8e0ea |
--wf-border-strong |
#cbd5e1 (Slate-300) |
输入框聚焦外沿、关键分割线、Tab底边 | 替换 #b4c1d0 |
--wf-text-strong |
#0f172a (Slate-900) |
大标题、加粗数值、核心状态 | 替换 --ink: #122033 |
--wf-text-body |
#334155 (Slate-700) |
正文描述、表单输入文字、表格通用项 | 保证 7:1 极高对比度 |
--wf-text-muted |
#64748b (Slate-500) |
次要说明、时间戳、辅助标签(4.6:1 达标) | 替换老 --muted: #5b6b80 |
--wf-text-disabled |
#94a3b8 (Slate-400) |
禁用态文字、占位符文字 | 替换零散灰色 |
1.2 状态反馈色 (State Feedbacks)
| 语义状态 | 主前景色 (Solid/Text) | 浅背景底色 (Surface) | 边框色 (Border) | 业务语境应用 |
|---|---|---|---|---|
| 成功 (Success) | #15803d (Green-700) |
#f0fdf4 (Green-50) |
#bbf7d0 (Green-200) |
运行成功、门禁全绿、服务就绪、健康 |
| 警告 (Warning) | #b45309 (Amber-700) |
#fffbeb (Amber-50) |
#fde68a (Amber-200) |
排队等待、需人工确认、超卖预警、待审 |
| 危险 (Danger) | #b91c1c (Red-700) |
#fef2f2 (Red-50) |
#fecaca (Red-200) |
运行失败、门禁阻断、容器 OOM、异常崩溃 |
| 信息 (Info) | #0369a1 (Sky-700) |
#f0f9ff (Sky-50) |
#bae6fd (Sky-200) |
阶段通知、只读说明、执行器准备中 |
1.3 核心分级风控色 (Risk Level Hierarchy)
用于防事故门禁(G4)与发布审批,严格杜绝误操作:
| 风险级别 | 主题色与 Tag 表现 | 适用范围与阻断规则 | 审批要求与视觉指示 |
|---|---|---|---|
| 低风险 (Low) | 文字 #15803d底色 #f0fdf4边框 #bbf7d0 |
纯前端样式、文档修订、只读配置、无破坏性脚本 | 客户负责人自主审批。 浅绿扁平徽标,小勾图标。 |
| 中风险 (Medium) | 文字 #b45309底色 #fffbeb边框 #fde68a |
后端普通业务逻辑变更、依赖小版本升级、轻量配置增删 | 客户负责人审批,双重确认提示。 明黄警示徽标。 |
| 高风险 (High) | 文字 #b91c1c底色 #fef2f2边框 #ef4444 (实线 1.5px) |
涉及数据库迁移/破坏性改动、权限放大、节点资源超限/缩为0、测试基线篡改 | 必须平台方技术审批,客户无权单独发布。 刺目朱红、外圈呼吸脉冲边框、双人签名卡。 |
2. 标尺阶梯与排版 (Type & Layout Scales)
2.1 字号与行高阶梯 (Typography)
统一采用系统字体栈:Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif。代码/数字等宽字体栈:"JetBrains Mono", SFMono-Regular, Consolas, monospace。
| Token | 字号 / 行高 | 字重 (Weight) | 推荐使用场景 |
|---|---|---|---|
--wf-font-xs |
11px / 16px |
400 / 500 | 徽章 Tag、细小时间戳、辅助注释 |
--wf-font-sm |
12px / 18px |
400 / 500 / 600 | 表格正文、键值对标签、代码片段、终端日志 |
--wf-font-base |
14px / 20px |
400 / 500 | 页面正文字体、输入框文本、按钮文字 |
--wf-font-md |
16px / 24px |
600 | 卡片二级标题、列表分组标题、弹窗标题 |
--wf-font-lg |
20px / 28px |
600 | 核心模块标题、阶段大步标题 |
--wf-font-xl |
24px / 32px |
700 | 页面一级标题 (PageHeader)、关键总账数字 |
2.2 间距网格 (Spacing Grid - 4px/8px System)
| Token | 数值 | 经典对齐场景 |
|---|---|---|
--wf-space-1 |
4px |
图标与文字间隙、Tag 内部小间距 |
--wf-space-2 |
8px |
紧凑表单控件行距、按钮内边距上下、表格紧凑单元格 |
--wf-space-3 |
12px |
标准表单控件行距、按钮内边距左右、卡片内小组件间距 |
--wf-space-4 |
16px |
面板 Padding、列表项间距、标准栅格缝隙 (Gap) |
--wf-space-6 |
24px |
页面区块大间隔、PageHeader 与主内容分界 |
--wf-space-8 |
32px |
页面顶部与底部大外边距、空状态垂直撑开高度 |
2.3 圆角、边框与投影 (Radius, Borders & Elevation)
:root {
/* 圆角规范 */
--wf-radius-sm: 4px; /* 小型 Tag、复选框、代码片段 */
--wf-radius-md: 6px; /* 标准按钮、输入框、常规卡片内元素 (取代原本古怪的 7px) */
--wf-radius-lg: 10px; /* 核心 Panel、Modal 对话框、悬浮浮窗 */
--wf-radius-full: 9999px; /* 胶囊型 Status 指示器、头像 */
/* 边框规范 */
--wf-border-width: 1px;
--wf-border-focus: 2px solid var(--wf-brand-primary);
/* 阴影层级 */
--wf-shadow-xs: 0 1px 2px 0 rgba(15, 23, 42, 0.05); /* 平铺卡片微投影 */
--wf-shadow-sm: 0 1px 3px 0 rgba(15, 23, 42, 0.1), 0 1px 2px -1px rgba(15, 23, 42, 0.1);
--wf-shadow-md: 0 4px 6px -1px rgba(15, 23, 42, 0.1), 0 2px 4px -2px rgba(15, 23, 42, 0.1); /* 下拉菜单、Hover浮起 */
--wf-shadow-lg: 0 10px 15px -3px rgba(15, 23, 42, 0.1), 0 4px 6px -4px rgba(15, 23, 42, 0.1); /* Modal、侧滑 Copilot */
}
3. 标准组件规范 (Component Specs)
3.1 按钮 (Button)
- Primary:实心背景
var(--wf-brand-primary),文字纯白,无外边框。Hover 为var(--wf-brand-hover)。高度统一为 34px(移动端 40px),内边距0 14px。 - Secondary:纯白底
var(--wf-bg-surface),边框1px solid var(--wf-border-subtle),文字var(--wf-text-strong)。Hover 浅灰底var(--wf-bg-subtle)。 - Danger:浅红底
var(--wf-danger-surface),红边框var(--wf-danger-border),文字var(--wf-danger-solid)。涉及破坏性操作(如强制回滚、终止任务)。 - Ghost:无底色无描边,Hover 浅灰底,用于折叠展开、次要辅助操作。
- Busy 状态:禁用指针,文案透明度 0.6,内置 14px Lucide Spinner 平滑旋转,严禁产生宽度抖动。
3.2 表格与数据列 (Table & Data Grid)
- 表头 (Th):高度 36px,背景
var(--wf-bg-subtle),文字var(--wf-text-muted),字号12px,大写字母略微间距,底边1px solid var(--wf-border-subtle)。 - 单元格 (Td):高度 48px(紧凑模式 40px),垂直居中,正文字号
13px。斑马纹可选,Hover 单行整体着色浅蓝/灰var(--wf-brand-surface)。 - 操作列:靠右对齐,操作按钮紧凑化排列。
3.3 面板与卡片 (Panel & Card)
- 容器采用
var(--wf-bg-surface),描边1px solid var(--wf-border-subtle),圆角var(--wf-radius-lg),阴影var(--wf-shadow-xs)。 - Panel Header:高度 48px,左右 flex 布局,左侧标题
15px粗体加图标,右侧次要操作或统计标签。 - 移除非必要的多层嵌套内边框,减少视觉噪点。
3.4 状态与徽标 (Badges & Statuses)
- 统一为 圆角胶囊 (Capsule) 或 微圆角矩形 (Tag)。
- 必须包含 前置实体微圆点 (Status Dot, 6px):
- 成功:绿点呼吸(运行中为青蓝点脉冲);
- 待审/等待:明黄点常亮;
- 失败/告警:鲜红点常亮。
- 杜绝纯依靠颜色传递信息,文案必须严格使用受控词汇(如「健康」、「待审批」、「平台审批中」)。
3.5 表单与输入控件 (Form Controls)
- 高度 36px,边框
1px solid var(--wf-border-strong),圆角var(--wf-radius-md)。 - 聚焦态统一为
box-shadow: 0 0 0 3px rgba(15, 118, 110, 0.15)加主色实线,替代粗暴的全局黑色粗外框。 - 错误态:边框标红,输入框下方紧跟单行 12px 错误提示与 Alert 图标,不造成表单高度突变。
3.6 空状态与加载骨架屏 (EmptyState & Skeleton)
- 空状态:禁止单调的白板或无意义灰色图标。必须包含:
- 32px 扁平线条业务图标(如
Inbox、FolderSearch、ShieldCheck); - 极简标题(如「暂无待审批发布」);
- 一句简明上下文;
- 恢复入口(主操作按钮或一键清空筛选)。
- 32px 扁平线条业务图标(如
- 骨架屏 (Skeleton):彻底替代粗暴的全局居中 Spinner。
- 使用
@keyframes wf-pulse(0% 灰度 0.06,50% 灰度 0.15); - 骨架严格按照目标卡片/表格的实际网格尺寸渲染占位条,彻底消除 CLS(累计布局位移)。
- 使用
4. globals.css 拆分方案与迁移顺序 (Refactor Roadmap)
4.1 拆分架构目标
将 3580 行单体 CSS 解耦为:
- 全局核心层 (
app/globals.css, ~200 行):仅保留 CSS Reset、全局@theme / :rootTokens 变量定义、全局 Typography 字体栈与通用工具类。 - 基础 UI 组件层 (
components/ui.module.css, ~400 行):Buttons, Modals, Forms, Panels, Badges, EmptyStates, Skeletons。 - 领域特性层 (Feature CSS Modules):
features/copilot.module.css(Copilot 对话流、引用卡、转 Wish 界面)features/runs.module.css(时间线、门禁网格、Diff 对比、四栏交付报告)features/releases.module.css(审批流、改动核验单、回滚确认抽屉)features/cluster-resources.module.css(总账看板、节点负载、服务列表、存储卷)features/dashboard.module.css(工作概览)
4.2 渐进式迁移四阶段 (Migration Phases)
[阶段 1: 变量沉淀] -> [阶段 2: 基础 UI 抽取] -> [阶段 3: 核心 4 页迁移] -> [阶段 4: 缩容清理]
- 阶段 1:全局 Tokens 注入 (无风险)
- 在
globals.css头部注入本规范定义的--wf-*语义变量系统,将现有的--teal、--navy等指向新变量作为向后兼容层。
- 在
- 阶段 2:公共组件模块化 (
components/ui.module.css)- 提取
button,panel,modal,notice,status,empty-state到 CSS Module。 components/ui.tsx切换使用 CSS Module 局部类名。
- 提取
- 阶段 3:按业务领域页面逐一解耦 (重点是四大核心页)
- 先为新页创建独立 CSS Module(如
cluster-resources.module.css); - 逐步将
runs.tsx、releases.tsx、copilot.tsx页面级私有类(如.run-timeline、.diff-container)迁移至对应的.module.css。
- 先为新页创建独立 CSS Module(如
- 阶段 4:老旧样式剪除与死代码清理
- 借助 CSS 检查工具扫描
globals.css中未被引用的历史类名并删除,最终将globals.css行数控制在 250 行以内。
- 借助 CSS 检查工具扫描