@lark-apaas/coding-steering 0.1.11-alpha.0 → 0.1.11-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.11-alpha.0",
+  "version": "0.1.11-alpha.1",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/html/skills/rich-interactive-design/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: rich-interactive-design
+description: Use when generating HTML single-file artifacts for rich 2D/3D interactive experiences—games, real-time simulations, or 3D immersive scenes. 触发词：game, 游戏, 互动玩法, simulation, 模拟, 仿真, 沙盒, 流体, 布料, 粒子, 物理模拟, 元胞自动机, boid, 生态, interactive scene, 3D 场景, 3D 漫游, 沉浸, 虚拟展厅, 产品 3D 展示, Three.js, 虚拟现实, 数字孪生, 富交互.
+hook: SessionStart
+available-agents:
+  - Html
+---
+
+# Rich Interactive Design
+
+3 类富交互前端任务的统一入口：**游戏 / 实时模拟 / 3D 沉浸场景**。承载任务分类路由、跨任务设计原则底座，以及到 `references/` 子模块的渐进式披露。
+
+非富交互类的普通 HTML 任务（落地页、仪表盘、管理后台等）**不在本 skill 范围**——按通用前端设计原则执行，不要硬套本 skill 的方法论。
+
+## §1 任务分类
+
+动手前先判断任务类型。每个新任务归到下列一类，对应到任务文件。
+
+| 分类 | 关键特征 | 对应任务文件 |
+|---|---|---|
+| `game` | 游戏 / 互动玩法（**有胜负 / 挑战 / 玩法循环**） | `references/tasks/game.md` |
+| `simulation` | 实时模拟 / 沙盒 / 物理演示（**无胜负，乐趣来自系统行为本身**：流体、布料、粒子、生态、化学、社会行为等） | `references/tasks/simulation.md` |
+| `interactive-scene` | 3D / 沉浸式场景（自然景观、产品展示、虚拟漫游、建筑、3D 数据可视化） | `references/tasks/interactive-scene.md` |
+| `out-of-scope` | 不属于以上 3 类的 HTML 任务（落地页、仪表盘、报告、PPT、管理后台等） | 退出本 skill，按通用前端设计原则执行 |
+
+## §2 判定优先级
+
+按以下规则自上而下匹配：
+
+1. **玩法机制优先**：涉及胜负 / 挑战 / 玩法循环 → `game`（即使是 3D 游戏也归 game，不归 interactive-scene）
+2. **关键词匹配**：
+   - "模拟 / 仿真 / 沙盒 / 流体 / 布料 / 粒子 / 物理 / 元胞自动机 / boid / 生态" → `simulation`
+   - "3D 场景 / 沉浸 / 漫游 / 展厅 / 产品 3D 展示 / Three.js 场景 / 虚拟现实 / 数字孪生" → `interactive-scene`
+3. **系统行为 vs 视觉空间**：核心是"系统怎么演化" → `simulation`；核心是"场景多美 / 怎么探索" → `interactive-scene`
+4. **都不匹配** → `out-of-scope`，**退出本 skill**，不要给非富交互任务套用本 skill 的反模式与维度框架
+
+## §3 跨类任务
+
+按主要篇幅/价值选一个主类，主任务 `references/tasks/<task>.md` 必读。次类元素（如游戏里嵌一个 3D 关卡 / 模拟器里嵌挑战目标）在生成对应模块时读对应类任务文件的相关章节。
+
+plan 中说明「主类 X，包含 Y 模块」即可。
+
+示例：
+
+- **3D 山脉场景 + 隐藏地标找寻挑战**：主类 = `interactive-scene`（整体光照、相机、性能按 scene 规范）；次类元素 = 计分 / 通关 / 反馈按 `game` §6 难度反馈持久化章节
+- **物理沙盒 + 关卡式挑战目标**（如愤怒的小鸟）：主类 = `simulation`（物理积分、时间步长按 sim 规范）；次类元素 = 关卡 / 计分按 `game` §2 状态机 + §6 难度章节
+- **3D 流体效果展示**（咖啡拉花、wet paint）：主类 = `simulation`（流体算法是核心）；次类元素 = 3D 渲染按 `interactive-scene` §4 渲染性能、§5 光照章节
+
+## §4 易混类目判定
+
+- `game` vs `simulation`：**有胜负 / 挑战目标** → `game`；**无胜负，乐趣来自系统行为本身的可观察 / 可调 / 可创作** → `simulation`。Conway / falling sand 这种无胜负沙盒明确归 `simulation`，不归 `game`
+- `simulation` vs `interactive-scene`：**系统行为本身是核心**（流体演化 / 粒子相互作用 / 物理模拟）→ `simulation`；**视觉与空间体验是核心、系统简单或仅作氛围**（3D 山脉的昼夜变化属于氛围演化）→ `interactive-scene`
+- `interactive-scene` vs `game`（3D 漫游 vs 3D 游戏）：纯探索 / 观赏 / 信息展示 → `interactive-scene`；有目标 / 障碍 / 胜负 → `game`
+
+判断完后，用人话写进 plan 的任务理解部分（不必报内部标签名）。
+
+## §5 设计原则（跨任务底座）
+
+通用、跨富交互分类的视觉与交互设计底线。具体物理参数、相机配置、性能预算等下沉到任务分类文件。
+
+### 5.1 禁用反模式
+
+富交互场景常翻车的"AI 味"模式：
+
+- emoji 充当游戏精灵 / 角色 / 敌人 / 食物（🎮🐍🍎），或当 UI 功能图标
+- `alert()` / `confirm()` / `prompt()` 当反馈或弹窗 —— 破坏沉浸，必须用画布内 UI
+- 黑底白字 + Times New Roman 默认样式 —— 一眼"未做设计"
+- 占位图走 placeholder.com / unsplash 等不稳定外链
+- 七彩 / 多主色（一个作品用 > 2 个主色调），缺乏视觉收敛
+- 默认 60fps 假设、`setInterval` 当主循环、不处理 `visibilitychange` 暂停
+- 不区分桌面 / 移动端输入（PC 只 keydown / 移动端只 click）
+- 加载完成无 fade-in 过渡，首帧突现
+- 模拟 / 3D 场景里大面积装饰性紫蓝渐变背景（科幻味的廉价 AI 审美）
+- Canvas 2D 字符串颜色用 CSS Level 4 空格分隔语法（`hsl(200 90% 65%)` / `hsla(...)`）—— `addColorStop` / `fillStyle` / `strokeStyle` 只解析 Level 3 逗号分隔，空格分隔抛 `could not be parsed as a color`；CSS 上下文（`style.color` / CSS 变量 / Tailwind 配置）两种语法都支持，但写入 Canvas API 字符串参数（含模板字符串拼接）必须用逗号分隔 `hsla(200, 90%, 65%, 0.9)`
+
+### 5.2 默认设计倾向
+
+无明确指令时按以下方向走：
+
+- **配色**：4-6 色 palette 前置定义 + 全程引用常量，禁止散落 magic color；数值场可视化用 viridis / inferno 等色盲友好梯度
+- **字号阶梯**：UI 文字（分数、提示、按钮）字号阶梯清晰，避免 h1/h2/h3 大小近似
+- **间距**：8px grid，禁混用任意值（如 `p-[13px]`）
+- **留白**：UI 元素之间宁多勿少，密集排不出质感
+- **克制**：每个视觉装饰要解决具体问题（反馈玩家行为 / 标识系统状态），不为装饰而装饰
+- **文案**：UI 文字根据场景写真实文案（"开始游戏"、"再来一局"、"重置场景"），不要 Lorem ipsum / "Sample Text" / "Button 1"
+
+### 5.3 资产策略
+
+- **路径按视觉目标选**（不分主次）：
+  - 抽象 / 程式化 / 卡通 → 程序化（SVG / Canvas / Three.js Geometry / Web Audio）
+  - 写实复刻"在用户脑子里有视觉标准答案"的真实物体（地球、人体、汽车……）→ CDN 贴图 + PBR + 真实模型（jsDelivr / threejs.org examples）；程序化几何模拟这类物体一定假
+  - 原创艺术内容（角色 sprite、风格化场景、封面）→ GenerateImage 兜底；详见各 task 文件
+- **图标**：禁止 emoji 充当功能性图标（导航 / 按钮 / 状态指示），用 Lucide 风格 inline SVG
+- **`<img>` alt**：每个 `<img>` 的 `alt` 必须有意义（描述图片内容），不要空 alt 或填文件名
+- **占位图**：禁用 placeholder.com 等外链占位服务；需要时用纯 CSS 占位框或程序化生成
+
+### 5.4 排版纪律（UI 覆盖层适用）
+
+UI 覆盖层（HUD、菜单、参数面板）翻车的常见点：
+
+- **对齐统一**：HUD 各元素左右内边距走同一基线，避免分数 `px-4`、暂停按钮 `px-2`、生命槽 `px-6` 这种混搭
+- **间距分层**：元素内 padding < 元素间 gap < 区块间 section gap，三层至少 1.5-2 倍差异，UI 才不会糊
+- **主从对比**：关键信息（当前分数 / 主操作按钮 / 关键提示）必须靠尺寸、字重、颜色任一维度突出
+
+## §6 渐进式披露指令
+
+识别任务类后，按以下顺序加载文档。**必读组合在同一轮 tool call 中并行 Read**，避免串行等待拉长首响。
+
+### 6.1 已加载
+
+本 SKILL.md §1-§5。
+
+### 6.2 必读组合（同一轮 tool call 并行 Read）
+
+每类任务的 `references/tasks/<task>.md` 都是必读首步。下表列出还要与之**并行加载**的 common 模块（"—" 表示无额外 common，但任务文档本身仍必读）：
+
+| 任务 | 并行加载的 common 模块 |
+|---|---|
+| `game` | `image-generation.md` |
+| `simulation` | `color-system.md`（数值场色彩映射 / 科学可视化配色） |
+| `interactive-scene` | `color-system.md` + `image-generation.md`（环境/纹理素材按需） |
+
+common 模块路径前缀统一为 `references/common/`。
+
+### 6.3 按需补读（出现非典型决策时再发起 Read）
+
+- 涉及生图 prompt（如 `simulation` 需要科学可视化封面图）→ `references/common/image-generation.md`
+- 涉及配色方法论（如 `game` 走色彩心理学）→ `references/common/color-system.md`

package/steering/html/skills/rich-interactive-design/references/common/color-system.md

