geMoldInsight/.trae/documents/技术架构_设计体系令牌与灰度发布.md

1.Architecture design

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 等）作为扩大/停止灰度依据。