优化 AGC UI 动效与操作体验 #563

New Issue

2026-10-01T12:20:41+08:00

suzmii commented

2026-10-01 12:20:41 +08:00

需求来源

包仲航反馈：

还有易用性优化，大家也用一段时间泡沙儿了，把那些不通顺的动线捋通，低频的功能不要浪费用户注意力，高频的做得更醒目。用动效把泡沙儿每个操作变得更精致。例如游戏首次生成后的预览可以在预览窗口加个高亮特效，按键都做交互动画，但不要杂乱。开始生成按钮可以不那么呆板是个箭头，要知道我们不是 codex，我们是专门做游戏的工具，不用通用，向游戏创作者的审美和口味转化设计。

优化方向

梳理 AGC UI 中不顺畅的操作动线，降低用户完成创作任务的操作成本。
区分操作优先级：让高频功能更醒目，减少低频功能对用户注意力的占用。
在首次生成完成后的预览窗口增加克制、明确的高亮引导，帮助用户发现预览结果。
为按钮补充统一的交互反馈动效，让操作更精致，但避免动画过多造成干扰或视觉杂乱。
重新设计「开始生成」按钮的视觉表达和动效，不局限于通用工具式的箭头按钮，体现面向游戏创作者的产品定位与审美。

验收判据

首次生成完成后，预览区域有明确且不打扰阅读的视觉引导。
高频操作易于发现和理解，低频功能不抢占主要操作的注意力。
主要按钮具有一致、及时的交互反馈，动效不阻塞操作、不造成视觉噪声。
「开始生成」按钮的视觉和动效与游戏创作工具定位一致，不再呈现为通用编码工具样式。
优化覆盖桌面端和 Web 端 AGC UI 的对应交互状态，并保持无障碍可操作性。

原始反馈截图

## 需求来源包仲航反馈： > 还有易用性优化，大家也用一段时间泡沙儿了，把那些不通顺的动线捋通，低频的功能不要浪费用户注意力，高频的做得更醒目。用动效把泡沙儿每个操作变得更精致。例如游戏首次生成后的预览可以在预览窗口加个高亮特效，按键都做交互动画，但不要杂乱。开始生成按钮可以不那么呆板是个箭头，要知道我们不是 codex，我们是专门做游戏的工具，不用通用，向游戏创作者的审美和口味转化设计。 ## 优化方向 - 梳理 AGC UI 中不顺畅的操作动线，降低用户完成创作任务的操作成本。 - 区分操作优先级：让高频功能更醒目，减少低频功能对用户注意力的占用。 - 在首次生成完成后的预览窗口增加克制、明确的高亮引导，帮助用户发现预览结果。 - 为按钮补充统一的交互反馈动效，让操作更精致，但避免动画过多造成干扰或视觉杂乱。 - 重新设计「开始生成」按钮的视觉表达和动效，不局限于通用工具式的箭头按钮，体现面向游戏创作者的产品定位与审美。 ## 验收判据 - 首次生成完成后，预览区域有明确且不打扰阅读的视觉引导。 - 高频操作易于发现和理解，低频功能不抢占主要操作的注意力。 - 主要按钮具有一致、及时的交互反馈，动效不阻塞操作、不造成视觉噪声。 - 「开始生成」按钮的视觉和动效与游戏创作工具定位一致，不再呈现为通用编码工具样式。 - 优化覆盖桌面端和 Web 端 AGC UI 的对应交互状态，并保持无障碍可操作性。 ## 原始反馈截图 ![AGC UI 动效优化反馈截图](https://git.genarrative.world/git/attachments/7eb07960-397e-4cc5-8ec5-733f6dc02cee)

agc-ui-motion-feedback.png

74 KiB

suzmii added the Kind/Enhancement

Priority

Medium

3

labels 2026-10-01 12:20:41 +08:00

suzmii self-assigned this 2026-10-01 16:36:27 +08:00

suzmii commented

2026-10-01 18:22:50 +08:00

调研结论与优化方案（待评审）

先说结论：这个需求的根因不是「动效太少」，而是 AGC 没有动效层。装了动效依赖没用、设计 token 只覆盖静态视觉不覆盖时间维度，于是每处动效各自拍数字。先补地基再改表现，否则会一边加动效一边制造新的不一致。

一、现状证据

动效依赖装了但零使用

package.json:243 已有 motion@^12.23.24，vite.config.ts:649 甚至已为它切出 motion-vendor chunk —— 但全仓库零 import。
packages/shared/src/theme.css 有 100+ 个 --platform-* token（颜色、填充、阴影），没有任何动效 token：无 duration、无 easing。

时长与曲线已经漂移