@@ -0,0 +1,123 @@
+# Color System
+
+跨富交互任务（`game` / `simulation` / `interactive-scene`）通用的 HSL 配色方法论：主色推导 / 灰阶派生 / 对比度 / 状态色 / 科学可视化数值映射。各 task 文件 §视觉风格 章节只列**风格特化收紧值**，方法论统一引用本文。
+
+## 主色选择
+
+**用户已指定主色时，跳过下面的主色推导直接用——本节方法只用于派生灰阶 / accent / 其他 token**。
+
+- 用户已指定 → 直接用，按下面方法派生其他 token
+- 没指定 → 按以下三步生成：
+
+**1. 色相 H**：从任务推出的调性词匹配下表
+
+| 调性方向 | H 范围 |
+|---|---|
+| 信任 / 专业 / 冷静（科学可视化、产品展示、严肃模拟）| 200-230°（蓝）|
+| 自然 / 健康 / 治愈（自然场景、生态模拟、休闲解谜）| 120-160°（绿）|
+| 活力 / 食欲 / 热情（休闲游戏、儿童类、家庭娱乐）| 10-30°（橙红）|
+| 高端 / 神秘 / 文化（沉浸艺术、暗调场景、深度解谜）| 260-300°（紫）|
+| 警示 / 紧迫 / 激情（动作游戏、危机感、危险模拟）| 0-15°（红）|
+| 友好 / 阳光 / 温暖（家庭娱乐、教育模拟、儿童类）| 35-55°（黄橙）|
+
+用法：
+
+- 用推出的**调性词**匹配最贴近的一行
+- 介于两个调性之间时，H 在两范围之间取值
+  - 例："温暖治愈" → 35-55° 与 120-160° 之间 → 取黄绿 80-110°
+- 表外调性按色彩心理学推导
+  - 例："硬核极简 / 工业极客" → 不限 H，S < 10%（中性单色），靠 L 阶梯做层次
+  - 例："霓虹赛博" → H 280-320°（紫粉）+ S > 80%（高饱和）
+
+**2. 饱和度 S** / **3. 亮度 L**：见下方"按风格的 S/L 速查"
+
+## 中性灰阶派生
+
+**从主色派生灰阶**，避免"主色与灰阶不和谐"：
+
+- 取主色色相 H，饱和度降到 **5-12%**（带主色相的"暖灰/冷灰"）
+- 明度阶梯（亮主题）：95% / 90% / 80% / 45% / 15%（对应 bg / surface / border / text-muted / text）
+
+```
+主色 hsl(215 65% 48%)  →  灰阶 hsl(215 8% 95%) / 90% / 80% / 45% / 15%
+```
+
+**禁用纯灰**（饱和度 0%）—— 跟有色主色一起使用会显得不和谐。
+
+**暗主题**（沉浸场景 / 科学可视化 / 暗调动作游戏常用）灰阶翻转：bg / surface / border / text-muted / text = 12% / 18% / 28% / 65% / 92%，灰阶 S = 5-10% 同样从主色派生。
+
+## Accent 选择
+
+- **默认**：主色明亮版（同 H、L 提高 15-20%），用于 hover / 高亮 / 关键反馈（命中提示 / 得分 toast）
+- **罕见**：主色补色做次强调（如蓝主色配橙 accent），需刻意设计才用，**避免七彩**
+
+## 对比度约束
+
+富交互场景的关键文字常常叠在动态背景上，对比要求**普遍高于普通 UI**：
+
+- 关键 UI 文字 on bg ≥ **4.5:1**
+- 主操作按钮（白字按钮）≥ **4.5:1**
+- **HUD 数字**（分数 / 生命 / 计时 / FPS）≥ **7:1** —— 动态背景下扫读必须快
+- **关键提示文字 on 动态背景**（游戏内 toast / 警告 / 模拟参数 readout）≥ **7:1**，必要时加 text-shadow / 半透明底纹保证可读性
+- 暗主题下尤其注意：浅灰文字 on 暗灰背景容易掉到 3:1 以下，要主动拉对比
+
+## 按风格的 S/L 速查
+
+富交互作品的 S/L 范围**更取决于美术风格而非任务类型**。常见风格收紧值：
+
+| 风格倾向 | S 范围 | L 范围 | 主题 | 典型适用 |
+|---|---|---|---|---|
+| **写实 PBR**（自然场景、产品展示、写实模拟）| 20-50% | 25-65% | 亮 / 暗 | `interactive-scene` 自然 / 产品；`simulation` 流体 / 写实拟物 |
+| **像素 8-bit / 16-bit** | 60-90% | 40-70% | 亮 | `game` 怀旧 / 街机 / 复古解谜 |
+| **卡通扁平** | 50-75% | 50-70% | 亮 | `game` 休闲 / 家庭娱乐；轻量教学模拟 |
+| **极简几何** | 30-60%（或 < 10% 中性）| 40-60% | 亮 / 暗 | `game` 益智解谜；`simulation` 抽象演化（boid / Conway）|
+| **霓虹赛博** | 80-100% | 45-65% | 暗 | `game` 节奏类 / 跑酷；`interactive-scene` 暗调氛围 |
+| **科学可视化** | 30-50% + 渐变梯度 | 25-55% | 暗 | `simulation` 数值场（温度 / 流速 / 密度）|
+| **抽象艺术 / 生成艺术** | 大胆，无限制 | 大胆，无限制 | 暗为主 | `interactive-scene` 生成艺术；`simulation` 抽象演化 |
+
+风格在各 task 文件 §视觉风格 / §视觉表达 章节决定，本表只给收紧基线。
+
+## 五类语义色（状态色）
+
+主要用于 **UI 覆盖层**（HUD、暂停菜单、参数面板、设置、通知 toast）。主体的成功 / 失败 / 警告反馈**优先用游戏化手段**（震屏、粒子、音效、hitstop、屏闪），状态色 token 只作辅助。
+
+| 语义 | 推荐色相 H | 用途（富交互场景）|
+|---|---|---|
+| **success**（通关 / 达标 / 模型稳态）| 绿 130-150° | 通关画面、达标徽章、模拟数值正常区间 |
+| **danger**（失败 / 错误 / 危险）| 红 0-10° | 失败画面、模拟即将发散、危险参数 |
+| **warning**（警示 / 临界）| 橙黄 35-50° | 性能下降、资源即将耗尽、参数靠近临界 |
+| **info**（处理中 / 提示）| 蓝 200-220°（或沿用主色）| 加载中、loading、教程提示 |
+| **muted**（已暂停 / 不可用）| 灰阶 text-muted | 暂停状态、不可用按钮、归档 |
+
+S / L 按本文 §主色选择 方法 HSL 化，注册到 `tailwind.config` 的 `success / danger / warning / info / muted` token。
+
+### 状态色纪律
+
+- **禁**把状态色挪用作普通分类色（"敌人类型一绿一红一橙"）—— 误导语义
+- **禁**同一状态用两种颜色 —— 全作品状态色一致映射
+- **禁**装饰性渐变 / 阴影叠在状态徽章上 —— 徽章应纯色 + 文字，扫读快
+- 徽章风格择一统一（填充 / outline），**同一作品不混用**
+
+## 科学可视化数值映射（`simulation` 专用）
+
+模拟类常需把**数值场**（温度 / 速度 / 密度 / 高度 / 浓度）映射到颜色：
+
+| 映射类型 | 推荐 |
+|---|---|
+| 单调数值（温度 / 高度 / 密度 / 速度大小）| **viridis** / **inferno** / **magma**（色盲友好，科学可视化标配）|
+| 方向 / 相位（旋度场 / 流向 / 朝向）| **HSL 色相环**（H 0-360° 映射方向，S/L 固定）|
+| 二极对比（电荷 / 引力符号 / 偏离均值）| 蓝-白-红 diverging（冷 / 中性 / 暖）|
+| 离散类别（粒子类型 / 物种 / 元素种类）| 5 色定性色板（Tableau 10 / Set2）|
+
+**禁用红绿映射数值**（色盲不友好 + 审美差）。
+
+viridis / inferno 等可在 fragment shader 内手写多项式近似（搜 "viridis polynomial GLSL"），不必引入额外库。
+
+## Token 集
+
+主任务通常需要的 token 集（注入 `tailwind.config`）：
+
+- **基础**：`bg / surface / text / text-muted / primary / accent / border`
+- **状态**：`success / danger / warning / info / muted`（仅 UI 覆盖层用）
+
+具体任务的 token 取舍详见各 task 文件。

package/steering/html/skills/rich-interactive-design/references/common/image-generation.md

@@ -0,0 +1,43 @@
+# Image Generation
+
+游戏 / 模拟 / 沉浸场景的 `GenerateImage` 用法。**优先程序化生成**（SVG / Canvas / Three.js Geometry / shader 等，详见各 task 文件），本文聚焦确实需要调 GenerateImage 时的 prompt 公式与开关。
+
+## prompt 构造公式
+
+按以下公式分段构造，每段从本任务推导：
+
+```
+[主体描述] + [风格词] + [构图] + [配色/光线] + 通用尾部
+```
+
+| 部分 | 推导依据 | 示例 |
+|---|---|---|
+| 主体 | 任务的"内容"维度 | "8-bit pixel game character"、"cyberpunk neon city skyline"、"3D mountain landscape at dawn"、"abstract fluid simulation cover" |
+| 风格词 | 各 task 文件 §视觉风格 已推 | "pixel 16-bit"、"flat cartoon"、"minimalist geometric"、"neon cyber"、"photorealistic PBR" |
+| 构图 | 用途决定 | sprite → "centered, transparent background"；场景 → "wide cinematic angle"；封面 → "16:9 hero composition"；seamless 纹理 → "seamless tileable" |
+| 配色 / 光线 | 主色 + 风格派生 | "warm earth tones"、"high contrast neon"、"soft natural lighting"、"dramatic rim light"、"HDR studio lighting" |
+
+通用尾部**按用途选一种**：
+
+- Sprite / 角色 / 物件：`flat icon, transparent background, game asset, no text overlay, no UI mockup`
+- 场景 / 背景 / 封面：`16:9, high resolution, no text overlay, no UI mockup, no AI watermark`
+- Seamless 纹理：`seamless tileable pattern, no obvious seams, high resolution`
+
+## 各任务生图开关
+
+| 任务 | 默认 GenerateImage | 适用场景 | 风格倾向 |
+|---|---|---|---|
+| `game` | **主动调** | sprite / 角色 / 敌人 / 道具 / 关卡背景 / 封面 | 跟随 game.md §5 推出的风格词，使用 game asset 通用尾部；详细公式见 game.md §5 |
+| `interactive-scene` | **按需** | 环境 HDR 风格图 / 关键背景 / 产品场景照 / 抽象艺术封面 | 跟随 interactive-scene.md §7 推出的风格词；写实场景倾向 PBR / studio / 自然光关键词 |
+| `simulation` | **极少**（默认全程式化）| 仅"科学可视化的封面图" / 抽象艺术化模拟的视觉调性参考 | 抽象克制，**禁营销词**（"震撼"/"未来感"/"活力"），用 "scientific visualization"、"abstract data art"、"minimal generative" 等 |
+
+## 风格一致性纪律
+
+同一作品多次调用 GenerateImage 时（如游戏的多个角色、场景的多张参考图），prompt 内**必须包含相同的风格描述词**（如统一带 "pixel 16-bit, warm earth tones"），避免画风分裂。
+
+## 通用禁令
+
+- `<img>` alt 必须有意义，描述图片内容，禁空 alt / 文件名
+- 禁用 placeholder.com / unsplash 等外链占位服务
+- 生成结果以 base64 data URL 嵌入 HTML，**禁外链**（详见各 task 文件资产策略）
+- 不要在生成尾部加 "epic / cinematic / masterpiece" 等大词，产出反而失控（详见 game.md "生图 prompt 写'epic game hero cinematic scene'——产出电影海报而非可用素材" 反模式）

