12 KiB
Raw Permalink Blame History

WishForge 设计规范与设计令牌 (Design Tokens & Component Rules)

适用范围:WishForge 前端 (apps/web)
设计语言与基调:工程严谨、数据透彻、零冗余装饰、轻盈沉稳。以最简文案规范(参考 droboticflow copy-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)

  • 空状态:禁止单调的白板或无意义灰色图标。必须包含:
    1. 32px 扁平线条业务图标(如 Inbox、FolderSearch、ShieldCheck);
    2. 极简标题(如「暂无待审批发布」);
    3. 一句简明上下文;
    4. 恢复入口(主操作按钮或一键清空筛选)。
  • 骨架屏 (Skeleton):彻底替代粗暴的全局居中 Spinner。
    • 使用 @keyframes wf-pulse(0% 灰度 0.06,50% 灰度 0.15);
    • 骨架严格按照目标卡片/表格的实际网格尺寸渲染占位条,彻底消除 CLS(累计布局位移)。

4. globals.css 拆分方案与迁移顺序 (Refactor Roadmap)

4.1 拆分架构目标

将 3580 行单体 CSS 解耦为:

  1. 全局核心层 (app/globals.css, ~200 行):仅保留 CSS Reset、全局 @theme / :root Tokens 变量定义、全局 Typography 字体栈与通用工具类。
  2. 基础 UI 组件层 (components/ui.module.css, ~400 行):Buttons, Modals, Forms, Panels, Badges, EmptyStates, Skeletons。
  3. 领域特性层 (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. 阶段 1:全局 Tokens 注入 (无风险)
    • 在 globals.css 头部注入本规范定义的 --wf-* 语义变量系统,将现有的 --teal、--navy 等指向新变量作为向后兼容层。
  2. 阶段 2:公共组件模块化 (components/ui.module.css)
    • 提取 button, panel, modal, notice, status, empty-state 到 CSS Module。
    • components/ui.tsx 切换使用 CSS Module 局部类名。
  3. 阶段 3:按业务领域页面逐一解耦 (重点是四大核心页)
    • 先为新页创建独立 CSS Module(如 cluster-resources.module.css);
    • 逐步将 runs.tsx、releases.tsx、copilot.tsx 页面级私有类(如 .run-timeline、.diff-container)迁移至对应的 .module.css。
  4. 阶段 4:老旧样式剪除与死代码清理
    • 借助 CSS 检查工具扫描 globals.css 中未被引用的历史类名并删除,最终将 globals.css 行数控制在 250 行以内。