apps/ai-game-creator-shell/src/styles.css（13021 行单体）中 23 处 transition 用了 120/140/150/160/180ms 五种值。
easing 出现两份孤本：CSS 里 cubic-bezier(0.2, 0.8, 0.2, 1)（styles.css:797），TS 里 cubic-bezier(0.2, 0.78, 0.2, 1)（resourceBookController.ts:23）。同一意图，两个数。
prefers-reduced-motion 只覆盖 5 处，有先例但远未成体系。

反馈点名的两个对象

「开始生成」= view/home/index.tsx:305-319，一个 size-7（28px）圆形 ArrowUp，全部动效是 transition-transform hover:scale-105。确实是通用工具的样子。
工作台发送/终止钮更直接：ComposerControls.tsx:455 注释原文写着「Codex 的停止方块」。对应 .project-chat-submit-button（styles.css:3091）是 #1f6feb 通用蓝，连 transition 都没有。
预览区 .local-game-preview-frame（styles.css:2659）只有黑底 + iframe，无进场、无加载态、无高亮。

可复用的好底子（不另写新套）

ui-editor-status-attention（styles.css:738-830）已是一套克制的三段式强调：arrive 落位 + ring 扩散 + breathe 呼吸，且带 reduced-motion 降级（注释明确「收敛动画但不收敛可见性」）。首次生成高亮应泛化它。
resourceBook 已有完整 JS 动效引擎（420ms + 最小时长下限 + reduced-motion 抑制）。
tests/styleCascade.ts 支持声明级 CSS 断言，已有 6 个样式测试。动效可被测试钉死，不会改回去。

二、方案：四个里程碑

M1 动效 token 层（地基，零视觉变化）

theme.css 补 --motion-duration-{instant,fast,base,slow} 与 --motion-ease-{standard,out,spring}，统一到现有 0.2, 0.8, 0.2, 1 一族，并把 TS 侧 0.78 的孤本并过来。在 token 层做一次全局 reduced-motion 兜底（时长压到 1ms），后续所有动效默认无障碍合规，不必每处单写 media query。用 styleCascade 加门禁测试禁止新增裸数字时长。

M2 交互反馈统一（覆盖面最大）

23 处 transition 收口到 token；按钮补一致的 hover / active / focus-visible / disabled 四态。遵循 UI_CODING_STANDARD 既有约束：像素框控件不用非整数 scale()，走 translateY + brightness。现有 66 处 focus-visible 说明键盘可达性有基础，一并对齐。

M3 主行动按钮重设计（反馈的正面诉求）

「开始生成」从 28px 箭头升级为有文案、有体积的主行动按钮，视觉语言转向游戏创作工具 —— 倾向「生成 / 点燃」意象 + 聚能式 loading，而非通用 spinner。顺带把 #1f6feb 这类硬编码通用蓝接回 --platform-*。同一套语言覆盖工作台发送 / 终止钮，去掉「Codex 停止方块」这个定位。

M4 首次生成高亮 + 动线分层

泛化 ui-editor-status-attention 到预览区，做一次性首次生成完成引导（只触发一次，不打扰后续阅读）。同时做高低频分层：高频操作提权，低频收进既有 OverflowActions（团队约定已有该收纳组件与现役用法）。

三、两个明确的不做项

不引入 motion 库做路由级转场。 AGC 是桌面壳 + 离线前端，页面切换加转场拖慢体感；且引新运行时依赖进渲染层收益不匹配。M1-M4 全部用 CSS token + 现有 JS 引擎即可。若评审认为需要转场，再单开里程碑启用那个已切好的 motion-vendor。
不重构 13021 行 styles.css 的结构。 本次只收口动效声明，文件拆分是独立议题。

四、流程

按 AGENTS.md，「复杂 UI 状态链路」属必须走 SDD 的范围。实现前先产出主规范 + 里程碑规范 + 单里程碑实施计划，评审通过再动代码。已在 feat/agc-ui-motion-ux 开 draft PR 挂文档产物，保证进度每天可见。

请评审，特别是：M3 的「生成 / 点燃」意象方向是否符合预期，以及上面两个不做项是否认可。