package/steering/html/skills/rich-interactive-design/references/tasks/game.md

@@ -0,0 +1,208 @@
+# Game Design
+
+HTML 单文件游戏 / 互动玩法的专属设计决策。
+
+## Quick Reference
+
+| 决策 | 默认 | 例外 |
+|---|---|---|
+| 类型识别 | 见 §1 三维度推导 | 用户已指定具体玩法 → 直接尊重 |
+| 渲染层 | 见 §3 决策树 | 用户指定 Canvas / DOM → 尊重 |
+| 状态机 | 4 态必有：menu / playing / paused / over | 回合驱动游戏可省 paused |
+| "再来一局" | **必须 reset 全部状态**，禁 `location.reload()` | — |
+| 输入支持 | 桌面键鼠 + 移动 touch **必须同时** | 用户明确单端时尊重 |
+| 关键反馈延迟 | ≤ 100ms | — |
+| 最高分 | 持久化到 localStorage | 用户明确不需要 |
+| 素材 | 主动调 `GenerateImage` 产精灵 / 背景 / UI | 用户已提供 / 玩法不需要素材 |
+
+## 1. 游戏类型识别
+
+从用户描述推三个维度，每次得出**一句话定位**写进 plan：
+
+| 维度 | 取值 |
+|---|---|
+| 实时性 | 实时连续帧（每秒重绘）/ 回合驱动（仅在用户输入后更新） |
+| 状态离散度 | 离散格子（棋盘/网格/卡牌）/ 连续物理（位置 / 速度浮点）/ 表单选择（题目 / 选项） |
+| 主输入通道 | 方向键 WASD / 单击 / 拖拽 / 滑动手势 / 鼠标移动追踪 / 选择题点击 |
+
+输出例：
+
+- "回合驱动 + 离散网格 + 滑动手势 → 合并解谜类（2048）"
+- "实时连续 + 连续物理 + 方向键 → 横版动作 / 跑酷"
+- "回合驱动 + 表单选择 + 点击 → 多步答题 / 剧情分支"
+- "实时连续 + 离散网格 + 单击 → 打地鼠 / 反应速度类"
+
+这三个维度直接决定 §3 渲染层、§4 输入、§5 视觉。
+
+**禁止组合**（违反认知）：益智解谜 × 抖屏闪光 / 儿童益智 × 暗黑血腥 / 慢节奏阅读 × 高刺激粒子 / 单功能反应训练 × 复杂剧情。
+
+## 2. 核心循环与状态机
+
+### 4 态状态机（强制）
+
+```
+menu  ──start──▶  playing  ──pause──▶  paused
+                     │  ◀──resume──┘
+                     │
+                     └──lose/win──▶  over  ──restart──▶  playing
+```
+
+每个状态都要有清晰的回退路径，禁"卡死"无出口的中间态。回合驱动游戏可省 paused（玩家自然停手即是暂停）。
+
+### 核心循环契约
+
+- **反馈窗口**：用户输入到屏幕产生**任何**视觉变化 ≤ 100ms。粒子 / 数字弹出 / 缩放 / 颜色脉冲任选一种作为"打击感"
+- **"再来一局"必须 reset 整局状态**：分数清零、棋盘清空、计时器重置。**禁用** `location.reload()` 当重启——交互契约要求按钮真实工作，而非粗暴刷新页面
+- **暂停态**：实时类游戏必须暂停时停止主循环（`cancelAnimationFrame`），不是把 dt 设 0 继续空转；回合类不需要暂停
+- **结束态**：必须有 Game Over 面板（本局分数 + 最高分 + 再来一局按钮），**禁用** `alert()` / `confirm()` 报分或问"是否重玩"
+
+### 主循环写法
+
+实时类用 `requestAnimationFrame`，**禁** `setInterval` 当主循环（与刷新率失同步 / Tab 失焦累积）。回合类无需主循环，事件驱动即可——不要为了"像游戏"硬塞 rAF。
+
+## 3. 渲染选择决策树
+
+按三问决定渲染层，**不要默认 Canvas**：
+
+1. **状态是否离散网格？** 是 → DOM
+2. **是否需要每帧重绘连续动画？** 是 → Canvas
+3. **是否纯静态形状 + 简单过渡？** 是 → SVG / CSS 动画即可
+
+| 类型推导（§1） | 推荐层 |
+|---|---|
+| 回合 + 离散网格（2048 / 三消 / 推箱子 / 卡牌） | **DOM 网格** |
+| 实时 + 连续物理（跑酷 / 打砖块 / 弹幕） | **Canvas 2D** |
+| 实时 + 离散网格（打地鼠） | **DOM**；动画密集才 Canvas |
+| 回合 + 表单选择（答题 / 剧情） | **DOM 表单 + 状态** |
+| 静态几何 + 过渡（拼图慢动作） | **SVG** 或 CSS |
+
+DOM 网格常见误区：用 `position: absolute` 配像素 left/top 排格子。改用 **CSS Grid**（`grid-template-columns: repeat(N, 1fr)`），每格是 grid item，合并/移动用 `transform` + `transition`。
+
+## 4. 双端输入设计
+
+HTML 单文件不能预设设备，桌面键鼠 + 移动 touch **必须同时**支持，**除非**用户明确说"只做桌面 / 只做移动"。
+
+### 输入通道映射
+
+| 主输入（§1 推出） | 桌面绑定 | 移动绑定 |
+|---|---|---|
+| 方向键 / WASD | `keydown` | 屏幕方向虚拟键 **或** 画布 swipe 手势 |
+| 单击 / 选择题 | `click` | `click`（浏览器自动合成） |
+| 拖拽 | `mousedown/move/up` | `touchstart/move/end`（或 Pointer Events 统一） |
+| 滑动手势（2048 类） | 方向键 `keydown` + 画布 swipe | 画布 swipe |
+| 鼠标移动追踪 | `mousemove` | 退化为 `touchmove` 拖拽 |
+
+优先 **Pointer Events** 统一两端，减少分支。
+
+### 移动端额外约束
+
+- 游戏容器加 `user-select: none; touch-action: none;`——防止长按选中、防止 swipe 触发页面滚动
+- 顶部留出 safe area：`padding-top: env(safe-area-inset-top)`
+- 移动端字号 ≥ 14px，按钮触控区 ≥ 44 × 44px
+
+## 5. 视觉风格与游戏素材生图
+
+### 风格选择（从 §1 类型推一句话风格词）
+
+常见方向（任选其一，**不要混风格**）：
+
+- 像素 8-bit / 16-bit（怀旧街机 / 复古解谜）
+- 卡通扁平（休闲 / 家庭娱乐）
+- 极简几何（益智解谜 / 抽象类）
+- 霓虹未来（赛博跑酷 / 节奏类）
+- 手绘水彩 / 涂鸦（绘本 / 儿童 / 剧情）
+
+风格词写进 plan 一行，后续配色、字体、生图、动效都依据这条决策。
+
+### 游戏素材 prompt 公式（本任务特有，与 `references/common/image-generation.md` 通用公式不同）
+
+```
+[游戏元素] + [素材类型] + [风格词] + [构图/视角] + [配色] + flat icon, transparent background, game asset, no text overlay
+```
+
+游戏要的是 **game sprite / tile / character icon**，构图是"中央元素 + 透明背景"，**不是**电影级场景。
+
+| 部分 | 推导依据 | 示例 |
+|---|---|---|
+| 游戏元素 | 玩法本身 | "数字方块 2/4/8"、"卡通蛇头"、"打砖块块"、"答题角色头像" |
+| 素材类型 | 用途 | "game tile sprite"、"character avatar"、"background tile"、"icon button" |
+| 风格词 | 上面已推 | "pixel 16-bit"、"flat cartoon"、"minimalist geometric"、"neon cyber" |
+| 构图 | 素材常用中央透明 | "centered icon, transparent background" / "seamless pattern"（背景平铺） |
+| 配色 | 跟主题色一致 | "warm earth tones"、"high contrast neon" |
+
+通用尾部固定追加：`flat icon, transparent background, game asset, no text overlay, no UI mockup`。
+
+仅需要场景背景大图（非精灵）时才用 16:9 横构图。
+
+## 6. 难度 / 反馈 / 持久化
+
+### 难度曲线
+
+- **第一局别 3 秒死**：起手难度必须让玩家拿到 ≥ 1 次反馈循环（≥ 1 个合并、≥ 1 次得分、≥ 1 关通过）才"开始有挑战"
+- **进度感**至少满足一种：得分递增 / 速度递增 / 关卡推进 / 等级提升 / 棋盘扩大
+- 无限模式：动态调难度（每 N 分加速 / 每 N 关增加敌人）。有限关卡：内嵌数据，关卡 ≥ 5
+
+### 反馈强度（HTML 单文件无音频默认 → 视觉是核心）
+
+每次有效操作至少触发一种视觉反馈：
+
+- 数字/分数变化用**动画**（弹出、缩放、上浮消失）而非瞬移
+- 关键状态变更（合并 / 命中 / 击破 / 答对）用粒子或闪光，1-2 帧高亮
+- 错误反馈用**抖动**（CSS keyframes `translate: ±4px`），不要全屏颜色闪烁
+- 屏幕震动只对**游戏容器**做 `transform: translate()` 关键帧，**不要**改 body margin / scroll 位置
+
+`alert()` / `confirm()` / `prompt()` **全程禁用**——破坏沉浸。所有提示用游戏内 UI 面板。
+
+### 持久化
+
+- 最高分 `localStorage.setItem('<game>_best', score)`，开局读出来在 HUD 显示
+- 当前局进度不必持久化（关 Tab = 重玩）
+- localStorage 读写包 `try/catch`（隐私模式可能抛错）
+
+## 游戏特有反模式
+
+- Game Over 后只能 `location.reload()`，"再来一局"按钮实际是刷新页面
+- 用 `alert("得分：" + score)` 报分 / 用 `confirm()` 问"是否再来一局"
+- 移动端长按游戏元素弹出系统菜单（缺 `user-select: none` / `touch-action: none`）
+- 实时类游戏用 `setInterval(loop, 16)` 当主循环
+- emoji（🎮🐍🍎🍪）当游戏精灵 / 角色 / 敌人 / 食物
+- 棋盘 / 格子用 `position: absolute` + 像素 left/top，而非 CSS Grid
+- 暂停按钮存在但无 handler，或暂停后主循环继续空转
+- 单一难度——从开局到第 100 分速度毫无变化
+- 移动端用 `keydown` / `keypress` 检测输入（移动端无键盘）
+- 生图 prompt 写"epic game hero cinematic scene"——产出电影海报而非可用素材
+
+## Worked Example
+
+> 用户输入："做一个 2048 风格的合并解谜小游戏，要好看。"
+>
+> **§1 类型识别**：回合驱动 + 离散 4×4 网格 + 滑动手势 → 「回合制 / 离散网格 / 滑动 → 合并解谜类」
+>
+> **§2 状态机**：menu（开始按钮 + 最高分）→ playing（4×4 网格 + 当前分 + 最高分 HUD）→ over（棋盘满且无可合并触发）→ restart 回 playing。无 paused（回合驱动不需要）。
+>
+> **§3 渲染层**：离散网格 + 回合驱动 → **DOM 网格**：
+>
+> - CSS Grid `grid-template-columns: repeat(4, 1fr)`，每数字格是 grid item
+> - 合并动画 `transform: scale(1.15) → scale(1)` + `transition: 120ms`
+> - 新格出现 `scale(0) → scale(1)` 弹出
+> - 不上 Canvas
+>
+> **§4 双端输入**：
+>
+> - 桌面：`keydown` 绑 4 方向键 + WASD
+> - 移动：游戏容器监听 `touchstart/touchend`，按 dx/dy 判 4 方向 swipe
+> - 容器加 `user-select: none; touch-action: none;`
+>
+> **§5 视觉风格**：「极简几何 + 暖色阶」（解谜类合适极简）
+>
+> - 主色按配色规则推：H ≈ 30° 暖橙，S 65% L 55%；灰阶从 30° 派生
+> - HUD 字体：`font-family: 'Press Start 2P', monospace, sans-serif`
+> - **不调 GenerateImage**——2048 没有精灵需求，纯数字 + 色块就够
+>
+> **§6 难度 / 反馈 / 持久化**：
+>
+> - 难度：自然进阶（合并越大越难凑）
+> - 反馈：合并时格子 `scale` 弹动 + 数字上浮 `+N`；新格 `scale` 弹出；首次 2048 出现时全屏闪光 + 提示面板
+> - 持久化：`localStorage` 存 `best`，开局读
+>
+> **不要照抄此例**——同样需求另一次推可能选「卡通扁平 + 蓝绿主色」或「霓虹暗色 + Canvas 走粒子合并」，都是合理的。按 §1-§6 维度从本任务重新推导。

