# Viva UI 设计系统优先工作流 ## Before / After | 环节 | Before：直接画 mockup | After：Design System First | |---|---|---| | 输入 | 用户说“做三套 Figma 原型”后，直接画 A/B/C 三个界面方向 | 先把 Viva 的产品原则写成系统：阅读优先、发音显性、即时响应、队列透明 | | 设计产物 | 每张图都有自己的颜色、控件、状态表达，后续改动靠人工对齐 | 先交付 token、字体层级、布局语法、控件、状态机、异步队列，再给一个 UI realization | | 前端实现 | Codex 从截图推断 CSS 和组件，容易做成不可维护的一次性页面 | Codex 按 `viva-design-system-first.md` 实现 CSS vars、组件 contract 和状态 contract | | 回归检查 | 只看页面像不像截图 | 检查 IPA 层级、Anki/ROI 状态、queue/retry/optimistic UI 文案、截图渲染是否都符合 contract | ## Contract 结构 | 模块 | 必须写清楚什么 | 变更示例 | |---|---|---| | principles | Viva UI 的稳定原则和取舍顺序 | 阅读优先、发音显性、学习状态不打扰正文 | | tokens | 颜色、字号、间距、阴影、圆角、层级 | `--viva-ipa-size-lg`、`--viva-queue-muted-bg` | | components | tooltip、inline highlight、queue toast、Anki action 的结构 | tooltip 内 IPA、释义、动作区的固定顺序 | | states | Anki、ROI、known/learning/unknown 的可见状态 | `learning-local` 优先显示为可复习，而不是被 known 覆盖 | | async timeline | optimistic、queued、retry、failed、synced 的文案和视觉 | 队列弱提示、失败可重试、同步成功不抢注意力 | | acceptance | Figma、CSS、DOM、截图必须验证的点 | CSS vars 存在、状态文案一致、移动端不遮挡正文 | ### 推荐流程 1. 读现有 Viva UI、最新反馈和 `viva-design-system-first.md`，先写 DS delta 表，不直接画新界面。 2. 更新 contract：新增或修改 token、component、state、async timeline、copy rules 和 acceptance checklist。 3. 在 Figma 里先更新系统图，再用同一套系统拼出 UI realization；Figma node-id 回写到 contract 页首。 4. 前端只实现 contract：CSS vars、组件类名、状态名、异步队列文案都要能从文档追溯。 5. 跑 CSS/DOM/截图回归，并把截图路径和失败项回写到 contract。 ### 成功信号 - 用户说“音标再大一点”时，只需要改 typography/IPA scale，而不是重画所有 tooltip。 - 用户说“Anki 队列弱一点”时，只需要改 async queue token 和组件状态，而不是重构业务逻辑。 - Figma 页面、Markdown contract、前端 CSS/tests 三者能互相指向同一组命名。 - 任何新 UI 需求都能先落成一张 DS delta 表，再进入 Figma 和代码实现。