diff --git a/docs/README.md b/docs/README.md index 65d144aa8..fe43fb4d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -95,6 +95,7 @@ - [AGC 抠图模式与背景色透传方案](./technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)：External v1 与 AGC 客户端扩展 `flat`/`complex` 及 BgFilter `auto` 透传。 - [共享基础组件库与展示页](./technical/【前端架构】共享基础组件库与展示页-2026-08-26.md)：网站与客户端复用的无业务 UI chrome、样式边界和 `/components` 展示页。 +- [AGC 动效层与交互反馈系统](./technical/【前端架构】AGC动效层与交互反馈系统-2026-10-01.md)：动效时长与曲线 token 的唯一事实源、可交互元素四态反馈、主行动入口视觉定位、首次生成引导与 reduced-motion 降级口径。 - [Raw GPT Image 2 图片编辑代理](./technical/【技术方案】Raw GPT Image 2图片编辑代理-2026-09-07.md)：主站客户端调用的同步图片编辑代理、multipart 输入、预检查与计费边界。 - [UI 编辑器自动切分素材工作流](./technical/【技术方案】UI编辑器自动切分素材工作流-2026-09-08.md)：UI 设计图素材切分、Raw GPT Image 2 调用与结果持久化边界。 - [图片画布结构化持久化与迁移回滚](./【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md) diff --git a/docs/project-memory/plans/【实施计划】AGC动效token层-2026-10-01.md b/docs/project-memory/plans/【实施计划】AGC动效token层-2026-10-01.md new file mode 100644 index 000000000..c662a42f5 --- /dev/null +++ b/docs/project-memory/plans/【实施计划】AGC动效token层-2026-10-01.md @@ -0,0 +1,53 @@ +# 【实施计划】AGC 动效 token 层 + +| 字段 | 值 | +| --------- | ----------------------------------------------------------- | +| Milestone | `docs/project-memory/plans/【里程碑】AGC动效token层-2026-10-01.md` | +| Status | ready | +| Owner | Agent（Claude） | + +## 修改边界 + +### 允许修改 + +- `packages/shared/src/theme.css`：新增动效 token 与 token 层 reduced-motion 降级。 +- `apps/ai-game-creator-shell/src/view/project-development/resourceBookController.ts`：曲线常量并入 token 口径（仅该常量，不动动效引擎逻辑）。 +- `apps/ai-game-creator-shell/tests/`：新增 token 与门禁测试。 +- `packages/shared/src/theme.test.ts`：按需补 token 断言。 + +### 明确不修改 + +- `apps/ai-game-creator-shell/src/styles.css` 的既有动效声明（下一里程碑收口）。 +- 任何组件的 `.tsx`。 +- `vite.config.ts`、`package.json`（不增删依赖）。 +- 模板库 `template-library/v1/**`。 +- 任何后端代码、契约、schema。 + +## 实现顺序 + +1. 在 `theme.css` 定义动效时长与曲线 token。档位按语义划分，覆盖现存五种取值所需区间；曲线统一到 `cubic-bezier(0.2, 0.8, 0.2, 1)` 一族。 +2. 在 `theme.css` 增加 token 层 `prefers-reduced-motion: reduce` 降级：时长压到接近零，曲线保持线性。只改时长类 token，不改任何可见性或尺寸属性。 +3. 把 `resourceBookController.ts` 的 `EASING` 常量改为取 token 口径的同一曲线值，保留其 JS 侧常量形态（该引擎按 JS 计算，不走 CSS 变量）。 +4. 新增声明级测试：token 存在、档位齐备、reduced-motion 降级生效且只影响时长。 +5. 新增门禁测试：扫描 AGC 样式表与共享主题，对 `transition` / `animation` 声明中的裸数字时长报错；当前代码存在的既有裸数字先以白名单钉住现状（白名单条目在下一里程碑逐条清空），并附一条负向样本验证门禁真的会拒绝。 +6. 全仓检索确认无第二处动效曲线定义。 + +## 验证命令 + +1. `npx vitest run apps/ai-game-creator-shell/tests/<新增测试文件>` —— token 与门禁测试。 +2. `npx vitest run packages/shared/src/theme.test.ts` —— 共享主题断言。 +3. `npx tsc -p tsconfig.json --noEmit`（按仓库现行类型检查入口调整）。 +4. `npm run check:encoding`。 +5. `git diff --check`。 +6. 真机：`npm run agc` 启动后确认资源栏目画布过渡、状态强调与 spinner 观感未变。 + +## 风险与回滚点 + +| 风险 | 应对 | +| ---- | ---- | +| token 档位划分不足，下一里程碑发现无法覆盖某处语义 | 档位按语义而非按现存数字设计；不足时在下一里程碑补档，不回改本里程碑结论 | +| token 层 reduced-motion 降级影响到非动效属性 | 降级块只声明时长类 token；测试断言其不触及可见性与尺寸 | +| 曲线孤本并入导致资源栏目画布观感变化 | `0.78` → `0.8` 差异在感知阈值内；真机 smoke 确认并在证据中记录 | +| 门禁白名单被误当作长期豁免 | 白名单条目在里程碑二逐条清空；白名单内注明其为临时现状钉子 | + +**回滚点**：本里程碑全部修改集中在 token 定义、一个 JS 常量与新增测试，无组件改动。回滚即还原 `theme.css` 增量与该常量。 diff --git a/docs/project-memory/plans/【里程碑】AGC动效token层-2026-10-01.md b/docs/project-memory/plans/【里程碑】AGC动效token层-2026-10-01.md new file mode 100644 index 000000000..80d6b3f05 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC动效token层-2026-10-01.md @@ -0,0 +1,48 @@ +# 【里程碑】AGC 动效 token 层 + +| 字段 | 值 | +| ----------- | ------------------------------------------------------------- | +| Version | 1.0 | +| Status | proposed | +| Date | 2026-10-01 | +| Parent Spec | `docs/technical/【前端架构】AGC动效层与交互反馈系统-2026-10-01.md` | + +## 目标 + +让动效的时长与缓动曲线成为有唯一事实源的设计 token，并在 token 层一次性建立 `prefers-reduced-motion` 降级。本里程碑交付地基，不改变任何可见视觉表现。 + +## 范围 + +- 动效时长与缓动曲线以 CSS 自定义属性定义在共享主题中，成为唯一事实源。 +- 曲线口径统一：既有的 `cubic-bezier(0.2, 0.78, 0.2, 1)` 孤本并入 `cubic-bezier(0.2, 0.8, 0.2, 1)` 一族。 +- 在 token 层建立全局 `prefers-reduced-motion` 降级，使后续动效默认合规，无需每处单写 media query。 +- 建立自动化门禁：拒绝新增裸数字动效时长。 + +## 不在范围内 + +- 不改任何组件的视觉表现、布局或交互行为。 +- 不收口既有的 23 处 transition 声明（属下一里程碑）。 +- 不重设计任何按钮。 +- 不新增动画效果。 +- 不重构 `styles.css` 文件结构。 +- 不引入新的运行时依赖。 + +## 依赖与前置条件 + +- 主规范已评审通过。 +- 现有声明级样式测试设施（`styleCascade`）可用。 + +## 验收标准 + +- [ ] 动效时长与曲线 token 定义在 `packages/shared/src/theme.css`，且仓库内不存在第二处动效曲线定义。 +- [ ] token 档位覆盖现存的 120 / 140 / 150 / 160 / 180ms 五种取值所需的语义区间。 +- [ ] `prefers-reduced-motion: reduce` 下 token 层时长统一降级，且降级不改变任何元素的可见性或最终视觉档位。 +- [ ] 门禁测试能拒绝新增的裸数字动效时长，并在当前代码上通过。 +- [ ] 既有动效行为无可见变化：现存动画与过渡的观感保持原状（曲线孤本并入带来的差异在感知阈值内，需在证据中说明）。 +- [ ] 类型检查、相关定向测试、`npm run check:encoding`、`git diff --check` 全部通过。 + +## 证据要求 + +- **自动化**：声明级样式测试覆盖 token 存在性、唯一性与 reduced-motion 降级档位；门禁测试覆盖裸数字拒绝能力（含一条应被拒绝的负向样本）。 +- **运行时**：AGC 真机客户端启动，确认既有动效（资源栏目画布过渡、状态强调、各 spinner）观感未变。 +- **边界**：确认 reduced-motion 降级下无元素消失、无永久动画残留、无中间态卡死。 diff --git a/docs/technical/【前端架构】AGC动效层与交互反馈系统-2026-10-01.md b/docs/technical/【前端架构】AGC动效层与交互反馈系统-2026-10-01.md new file mode 100644 index 000000000..35f8e6087 --- /dev/null +++ b/docs/technical/【前端架构】AGC动效层与交互反馈系统-2026-10-01.md @@ -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 本地，使网页端后续可复用同一时间语言。