package/steering/html/skills/rich-interactive-design/references/tasks/interactive-scene.md

@@ -0,0 +1,274 @@
+# Interactive Scene Design
+
+HTML 单文件 3D / 沉浸式场景类的专属设计决策。覆盖自然场景（山脉、海洋、星空）、产品展示（360° 旋转预览）、虚拟漫游（建筑、虚拟展厅）、抽象空间（数据结构 3D 可视化、概念演示）等"用户探索 + 美学体验"为主的场景。
+
+与 `simulation` 的本质区别：**简单系统下的强视觉/强空间感**，而非"模拟系统行为"。与 `game` 的本质区别：**没有挑战与胜负**。
+
+## Quick Reference
+
+| 决策 | 默认 | 例外 |
+|---|---|---|
+| 技术栈 | **Three.js** | 用户明确要 Babylon / WebGPU 时尊重 |
+| 相机控制 | OrbitControls + 阻尼 + 移动端 touch 支持 | 第一人称漫游 → PointerLockControls；纯展示无交互 → 仅自动旋转 |
+| 加载体验 | **必有 loading 进度**（黑/纯色屏 + 进度数字），禁直接白屏到首帧 | 加载 < 200ms 可省 |
+| 光照基础 | 至少 1 直射 + 1 环境，禁纯 ambient 全亮 | 卡通/扁平风格可调整 |
+| 材质 | **MeshStandardMaterial**（PBR） 默认，不要 MeshBasicMaterial 当主材质 | 程式化/极简风格除外 |
+| 性能预算 | Draw calls ≤ 100；总顶点 ≤ 500k；纹理总和 ≤ 32MB | 移动端各砍半 |
+| 资源释放 | 切换 / 销毁场景必须 `geometry.dispose()` + `material.dispose()` + `texture.dispose()` | — |
+| Pixel Ratio | `min(devicePixelRatio, 2)`，不能直接用 dpr | — |
+| 移动端 | `touch-action: none` + 双指缩放手势 + 减面减分辨率 | — |
+
+## 1. 场景类型识别
+
+从用户描述推三个维度，得出**一句话定位**写进 plan：
+
+| 维度 | 取值 |
+|---|---|
+| 场景内容 | 自然（地形/天空/海/植物）/ 产品（单物体展示/对比）/ 建筑空间（漫游/导览）/ 抽象（数据/概念可视化）/ 抽象艺术（生成几何/参数化） |
+| 用户角色 | 观看（仅看自动巡游）/ 操控相机（轨道旋转、缩放、平移）/ 漫游（第一人称走动）/ 探索（点击热点、模式切换、对比） |
+| 时间维度 | 静态（无演化）/ 周期演化（昼夜、季节、潮汐自动循环）/ 用户驱动演化（拨滑块控制时间） |
+
+输出例：
+
+- "自然 + 操控相机 + 周期演化 → 3D 自然景观（山脉昼夜、海洋日落）"
+- "产品 + 操控相机 + 静态 → 商品 3D 展示（鞋、车、家具）"
+- "建筑空间 + 漫游 + 静态 → 虚拟展厅 / 房屋导览"
+- "抽象 + 探索 + 静态 → 3D 数据可视化（节点图、力导向）"
+- "抽象艺术 + 观看 + 周期演化 → 生成艺术展示"
+
+这三维度直接决定 §3 相机方案、§5 光照与时间、§6 交互层。
+
+**禁止组合**（违反认知）：商品展示 × 阴森暗光 / 自然景观 × 霓虹紫粉 / 严肃数据可视化 × 卡通材质 / 建筑漫游 × 强烈鱼眼变形。
+
+## 2. 资源加载与首屏
+
+3D 场景的杀手用户体验 = **白屏 → 突然出现完整场景**。必须有过渡：
+
+### 加载状态（必备）
+
+```js
+const loadingManager = new THREE.LoadingManager(
+  () => fadeOutLoadingScreen(),        // 全部加载完
+  (url, loaded, total) => updateProgress(loaded / total)  // 进度更新
+);
+const textureLoader = new THREE.TextureLoader(loadingManager);
+const gltfLoader = new GLTFLoader(loadingManager);
+```
+
+页面打开 → 全屏纯色 + 进度条/数字 → 加载完 fade out → 场景渐现（0.5s）。**禁止**首帧白屏到画面突现。
+
+### 资源策略
+
+- 模型：`.glb` 二进制格式（不要 `.gltf` + 分离的 bin），DRACO 压缩可选
+- 纹理：`.webp` 优先，回退 `.jpg`；HDR 环境贴图用 `.hdr` 或 RGBM `.png`
+- 资源体积控制：单纹理 ≤ 4MB，总场景 ≤ 32MB（移动端 ≤ 16MB）
+- CDN 路径：自由选用 jsDelivr / Three.js 官方 examples，禁占位图外链
+
+## 3. 相机控制
+
+按用户角色（§1）选控制器：
+
+| 用户角色 | 控制器 | 关键配置 |
+|---|---|---|
+| 观看 | 无控制器 + 自动 `orbit` 缓慢自转 | rotation per frame ≈ 0.001 rad |
+| 操控相机 | **OrbitControls** | `enableDamping = true`、`dampingFactor = 0.05`、限制 polarAngle 防止穿地 |
+| 漫游 | PointerLockControls + WASD + 重力 | 桌面专属；移动端退化为虚拟摇杆 |
+| 探索 | OrbitControls + 点击切视角（tween 过渡） | 视角切换手写 lerp + easing 函数（如 `easeInOutCubic`），禁瞬移； |
+
+### 必备约束
+
+- **限制角度**：地面场景 polarAngle ∈ [10°, 80°]，禁止看到地面以下
+- **限制距离**：min/max distance 防止穿物体或飞到太空
+- **阻尼**：`enableDamping` 让操作有惯性感，不要瞬停
+- **重置视角按钮**：用户飞偏了能一键回到初始视角，tween 0.6s
+
+### 移动端
+
+- `touch-action: none`（防 swipe 触发页面滚动）
+- 双指缩放 + 单指拖拽旋转 + 双指拖拽平移（OrbitControls 默认支持）
+- 灵敏度移动端略低于桌面（避免误触）
+
+## 4. 渲染与性能
+
+### Pixel Ratio
+
+```js
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+```
+
+不要 `setPixelRatio(window.devicePixelRatio)`——4K 屏 dpr = 2 但有些手机 dpr = 3 或 4，纯按 dpr 渲染量爆炸卡死。
+
+### Draw Call 预算
+
+- 桌面 ≤ 100，移动端 ≤ 50
+- 多个相同物体用 **InstancedMesh** 合并（一次 draw call 渲染 N 个）
+- 静态场景用 **BufferGeometryUtils.mergeBufferGeometries** 合并相邻 mesh
+
+### LOD（细节层次）
+
+镜头远了切低面模型，近了切高面：
+
+```js
+const lod = new THREE.LOD();
+lod.addLevel(highMesh, 0);
+lod.addLevel(midMesh, 50);
+lod.addLevel(lowMesh, 200);
+```
+
+地形/植被类场景必用 LOD，否则远处大片高面物体把性能拖垮。
+
+### 移动端优化
+
+- 减半渲染分辨率：`renderer.setSize(w * 0.7, h * 0.7)` + CSS 拉伸
+- 关闭阴影或用低分辨率阴影（`shadow.mapSize = 512`）
+- 减少粒子数 / 关闭高级后期（bloom、SSAO）
+
+### 资源释放（切场景 / 销毁必做）
+
+```js
+function disposeScene(scene) {
+  scene.traverse((obj) => {
+    if (obj.geometry) obj.geometry.dispose();
+    if (obj.material) {
+      const m = obj.material;
+      Object.values(m).forEach(v => v?.isTexture && v.dispose());
+      m.dispose();
+    }
+  });
+}
+```
+
+不 dispose 切场景一次内存涨几十 MB，第三次切就 crash。
+
+## 5. 光照与时间演化
+
+### 光照基础组合
+
+| 场景类型 | 推荐光照 |
+|---|---|
+| 室外自然 | DirectionalLight（太阳）+ HemisphereLight（天空 + 地面色） |
+| 室内/产品 | 3 点布光：主光（DirectionalLight）+ 辅光（DirectionalLight 弱）+ 边缘光 |
+| 程式化/极简 | AmbientLight + 1 DirectionalLight |
+| 写实 | EnvironmentMap（HDR）+ DirectionalLight 阳光，PMREMGenerator 预处理 |
+
+**禁止**：纯 AmbientLight 全亮（场景扁平无立体）；强度全开（>2 的 intensity 让金属材质曝白）
+
+### 昼夜 / 周期演化
+
+时间演化场景（§1 时间维度 = 周期演化 / 用户驱动）必做：
+
+- 太阳位置随时间在天穹上扫弧
+- 太阳颜色：日出/日落 `0xffaa44` 暖橙 → 正午 `0xfff5e0` 暖白 → 夜晚 `0x223366` 冷蓝
+- 天空颜色用 `Sky` shader（Three.js examples 自带）或自实现 fragment shader 上下渐变
+- 环境光强度随昼夜变化（夜晚 0.2，正午 0.6）
+- 用户驱动：滑块 ∈ [0, 24]，实时更新太阳与光色
+
+## 6. 交互层与模式切换
+
+3D 场景"沉浸"之上还得"可探索"。常用交互模式：
+
+### 热点 / 信息点
+
+- 用 `Sprite` + 透明纹理或 HTML overlay（CSS `position: absolute` + WebGL 坐标 → 屏幕坐标投影）
+- 点击触发面板弹出 / tween 相机到该位置
+- 移动端用 `touchend`，不用 `click`（300ms 延迟会让用户觉得卡）
+
+### 模式切换（如等高线 / 线框 / 透明）
+
+- 切换按钮浮在右上角，托盘式 UI
+- 等高线：自实现 fragment shader 用 `fract(vWorldPosition.y * lineFreq)` 阈值判定，比加 mesh 高效
+- 线框：`material.wireframe = true`（最简但低质感），或自实现 fragment shader 画边
+- 透明 / X 光：调 `material.opacity` + `transparent: true` + `depthWrite: false`
+
+### Raycaster 点击拾取
+
+```js
+const raycaster = new THREE.Raycaster();
+raycaster.setFromCamera(pointer, camera);
+const hits = raycaster.intersectObjects(targets, false);
+```
+
+`targets` 显式列出可点物体，**不要** `intersectObjects(scene.children, true)`——递归遍历整个场景每帧爆炸。
+
+### 自动巡游 / 相机动画
+
+观看类场景默认应该有"惊艳首屏"动画：开局相机从远处缓慢推近 + 轻微环绕，2-3 秒后停止让用户接管。
+
+## 7. 视觉风格
+
+### 风格倾向
+
+| 场景类型 | 推荐风格 |
+|---|---|
+| 自然景观 | 写实 PBR + HDR 环境光 + 真实大气散射 |
+| 产品展示 | 干净 studio 灯光（HDR studio.hdr）+ 浅灰/纯色背景 + 柔和阴影 |
+| 建筑漫游 | 写实 PBR + 真实材质（混凝土、玻璃、木）+ 局部强调灯 |
+| 抽象数据 | 暗底 + 高饱和发光（emissive + bloom 后期） |
+| 生成艺术 | 极简几何 + 程式化材质 + 大胆配色 |
+
+### 后期处理（按需）
+
+`EffectComposer` + `UnrealBloomPass`（发光）/ `SMAAPass`（抗锯齿）/ `SSAOPass`（环境光遮蔽）
+
+不要默认全开后期——移动端会爆。只在视觉受益大的场景加（如夜景发光、暗调氛围）。
+
+## 场景特有反模式
+
+- **白屏到首帧突现**——没有 loading 进度
+- **纯 AmbientLight 全亮**——画面扁平如纸片
+- **MeshBasicMaterial 当主材质**——无光照响应，看着像未渲染
+- **Canvas 2D / 程序化生成写实物体纹理（地球、月球、人脸、汽车、知名建筑等"用户脑中有真实标准答案"的物体）**——一定会被识破为假；必须用 CDN 真实贴图
+- **不 dispose**——切场景内存爆炸，几次后 crash
+- **`setPixelRatio(devicePixelRatio)`**——高 dpr 手机直接卡死
+- **OrbitControls 不限制 polarAngle**——用户翻到地下看到悬空模型
+- **Raycaster 每帧 `intersectObjects(scene.children, true)`**——递归全场景 60 次/秒
+- **render loop 里 `new THREE.Vector3()`**——GC 风暴
+- **移动端不 `touch-action: none`**——拖拽场景同时滚动页面
+- **桌面 / 移动同一套灵敏度**——手机操作太灵或太钝
+- **加载完场景突现无过渡**——0 帧 fade in 突兀
+- **太阳颜色一日不变**——黄昏还是白光太阳，假
+- **后期 bloom 强度 > 2**——所有亮处都晕成一团白
+
+## Worked Example
+
+> 用户输入："3D HTML 山脉场景，含悬崖、河流、昼夜光照变化。支持拖动缩放、动画过渡、真实感渐变色，可切换等高线显示。"
+>
+> **§1 类型识别**：自然 + 操控相机 + 周期演化 + 探索（等高线切换）→ 「3D 自然景观 + 时间演化 + 模式切换」
+>
+> **§2 加载**：LoadingManager 接 TextureLoader（地形 heightmap、岩石/草地纹理、HDR 天空）；纯黑屏 + 进度数字 → 加载完 fade out 0.5s → 场景 fade in
+>
+> **§3 相机**：OrbitControls，dampingFactor 0.05；polarAngle ∈ [10°, 80°] 防穿地；min/max distance 限制；右上角"重置视角"按钮 tween 0.6s
+>
+> **§4 性能**：
+>
+> - 地形：PlaneGeometry 256×256 段，displacement 用 heightmap 纹理（不用 vertex 数组手动算）
+> - LOD：远景地形 64×64 段切换
+> - InstancedMesh：树木 / 岩石散布 500 个，单 draw call
+> - PixelRatio `min(dpr, 2)`；移动端 `setSize(w * 0.7, h * 0.7)` + CSS 拉伸
+> - 阴影：DirectionalLight casts shadow，`shadow.mapSize = 1024`（移动端 512）
+>
+> **§5 光照与时间**：
+>
+> - DirectionalLight 太阳 + HemisphereLight 天空-地面光
+> - Sky shader（Three.js examples）+ Sun position 联动
+> - 滑块 0-24 控制时间：日出 (5h) 暖橙 → 正午 (12h) 暖白 → 黄昏 (18h) 深橙 → 夜 (22h) 冷蓝 + 月光弱直射
+> - 自动循环模式：勾选后时间自动以 1 分钟/天 流逝
+>
+> **§6 交互层**：
+>
+> - 模式切换托盘（右上角）：默认渲染 / 等高线 / 线框
+> - 等高线模式：fragment shader 用 `step(0.05, fract(vWorldPosition.y * 0.1))` 画等高线 + 高度颜色映射（viridis）
+> - 河流：PlaneGeometry + 水 shader（动画 uv 偏移 + 法线扰动 + 透明 + 反射环境）
+> - 拖拽 / 缩放：OrbitControls 自动支持桌面 + 移动 touch
+>
+> **§7 视觉**：写实 PBR + HDR 环境光（开源 venice_sunset.hdr 或类似）；地形材质用 splat map（草 / 岩 / 雪按高度混合）
+>
+> **反模式提醒**：
+>
+> - 必须 `min(dpr, 2)` 不能直接 dpr
+> - 必须 dispose geometry/material/texture（虽然这是单场景，但树木 InstancedMesh 需要正确释放）
+> - Raycaster 不要每帧全场景遍历——本例没有点击拾取，可省
+> - 太阳颜色不能恒定，必须随时间变
+> - 必须有 loading 进度
+>
+> **不要照抄此例**——同样需求换成"低多边形风格 + 程式化生成地形（noise）"也合理。按 §1-§7 维度从本任务重新推导。