## 调研结论与优化方案（待评审）先说结论：这个需求的根因不是「动效太少」，而是 **AGC 没有动效层**。装了动效依赖没用、设计 token 只覆盖静态视觉不覆盖时间维度，于是每处动效各自拍数字。先补地基再改表现，否则会一边加动效一边制造新的不一致。 ### 一、现状证据 **动效依赖装了但零使用** - `package.json:243` 已有 `motion@^12.23.24`，`vite.config.ts:649` 甚至已为它切出 `motion-vendor` chunk —— 但全仓库零 import。 - `packages/shared/src/theme.css` 有 100+ 个 `--platform-*` token（颜色、填充、阴影），**没有任何动效 token**：无 duration、无 easing。 **时长与曲线已经漂移** - `apps/ai-game-creator-shell/src/styles.css`（13021 行单体）中 23 处 transition 用了 120/140/150/160/180ms 五种值。 - easing 出现两份孤本：CSS 里 `cubic-bezier(0.2, 0.8, 0.2, 1)`（`styles.css:797`），TS 里 `cubic-bezier(0.2, 0.78, 0.2, 1)`（`resourceBookController.ts:23`）。同一意图，两个数。 - `prefers-reduced-motion` 只覆盖 5 处，有先例但远未成体系。 **反馈点名的两个对象** - 「开始生成」= `view/home/index.tsx:305-319`，一个 `size-7`（28px）圆形 `ArrowUp`，全部动效是 `transition-transform hover:scale-105`。确实是通用工具的样子。 - 工作台发送/终止钮更直接：`ComposerControls.tsx:455` 注释原文写着「Codex 的停止方块」。对应 `.project-chat-submit-button`（`styles.css:3091`）是 `#1f6feb` 通用蓝，**连 transition 都没有**。 - 预览区 `.local-game-preview-frame`（`styles.css:2659`）只有黑底 + iframe，无进场、无加载态、无高亮。 **可复用的好底子（不另写新套）** - `ui-editor-status-attention`（`styles.css:738-830`）已是一套克制的三段式强调：arrive 落位 + ring 扩散 + breathe 呼吸，且带 reduced-motion 降级（注释明确「收敛动画但不收敛可见性」）。首次生成高亮应泛化它。 - `resourceBook` 已有完整 JS 动效引擎（420ms + 最小时长下限 + reduced-motion 抑制）。 - `tests/styleCascade.ts` 支持声明级 CSS 断言，已有 6 个样式测试。**动效可被测试钉死，不会改回去。** ### 二、方案：四个里程碑 **M1 动效 token 层（地基，零视觉变化）** `theme.css` 补 `--motion-duration-{instant,fast,base,slow}` 与 `--motion-ease-{standard,out,spring}`，统一到现有 `0.2, 0.8, 0.2, 1` 一族，并把 TS 侧 `0.78` 的孤本并过来。在 token 层做一次全局 reduced-motion 兜底（时长压到 1ms），后续所有动效默认无障碍合规，不必每处单写 media query。用 `styleCascade` 加门禁测试禁止新增裸数字时长。 **M2 交互反馈统一（覆盖面最大）** 23 处 transition 收口到 token；按钮补一致的 hover / active / focus-visible / disabled 四态。遵循 `UI_CODING_STANDARD` 既有约束：像素框控件不用非整数 `scale()`，走 `translateY` + brightness。现有 66 处 `focus-visible` 说明键盘可达性有基础，一并对齐。 **M3 主行动按钮重设计（反馈的正面诉求）** 「开始生成」从 28px 箭头升级为有文案、有体积的主行动按钮，视觉语言转向游戏创作工具 —— 倾向「生成 / 点燃」意象 + 聚能式 loading，而非通用 spinner。顺带把 `#1f6feb` 这类硬编码通用蓝接回 `--platform-*`。同一套语言覆盖工作台发送 / 终止钮，去掉「Codex 停止方块」这个定位。 **M4 首次生成高亮 + 动线分层** 泛化 `ui-editor-status-attention` 到预览区，做一次性首次生成完成引导（只触发一次，不打扰后续阅读）。同时做高低频分层：高频操作提权，低频收进既有 `OverflowActions`（团队约定已有该收纳组件与现役用法）。 ### 三、两个明确的不做项 1. **不引入 `motion` 库做路由级转场。** AGC 是桌面壳 + 离线前端，页面切换加转场拖慢体感；且引新运行时依赖进渲染层收益不匹配。M1-M4 全部用 CSS token + 现有 JS 引擎即可。若评审认为需要转场，再单开里程碑启用那个已切好的 `motion-vendor`。 2. **不重构 13021 行 `styles.css` 的结构。** 本次只收口动效声明，文件拆分是独立议题。 ### 四、流程按 `AGENTS.md`，「复杂 UI 状态链路」属必须走 SDD 的范围。实现前先产出主规范 + 里程碑规范 + 单里程碑实施计划，评审通过再动代码。已在 `feat/agc-ui-motion-ux` 开 draft PR 挂文档产物，保证进度每天可见。请评审，特别是：M3 的「生成 / 点燃」意象方向是否符合预期，以及上面两个不做项是否认可。

suzmii referenced this issue from a commit

2026-10-01 18:39:29 +08:00

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

~~suzmii referenced this issue 2026-10-01 19:08:50 +08:00~~

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#563