zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/docs/agent-specs/2026-06-16-studio视觉体系-i18n-组件库-execution.md
zizi f98ad0f801 docs(fe-ds): studio视觉体系/i18n/通用组件库 双spec+mockup+P1token层(HJ-FE-DS-001) 
评审版+执行版双spec、真chrome验证mockup(zh/en+暗/浅/柔三主题实时切换)、P1 tokens.css体系化补全(全additive·旧令牌保留→暗色零回归)。
创始人5决议:响应式消费Web否决demo桌面侧栏/暗色先行+设置内多档主题/SVG图标替emoji/金样板先行/统一圆角矩形(禁药丸椭圆)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 14:55:47 +00:00

6.6 KiB
Raw Blame History

studio 视觉体系 / i18n / 通用组件库 · 执行版（HJ-FE-DS-001-EXEC）

性质：执行版（供 agent 落地）。日期：2026-06-16 ｜ owner：L0 ｜ 状态：在飞 上游评审版（创始人 §8 五决议已拍）：2026-06-16-studio视觉体系-i18n-组件库-review.md 验证基准（真 chrome 已验）：docs-design/studio-redesign-mockup.html

0. 目标与范围（金样板先行）

目标：按评审版 5 决议建成 studio 前端体系「金样板」——token 层 + 通用组件库 + i18n 双语 + 多档主题 + 统一圆角矩形，落到 2 个代表面（消费=Feed、创作=Create），验证后再批量克隆其余 15 视图。

  • in：① token 层补全 ② vue-i18n 脚手架 ③ AppButton 重构 + 新增 Field·Icon·设置切换 ④ Feed+Create 两面 token化+i18n化+主题反应 ⑤ Profile 内「主题/语言」设置入口。
  • out（后续批量波次）：其余 15 视图 token化+i18n化、admin、原生 App、护眼/高对比主题。

1. 前置

  • mini-desktop 有 game-studio 可构建检出（node22）；构建门 = npm run build -- --mode staging（vue-tsc --noEmit 是假门，见 staging-ops §4）。
  • 代码同步：git push → mini-desktop clone/pull（需创始人授权 commit）。
  • 现状实证（L0 盘点）：零 Vant UI 真渲染、tokens.css 仅 2 级面板/1 级描边、无 --on-accent、无 spacing 令牌、无 i18n、17/19 视图硬编码中文。

2. 模块与文件路径

层 文件 动作
token L0 src/styles/tokens.css 扩展（additive，旧令牌保留为别名）
src/styles/index.css / vant-theme.css 导入序不变 / 补 --van-* 映射
i18n src/i18n/index.ts（新）、src/locales/{zh-CN,en-US}/{common,feed,create,profile}.json（新）、main.ts createI18n + 注册 + 持久化
防闪烁 index.html 首屏前内联脚本读 localStorage 设 <html data-theme/lang>（防 FOUC）
组件 L2 src/components/AppButton.vue 重构（签名渐变+全态+圆角令牌）
src/components/Field.vue、Icon.vue(SVG)、AppearanceSwitch.vue（新） 新增
图标 public/icons/sprite.svg 或内联 <symbol> SVG 雪碧替 emoji
设置入口 src/views/profile/Profile.vue 加「主题/语言」行
代表面 L3 src/views/feed/Feed.vue + components/GameCard.vue/InteractBar.vue、src/views/create/Create.vue token化+i18n化+圆角统一+主题反应

3. 数据流 / 依赖

token(L0) → vant-theme(L1) → 品牌组件(L2) → 业务面(L3)
i18n :  main 注册 → 组件 useI18n($t) → localStorage(studio.lang) + <html lang>
theme:  localStorage(studio.theme) → <html data-theme> → 语义层覆盖 → 全组件自动反应（只用语义令牌→零改组件）

4. 契约（token / 组件 / i18n）

