60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
|
## 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 等）作为扩大/停止灰度依据。
|