package/steering/html/skills/rich-interactive-design/references/tasks/simulation.md

@@ -0,0 +1,238 @@
+# Simulation Design
+
+HTML 单文件实时模拟 / 沙盒 / 物理演示类的专属设计决策。覆盖流体、布料、粒子、生态、化学、电路、社会行为等"用户观察 + 调参 + 体验系统演化"的场景。
+
+与 `game` 的本质区别：**没有胜负目标，乐趣来自系统行为本身的可观察性、可调性、可创作性**。
+
+## Quick Reference
+
+| 决策 | 默认 | 例外 |
+|---|---|---|
+| 类型识别 | 见 §1 三维度推导 | 用户已指定具体模拟物 → 直接尊重 |
+| 时间步长 | **固定 dt（如 1/60s）+ 帧间多步细分**，禁止用真实帧 dt 直接积分 | 纯展示无物理时可放宽 |
+| dt 上限 | **强制夹紧到 ≤ 50ms**，防止 tab 切回时一次性追赶炸毁 | — |
+| 主循环暂停 | `visibilitychange` 切走必须停 `cancelAnimationFrame` | — |
+| 渲染层 | 见 §4 决策树 | 用户指定 Canvas/WebGL/Three → 尊重 |
+| 参数面板 | **必有**，关键参数实时可调 + 预设档位 + 重置按钮 | 演示类极简可省，但至少保留重置 |
+| 性能预算 | Canvas 2D 粒子 ≤ 5000；WebGL/Three ≤ 100k | 用户明确低端机适配则各砍半 |
+| FPS 显示 | 调试期内嵌（角落小字），release 可去 | — |
+| 用户创作 | 若涉及绘制/雕刻，必须支持撤销 / 清空 / 截图保存 | 纯观察类不需要 |
+
+## 1. 模拟类型识别
+
+从用户描述推三个维度，得出**一句话定位**写进 plan：
+
+| 维度 | 取值 |
+|---|---|
+| 系统介质 | 连续场（流体/电磁/温度）/ 离散粒子（沙、雪、雨）/ 刚体（碰撞、堆叠）/ 软体（布料、绳索、果冻）/ 离散网格演化（Conway / 元胞自动机）/ 行为体（boid / 蚁群 / 捕食） |
+| 用户角色 | 旁观（看演化）/ 调参（拨滑块改变行为）/ 创作（拖拽 / 喷射 / 雕刻输入物质）/ 干预（点击施加力 / 删除粒子） |
+| 视觉维度 | 2D 平面（俯视/侧视/截面）/ 3D 场景 / 2D + 伪 3D（等距视图 + 深度排序） |
+
+输出例：
+
+- "连续场 + 创作 + 3D 场景 → 流体绘画类（咖啡拉花、wet paint）"
+- "离散粒子 + 干预 + 2D 截面 → 沙池模拟（falling sand）"
+- "刚体 + 创作 + 2D 平面 → 物理积木（box2d 演示）"
+- "行为体 + 旁观/调参 + 2D 俯视 → 群体行为（boid 鸟群）"
+- "离散网格演化 + 旁观/调参 + 2D 平面 → Conway / 元胞自动机"
+
+这三维度直接决定 §3 时间步长策略、§4 渲染层、§5 交互形态。
+
+## 2. 时间步长与数值稳定性
+
+**模拟类的头号杀手是 dt 失控**。必须按以下契约写主循环：
+
+### 固定 dt + 帧间细分（推荐范式）
+
+```js
+const FIXED_DT = 1 / 60; // 物理步长，跟显示无关
+let accumulator = 0;
+let lastTime = performance.now();
+
+function loop(now) {
+  let frameDt = (now - lastTime) / 1000;
+  lastTime = now;
+  if (frameDt > 0.05) frameDt = 0.05; // 强制夹紧上限，防 tab 切回炸毁
+  accumulator += frameDt;
+  while (accumulator >= FIXED_DT) {
+    simulate(FIXED_DT);
+    accumulator -= FIXED_DT;
+  }
+  render(accumulator / FIXED_DT); // 插值因子供渲染层做平滑
+  requestAnimationFrame(loop);
+}
+```
+
+### 数值积分选型
+
+| 场景 | 积分方法 |
+|---|---|
+| 简单粒子、boid、低精度 | Explicit Euler（最简单，可能漂移） |
+| 弹簧、布料、软体 | Verlet（位置式，能量保持好） |
+| 高精度刚体 / 轨道 | RK4 或子步细分 Euler |
+| 流体 / Navier-Stokes | Semi-Lagrangian 或 Stable Fluids（Jos Stam 范式） |
+
+不要默认 Euler——布料和流体用 Euler 会"炸"（数值发散）。
+
+### 暂停 / 失焦
+
+- 切 tab：`document.visibilitychange` → 切走 `cancelAnimationFrame` + 记录暂停时刻，切回不要补帧
+- 显式 pause 按钮：与失焦走同一暂停状态，恢复时重置 `lastTime = performance.now()` 防 dt 跳变
+
+## 3. 性能预算与优化
+
+### 默认上限
+
+| 渲染层 | 粒子/单元上限 | 备注 |
+|---|---|---|
+| Canvas 2D `fillRect` 逐粒子 | ~5000 | 用 `ImageData` 直绘像素可到 10w+ |
+| Canvas 2D `arc` 逐粒子 | ~2000 | 圆形开销大于矩形 |
+| WebGL points/instanced | 100k+ | 唯一可行的高粒子方案 |
+| Three.js InstancedMesh | 50k+ | 单 draw call |
+| DOM 网格（CSS Grid） | ~2500（50×50） | 元素数超过 5000 浏览器吃力 |
+
+### 必备优化
+
+- **Spatial partitioning**：邻域查询走网格哈希或四叉树，禁止 O(n²) 两两遍历（超过 500 粒子直接卡）
+- **对象池**：粒子频繁生成销毁时复用对象，避免 GC 风暴
+- **render loop 不分配**：禁止在每帧 `new Vector3()` / `new Array()`，全程复用 scratch 对象
+- **典型反例**：`particles.forEach(p => particles.forEach(q => { /* 算距离 */ }))` — 200 粒子还行，2000 直接炸
+- **OffscreenCanvas + Worker**：超大粒子或重计算（流体场）跑 worker，主线程只 blit
+
+## 4. 渲染层决策树
+
+按四问决定渲染层：
+
+1. **是否需要 3D 视角 / 光影 / 相机切换？** 是 → **Three.js**
+2. **是否粒子/单元数 > 5000？** 是 → **WebGL（自写 shader 或 Three.js InstancedMesh）**
+3. **是否离散网格 ≤ 50×50 且需要交互单元格？** 是 → **DOM Grid**
+4. **其他情况** → **Canvas 2D**
+
+| 类型推导（§1） | 推荐层 |
+|---|---|
+| 连续场流体 + 2D | Canvas 2D（双 buffer 直绘 ImageData） |
+| 连续场流体 + 3D（如咖啡拉花） | Three.js（surface mesh + shader uv 扰动）或 WebGL |
+| 离散粒子（≤ 5k） | Canvas 2D |
+| 离散粒子（> 5k） | WebGL points |
+| 刚体物理 | 简单场景（Pong / Breakout / 弹球 / 单体重力）原生自实现；复杂场景（多体堆叠 / Joint / 约束 / 完整 2D 物理沙盒）→ **Matter.js**；3D 物理需求 → Rapier（需说明理由） |
+| 离散网格演化（Conway） | Canvas 2D 直绘像素 |
+| 行为体（boid） | Canvas 2D |
+
+### 常见库
+
+- **2D 刚体物理**：
+  - 简单场景（AABB 碰撞、弹簧、单体重力、Verlet 粒子）→ **原生 JS 自实现**，更轻、依赖少
+  - 复杂场景（多体堆叠、Joint、约束、完整物理沙盒）→ **Matter.js**
+- **3D 物理**：Rapier，**不在默认白名单**，需在 plan 中说明理由后引入
+- **流体**：建议自实现 Stable Fluids（短小）；复杂的用 GPGPU + GLSL
+- **3D 渲染**：Three.js
+
+## 5. 用户交互与参数面板
+
+模拟类的"可玩性"基本全在交互上。**至少满足两件事：参数实时可调 + 用户能产生影响**。
+
+### 参数面板（必备）
+
+- 关键参数 2-6 个用滑块暴露（如重力、粘度、扩散率、密度、温度）
+- **预设档位**至少 3 个（如"稳态 / 失稳 / 极端"），点击切换给玩家一个"哇"的入口
+- 重置按钮：清空场到初始态
+- 不用 `dat.GUI` 等老库——用原生 `<input type="range">` + Tailwind 自己写，更轻
+- 移动端折叠：默认收起，点击展开抽屉
+
+### 用户输入映射
+
+| 用户角色（§1） | 输入设计 |
+|---|---|
+| 旁观 | 仅参数面板 + 暂停/重置 |
+| 调参 | 参数面板 + 实时反馈（数值变更立刻可见） |
+| 创作 | Pointer drag 喷射 / 雕刻 + 撤销 / 清空 / 截图保存 |
+| 干预 | 点击施加冲击波 / 删除局部 / 拖拽刚体 |
+
+### 创作类必备
+
+- **撤销栈**：至少 10 步
+- **清空场景**：与重置区分开（重置回初始预设，清空到空）
+- **截图保存**：`canvas.toBlob()` 触发下载，或 `canvas.toDataURL()` 弹预览
+- **可分享**：序列化关键参数到 URL hash，刷新可复现
+
+## 6. 状态指示与可观察性
+
+模拟的灵魂是"看见系统在做什么"。隐藏内部状态的模拟是失败的模拟。
+
+- **FPS 显示**：开发期角落小字（如 `{ fps, particles, dt }`），release 可隐藏在 `?debug=1`
+- **系统状态读数**：模拟物的关键指标实时显示（如流体的总动量、生态的种群数量、电路的总电流）
+- **暂停按钮 + 时间倍率**：实时类必有暂停；高级模拟可加 0.25× / 1× / 2× 时间倍率方便观察
+- **典型反例**：模拟跑着但屏幕上没任何数字，用户不知道"正常 vs 异常"
+
+## 7. 视觉表达
+
+### 风格倾向
+
+模拟类常用风格：
+
+- **科学可视化感**：暗底 + 高对比单色梯度（青蓝→品红常见，温度图）
+- **沙盒玩具感**：亮底 + 高饱和色块（如 falling sand 经典风）
+- **写实拟物**：流体/咖啡/液体走真实材质 + 光照
+- **抽象艺术感**：boid / Conway 类用渐变 + 拖尾长曝光
+
+### 拖尾 / 长曝光（粒子类必杀技）
+
+每帧不清屏全黑，而是 `ctx.fillStyle = 'rgba(0,0,0,0.05)'` 半透明 fillRect 覆盖——粒子运动轨迹自然形成漂亮拖尾。这是粒子类最便宜的"高级感"开关。
+
+### 颜色映射
+
+数值场（温度 / 速度 / 密度）可视化时：
+
+- **viridis** / **inferno**：科学可视化标配，色盲友好
+- **HSL 色相环映射**：方向/相位类（如旋度场）
+- 禁止用"红绿"映射数值（色盲不友好 + 审美差）
+
+## 模拟特有反模式
+
+- 用真实帧 dt 直接积分（`x += v * realDt`），切 tab 回来粒子飞到宇宙外
+- O(n²) 邻域查询不上空间分割，500 粒子就卡
+- render loop 里 `new Vector3()` 每帧 GC 风暴
+- 用 `setInterval(simulate, 16)` 当物理循环（与刷新率失同步）
+- 参数面板做了但**没有重置按钮**，调坏了只能刷新页面
+- FPS 不显示，性能问题没法诊断
+- 创作类没有撤销，用户画错一笔只能 clear all
+- 暂停按钮存在但暂停后主循环继续空转
+- 流体 / 布料用 Explicit Euler 积分（数值发散炸开）
+- 移动端不监听 `touchstart/move`，只支持鼠标拖拽
+- 拖动滑块改参数后**不立即反映**（要等下一次重置才生效）—— 失去"调参"的意义
+
+## Worked Example
+
+> 用户输入："3D 咖啡拉花模拟器，倾斜咖啡杯液体表面，能实时模拟奶沫注入、扩散、与浓缩咖啡混合，并可通过交互控制奶流来绘制复杂花纹。"
+>
+> **§1 类型识别**：连续场（液体表面颜色场）+ 创作（用户绘制奶流路径）+ 3D 场景（倾斜杯子） → 「流体绘画类」
+>
+> **§2 时间步长**：固定 dt = 1/60，accumulator 多步细分；dt 上限 50ms 防 tab 切回炸毁；流体走 Stable Fluids（Jos Stam）范式，advection + diffusion + projection 三步
+>
+> **§3 性能**：场分辨率 256×256（液面 uv），WebGL fragment shader 跑 advection；CPU 不参与逐像素计算
+>
+> **§4 渲染层**：3D 视角 → **Three.js**：
+>
+> - 咖啡杯：CylinderGeometry 倾斜 15°，外壁陶瓷材质 PBR
+> - 液面：PlaneGeometry，shader 采样颜色场纹理决定颜色（深棕咖啡 → 米白奶沫的渐变）
+> - 奶流：用户 pointer 路径转 (u, v) 坐标，向颜色场注入白色源项 + 速度场注入向下速度（模拟重力扰动）
+>
+> **§5 交互**：
+>
+> - 用户角色：创作
+> - 输入：鼠标/触摸拖拽液面 = 注入奶流路径
+> - 参数面板：奶流粗细（滑块）/ 流速（滑块）/ 杯子倾角（滑块）/ 预设花纹（心形 / 玫瑰 / 树叶 一键演示）
+> - 必备：撤销栈（10 步液面快照）+ 清空（液面重置为纯咖啡）+ 截图（canvas.toBlob 下载）+ URL hash 分享当前花纹的种子
+>
+> **§6 状态显示**：角落小字显示 FPS + 总奶量 + 当前混合度（颜色场方差）
+>
+> **§7 视觉**：写实拟物风 —— 杯子有真实陶瓷反光，咖啡表面有微弱 specular，奶流接触液面有边缘扩散光晕
+>
+> **反模式提醒**：
+>
+> - 禁止用 setInterval 跑流体步进
+> - 禁止每帧 new THREE.Vector3() 在 shader 设置时
+> - 必须在 visibilitychange 切走时停 rAF
+> - 参数面板的滑块改值必须立刻反映到渲染，不要等下次清空
+>
+> **不要照抄此例**——同样需求换成"2D 俯视咖啡杯 + Canvas 2D Stable Fluids"也合理。按 §1-§7 维度从本任务重新推导。

