games-development-ai/docs/agent-specs/studio前端设计体系.md

studio 前端设计体系 · canonical（子系统 SoT）

类型=canonical 活档（子系统单一事实源）· 更新 2026-06-17 取代=3 份历史 spec（已 FOLD 删或归档，见 git 历史与 _archive/：2026-06-16-studio视觉体系-i18n-组件库-{review,execution}.md、2026-06-16-studio-vs-demo-UI差距-review.md） 读法=读本档即知现行真相；深落地配方见 .agents/skills/{staging-ops,ui-walkthrough-cdp}、.agents/rules/ui-uniform-rounded-rectangles.md；决策史见 git。

---

1. 一句话定位与现状

HJ-FE-DS-001 = 绘境AI 产品前端 game-studio 的体系化波次：设计 token 两层 + vue-i18n 中英双语 + 通用组件库（封装 Vant + 自研品牌层）+ 暗/浅/柔三档主题 + 统一圆角矩形 + SVG 图标。

现状 = 已全量收口并合入 dev/2.0.0。 落地链：42342e8c（Phase0 卖相批：退出登录入口/品牌渐变/Inter 字体/字号 token/创作页诚实空态）→ f98ad0f8（双 spec+mockup+P1 token 层）→ ecae9025（P2 i18n 脚手架）→ 655673eb（P3 组件库）→ caa2e1ba（P4 代表面 Feed/Create/Profile/TabBar）→ 2c96e63a（品牌→绘境AI + helper i18n + 裸令牌收口）。19 视图全上体系，6 道 mini-desktop 构建门绿 + 真机三主题×双语 CDP 走查全过。 （注：_index.md/execution 中『待拍板/在飞』状态已过期，以本档与代码实证为准。）

2. 核心判断（为什么这么设计）

• 保留 demo（docs-design/huijing-ai-demo.html）的「设计语言」（token 体系 + cyan→green 品牌渐变 + 暗色玻璃质感），否决其「桌面侧栏控制台布局」作 ToC 网站基线。 demo 是投资人版桌面产品外壳（grid:236px 固定侧栏 + workbench 1140px，短视频流塞进 390×660 模拟手机框），不是消费级范式；现行定位=响应式优先消费级 Web（移动沉浸/桌面居中放大），桌面 App + 移动 App 是 later 层。
• 设计 token 做跨端单一事实源：同时服务「later 双 App」与「避免长期垃圾代码」——Web 现在吃 CSS 变量，桌面 App 复用 Web 技术，移动 App 用同份 token JSON→RN/Flutter。

3. 创始人 5 项决议（已拍 · 硬约束）

1. 响应式优先消费级 Web，否决 demo 桌面侧栏控制台（移动沉浸/桌面居中放大，一套组件）。
2. 暗色先行 + 设置内多档舒适主题（暗/浅/柔和）可切：语义层 [data-theme] 覆盖 + localStorage 持久化，初值跟随 prefers-color-scheme。
3. SVG 图标（lucide 取向）替 Unicode/emoji。
4. 金样板先行：token + 组件库 + 1 消费面（Feed）+ 1 创作面（Create）i18n 化，验证后再批量推其余视图。
5. 统一圆角矩形：禁药丸/椭圆/正圆混用，半径 xs/sm/md/lg/xl=4/6/8/12/20 按尺寸比例（仅 loading 旋转环保留圆形）——铁律见 .agents/rules/ui-uniform-rounded-rectangles.md。

4. 现行架构（4 层组件库 + token 两层 + i18n/主题数据流）

flowchart TD
  subgraph token两层[设计 token · 跨端单一事实源]
    P[primitive<br/>原色板/灰阶/尺寸原子] --> S[semantic<br/>语义令牌] --> CT[component<br/>组件级令牌]
  end
  S --> L0
  subgraph 组件库4层
    L0[L0 token · CSS 变量] --> L1[L1 Vant 适配<br/>vant-theme.css 把 --van-* 映射 semantic<br/>复用 Vant 交互/无障碍/键盘]
    L1 --> L2[L2 品牌基元<br/>AppButton/Field/Icon/Card/Chip/Badge<br/>EmptyState/NavHeader/TabBar/Skeleton/Toast]
    L2 --> L3[L3 业务组合<br/>GameCard/InteractBar/FilterTabs…]
  end
  S -.同份 token JSON.-> 双App[桌面App 复用Web技术 · 移动App RN/Flutter（later）]

数据流：

• token：token(L0) → vant-theme(L1) → 品牌组件(L2) → 业务面(L3)。
• theme：localStorage(studio.theme) → <html data-theme> → 语义层覆盖 → 全组件自动反应（组件只用语义令牌→换肤零改组件）；防 FOUC=index.html 首屏前内联脚本读 localStorage 先设 data-theme/lang。
• i18n：main 注册 → 组件 useI18n($t) → localStorage(studio.lang) + <html lang>。

5. 关键契约（token / 组件 / i18n）

全 additive（旧令牌保留为别名，逐面迁移期共存）；逐令牌清单以 game-studio/src/styles/tokens.css 为权威，此处只列骨架与命名空间。