4.1 token（全 additive；值取自已验证 mockup）

  • primitive：--c-cyan/green/pink/amber/violet/red、--c-ink-0..3、--c-fg-0/1、--c-on-accent:#061014、--c-on-danger:#2a0608。
  • semantic：--bg/--surface-1..3/--ink/--muted/--accent/--success/--warning/--danger/--on-accent/--on-danger/--border-1..2/--grad-primary/--grad-hot/--focus-ring。
  • 尺度：--sp-1..6=4/8/12/16/22/32；--radius-xs/sm/md/lg/xl=4/6/8/12/20，--radius=md；--elev-1..3；--fs-h1/h2/h3/body/caption；--fw-body/medium/label/cta/mark。
  • 主题：[data-theme=light]、[data-theme=dim] 覆盖 semantic（值见 mockup）。
  • 旧令牌兼容：现有 --bg/--panel/--ink/--muted/--cyan/--green/--radius/--shadow… 全保留（--cyan 等可设为 --accent 别名），不破坏现有引用，逐面迁移期共存。

4.2 组件

  • AppButton props 不变（type/size/block/loading/disabled）；primary 恢复签名渐变（--grad-primary+--fw-cta+--on-accent）；全状态（focus-visible 环 / disabled .42 / active scale .97）；圆角 --radius-md。
  • Field props：label/modelValue/type/placeholder/error/helper/required；内部可包 van-field(L1) 统一 focus 环 / error 态。
  • Icon props：name(对应 sprite symbol id)/size；禁 emoji。

4.3 i18n

  • key 命名空间：common.* / feed.* / create.* / profile.*；禁组件内裸中文。
  • $t 注入；缺 key fallback zh-CN；数字/日期/货币用 Intl。
  • 品牌串「绘境AI/造梦AI」收敛 common.brand。

5. 实施步骤（分阶段）

阶段 内容 门
P1 token 层 扩展 tokens.css(4.1)+ [data-theme] 覆盖 + vant-theme 补映射；旧令牌别名共存 构建绿 + 现有页面零视觉回归(截图 diff)
P2 i18n 脚手架 装 vue-i18n、i18n/index.ts+locales 骨架+main 注册+防闪烁脚本+持久化 构建绿 + 切语言/主题生效
P3 组件库 重构 AppButton(签名渐变+全态+圆角)、新增 Field/Icon/AppearanceSwitch 构建绿 + 组件自检
P4 代表面 Feed+Create 全量 token化(杀硬编码 hex/rgba 手抄)+i18n化+圆角统一+主题反应；Profile 加设置入口 构建绿 + 真 UI 走查(CDP,三主题×双语) + i18n 残留扫描 0 + 对比 AA
P5 收口 1 轮 opus 实现评审(impl-review-one-opus-round)→修→收口 评审过

6. 边界 / 失败路径

  • vue-i18n 与 vue3.5 兼容版（@9/@10）；装包后构建门兜。
  • 主题闪烁(FOUC)：首屏前内联脚本读 localStorage 设 data-theme，防暗→亮闪。
  • Vant 引真组件改 DOM/样式：L1 封装隔离，逐组件替换，构建门+走查。
  • 旧令牌别名映射错 → 现有页面变色：P1 门做现状回归截图 diff。
  • i18n 抽 key 漏（中文假阴性）：脚本扫模板残留中文（非 strings|grep），双语对照。

7. 验证方法

  • 构建门：mini-desktop npm run build -- --mode staging。
  • 真 UI 走查：CDP（ui-walkthrough-cdp）Feed+Create，三主题×双语截图。
  • i18n 残留扫描：脚本扫 src/views/{feed,create} 模板中文字面量 = 0。
  • 对比度：关键文本 ≥WCAG AA（三主题各验）。
  • 回归：P1 后旧页面截图 diff 无变色。

8. 完成条件

P1–P4 各门绿 + P5 opus 评审过；金样板（token+组件库+Feed+Create+设置切换）三主题×双语 e2e 可演示；现状零回归。→ 批量波次（其余 15 视图）另起 execution。

9. 回滚

各 P 独立 commit；token 层 additive 可直接 revert；组件改造按文件 revert；i18n 脚手架移除即回原硬编码（保留期不删旧文案直到 i18n 化完成）。