package/steering/html/skills/animated-video/SKILL.md

@@ -1,26 +0,0 @@
----
-name: animated-video
-description: Use when creating animated videos, motion graphics, product walkthroughs, or visual storytelling with timeline-based playback. 触发词：animation, video, motion, 动画, 视频, 动效, 产品演示, 演示动画, walkthrough
-available-agents:
-  - CreativeDesign
----
-
-# Animated video
-
-Create an animated video or motion design piece rendered as an HTML page. Build a timeline-based animation with smooth transitions. Design frame-by-frame sequences with playback controls (play/pause, scrubber). Focus on visual storytelling with the Anthropic brand palette. Export-ready at a fixed aspect ratio (16:9 or 9:16). If you need to know the position of an element (eg to move a cursor or character between elements) use refs to grab the position.
-
-START by calling `copy_starter_component` with `kind: "animations.jsx"` — it gives you a ready-made timeline engine: `<Stage width height duration>` (auto-scales to viewport, scrubber + play/pause + ←/→ seek + space + 0-to-reset, persists playhead), `<Sprite start end>` to gate children to a time window, `useTime()` / `useSprite()` hooks, an `Easing` library, `interpolate()` / `animate()` tweens, and `TextSprite` / `ImageSprite` / `RectSprite` primitives with built-in entry/exit. Read the file after copying and build YOUR scenes by composing Sprites inside a Stage; only fall back to Popmotion (https://unpkg.com/popmotion@11.0.5/dist/popmotion.min.js) if the starter genuinely can't do what you need.
-
-Animations are complex code! Make reusable JSX components for each visual element and each scene. Invest in tweaking the timeline iteratively.
-
-Animation tips:
-- Storytelling is KEY! Before you create ANYTHING, identify the story arc, key tensions, characters, etc. Align on the message you want to convey. Run it by the user.
-- Use good animation principles... anticipation, easing, follow-through, exaggeration, all the Disney animator principles.
-- Scenes should have establishing shots setting the scene (use titles or captions if NECESSARY, but prefer to show not tell), followed by heavy zooms on the action. (either hard cuts, or ken-burns-style zooms, or mouse-follows.) Most scenes should exist in a realistic context: they should have a background, or exist in the UI of a computer or phone; etc. Elements should generally not float in the aether.
-- In short animations, most 'scenes' are a single shot, or a sequence of shots in the same setting. Scenes may be slides (e.g. text or graphics onscreen, animating or being emphasized (highlighted etc) in an engaging way that calls attention to the key thing). Decide what the shot is going to be. Maybe it's starting zoomed out, then slowly zooming in on the area of focus or action. Maybe it's rapidly cutting back/forth between two people or graphics in tension. Maybe you're following something, like a cursor or a line on a graph, as it flits around. Be creative!
-- Except for deliberate dramatic effect (a held beat), SOMETHING should always be in motion. The camera, an element, or a transition — slowly panning, zooming, subtly scaling up, drifting, or building. A truly static frame reads as a bug. Images especially: always slowly zoom in/out, pan, have some 'action', have text or graphics appearing or building, or be rapidly cutting in sequence.
-- Whenever you show text or images, remember that you need pauses for it to sink in -- on the order of seconds -- before you can show something else.
-
-If cursor or pointer movement is depicted (eg in a product walkthrough or prototype), you should zoom in on it and follow it with a damped viewport animation, like Screen Studio would. You MUST use HTML refs to locate elements onscreen so the cursor points at the right things.
-
-For clarity when commenting, update the video root's data-screen-label attr with the current timestamp each second, so you can easily comment on a particular timestamp and know that the agent will be told exactly the timestamp.

package/steering/html/skills/frontend-design/SKILL.md

@@ -1,56 +0,0 @@
----
-name: frontend-design
-description: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
-available-agents:
-  - CreativeDesign
----
-
-# Frontend Design
-
-Approach this as the design lead at a small studio known for giving every client a visual identity that could not be mistaken for anyone else's. This client has already rejected proposals that felt templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take one real aesthetic risk you can justify.
-
-## Ground it in the subject
-
-If the brief does not pin down what the product or subject is, pin it yourself before designing: name one concrete subject, its audience, and the page's single job, and state your choice. If there's any information in your memory about the human's preferences, context about what they're building, or designs you've made before – use that as a hint. The subject's own world, its materials, instruments, artifacts, and vernacular, is where distinctive choices come from. Build with the brief's real content and subject matter throughout.
-
-## Design principles
-
-For web designs, the hero is a thesis. Open with the most characteristic thing in the subject's world, in whatever form makes sense for it: a headline, an image, an animation, a live demo, an interactive moment. Be deliberate with your choice: a big number with a small label, supporting stats, and a gradient accent is the template answer, only use if that's truly the best option.
-
-Typography carries the personality of the page. Pair the display and body faces deliberately, not the same families you would reach for on any other project, and set a clear type scale with intentional weights, widths, and spacing. Make the type treatment itself a memorable part of the design, not a neutral delivery vehicle for the content.
-
-Structure is information. Structural devices, numbering, eyebrows, dividers, labels, should encode something true about the content, not decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence - like a real process or a typed timeline where order carries information the reader needs. Question if choices like numbered markers actually make sense before incorporating them.
-
-Leverage motion deliberately. Think about where and if animation can serve the subject: a page-load sequence, a scroll-triggered reveal, hover micro-interactions, ambient atmosphere. An orchestrated moment usually lands harder than scattered effects; choose what the direction calls for. However, sometimes less is more, and extra animation contributes to the feeling that the design is AI-generated.
-
-Match complexity to the vision. Maximalist directions need elaborate execution; minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.
-
-Consider written content carefully. Often a design brief may not contain real content, and it's up to you to come up with copy. Copy can make a design feel as templated as the design itself. See the below section on writing for more guidance.
-
-## Process: brainstorm, explore, plan, critique, build, critique again
-
-For calibration: AI-generated design right now clusters around three looks: (1) a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns. All three are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults. Just like a human designer who's hired, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.
-
-Work in two passes. First, brainstorm a short design plan based on the human's design brief: create a compact token system with color, type, layout, and signature. Color: describe the palette as 4–6 named hex values. Type: the typefaces for 2+ roles (a characterful display face that's used with restraint, a complementary body face, and a utility face for captions or data if needed). Layout: a layout concept, using one-sentence prose descriptions and ASCII wireframes to ideate and compare. Signature: the single unique element this page will be remembered by that embodies the brief in an appropriate way.
-
-Then review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why. Only after you've confirmed the relative uniqueness of your design plan should you start to write the code, following the revised plan exactly and deriving every color and type decision from it.
-
-When writing the code, be careful of structuring your CSS selector specificities. It's easy to generate CSS classes that cancel each other out (especially with a type-based selector like .section and a element-based selector like .cta). This can happen often with paddings/margins between sections.
-
-Try to do a lot of this planning and iteration in your thinking, and only show ideas to the user when you have higher confidence it'll delight them.
-
-## Restraint and self-critique
-
-Spend your boldness in one place. Let the signature element be the one memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Not taking a risk can be a risk itself! Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected. Critique your own work as you build, taking screenshots if your environment supports it – a picture is worth 1000 tokens. Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory. Human creators have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes.
-
-## More on writing in design
-
-Words appear in a design for one reason: to make it easier to understand, and therefore easier to use. They are design material, not decoration. Bring the same intentionality to copy that you would bring to spacing and color. Before writing anything, ask what the design needs to say, and how it can best be said to help the person navigate the experience.
-
-Write from the end user's side of the screen. Name things by what people control and recognize, never by how the system is built. A person manages notifications, not webhook config. Describe what something does in plain terms rather than selling it. Being specific is always better than being clever.
-
-Use active voice as default. A control should say exactly what happens when it's used: "Save changes," not "Submit." An action keeps the same name through the whole flow, so the button that says "Publish" produces a toast that says "Published." The vocabulary of an interface is the signposting for someone navigating the product. Cohesion and consistency are how people learn their way around.
-
-Treat failure and emptiness as moments for direction, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors don't apologize, and they are never vague about what happened. An empty screen is an invitation to act.
-
-Keep the register conversational and tuned: plain verbs, sentence case, no filler, with tone matched to the brand and the audience. Let each element do exactly one job. A label labels, an example demonstrates, and nothing quietly does double duty.

