补充 AGC 动效层与交互反馈系统主规范及首个里程碑文档

新增主规范 docs/technical/【前端架构】AGC动效层与交互反馈系统-2026-10-01.md，确立动效 token 唯一事实源、四态反馈、主行动入口定位、首次生成引导与 reduced-motion 降级口径明确两项非目标：不引入 motion 库做路由级页面转场，不重构 styles.css 文件结构新增里程碑规范 docs/project-memory/plans/【里程碑】AGC动效token层-2026-10-01.md，交付零视觉变化的动效 token 地基新增实施计划 docs/project-memory/plans/【实施计划】AGC动效token层-2026-10-01.md，钉住修改边界、实现顺序、验证命令与回滚点 docs/README.md 前端架构索引挂入该主规范关联 Issue #563 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:37:39 +08:00
parent 55375b1406
commit deb95c2474
4 changed files with 229 additions and 0 deletions
@@ -0,0 +1,127 @@
+# 【前端架构】AGC 动效层与交互反馈系统
+
+更新时间：`2026-10-01`
+
+关联 Issue：#563
+
+## 目标
+
+为 AGC 渲染层建立**统一的动效层**，让页面跳转、元素出入场和可交互元素的反馈走同一套时间语言，并把主行动入口的视觉表达从通用工具形态转向游戏创作工具定位。
+
+1. 动效的**时长与曲线**成为设计 token，与现有 `--platform-*` 静态 token 同级，可被测试钉住。
+2. 可交互元素具备一致、及时的四态反馈（hover / active / focus-visible / disabled）。
+3. 「开始生成」等主行动入口的视觉与动效体现游戏创作工具定位，不呈现通用编码工具样式。
+4. 首次生成完成后，预览区域有明确且不打扰阅读的一次性视觉引导。
+5. 操作动线按使用频率分层：高频操作醒目，低频功能不抢占注意力。
+6. 全部动效默认满足 `prefers-reduced-motion`，且收敛动画时不收敛可见性。
+
+## 非目标
+
+- **不引入 `motion` 库做路由级页面转场。** AGC 是桌面壳 + 离线前端，页面切换增加转场会拖慢体感；向渲染层引入新运行时依赖的收益与成本不匹配。本规范范围内的动效全部由 CSS token 与既有 JS 动效引擎承担。`vite.config.ts` 中已存在的 `motion-vendor` 分块保持原状，不因本规范启用。
+- **不重构 `apps/ai-game-creator-shell/src/styles.css` 的文件结构。** 本规范只收口其中的动效声明；13021 行单体样式表的拆分是独立议题。
+- 不改变任何后端契约、DTO、SpacetimeDB schema 或 `/api/external/v1` 行为。本规范是纯渲染层表现与交互变更。
+- 不新增业务状态。首次生成引导所需的「是否已引导过」属于临时 UI 状态，不进入后端投影。
+- 不改动模板库 `template-library/v1/**` 下各模板自带的 `style.css`（那是产物内容，不是 AGC 界面）。
+
+## 入口与边界
+
+### 用户入口
+
+| 入口 | 位置 | 本规范涉及的行为 |
+| ---- | ---- | ---------------- |
+| 首页创作输入区主行动按钮 | `apps/ai-game-creator-shell/src/view/home/index.tsx` | 视觉重设计、生成中状态表达 |
+| 工作台对话发送 / 终止钮 | `.../chat/components/DirectProjectComposer/ComposerControls.tsx` | 与主行动按钮统一视觉语言 |
+| 本地游戏预览区 | `apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx` | 首次生成完成的一次性高亮引导 |
+| 全局可交互元素 | `apps/ai-game-creator-shell/src/styles.css` 及各组件 | 四态反馈统一 |
+
+### 涉及模块
+
+- `packages/shared/src/theme.css`：动效 token 的唯一定义处。
+- `apps/ai-game-creator-shell/src/styles.css`：AGC 动效声明的收口对象。
+- `apps/ai-game-creator-shell/src/view/project-development/resourceBookController.ts`：既有 JS 动效引擎，其时长与曲线并入 token 口径。
+- `packages/shared/src/components/OverflowActions.tsx`：低频功能收纳的既有承载组件，按现役用法复用。
+
+### 正式状态来源
+
+本规范不引入正式业务状态。首次生成引导的触发依据来自既有的预览运行态与生成完成态；「已引导过」是临时 UI 状态，页面生命周期内有效，不落盘、不进后端。
+
+## 必须成立的行为
+
+### 动效 token 与时间语言
+
+1. 动效时长与缓动曲线在 `packages/shared/src/theme.css` 以 CSS 自定义属性定义，形成**唯一事实源**。
+2. 曲线统一到既有 `cubic-bezier(0.2, 0.8, 0.2, 1)` 一族。当前 `resourceBookController.ts` 中的 `cubic-bezier(0.2, 0.78, 0.2, 1)` 是同一意图的孤本，必须并入 token 口径。
+3. AGC 样式表与组件中的动效声明引用 token，不写裸数字时长。现存的 120 / 140 / 150 / 160 / 180ms 五种取值收敛到 token 档位。
+4. 新增裸数字时长由自动化门禁拒绝。
+
+### 交互反馈
+
+1. 可交互元素具备 hover / active / focus-visible / disabled 四态的一致反馈；反馈必须即时，不阻塞操作。
+2. 反馈不得造成布局抖动。按 `UI_CODING_STANDARD` 既有约束，像素框控件不使用非整数 `scale()`，改用 `translateY`、brightness 或阴影位移。
+3. 键盘可达性不退化：现有 `focus-visible` 覆盖处的可见焦点指示保持或增强。
+4. 禁用态在视觉上可区分，且不依赖颜色单一通道传达。
+
+### 主行动入口
+
+1. 「开始生成」具备足以承载文案的体积与明确的行动语义，不是仅图标的通用小圆钮。
+2. 生成中状态的表达与「等待通用任务」区分开，体现创作工具的产出感，不使用通用 spinner 作为唯一表达。
+3. 发送 / 终止钮与主行动按钮共用同一视觉语言；硬编码的通用色值（如 `#1f6feb`）接回 `--platform-*` token。
+4. 主行动按钮在 disabled 与运行中两种不可提交状态下，`aria-label` 与可见文案都准确反映当前状态。
+
+### 首次生成引导
+
+1. 首次生成完成后，预览区域出现一次性强调，使用户注意到产出位置。
+2. 引导**只触发一次**，后续生成不重复触发，不干扰阅读与操作。
+3. 引导不拦截指针事件，不阻塞预览区内的任何交互。
+4. 引导的实现泛化既有 `ui-editor-status-attention` 的三段式强调（落位 + 扩散 + 呼吸），不另写平行实现。
+
+### 动线分层
+
+1. 高频操作在视觉层级上先于低频操作被发现。
+2. 低频功能收进既有 `OverflowActions`，遵循其现役的展示数量与宿主决定权约定。
+3. 收纳不得使任何现有功能不可达，键盘与读屏路径保持完整。
+
+### 无障碍与降级
+
+1. `prefers-reduced-motion: reduce` 下，动效在 token 层统一降级，不要求每处单独声明 media query。
+2. 降级收敛动画但**不收敛可见性**：强调类效果静态停在可见档位，信息不因降级丢失。此口径沿用 `styles.css` 既有注释确立的做法。
+3. 降级后所有功能保持可用，不残留永久动画或中间态。
+
+## 契约与迁移
+
+- **API / DTO / OpenAPI**：无变化。
+- **SpacetimeDB schema / migration / bindings**：无变化。
+- **兼容与迁移策略**：动效 token 为新增 CSS 自定义属性，不删除或改名既有 `--platform-*`。既有动效声明改为引用 token 属于等价替换，视觉结果在 token 档位对齐后保持一致或更一致。`resourceBookController.ts` 的曲线并入会使其从 `0.78` 变为 `0.8`，这是有意的口径统一，差异在感知阈值内。
+
+## 验收标准与证据
+
+| 条款 | 验收方式 | 证据 |
+| ---- | -------- | ---- |
+| 动效 token 在 `theme.css` 唯一定义 | 声明级样式测试 | 待补 |
+| 曲线孤本已并入，仓库内无第二份动效曲线 | 门禁测试 + 全仓检索 | 待补 |
+| AGC 动效声明无裸数字时长 | 门禁测试 | 待补 |
+| 可交互元素四态反馈一致 | 声明级样式测试 | 待补 |
+| 像素框控件无非整数 `scale()` | 门禁测试 | 待补 |
+| 主行动按钮非仅图标小圆钮，状态文案准确 | 组件测试 + 真机 smoke | 待补 |
+| 通用色值已接回 token | 全仓检索 | 待补 |
+| 首次生成引导只触发一次且不拦截指针 | 组件测试 | 待补 |
+| 低频功能收纳后仍键盘可达 | 组件测试 | 待补 |
+| reduced-motion 下动画收敛、可见性保留 | 声明级样式测试 | 待补 |
+| 桌面端与 Web 端表现一致 | 真机 smoke | 待补 |
+
+证据来源以 `apps/ai-game-creator-shell/tests/` 下的声明级样式测试（`styleCascade`）与组件测试为主，叠加 AGC 真机客户端 smoke。
+
+## 里程碑拆分
+
+1. **动效 token 层**：建立 token 与全局 reduced-motion 兜底，并入曲线孤本，加门禁。零视觉变化。
+2. **交互反馈统一**：动效声明收口到 token，补齐四态反馈。
+3. **主行动入口重设计**：「开始生成」与发送 / 终止钮的视觉与动效重做，通用色值接回 token。
+4. **首次生成引导与动线分层**：预览区一次性强调，高低频分层与低频收纳。
+
+里程碑逐个评审与验收，未验收的里程碑不作为下一个的已完成依赖。
+
+## 未决问题与决策
+
+- **待评审**：主行动按钮的意象方向。当前倾向「生成 / 点燃」语义配聚能式 loading，替代通用 spinner。需产品侧确认是否符合面向游戏创作者的审美预期。
+- **已决策（本规范）**：不引入路由级页面转场，理由见非目标。若后续评审认为必要，另开规范变更并启用既有 `motion-vendor` 分块。
+- **已决策（本规范）**：动效 token 放在 `packages/shared/src/theme.css` 而非 AGC 本地，使网页端后续可复用同一时间语言。