init

2026-03-25 23:59:29 +08:00
parent 7964ce1033
commit 23e5df0364
46 changed files with 4168 additions and 254 deletions
@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json.schemastore.org/design-tokens.json",
+  "name": "Gemold UI",
+  "version": "2.0.0",
+  "modes": ["light", "dark"],
+  "tokens": {
+    "color": {
+      "brand": {
+        "50": { "value": "#eef2ff" },
+        "100": { "value": "#e0e7ff" },
+        "200": { "value": "#c7d2fe" },
+        "300": { "value": "#a5b4fc" },
+        "400": { "value": "#818cf8" },
+        "500": { "value": "#6366f1" },
+        "600": { "value": "#4f46e5" },
+        "700": { "value": "#4338ca" },
+        "800": { "value": "#3730a3" },
+        "900": { "value": "#312e81" }
+      },
+      "neutral": {
+        "50": { "value": "#fafafa" },
+        "100": { "value": "#f4f4f5" },
+        "200": { "value": "#e4e4e7" },
+        "300": { "value": "#d4d4d8" },
+        "400": { "value": "#a1a1aa" },
+        "500": { "value": "#71717a" },
+        "600": { "value": "#52525b" },
+        "700": { "value": "#3f3f46" },
+        "800": { "value": "#27272a" },
+        "900": { "value": "#18181b" }
+      },
+      "semantic": {
+        "success": { "value": "#16a34a" },
+        "warning": { "value": "#d97706" },
+        "danger": { "value": "#dc2626" },
+        "info": { "value": "{color.brand.600}" }
+      },
+      "surface": {
+        "bgPrimary": {
+          "value": {
+            "light": "#ffffff",
+            "dark": "#0a1020"
+          }
+        },
+        "bgSecondary": {
+          "value": {
+            "light": "#f8fafc",
+            "dark": "#0b1326"
+          }
+        },
+        "bgTertiary": {
+          "value": {
+            "light": "#f1f5f9",
+            "dark": "#0d1930"
+          }
+        },
+        "borderDefault": {
+          "value": {
+            "light": "rgba(15, 23, 42, 0.12)",
+            "dark": "rgba(255, 255, 255, 0.10)"
+          }
+        }
+      },
+      "text": {
+        "primary": {
+          "value": {
+            "light": "#111827",
+            "dark": "#f3f4f6"
+          }
+        },
+        "secondary": {
+          "value": {
+            "light": "#374151",
+            "dark": "#d1d5db"
+          }
+        },
+        "tertiary": {
+          "value": {
+            "light": "#6b7280",
+            "dark": "#9ca3af"
+          }
+        }
+      }
+    },
+    "typography": {
+      "fontFamily": {
+        "sans": {
+          "value": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif"
+        },
+        "mono": {
+          "value": "'SF Mono', Monaco, Consolas, monospace"
+        }
+      },
+      "fontSize": {
+        "xs": { "value": "0.75rem" },
+        "sm": { "value": "0.875rem" },
+        "base": { "value": "1rem" },
+        "lg": { "value": "1.125rem" },
+        "xl": { "value": "1.25rem" },
+        "2xl": { "value": "1.5rem" },
+        "3xl": { "value": "1.875rem" }
+      },
+      "fontWeight": {
+        "normal": { "value": 400 },
+        "medium": { "value": 500 },
+        "semibold": { "value": 600 },
+        "bold": { "value": 700 }
+      }
+    },
+    "spacing": {
+      "1": { "value": "0.25rem" },
+      "2": { "value": "0.5rem" },
+      "3": { "value": "0.75rem" },
+      "4": { "value": "1rem" },
+      "5": { "value": "1.25rem" },
+      "6": { "value": "1.5rem" },
+      "8": { "value": "2rem" },
+      "10": { "value": "2.5rem" },
+      "12": { "value": "3rem" }
+    },
+    "radius": {
+      "sm": { "value": "0.5rem" },
+      "md": { "value": "0.75rem" },
+      "lg": { "value": "1rem" },
+      "xl": { "value": "1.25rem" },
+      "full": { "value": "9999px" }
+    },
+    "shadow": {
+      "xs": { "value": "0 1px 2px rgba(15, 23, 42, 0.06)" },
+      "sm": { "value": "0 2px 10px rgba(15, 23, 42, 0.08)" },
+      "md": { "value": "0 12px 30px rgba(15, 23, 42, 0.12)" }
+    },
+    "motion": {
+      "easing": {
+        "standard": { "value": "cubic-bezier(0.4, 0, 0.2, 1)" }
+      },
+      "duration": {
+        "fast": { "value": "140ms" },
+        "normal": { "value": "180ms" },
+        "slow": { "value": "260ms" }
+      },
+      "reducedMotion": {
+        "value": "prefers-reduced-motion: reduce"
+      }
+    }
+  }
+}
@@ -0,0 +1,49 @@
+## 1. Product Overview
+对你现有前端进行「全量视觉与交互」重构：统一设计体系与设计令牌（Design Tokens），并达到 WCAG 2.1 AA。
+交付要求包含像素级验收标准、灰度发布策略与一键回滚预案，确保可控上线与风险可管理。
+
+## 2. Core Features
+
+### 2.1 User Roles
+| 角色 | 参与方式 | 核心权限 |
+|------|----------|----------|
+| 设计师 | 项目成员 | 维护设计体系规范；输出像素级标注与验收基线 |
+| 前端开发 | 项目成员 | 落地设计令牌与组件；改造页面交互；接入自动化验收 |
+| QA/测试 | 项目成员 | 执行无障碍与视觉回归验收；管理缺陷闭环 |
+| 发布负责人 | 项目成员 | 配置灰度、监控指标、执行回滚 |
+
+### 2.2 Feature Module
+本次重构需求由以下最小页面集合承载（现有业务页面不新增路由，仅整体替换视觉与交互实现）：
+1. **全站现有业务页面（整体改造范围）**：统一设计体系应用、交互一致性、无障碍支持、像素级对齐。
+2. **设计体系与组件库（内部）**：设计令牌预览、组件展示/用法、可访问性与交互规范说明。
+3. **灰度发布与验收面板（内部）**：灰度配置、验收结果汇总、回滚操作与审计。
+
+### 2.3 Page Details
+| Page Name | Module Name | Feature description |
+|-----------|-------------|---------------------|
+| 全站现有业务页面（整体改造范围） | 设计体系应用 | 应用统一色板/字体/间距/圆角/阴影等令牌；保证跨页面一致性与可复用性 |
+| 全站现有业务页面（整体改造范围） | 交互一致性 | 统一表单校验/错误提示/加载态/空态/弹窗/提示条等行为与文案；保持可预测的交互反馈 |
+| 全站现有业务页面（整体改造范围） | WCAG 2.1 AA | 支持键盘可达与可见焦点；语义化结构与必要 ARIA；颜色对比度达标；支持减少动效偏好 |
+| 全站现有业务页面（整体改造范围） | 像素级验收 | 以设计基线为准对齐尺寸/间距/字号/行高；定义容差规则与截图基线；记录差异与闭环 |
+| 设计体系与组件库（内部） | Design Tokens | 浏览/搜索令牌（颜色、排版、间距、动效、z-index 等）；展示令牌到 CSS 变量/类名/组件 props 的映射 |
+| 设计体系与组件库（内部） | 组件与模式 | 展示基础组件与复合模式（表单、表格、弹窗等）；提供交互状态（hover/focus/disabled/loading/invalid） |
+| 设计体系与组件库（内部） | 无障碍规范 | 提供组件级 a11y 清单（键盘、读屏、对比度、焦点顺序）；给出 Do/Don’t 与示例 |
+| 灰度发布与验收面板（内部） | 灰度发布 | 配置灰度策略（按环境/用户段/百分比/白名单）；实时显示启用状态与版本信息 |
+| 灰度发布与验收面板（内部） | 验收总览 | 汇总自动化 a11y 扫描、视觉回归、关键路径冒烟结果；支持按版本/页面/组件查看 |
+| 灰度发布与验收面板（内部） | 回滚与审计 | 一键关闭灰度/回滚到上个稳定版本；记录操作人、时间、原因、影响范围 |
+
+## 3. Core Process
+**设计→开发→测试→灰度→全量→回滚（可选）**
+- 设计师流程：沉淀设计体系（颜色/排版/栅格/动效/组件状态）→ 输出令牌字典与组件规范 → 提供像素级标注与验收基线截图。
+- 前端开发流程：令牌工程化（生成 CSS 变量/主题）→ 组件库落地并替换旧组件 → 分批改造现有页面（优先核心路径）→ 接入自动化 a11y 与视觉回归。
+- QA/测试流程：执行无障碍检查（键盘、读屏、对比度）→ 执行视觉回归与关键路径冒烟 → 缺陷闭环并冻结验收基线。
+- 发布负责人流程：开启小流量灰度→ 观察关键指标与错误率 → 分阶段扩大→ 全量；如异常则关闭灰度并回滚。
+
+```mermaid
+graph TD
+  A["全站现有业务页面"] --> B["设计体系与组件库（内部）"]
+  B --> A
+  A --> C["灰度发布与验收面板（内部）"]
+  C --> A
+  C --> D["回滚到上一稳定版本"]
+```
@@ -0,0 +1,89 @@
+# 交互走查（UI v2）
+
+## 1. 动效参数（Motion Tokens）
+- Easing
+  - `--ease-default`: `cubic-bezier(0.4, 0, 0.2, 1)`
+- Duration
+  - `--duration-fast`: `140ms`（hover/press/focus 的轻量过渡）
+  - `--duration-normal`: `180ms`（弹窗/抽屉等容器级过渡）
+  - `--duration-slow`: `260ms`（页面级淡入、复杂布局切换）
+- Reduced Motion
+  - 当 `prefers-reduced-motion: reduce`：所有 transition/animation 时长强制为 `1ms`，并关闭平滑滚动。
+
+## 2. 微交互规范（Micro-interactions）
+- Button
+  - Hover：轻微提升（如 `translateY(-1px)`）+ 阴影增强
+  - Active：回落（`translateY(0)`）+ 阴影减弱
+  - Focus-visible：3px 可见焦点环（UI v2 使用 indigo 系）
+- Input / Select
+  - Focus：边框高亮 + 3px 焦点环
+  - Invalid：`aria-invalid="true"` 时显示错误态（颜色 + 文案）
+- Loading
+  - 页面级：使用非阻塞 Loading（避免焦点丢失/Tab 被截断）
+  - 按钮级：loading 状态应禁用重复提交并提示“处理中”
+
+## 3. 键盘与焦点顺序（Tab Order）
+### 3.1 全局
+- 焦点顺序必须与视觉顺序一致（从左到右、从上到下）。
+- 页面切换（路由变化）后：
+  - 默认把焦点设置到页面标题 `h1`（若可实现）或第一个可交互元素。
+
+### 3.2 组件级
+- 导航链接（`a`）
+  - `Tab` 聚焦
+  - `Enter` 触发导航
+- Button（`button`）
+  - `Tab` 聚焦
+  - `Enter/Space` 触发
+- 输入框（`input`/`textarea`）
+  - `Tab` 聚焦
+  - `Esc` 不应清空内容（除非明确说明）
+- Select（`select`）
+  - `Tab` 聚焦
+  - `Arrow` 在打开态变更选项
+
+### 3.3 模态框（Modal）
+- 打开时：
+  - 焦点移动到第一个可交互控件（或标题 + 关闭按钮）。
+- 关闭时：
+  - 焦点回到触发打开的按钮。
+- `Esc`：关闭（如果业务允许）。
+
+## 4. 无障碍标签与语义（WCAG 2.1 AA 关键点）
+### 4.1 颜色对比
+- 正文、按钮文字、表单占位与边框需满足 AA 对比度要求。
+- 通过令牌层保证：`--text-primary/secondary/tertiary` 与 `--bg-*` 配对达标。
+
+### 4.2 表单
+- 每个输入控件必须有可见 `label`。
+- 错误提示与输入框绑定：
+  - 输入框：`aria-invalid="true"`
+  - 错误文本：为其生成 `id` 并用 `aria-describedby` 关联
+- 提交失败：聚焦到第一个错误字段并播报错误（可通过 `aria-live`）。
+
+### 4.3 图标按钮
+- 若按钮仅图标，必须提供可读名称：
+  - `aria-label="关闭"` / `title="关闭"`
+
+### 4.4 通知（Toast/Alert）
+- 错误类：建议 `role="alert"`（立即播报）
+- 信息类：建议 `role="status"`（非打断播报）
+
+## 5. 像素级验收建议（与工程联动）
+- 验收基线：
+  - 每个关键页面至少 1 张桌面端基线截图（含主要状态：默认/空态/加载/错误）。
+- 容差：
+  - 像素级对比误差 ≤ 1px（文本抗锯齿允许极小差异，建议在工具中配置阈值）。
+- 关键路径：
+  - 登录 → 进入首页 → 打开核心模块 → 创建/编辑/删除关键实体（若业务允许）。
+
+## 6. 灰度与回滚交互（前端开关）
+- UI 版本
+  - `document.documentElement.dataset.ui`：`v1` / `v2`
+  - 本地覆盖：`localStorage.gemold_ui_version`
+  - 灰度比例：`localStorage.gemold_ui_rollout_percent`（0–100）
+- 主题
+  - `document.documentElement.dataset.theme`：`light` / `dark`
+  - 本地覆盖：`localStorage.gemold_theme`
+- 内部控制台
+  - `/_release`：提供切换 v1/v2、设置灰度比例与“一键回滚”
@@ -0,0 +1,59 @@
+## 1.Architecture design
+```mermaid
+graph TD
+  U["User Browser"] --> FE["Vue 3 Frontend (CDN)"]
+  FE --> TOK["Design Tokens (JSON + CSS Variables)"]
+  TOK --> CSSV["CSS Variables / Theme Styles"]
+  FE --> DS["Internal Design System & Release Pages"]
+  FE --> QA["A11y + Visual Regression (Optional Tooling)"]
+
+  subgraph "Frontend Layer"
+    FE
+    DS
+    CSSV
+  end
+
+  subgraph "Build/QA Tooling"
+    TOK
+    QA
+  end
+```
+
+## 2.Technology Description
+- Frontend: Vue@3（CDN）+ vue-router@4（CDN），单文件静态应用（`static/index.html` + `static/vue-app.js`）
+- Styling: CSS Variables（`static/style.css`），通过 `data-ui`/`data-theme` 做主题与版本切换
+- Design Tokens: `./.trae/documents/DesignTokens_Gemold_UIv2.json`（令牌源）+ `static/style.css`（运行时变量）
+- A11y: 工程内置 focus-visible 与 reduced-motion；建议在 CI 中补充 axe-core/Playwright 扫描（本仓库暂不强制引入 Node 工具链）
+- Pixel-level: 建议 Playwright 截图对比作为像素级验收基线（同上，CI 可选）
+- Release: 纯前端 Feature Flags（localStorage + 稳定分桶）+ 内部控制台 `/_release`
+- Backend: 不新增后端；如后端可下发配置，可替换本地灰度为服务端策略
+
+## 3.Route definitions
+| Route | Purpose |
+|-------|---------|
+| （保持现有路由不变） | 业务页面继续对外提供服务，仅替换视觉/交互实现 |
+| /_design-system | 内部设计体系与组件库预览（建议仅开发/预发可用） |
+| /_release | 内部灰度发布与验收面板（建议仅预发/生产受控可用） |
+
+## 4.API definitions (If it includes backend services)
+- Backend: None
+
+## 6.Data model(if applicable)
+- No database changes
+
+---
+
+### 关键工程约束（实现要点）
+1) **Design Tokens 单一事实源**：颜色/排版/间距/圆角/阴影/动效时长等以 token 定义；组件与页面不得硬编码魔法值。
+2) **WCAG 2.1 AA 落地**：
+- 颜色对比度：令牌层保证正文/交互控件在常见背景下达标；
+- 键盘与焦点：全站可 Tab 导航且焦点可见；
+- 语义与读屏：优先语义标签；必要处补 ARIA；
+- 动效：支持 prefers-reduced-motion。
+3) **像素级验收**：
+- 以“设计基线截图 + 视觉回归”作为可重复验收手段；
+- 定义容差策略（例如仅允许极小抗锯齿差异）与忽略区域（时间戳/随机数）。
+4) **灰度发布与回滚**：
+- Feature Flag 策略：环境开关（dev/staging/prod）+ 百分比灰度（基于用户标识做稳定哈希）+ 白名单；
+- 回滚手段：立即关闭 flag（热回滚体验）+ 回退到上一稳定构建产物（部署回滚）；
+- 监控信号：前端错误率、关键交互成功率、性能指标（LCP/CLS 等）作为扩大/停止灰度依据。
@@ -0,0 +1,108 @@
+# 页面设计说明（桌面端优先）
+
+## 全局样式（适用于全站与内部页面）
+- Layout：桌面端以 12 栅格 + 8px spacing scale；内容最大宽度（例如 1200–1440）并居中；二级页面可用左侧栏 + 右侧内容区。
+- Responsive：
+  - Desktop（≥1200）：完整导航与并列布局
+  - Tablet（768–1199）：侧栏可折叠；表格降级为分组卡片
+  - Mobile（<768）：纵向堆叠；主操作按钮置底吸附（仅必要场景）
+- Global Design Tokens（以 CSS Variables 注入）：
+  - Color：brand/neutral/semantic（success/warning/danger/info）
+  - Typography：font family、字号阶梯、行高、字重
+  - Spacing/Radii/Shadows/Z-index
+  - Motion：duration/easing；遵循 prefers-reduced-motion
+- 通用交互状态：hover / active / focus-visible / disabled / loading / invalid；focus ring 颜色与对比度满足可见性。
+- 无障碍通用规则：
+  - 键盘：所有可操作元素可达；焦点顺序与视觉顺序一致
+  - 读屏：图标按钮必须有可读名称；表单必须有 label 与错误关联
+  - 对比度：正文/控件/边框按 AA 标准设计（在令牌层保障）
+
+---
+
+## 页面 1：全站现有业务页面（整体改造规范）
+### Layout
+- 使用「页面壳（App Shell）」统一：顶栏（品牌/导航/用户区）+ 内容区（栅格）+ 可选页脚。
+- 页面间距、卡片、表单、表格、弹窗等均由组件库提供，页面不再自定义样式细节。
+
+### Meta Information
+- Title：沿用现有页面标题规则（不更改信息架构）。
+- Description/OG：沿用现有策略；若无则保持空以避免误配。
+
+### Page Structure（通用结构）
+1. 顶栏：主导航、面包屑（如原有）、全局搜索（如原有）、用户菜单（如原有）
+2. 内容区：
+   - 标题区（H1 + 次要说明）
+   - 主内容（表单/表格/卡片/图表等现有模块）
+3. 全局反馈：Toast/Inline Alert；全屏 Loading 避免阻塞键盘焦点
+
+### Sections & Components（交互要点）
+- 表单：
+  - 必填标识、错误提示（文本 + aria-describedby）、提交后聚焦到首个错误
+  - 输入控件状态一致（hover/focus/invalid/disabled）
+- 表格：
+  - 可点击行/排序/分页等交互保持一致反馈；空态提供下一步指引
+- 弹窗/抽屉：
+  - focus trap；Esc 关闭；关闭按钮可读名称；关闭后焦点回到触发点
+- 动效：仅用于状态过渡与层级变化；支持 reduced motion
+
+---
+
+## 页面 2：设计体系与组件库（内部）
+### Layout
+- 左侧栏（固定宽度）：分类导航（Tokens / Components / Patterns / A11y）
+- 右侧内容：文档内容区 + 组件预览区（可上下分栏）
+- 顶部工具条：主题切换（浅色/深色）、缩放预览（100%/125%）、搜索
+
+### Meta Information
+- Title：设计体系与组件库
+- Description：设计令牌、组件状态与无障碍规范的单一入口
+
+### Page Structure
+1. Tokens 区：令牌分组列表 + 详情面板
+2. Components 区：组件目录 + 交互状态矩阵 + 代码用法
+3. Patterns 区：表单/表格/弹窗等复合模式（推荐组合）
+4. A11y 区：组件级检查清单与示例
+
+### Sections & Components（关键元素）
+- Token 浏览器：
+  - 支持按名称/别名搜索；展示值（HEX/px/ms 等）与使用建议
+  - 展示“映射关系”：token → CSS variable → Tailwind theme → 组件 props
+- 组件预览：
+  - 每个组件提供状态面板：default/hover/focus/disabled/loading/invalid
+  - 提供键盘操作说明（Tab/Enter/Space/Arrow）与读屏提示
+- 规范说明：
+  - 明确“禁止事项”（例如页面层硬编码颜色）与迁移策略（旧组件替换路径）
+
+---
+
+## 页面 3：灰度发布与验收面板（内部）
+### Layout
+- 顶部：版本信息条（当前版本、上个稳定版本、灰度开关状态）
+- 主体：左右分栏
+  - 左：灰度策略配置
+  - 右：验收与监控摘要
+- 底部：操作审计表（仅追加写入展示）
+
+### Meta Information
+- Title：灰度发布与验收
+- Description：灰度配置、验收汇总与回滚操作入口
+
+### Page Structure
+1. 灰度配置卡片
+2. 验收结果汇总
+3. 回滚操作区（高风险操作）
+4. 审计与记录
+
+### Sections & Components（关键交互）
+- 灰度配置：
+  - 环境选择（预发/生产）
+  - 百分比滑杆（0–100）+ 白名单输入
+  - 变更预览：显示预计影响范围（如可估算）与生效时间
+- 验收汇总：
+  - A11y：阻断项（AA 不通过）必须红色拦截并禁止扩大灰度
+  - 视觉回归：按页面/组件维度展示 diff；可查看基线截图与当前截图
+  - 冒烟：关键路径用例通过率
+- 回滚：
+  - 两步确认（输入“ROLLBACK”）+ 原因必填
+  - 支持“关闭灰度开关（热回滚）”与“回退构建产物（部署回滚）”两种动作
+- 审计：记录操作人、时间、版本、策略变更、回滚原因（只读）