package/steering/html/skills/hi-fi-design/SKILL.md

@@ -1,29 +0,0 @@
----
-name: hi-fi-design
-description: Use when creating high-fidelity UI mockups, design explorations, or polished visual prototypes with multiple variations. 触发词：mockup, hi-fi, prototype, UI design, 高保真, 设计稿, 原型, 界面设计, 视觉设计, 设计方案
-available-agents:
-  - CreativeDesign
----
-
-# Hi-fi design
-
-Create a high-fidelity, polished design.
-
-Follow this general design process (use the todo list to remember):
-1. ask questions
-2. find existing UI kits and collect design context — copy ALL relevant components and read ALL relevant examples; ask the user if you can't find them
-3. start your file with assumptions + context + design reasoning (as if you are a junior designer and the user is your manager), with placeholders for the designs, and show it to the user early
-4. build out the designs and show the user again ASAP; append some next steps
-5. use your tools to check, verify and iterate on the design
-
-Good hi-fi designs do not start from scratch — they are rooted in existing design context. Find a suitable UI kit / design resources, or ask for screenshots of existing UI. You MUST spend time trying to acquire design context, including components. If you cannot find them, ask the user for them. Mocking a full product from scratch is a LAST RESORT and will lead to poor design. Use the starter components (device frames and the like) to get high-quality scaffolding for free.
-
-When presenting several options or explorations side-by-side, lay them out clearly: give the page a neutral gray background, put each option in its own labeled frame (a small heading + a white rounded card sized to its content), and group related options into sections.
-
-When designing, asking many good questions is ESSENTIAL.
-
-Give options: try to give 3+ variations across several dimensions. Mix by-the-book designs that match existing patterns with new and novel interactions, including interesting layouts, metaphors, and visual styles. Have some options that use color or advanced CSS; some with iconography and some without. Start your variations basic and get more advanced and creative as you go! Try remixing the brand assets and visual DNA in interesting ways — play with scale, fills, texture, visual rhythm, layering, novel layouts, type treatments. The goal is not the perfect option; it's exploring atomic variations the user can mix and match.
-
-CSS, HTML, JS and SVG are amazing. Users often don't know what they can do. Surprise the user.
-
-If you do not have an icon, asset or component, draw a placeholder: in hi-fi design, a placeholder is better than a bad attempt at the real thing.