• token：旧 --cyan/--green/--radius/--shadow… 全保留（--cyan 等设为 --accent 别名，零破坏现有引用）；新增 primitive（--c-cyan/green/pink/amber/violet/red、--c-ink-0..3、--c-on-accent:#061014、--c-on-danger:#2a0608）+ semantic（--bg/--surface-1..3/--accent/--success/--warning/--danger/--border-1..2/--grad-primary/--grad-hot/--focus-ring）+ 尺度（--sp-1..6=4/8/12/16/22/32、--radius-xs..xl=4/6/8/12/20 默认 md、--elev-1..3、--fs-h1/h2/h3/body/caption、--fw-*）；主题 [data-theme=light|dim] 仅覆盖 semantic。手抄 rgba() alpha 统一改 color-mix(in srgb, var(--token) N%, transparent)。
• 组件：AppButton props 不变（type/size/block/loading/disabled），primary 恢复签名渐变（--grad-primary+--fw-cta+--on-accent）、全态（focus-visible 环 / disabled .42 / active scale .97）；Icon 禁 emoji。
• i18n：vue-i18n@10，locale 文件 src/locales/*.{zh,en}.ts 按域命名空间（common/feed/create/profile/entry/taskflow/project/hub/biz）；禁组件内裸中文，缺 key fallback zh-CN，数字/日期/货币用 Intl，品牌串收敛 common.brand（值=绘境AI）。

6. studio vs demo —— 勿误砍 / 勿误判清单

两份「记录型」结论，防后人把 demo 当目标削弱真实能力，或把有意 descope 当缺陷返工。

① 反向超出（studio 有 / demo 无，MVP 真实可用性必需，勿砍）：

• 真实试玩宿主（iframe 沙箱 + SDK/Runtime 注入 + postMessage bridge 双校验 + manifest sha256）——护城河命门，demo 的「试玩」只是 toast + 静态 div。
• 登录注册整屏（sms-login 登录即注册 + 协议门 + redirect 回跳 + anonId 衔接）；demo 无登录概念。
• 分享落地页（独立 /share/:gameId + OG 元数据 + utm 渠道归因）；demo 仅 toast。
• 失败/取消/重试闭环（Task 七枚举失败原因可读映射 + 取消重试 + 进度色）；demo 720ms 模拟整卡 complete 无失败态。
• 发布门禁（7 项客户端预检 + 服务端权威 {admitted,gates} + 三态）；demo 乐观直发无审核。
• 鉴权守卫 + 全链埋点（路由守卫 isRealLogin 仅真 token + perf/play/session 埋点）；demo 纯前端切屏无后端契约。

② 有意 MVP descope（范围非缺陷，勿当缺陷返工）：

• 首页门户（投资人路演载体，归 PC 官网/投资人 demo 远期）。
• 素材中心（Doc A P1/v2.0，不在 55 P0；落地前须补素材契约 + 授权/分成支付模型，采购走后端可信边界不可停 mock）。
• 玩法模板中心（注：此处指 demo 的『玩法品类层市场』屏，已被创始人 2026-06-12 W-CLEAN 废除——与 AGENTS/tech-decisions 中『玩法模板=品类框架·未废·待建』是两回事，勿混）。
• 创作者数据后台（远期；落地须反向定义回读 API + 诊断接生成侧，避免孤儿数据）。
• 多渠道发布（抖音/微信/快手/TapTap，归 HJ-CH-001 另行竞标；feed 终裁不动）。
• 工作坊 IDE 化（六类资产台/智能体对话/授权 IP 模式/编辑态调参；MVP 走「一句话+选模板→整包生成」）。

7. 现状债与遗留

已 done：

• F-1 退出登录孤儿已闭合（Profile 调既有 userStore.logout()，真清 5 个 localStorage 键）。
• 主按钮品牌青绿渐变已回归（AppButton.primary 用 --grad-primary+--on-accent，weight~800）。
• Inter 字体已 self-host（reset.css @font-face + font-display:swap，中文兜底）。
• L-1 消息一级入口已落（TabBar 3→4 tab 含 /message，messageStore.unreadTotal 未读角标）。
• B 端前端归属已定 = studio 承接（src/views/biz/ 已建 BizLeads/BizLeadDetail/BizTemplatePicker/BizCreate，接既有 /app-api/biz/* 7 端点）。
• 字号阶梯 token 已抽（--fs-h1/h2/h3/body/caption）。

遗留（小尾巴）：

• tokens.css:3 注释残留 zaomeng-ai-demo.html 旧路径（实际文件=huijing-ai-demo.html，品牌=绘境AI），措辞漂移待清。
• out 明确不做：原生 App（仅 token 契约就绪）/ RTL / 护眼·高对比主题（后续增量档）。

8. 关键指针

• 落地 commits（均 dev/2.0.0）：42342e8c（Phase0）/ f98ad0f8（P1 token）/ ecae9025（P2 i18n）/ 655673eb（P3 组件库）/ caa2e1ba（P4 代表面）/ 2c96e63a（品牌+helper 收尾）。
• 权威 token 源：game-studio/src/styles/tokens.css。
• 可直开 mockup（真 chrome 验过，含实时 zh/en + 三主题切换）：docs-design/studio-redesign-mockup.html；设计基准：docs-design/huijing-ai-demo.html。
• 构建/走查门：.agents/skills/staging-ops.md（构建真门=npm run build/vue-tsc -b && vite build，vue-tsc --noEmit 是假门）、.agents/skills/ui-walkthrough-cdp.md（CDP 三主题×双语走查）。
• 圆角铁律：.agents/rules/ui-uniform-rounded-rectangles.md。
• 关联 MEMORY：studio-design-system-wave / brand-rename-huijing-to-zaomeng / frontend-spine-built。