package/steering/html/skills/make-a-deck/SKILL.md

@@ -1,64 +0,0 @@
----
-name: make-a-deck
-description: Use when creating slide presentations, pitch decks, or keynote-style visual talks. 触发词：presentation, slides, deck, PPT, keynote, pitch, 演示文稿, 幻灯片, 汇报材料, 述职, 路演
-available-agents:
-  - CreativeDesign
----
-
-# Make a deck
-
-Create a presentation deck as a single self-contained HTML page.
-
-Assume this role: you are a presentation designer. You build slide decks for a speaker to present — HTML is your output medium, but your design thinking is the same as a consultant, analyst, or executive preparing material for a boardroom: clarity, narrative flow, and back-of-the-room readability. You are not building a website.
-
-Every slide is an exercise in both layout design and copywriting. Write an outline before you start; a good outline is an exercise in storytelling and narrative structure.
-
-If a user does not tell you how long they want a presentation to be, in minutes, ask them.
-If the user does not tell you the visual aesthetic they want, use the `ask_user_question` tool to ASK what they want. Don't just provide a generic design!
-
-Build at 1920×1080 (16:9). Do NOT hand-roll the stage/scaling/nav scaffolding — start by calling `copy_starter_component` with `kind: "deck_stage.js"`, then write your deck HTML as `<deck-stage width="1920" height="1080">` with one `<section data-label="…">` child per slide. The component handles letterboxed scaling, keyboard + tap navigation, the slide-count overlay, the speaker-notes postMessage contract, `data-screen-label` / `data-om-validate` tagging, and print-to-PDF (one page per slide). Load it with a plain `<script src="deck-stage.js"></script>` — it is vanilla JS, not JSX.
-
-Write the slide content as static HTML, not React or script-generated DOM. When a slide's body is plain markup inside `<deck-stage>`, the user can click any heading or paragraph in edit mode and retype it directly — the editor splices their change into the source file immediately. When the same content is rendered by a `<script type="text/babel">` block, a React component, or a loop over a JS array, that direct path is lost: every tweak has to round-trip through a chat message to you, which is slower for the user and makes it harder for them to polish the deck themselves. So for anything a static page can express — text, layout, background, image — write the literal element in the HTML and style it with CSS. Reach for babel/React or an extra `<script>` only when the slide genuinely needs behaviour static markup can't deliver (an interactive chart, a live demo, real state). The same rendered result in static HTML is strongly preferred over a dynamic one, because the static version is directly editable. The Tweaks panel (`tweaks-panel.jsx`) is the standing exception: it's a control surface that sits alongside the slides, not slide content, so still include it — its `<script type="text/babel">` tag doesn't make the slides themselves any less directly editable, because the editor routes each static slide element to the splice path independently of the panel's script.
-
-Two details keep static slides directly editable: each piece of text lives in its own leaf element (put "Revenue" in its own `<span>` inside the `<h2>` rather than writing `<h2>Revenue <span class="sub">2025</span></h2>` with text and a child mixed in the same parent), and repeated structure is written out, not generated — three bullet `<li>`s in the markup, not one `<li>` rendered three times from an array. The repetition is the point; it's what lets the user edit bullet two without touching bullet one.
-
-Use large type sizes (at least 48px for titles). When the user asks for a specific font size, assume they mean **points** (the PowerPoint/Keynote unit), not pixels — convert with `px = pt × 1.333`. So "make titles 36pt" → set ~48px in your CSS.
-
-Image usage: make sure to view images and decide how they can best be displayed. Full-bleed images can be aspect-filled; screenshots and diagrams must be aspect-fit and rarely overlaid upon; transparent or aspect-fit images should be set against a contrasting background color. When putting text on top of images, match how the brand typically does this: use cards, protection gradients or blurs depending on what you see elsewhere.
-
-Use smooth transitions between slides. Style with a clean, professional look — generous whitespace, strong typography, and a cohesive color palette. Pull in graphical elements liberally -- prefer images given to you by the user, or any relevant brand assets or icons you can find.
-
-Do not use emoji or self-drawn assets unless asked. Use icons from your design system / brand, or images provided by the user.
-
-Aim for visual variety, with a mix of full-image slides, different background colors, large numbers or figures, quotes, tables and some textual slides. Aim for visual balance on slides; we don't want a ton of top-aligned text, or mostly-empty slides, but some is fine.
-
-Critical: AVOID PUTTING TOO MUCH TEXT ON SLIDES! This is a common failure mode. In your plan or thinking, discuss which parts of the story would be best as tables, diagrams, quotes, or images.
-
-Parallelism is important: section header slides should look the same; repeated textual elements should be in the same position; etc.
-
-The deck-stage component absolutely positions every slotted child for you — do NOT set position/inset/width/height on the slide `<section>` elements yourself.
-
-# Slide writing guidelines
-
-In general, the titles of a slide deck alone should tell you the overall story/content of the deck (similar to ToC in a book)
-There are generally a few types of title structures that are used in slide decks:
-- Short textbook-title-style, all capitalized (e.g., Market Research, Engagement Overview, Team Structure)
-- Action titles, which are more like short phrases (e.g., “Asia is our largest market….”, “...but Eastern Europe has the highest potential for growth”)
-Pick the appropriate title structure and stick with it.
-
-Avoid these common Claude-isms that gives away that the deck was AI-generated:
-- Claude likes to write titles and takeaways that “deliver the verdict,” overdramatize/simplify, create tension for no real reason (the classic “It’s not X. It’s Y.”), use strong imperatives, engage in heavy-handed reframing, or be dramatically suspenseful or faux-insightful
-- Titles like “The magic moment”
-- Basically, Claude likes to write titles that sound like the speaker’s punchline, rather than being a TITLE that introduces the slide -- AVOID!
-
-# Planning steps
-
-In addition to your normal planning, make sure to do these things:
-
-1. Ask questions if you don't know audience, desired brand, and duration.
-2. Write out the full title sequence. Choose ONE grammatical style (for example, short topic noun-phrases or brief declarative sentences) that is appropriate for the content, and write every title in that style. Read them back to yourself and determine if a person reading ONLY the titles could follow the flow of the presentation. The titles should be like chapters in a book - they orient the reader on what to expect with straightforward language. Review the titles and revise as needed. Put these in an scratchpad.md file.
-3. Define your type scale and spacing as CSS custom properties in a `<style>` block in `<head>` before writing any slide — these commit you to projection-appropriate sizing and stop you defaulting to web density. At 1920×1080 a reasonable starting scale is `:root { --type-title: 64px; --type-subtitle: 44px; --type-body: 34px; --type-small: 28px; --pad-top: 100px; --pad-bottom: 80px; --pad-x: 100px; --gap-title: 52px; --gap-item: 28px; }`. At 1280×720, scale by ~0.67. Reference these everywhere — every font-size uses a `--type-*` variable, every padding/gap uses a `--pad-*` or `--gap-*` variable, via `var(…)` in inline styles or class rules. Keeping these as CSS (not JS constants) means the user can change one number — in the style block directly, or via a Tweaks slider bound to the same variable — to re-size the whole deck, and the slide markup stays static HTML with no script needed to compute sizes. The explicit `--pad-bottom` reserves breathing room at the base of every slide; that space is structural, not empty. Web defaults (14-16px body, 48-72px padding) are too small for slides; if the values don't feel generous, they aren't. Your validator will throw an error if you use a size smaller than 24px.
-4. Build the slides, remembering that each slide is an exercise in both design and copywriting. Give each slide the attention it deserves in terms of the layout, the text content, and the tone. Follow the principles below and ensure that each slide can stand alone; a person looking at that slide should be able to understand its high-level meaning without other context.
-
-# Verification tips for slide decks
-During review, check your screenshots against slide composition rules — not web-layout instincts. `align-items: flex-start` with open space in the bottom third is correct slide composition, not a defect. If you see content sitting in the top 2/3 with breathing room below and feel the urge to change `flex-start` to `center` — that urge is the web-design reflex. Resist it. The open space is intentional. Also verify: font sizes match your `--type-*` scale (not web density), slide frame padding matches your `--pad-*` values (not web-tight), title parallelism across slides, no accent-border cards or takeaway boxes