@lark-apaas/coding-steering 0.1.21 → 0.1.22-alpha.20260724081248

package/README.md

@@ -2,21 +2,23 @@
 
 Stack-specific steering content for [miaoda coding](https://code.byted.org/apaas/miaoda-coding) templates.
 
-Consumed by [miaoda-cli](https://code.byted.org/apaas/miaoda-cli) during `miaoda skills sync` (including `app init`). It is **not a runtime dependency** — no entry in the user project's `package.json`.
+Consumed by [miaoda-cli](https://code.byted.org/apaas/miaoda-cli) at `app init` time and synced into the user project's `.agent/steering/`. **Not a runtime dependency** — no entry in user `package.json`.
 
 ## Layout
 
 ```
 steering/
+├── _common/
+│   └── skills/                    # cross-stack shared skills
 ├── <stack>/
-│   ├── tech.md                    # optional, stack overview
-│   ├── skills_common/<id>/SKILL.md # both local and sandbox; copied first
-│   ├── skills/<id>/SKILL.md        # sandbox-only; copied after common
-│   └── skills_local/<id>/SKILL.md  # local-only; copied after common
+│   ├── tech.md                    # always-loaded, injected into agent system prompt
+│   ├── skills/<id>/SKILL.md       # progressive disclosure, triggered by description match
+│   └── skills_local/<id>/SKILL.md # local-only variant; overrides skills/<id> when syncing
+│                                  #   to a local-dev project (e.g. via lark-cli)
 └── ...
 ```
 
-Top-level directory names are stack IDs — discovery is by directory convention, with no central manifest.
+Top-level directory names (other than `_common`) ARE the stackId — discovery is by directory convention, no central manifest.
 
 ## Supported stacks
 
@@ -29,7 +31,7 @@ vice versa). Current state:
 | `vite-react` | React + Vite SPA | ✅ | `plugin-guide`, `react-three-fiber` | [`coding-template-vite-react`](../../templates/vite-react) |
 | `html` | 妙搭 html，带 devserver | ✅ | `rich-interactive-design` | [`coding-template-html`](../../templates/html) |
 | `nestjs-react-fullstack` | NestJS + React 全栈 | — | `authn`/`authz`/`feishu`/`plugin`/`devops`/`trigger`/`user-*` … + `skills_local/` (`code-fix`, `coding-guide`) | [`coding-template-nestjs-react-fullstack`](../../templates/nestjs-react-fullstack) |
-| `design-html` | **无构建**纯静态 HTML 托管（源码即产物，类 Claude Design） | — | _（占位，待补）_ | [`coding-template-design-html`](../../templates/design-html) |
+| `design-html` | **无构建**纯静态 HTML 托管（源码即产物） | — | _（占位，待补）_ | [`coding-template-design-html`](../../templates/design-html) |
 | `design-stack` | **带构建**的 design / 创意栈（有工具链，区别于 buildless 的 `design-html`） | — | _（占位，待补）_ | _（暂无）_ |
 
 `design-html` 与 `design-stack` 是两个**有意分开**的 design 栈：前者无构建、纯静态托管；
@@ -39,20 +41,20 @@ vice versa). Current state:
 
 ## Sync mapping (executed by miaoda-cli)
 
-`MIAODA_DEP_CACHE_DIR` selects the source mode; `--local` selects only the output layout. Do not use a sandbox environment plus `--local` as evidence for either supported flow.
+| Source in this package | Destination in user project |
+|---|---|
+| `steering/<stack>/tech.md` | `.agent/steering/tech.md` |
+| `steering/<stack>/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
+| `steering/<stack>/skills_local/<id>/**` | `.agent/steering/skills/<id>/**` (local-dev sync only) |
+| `steering/_common/skills/<id>/**` | `.agent/steering/skills/<id>/**` |
 
-| Source in this package                   | Local output (`MIAODA_DEP_CACHE_DIR` empty + `--local`) | Sandbox output (`MIAODA_DEP_CACHE_DIR` non-empty, no `--local`) |
-| ---------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
-| `steering/<stack>/skills_common/<id>/**` | `.agents/skills/<id>/**`                                | `.agent/skills/steering/<stack>/skills/<id>/**`                 |
-| `steering/<stack>/skills_local/<id>/**`  | Same local path, copied after common.                   | Not copied.                                                     |
-| `steering/<stack>/skills/<id>/**`        | Not copied.                                             | Same sandbox path, copied after common.                         |
+Precedence when the same `<id>` exists in multiple sources (lowest → highest, later wins):
+`_common/skills` → `<stack>/skills` → `<stack>/skills_local` (local-dev sync only).
 
-For a duplicated skill ID, the copy order is:
-
-- Local: `skills_common → skills_local`; the local variant wins.
-- Sandbox: `skills_common → skills`; the sandbox variant wins.
-
-Put a guide in `skills_common/<id>/SKILL.md` when it must reach both supported modes. Keep a same-name `skills/` or `skills_local/` copy only when a deliberate mode-specific override is required.
+`skills_local` is a stack-specific variant intended for the local-development sync path
+(`miaoda skills sync --local`, driven by `lark-cli apps`). The cloud sandbox sync path
+ignores `skills_local` and uses `skills` as-is, so authors of `skills_local` content can
+assume "本地 agent" semantics (no `ddl_sql` / `plugin_instance` / sandbox-log tools, etc.).
 
 ## Writing rules
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.21",
+  "version": "0.1.22-alpha.20260724081248",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
   "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**'"
   },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"

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

@@ -1,10 +1,8 @@
 ---
 name: animated-video
 description: Use when creating animated videos, motion graphics, product walkthroughs, or visual storytelling with timeline-based playback. 触发词：animation, video, motion, 动画, 视频, 动效, 产品演示, 演示动画, walkthrough
-metadata:
-  display-names:
-    zh-CN: 动画视频
-    en-US: Animated Video
+available-agents:
+  - CreativeDesign
 ---
 
 # Animated video

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

@@ -1,10 +1,8 @@
 ---
 name: charts
 description: "基于 ECharts 的数据可视化，用于浏览器直出 HTML。当需要创建图表、仪表盘或数据可视化时使用。触发词：chart, ECharts, 图表, 可视化, visualization, 饼图, 柱状图, 折线图, 数据图表, 甘特图, 热力图, 数据展示, dashboard, 仪表盘, 数据看板"
-metadata:
-  display-names:
-    zh-CN: 图表
-    en-US: Charts
+available-agents:
+  - CreativeDesign
 ---
 
 # 图表
@@ -141,7 +139,7 @@ Object.assign(window, { EChart });
 | 6 | Funnel label 被隐藏或位置不在内部 | `label: { show: true, position: 'inside' }` |
 | 7 | 容器高度 <300px | `min-height: 300px` |
 | 8 | 单张图表中分类色（每项一个色相）>8 种 | 聚合或分组 |
-| 9 | Pie / 环形图的分类或数值只能靠 tooltip 读到——用了外部引导线标签（`position` 为 `'outside'` 或缺失），或干脆 `label: { show: false }` 且既无图例也无中心标注 | 分类 + 数值必须**静态可读**（tooltip 不算，图表常被导出 / 截图当静态图看）。任选其一：inside 标签标注 `name` + 百分比（扇区够大时）、图例映射色 → 分类、或环形图中心标注关键数值。禁止外部引导线标签（`position: 'outside'` 易重叠 / 裁切），也禁止只靠 tooltip 承载分类 / 数值 |
+| 9 | Pie 使用了外部引导线标签（`position` 缺失或为 `'outside'`） | `label: { show: false }` + `emphasis: { label: { show: false } }`；使用 tooltip。允许 `position: 'inside'` 和 doughnut 中心标签 |
 | 10 | Pie 设置了 `itemStyle` | 完全移除 |
 | 11 | 任何 series 设置了 `label.color` | 禁止设置；由 theme 控制 |
 | 12 | `label.formatter` 使用字符串模板 | 改用回调：`formatter: (params) => ...` |

package/steering/design-html/skills/data-report/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: data-report
 description: "数据驱动的报表与看板设计。从数据分析到报表规划、信息层级组织，适用于用户有数据文件或明确指标，需要产出结构化数据报表的场景。图表绘制部分由 charts skill 承担。触发词：数据报表, 数据看板, 数据分析报表, BI, 经营报表, 指标看板, 周报, 月报, 数据大盘, KPI, 报表设计, data report, dashboard report, analytics report"
-metadata:
-  display-names:
-    zh-CN: 数据看板
-    en-US: Data Dashboard
+available-agents:
+  - CreativeDesign
 ---
 
 # 数据报表
@@ -54,7 +52,7 @@ metadata:
 
 在写代码之前，先确定报表由哪些组件构成：
 
-- **视觉方向**：参考 `frontend-design` 的方法先定主题世界、受众姿态、材料、配色逻辑和签名元素。例如环境数据可以像研究观测页，销售经营可以像运营战情室，财务/管理指标可以像管理层简报。风格必须服务数据可信度，不要套通用科技蓝或泛白卡。
+- **视觉方向**：参考 `frontend-design` 的方法先定主题世界、受众姿态、材料、配色逻辑和视觉签名。例如环境数据可以像研究观测页，销售经营可以像运营战情室，财务/管理指标可以像管理层简报。风格必须服务数据可信度，不要套通用科技蓝或泛白卡。
 - **阅读路径**：先判断读者是要快速扫现状、追异常、看趋势、比较对象、查明细还是读复盘。不同任务对应不同起手式，不要默认都从 KPI 卡开始。
 - **候选部件**：标题 / 范围 / 口径、摘要、KPI、主图表、辅助图表、文字洞察、明细表、时间线、矩阵、截图或注释都只是候选。需要哪个用哪个，不要为了"完整"把它们凑齐。
 - **核心承载**：只给真正承载核心问题的模块更大面积。核心可能是一张趋势图、一张排名表、一段异常解释、一个流程漏斗，也可能是一组明细，不固定。
@@ -78,7 +76,7 @@ metadata:
 - 布局按数据叙事组织，不按"先放所有图再放文字"组织。
 - 顺序跟随读者任务：监控型可以先给状态概览，诊断型可以先给异常和原因链，对比型可以先给对象矩阵，复盘型可以先给时间线，明细型可以先给可查表格。
 - 同一页面内至少使用两种不同的版式关系：例如 KPI 横条 + 左右不等分主图 + 双列洞察 + 表格/结论带。避免所有模块都是同尺寸白卡片上下排列。
-- 内容块采用平面化处理：优先用 `border:1px solid ...`、浅底色、分隔线、色条（仅当颜色编码真实分类 / 状态）、编号、标签和表格行背景；内容卡片和图表容器默认不加 `box-shadow`。
+- 内容块采用平面化处理：优先用 `border:1px solid ...`、浅底色、分隔线、色条、编号、标签和表格行背景；内容卡片和图表容器默认不加 `box-shadow`。
 - 图表旁边应有短洞察、口径或排名摘要，不要让图表孤零零占满整行。
 - 文字用于解释图表看不出的原因、口径、异常和行动建议，不重复图表标题。
 - 表格用于精确查数和比较对象，不要把长表伪装成密集柱状图。

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

@@ -1,69 +1,67 @@
 ---
 name: frontend-design
-description: 为设计确立独特、有意图的视觉方向的指引——配色、字体与美学选择不带模板化默认的痕迹。适用于各类媒介（deck、报告、UI、原型），不限于 Web UI。
-metadata:
-  display-names:
-    zh-CN: 创意设计
-    en-US: Creative 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
 
-以一家小型设计工作室的设计主管身份来做这件事——这家工作室以让每位客户拥有绝不会被认错的视觉形象而闻名。这位客户已经否掉过几版感觉模板化的提案，他们付费买的是一个鲜明的观点：针对这份 brief 做出深思熟虑、有主张的配色、字体与版式选择，并承担一次你能说清理由的真正的美学冒险。
+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
 
-如果 brief 没有钉死产品或主题是什么，动手设计前先自己钉死：点出一个具体的主题、它的受众、这个页面唯一要完成的任务，并明确说出你的选择。如果你的记忆里有关于用户偏好的信息、关于他们正在构建什么的上下文、或你以往做过的设计——把它们当作线索用起来。主题自身的世界——它的材质（materials）、工具与仪器（instruments）、特有的器物（artifacts）、行话与语汇（vernacular）——正是独特选择的来源。全程用 brief 的真实内容与题材来构建。
+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.
 
-## 视觉方向
+## Visual Direction
 
-在选定颜色或组件之前，先在思考中定下方向。填满四个槽位——每一个都要取自*这个*主题：
+Before choosing colors or components, decide the direction in your thinking. Fill four slots — each pulled from *this* subject:
 
-- **世界（World）**——这个页面属于哪个世界？去主题自己的世界里找：它的材质、工具与仪器、特有的器物、行话与语汇。
-- **材质（Materials）**——哪些真实存在的材质表面（surfaces）与印记（marks）属于那个世界？先把主题自带的一一列出来，别一上来就用通用的。
-- **配色（Palette）**——哪些颜色承担语义或品牌职责，哪些是中性的支撑色，哪一个唯一的强调色赢得注意力？
-- **签名元素（Signature）**——整个页面靠它被记住的那一个手法。它必须只可能属于这个主题；一个换到下份 brief 也能复用的签名元素，是默认值，不是选择。
+- **World** — what world does this page belong to? Go to the subject's own: its materials, instruments, artifacts, vernacular.
+- **Materials** — what real surfaces and marks belong to that world? Name the ones from the subject before reaching for a generic one.
+- **Palette** — which colors are semantic or branded, which are neutral supports, and which single accent earns attention?
+- **Signature** — the one device the page is remembered by. Make it something that could only belong to this subject; a signature generic enough to reuse on the next brief is a default, not a choice.
 
-风格不是版式排完后再涂上去的装饰。这个方向决定字体排印、间距、图表处理、章节节奏、边框、图标风格，以及哪些组件值得强调。
+Style is not decoration applied after layout. This direction decides typography, spacing, chart treatment, section rhythm, borders, icon style, and which components deserve emphasis.
 
-## 设计原则
+## Design principles
 
-对于网页设计，hero 区就是全页的论点。开场就亮出主题世界里最具特征的东西，形式因主题而定：一句大标题、一张图、一段动画、一个实时 demo、一个交互瞬间。选择要经过深思：「大数字 + 小标签 + 辅助统计数据 + 渐变点缀」是模板答案，只有当它确实是最佳选项时才用。
+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.
 
-字体排印承载页面的性格。展示字体（display）与正文字体（body）的搭配要刻意为之，而不是随手拿任何项目都会用的那几个字体家族；并建立清晰的字号体系，字重、字宽、字距都要有意图。让字体处理本身成为设计中令人记住的一部分，而不是承载内容的中性载体。
+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.
 
-结构即信息。结构件——编号、眉标、分隔线、标签——应当编码内容中真实存在的信息，而不是装饰内容。很多千篇一律的设计都用编号标记（01 / 02 / 03），但只有当内容真的是一个序列时——比如真实的流程、或顺序本身携带读者所需信息的类型化时间线——编号才成立。在采用编号标记这类选择之前，先质疑它们是否真的说得通。
+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.
 
-有意识地运用动效。想清楚动画是否、以及在哪里能服务主题：页面加载序列、滚动触发的揭示、hover 微交互、环境氛围。一个经过编排的时刻通常比散落的零星特效更有力；按视觉方向的需要来选。但有时少即是多——多余的动画会加重「这个设计是 AI 生成的」的观感。
+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.
 
-认真对待文字内容。设计 brief 往往不含真实内容，文案要由你来写。文案带来的模板感不亚于设计本身。更多指引见下文关于写作的章节。
+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
 
-先校准现状：当下的 AI 生成设计集中在四种长相上：(1) 暖奶油色背景（接近 #F4F1EA）+ 高对比衬线展示字体 + 陶土色（terracotta）强调色；(2) 近黑背景 + 单一亮色强调——酸性绿（acid green）或朱红（vermilion）；(3) 大报（broadsheet）式版面——发丝线（hairline rules）、零 border-radius、报纸般的密集分栏；(4) 深色底「科技感」版面——紫蓝渐变、发光光晕（glow）、半透明玻璃拟态（glassmorphism）卡片，科技 / AI / 数据类 brief 上尤其高发。四者对某些 brief 都站得住脚，但它们是默认值而非选择，而且不看主题就冒出来。凡是 brief 钉死了视觉方向的地方，严格照办——brief 自己的话始终优先，包括它点名要这四种长相之一的时候。凡是 brief 留出自由度的维度，别把这份自由花在这四个默认值上。就像受雇的人类设计师一样，往往要在「做自己擅长的」与「把每个项目当作试验和学习的机会」之间小心权衡。
+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.
 
-分两遍做。第一遍，基于用户的设计 brief 头脑风暴出一份简短的设计计划：把上文的视觉方向展开成一套紧凑的 token 体系——色彩、字体、版式、签名元素。色彩：用 4–6 个命名的 hex 值描述配色。字体：至少两种角色的字体（一款有性格、克制使用的展示字体，一款与之互补的正文字体，必要时再加一款用于图注或数据的功能字体）。版式：一个版式概念，用一句话的文字描述加 ASCII 线框图来构思和比较。签名元素：这个页面将被记住的那个唯一独特元素，以恰当的方式体现 brief。
+Work in two passes. First, brainstorm a short design plan based on the human's design brief: expand the visual direction above into a compact token system: 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.
 
-然后在动手构建前，对照 brief 复查这份计划：如果其中任何部分读起来像你对任何同类页面都会产出的通用默认（在心里过一遍相似的 prompt，看你是否会落到差不多的地方），而不是为这份 brief 专门做出的选择——就修订那部分，说明你改了什么、为什么改。只有在确认设计计划具备相对独特性之后，才开始写代码，严格遵循修订后的计划，让每一个颜色和字体决策都从计划中推导出来。
+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.
 
-写代码时，注意组织好 CSS 选择器的优先级（specificity）。很容易写出相互抵消的 CSS 类（尤其是 `.section` 这类分区级选择器与 `.cta` 这类元素级选择器之间）。区块之间的 padding/margin 上经常出这种问题。
+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
 
-把大胆花在一个地方。让签名元素成为唯一被记住的东西，它周围的一切保持安静、克制，砍掉任何不服务于 brief 的装饰。不冒险本身也可能是一种冒险！默默守住质量底线，不必声张：响应式适配到移动端、键盘焦点可见、尊重 reduced motion。边构建边评审自己的作品，环境支持就截图看——一图胜千 token。想想香奈儿的忠告：出门前照照镜子，摘掉一件配饰。人类创作者有记忆，总在尝试新东西；如果你有地方快速记下自己试过什么，会对后续迭代有帮助。
+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.
 
-站在屏幕另一侧的最终用户角度来写。以人们能控制、能认出的东西命名，绝不以系统的实现方式命名。用户管理的是「通知」，不是「webhook 配置」。用平实的语言描述某物做什么，而不是推销它。具体始终胜过抖机灵。
+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.
 
-默认使用主动语态。一个控件应当准确说明使用它时会发生什么：说 "Save changes"，而不是 "Submit"。同一个动作在整条流程中保持同名：写着 "Publish" 的按钮，产生的 toast 就写 "Published"。界面的词汇表就是用户穿行产品时的路标。连贯与一致是人们认路的方式。
+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.
 
-语域要像对话一样自然，并经过调校：动词平实、sentence case（句首大写）、没有废话，语气与品牌和受众匹配。让每个元素只做一件事：标签就是标注，示例就是演示，没有元素悄悄身兼二职。
+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/design-html/skills/hi-fi-design/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: hi-fi-design
 description: 用于创建高保真 UI mockup、设计探索，或带多种变体的视觉原型。触发词：mockup, hi-fi, prototype, UI design, 高保真, 设计稿, 原型, 界面设计, 视觉设计, 设计方案
-metadata:
-  display-names:
-    zh-CN: 高保真设计
-    en-US: Hi-Fi Design
+available-agents:
+  - CreativeDesign
 ---
 
 # 高保真设计

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

@@ -1,10 +1,8 @@
 ---
 name: interactive-prototype
 description: Working app with real interactions
-metadata:
-  display-names:
-    zh-CN: 交互原型
-    en-US: Interactive Prototype
+available-agents:
+  - CreativeDesign
 ---
 
 Create a fully interactive prototype with realistic state management and transitions. Use React useState/useEffect for dynamic behavior. Include hover states, click interactions, form validation, animated transitions, and multi-step navigation flows. It should feel like a real working app, not a static mockup.

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

@@ -1,143 +1,125 @@
 ---
 name: make-a-deck
-description: 当用户要求制作演示文稿 / PPT / PPTX / pitch deck / slides / keynote / 路演材料时使用——即供演讲者现场演示、固定画幅 16:9 的自包含 HTML deck。
-metadata:
-  display-names:
-    zh-CN: 幻灯片制作
-    en-US: Slide Deck
+description: 制作演示文稿 / PPT / pitch deck / slides / keynote。从零新建、从文档材料提炼重组、或对已有 PPTX 重新设计。触发词：presentation, slides, deck, PPT, PPTX, keynote, pitch, 演示文稿, 幻灯片, 路演
+available-agents:
+  - CreativeDesign
 ---
 
-# Make a deck
+# 制作演示文稿（deck）
 
-把演示 deck 做成一个自包含的 HTML 单页。
+把演示文稿做成单个自包含的 HTML 页面。HTML 是输出载体，但设计判断按 PPT 来做：固定画幅、强叙事、可投影 / 可异步阅读、每页只承担一个清楚的沟通任务。
 
-进入这个角色：你是一名演示设计师（presentation designer）。你为演讲者制作用于现场演示的幻灯片 deck——HTML 只是你的输出介质，你的作品要经得起现场检验：清晰、叙事流畅、后排也能看清。你不是在做网站。
+把自己当成演示文稿设计师，不是网页开发者：像顾问、分析师、高管准备董事会材料那样思考——清晰、叙事流、后排可读。每一页都同时是版式设计和文案写作。开始落 HTML 前，先写大纲；好的大纲本身就是一次叙事结构训练。
 
-**先判断场合，再定设计语气。** 判定场合后，代入该场合最专业的制作者身份——为这类场合做过上百场 deck 的人会怎么取舍——用它校准每一页的语气与密度。场合决定三件事：信息密度（听众扫读还是研读）、标题语法（论点式还是主题式）、节奏权重（哪类版式原型承担叙事高点）。动手前在 scratchpad 用一两句写明场合、代入的身份与这三项决策，全 deck 一致执行；工艺规则（构图、字号、平行性）不随场合变。
+## 信息密度
 
-每张幻灯片既是版式设计的练习，也是文案写作的练习。动手前先写大纲；好的大纲本身就是一次讲故事和叙事结构的练习。
+选一种密度，不要停在模糊的中间态：
 
-## 动手前先问
+| 模式 | 场景 | 做法 |
+| --- | --- | --- |
+| 演讲型 / 低密度 | 发布会、公开演讲、keynote、现场 pitch | 一页一个观点，大标题强视觉、留白足、要点 1-3 条，必要时增加页数 |
+| 阅读型 / 高密度 | 内部汇报、评审、复盘、异步传阅 | 每页更自洽，可用表格 / 结构卡片 / 注释 / 图表，但层级要明确 |
 
-- 如果用户没有说明想要的视觉风格，也没有提供 design system，就用提问工具（ask_user_question）**主动询问**。绝不要直接给出一个通用设计！
+无论哪种，都不要让页面滚动、溢出、重叠或用过小字体；放不下就拆页。**不要把整份文档直接贴进幻灯片**——这是最常见的失败模式。落 plan 时就想清楚：哪些内容更适合做成表格、图表、流程、引用页或图片页。
 
-## 构建准备与技术契约
+## 叙事与标题
 
-### deck-stage 组件
+- 先写完整标题序列放进 `scratchpad.md`。只读标题就应能看懂整份 deck 的逻辑（像书的目录）。检查是否形成清楚路径：背景 → 问题 → 洞察 → 方案 → 证据 → 下一步。
+- 选定一种标题语法并全程一致：要么名词短语（"市场机会""产品架构"），要么简短判断句（"新用户增长主要来自自然流量"）。
+- 每页正文只服务本页标题，不塞旁支。封面、章节页、转场页、结尾页也要服务故事，不做纯装饰。
 
-以 1920×1080（16:9）为基准构建。**绝不**手写 stage/缩放/翻页的脚手架——先调用 `copy_starter_component` 并传入 `kind: "deck-stage.js"`，然后将 deck HTML 写成 `<deck-stage width="1920" height="1080">`，每张幻灯片对应一个 `<section data-label="…">` 子元素。该组件负责：
+避免这些"AI 味"标题（它们会暴露 deck 是 AI 生成的）——标题的任务是**定位页面、推进叙事**，不是替演讲者甩结论 / 喊 punchline：
 
-- letterbox 缩放
-- 键盘 + 触控翻页
-- speaker-notes 的 postMessage 协议
-- `data-screen-label` / `data-miaoda-validate` 标记
-- print-to-PDF（每张幻灯片一页）
+- "不是 X，而是 Y"式过度反转。
+- "关键时刻""魔法时刻"式空泛或故作深刻。
+- 过度夸张的行动号召、为制造张力而制造张力。
+- 每页固定一个 takeaway 盒子，导致标题和正文重复。
 
-用 `<script src="deck-stage.js"></script>` 加载它——它是 vanilla JS，不是 JSX。（为了之后导出 PPTX：向 gen_pptx 传入 `resetTransformSelector: "deck-stage"`——该组件支持 `noscale` 属性来禁用 shadow-DOM 缩放，使截图拿到原始尺寸的几何信息。）
+## 页面类型与节奏
 
-deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**在幻灯片 `<section>` 元素上自行设置 position/inset/width/height。
+写第一页前先做 page-type map：为每页标注页型、叙事作用和需要承载的素材。避免所有页面都变成"标题 + 三栏卡片"。
 
-### 把幻灯片内容写成静态 HTML，而不是 React
+常用页型包括：
 
-幻灯片内容应写成静态 HTML，而非 React 或脚本生成的 DOM。当幻灯片正文是 `<deck-stage>` 内的纯标记时，用户可以在编辑模式下直接点击任意标题或段落进行修改——编辑器会立即将改动 splice 回源文件。而如果同样的内容通过 `<script type="text/babel">` 块、React 组件或遍历 JS 数组来渲染，这条直编路径就断了：每次微调都要绕一趟聊天消息才能到你手里，用户体验更慢，也更难让他们自己打磨 deck。因此，凡是静态页面能表达的——文本、布局、背景、图片——都直接在 HTML 里写字面元素并用 CSS 设置样式。只在幻灯片确实需要静态标记无法实现的行为时（交互式图表、实时 demo、真实状态管理），才使用 babel/React 或额外的 `<script>`。同样的渲染结果，静态 HTML 版本**始终优先于**动态版本，因为静态版本可被直接编辑。Tweaks 面板（`tweaks-panel.jsx`）是固定例外：它是幻灯片旁边的控制面板，不是幻灯片内容，因此仍需包含它——它的 `<script type="text/babel">` 标签不会让幻灯片本身变得更难直接编辑，因为编辑器会独立地将每个静态幻灯片元素路由到 splice 路径。
+- 封面 / 目录 / 使用说明：建立主题、范围、读法和关键承诺。
+- 章节分隔页：承载章节编号、主题、过渡判断或下一段问题，不做纯装饰页。
+- 观点 / 结论页：一句话 thesis + 1-3 个证据或影响。
+- 数据 / 指标页：KPI strip、图表或表格、口径 / 来源、短结论必须在同屏闭环。
+- 对比 / 选项页：A/B/多方案使用稳定代号、颜色和评价维度，贯穿方案封面、详情、排期和最终建议。
+- 流程 / 日程 / 预算 / 清单页：优先用表格、矩阵、时间轴、泳道或 checklist，不要把结构化信息改写成散文卡片。
+- 教学 / 练习页：保持稳定 scaffold，例如"编号 / 题型 / 进度 + 题干 + 条件 / 选项 + 答案 / 考点 / 易错点"。
+- 叙事 / 案例页：可以使用 prologue、chapter、turning point、proof、epilogue 等章节节拍，让情绪和判断同步推进。
 
-### 两个细节保持静态幻灯片可直接编辑
+每 3-5 页安排一次节奏变化：章节页、全屏观点页、数据页、对比页、表格页、案例页之间轮换。同层级的并列内容（成组案例、系列练习、多个方案）保持同一 scaffold，利于跨页比较——此时节奏变化靠在块之间插入章节页或小结页，而不是改动系列内页面的版式。不要把叙事功能不同的页面压平成同一个版式。变化来自页型和信息结构，不靠堆装饰。
 
-两个细节确保静态幻灯片可被直接编辑：每段文字都放在自己的叶子元素中（把 "Revenue" 放在 `<h2>` 内单独的 `<span>` 里，而不是写成 `<h2>Revenue <span class="sub">2025</span></h2>` 这样文本和子元素混在同一父节点的形式），重复结构要逐一写出而非生成——三条 `<li>` 直接写在标记里，而不是从数组渲染一个 `<li>` 三次。重复正是重点所在；它让用户能编辑第二条而不影响第一条。
+## 内容组织与版式策略
+deck 每页先判断它要让观众完成什么阅读动作：抓结论、看证据、比较差异、理解过程、记住模型、看到风险、做选择，还是进入下一章节。版式、文字、图形和动效都只是表达手段，选择最能讲清这一页的组合。
+- 根据当前页内容现场生成结构，不局限于常见页型。可以保留强文字页，也可以把材料转成模型图、关系图、流程、对比矩阵、时间线、象限、分层结构、地图、系统图、路径图、图表注释、截图标注或视觉隐喻；还可以把重要句子放大成观点页。示例只是启发，不是清单。
+- 同一章节内可以有连续叙事，但每页的结构不必一样。核心页给足面积和视觉重量，支撑页可以更密集；重要概念可以用图形和标注解释，也可以用排版、引用、数字、对照文本或图文组合解释。
+- 单页可以承载“小型演示过程”：先出现结论，再让支撑内容逐步显现，最后高亮关键判断。支撑内容可以是文字、数字、图形、数据、截图或关系结构；是否使用动效由表达目的决定。
+- 如果一页只有少量概念，不要机械铺成几张卡片。先判断概念之间有没有关系：并列、递进、因果、闭环、漏斗、分层、坐标、路径、前后对比或组合模型。关系明确时可以画出来；关系不明确时，可以改成更有力量的文字观点页、引用页，或合并到相邻页。
+- 版式变化来自内容关系，不来自凑组件。不要为了“丰富”而加无依据内容、无意义图标或装饰图形；图形、图片和动效只有在能帮助观众理解时才使用。
 
-## 幻灯片设计与构图
+## 版式系统（写第一页前先定）
 
-先定方向：动手前先调用 `frontend-design` skill 立视觉方向框架，再结合主题、受众、场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；frontend-design 的通用设计规则与本 skill 的 deck / 构图规则冲突时，以本 skill 为准。保持清晰的层级与一致的视觉系统。
+- 用 CSS 变量定义字号 / 间距，放在 `<head>` 的 `<style>` 里，**先于任何 slide**。这让整份 deck 改一个数（直接改变量，或用 Tweaks 滑块绑同一变量）就能统一缩放，slide 本体保持无脚本的静态 HTML。1920×1080 起点：
+  ```css
+  :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;
+  }
+  ```
+  1280×720 时整体 ×0.67。每个 font-size 都用 `--type-*`，每个 padding / gap 都用 `--pad-*` / `--gap-*`。`--pad-bottom` 是结构性的底部呼吸空间，不是空白。
+- 网页默认（14-16px 正文、48-72px 边距）对投影太小。标题 ≥ 48px，正文 / 注释**不得小于 24px**（验证器会对 < 24px 抛错）。用户说字号一般指 pt，按 PowerPoint / Keynote 换算：`px = pt × 1.333`（"标题 36pt" → CSS 设 ~48px）。
+- 规划页面类型：封面、章节页、观点页、数据页、对比页、流程页、图片页、结束页各有稳定样式。同类页面的标题位置、页码、章节名、脚注、来源、关键数字、图片位置要**平行对齐**，方便观众跨页比较。
+- 为每种页型固定布局锚点：标题、章节号、页码、来源、图表、主视觉和关键数字的位置不要随机漂移。相同页型要像同一个系统，不同页型再负责制造节奏。
 
-### 构图原则
+## 视觉设计
 
-- **留白 ≠ 空洞。** 判据是空白的**归属**：属于页面的空白（页边距、分组间隙、无边框的呼吸空间）是构图资产；被某个元素圈占的空白——边框、底色或阴影划出的范围远大于其内容——是未完成的构图，读者会把它读成「这里本来该有东西」。元素的边界应由内容撑出来，而不是由要填的空间决定；画布填不满时，把空间留在元素**之间**，或按「视觉平衡」的出路增密。
+视觉服务演示场景，不是网页首页。
 
-- **视觉锚点。** 每页要能回答：视线第一眼落在哪里，为什么是那里。锚点可以是一个大数字、一张图表、一句大字陈述，也可以是并列结构中被刻意加重的一项。所有元素等面积、等字号、等色彩权重的页面，是把第一落点交给了随机——那不是中性，是没做构图决策。
+- **明暗按需求选择**：根据品牌 / 主题 / 图片素材 / 演示场景选择浅色、暗色或混合背景。无论选择哪种，都要保证投影、截图和后排阅读的对比度。明暗切换应落在叙事节点上（章节转换、关键强调），不要无来由地跳变。
+- 字体克制（1-2 套）：展示字体可有个性，正文必须稳定可读；整体对比清楚、信息块边界明确。
+- 图片先判断内容和用途：摄影 / 氛围图可满版裁切；截图、图表、产品界面、架构图必须完整展示（aspect-fit），不能裁掉关键边界或文字；透明图 / 细线图放到有对比的底色上。图上压字用品牌常见方式保护可读性（遮罩、渐变、模糊或文字容器）。
+- 视觉要有节奏变化：全图页、大数字页、表格页、引用页、流程页、文字页交替出现；不要整套都是同一种卡片。也不要每页硬加描边卡片、固定结论框或装饰分割线——只有内容需要分组时才用容器。
+- 扁平基线：好的 deck 不依赖阴影和悬浮卡片堆叠。优先用全页背景、色带、分隔线、编号、表格网格、图片裁切、对比色块和尺度差建立层次。只有在需要表达真实物件、票券、照片或舞台层次时才少量使用阴影。
+- 不用 emoji、不临时手绘复杂假图；优先用用户素材、品牌资产、图标库或真实图片。
+- **空间重心**：内容集中在上方 2/3、底部留白，通常是**正确**的 slide 构图。看到 `align-items: flex-start` 加底部留空就想改成 `center`——那是网页设计的条件反射，忍住，留白是有意的。但留白有下界：内容页的主内容应占版心高度约 2/3 以上，撑不满就升格版式——放大成大数字、大卡片，或重排为居中的宣言页，而不是把原内容原样居中或任其悬浮在顶部。空本身不是缺陷，不均才是：同一页一处大空、一处拥挤，要重排。双栏页两列视觉重量要对等，悬殊时改 7:5 / 8:4 不对称栅格或并回单栏。
 
-- **视觉平衡。** 视觉重量要在整幅画布上分布均衡，不要全压在画幅一角。**内容只占上半画布、下半大面积空置的页面直接违规。** 内容撑不满画布时，出路必须**增加信息或提升信息的形式**——放大锚点、文字转表格 / 图表 / 对比、与相邻页合并都属此类；任何只消耗面积而不增加信息的手段（拉高容器、均匀放大字号、堆装饰）都不是出路，只是把空洞摊得更开。
+## HTML 实现（deck-stage 外壳）
 
-- **平行性。** 平行性很重要：章节标题页外观必须一致；页码、眉标等结构件在所有页面位置样式一致；以此类推。
+- **不要手写 stage / 缩放 / 导航 / 页码**。先调用 `copy_starter_component`，`kind: "deck-stage.js"`（连字符、含扩展名，照抄；传裸名字或错扩展名会失败）。用普通 `<script src="deck-stage.js"></script>` 引入（vanilla JS，不是 JSX）。
+- 用 `<deck-stage width="1920" height="1080">` 包住所有 slide，每页一个 `<section data-label="…">` 子元素。deck-stage 负责等比缩放、键盘 / 点击 / 翻页导航、页数与导航条、speaker-notes 的 postMessage，以及打印成 PDF（一页一张）。
+- deck-stage 会**自动**按位置生成 `data-screen-label` 并注入 `data-miaoda-validate`——你只需给每页写 `data-label`（人类可读的页名），不用手写另两个。
+- `data-label` 使用可读页名或章节名，例如"30秒结论""A方案日程""数据·增长产出"，不要写成无语义的 `slide-1`。
+- **不要**在 slide `<section>` 上自行设置 position / inset / width / height——deck-stage 会绝对定位每个子元素。
+- 演讲者备注写在全局 `<script type="application/json" id="speaker-notes">`（置于 `<deck-stage>` 之外），内容是一个**按页顺序排列的扁平字符串数组**——第 N 个元素就是第 N 个 `<section>` 的备注（含封面，从 0 起按位置对齐）；某页没有备注也要用空串 `""` 占位，让数组长度始终等于页数。随翻页 postMessage 给宿主。
+  ```html
+  <script type="application/json" id="speaker-notes">
+  ["首页开场白…", "", "第 3 页的讲解要点…"]
+  </script>
+  ```
 
-- **版式节奏。** 与平行性互为对偶：平行性守住不变的东西，节奏经营变化的东西。每页先为内容选对形式——最适合表格、图表、引用或图片的内容就转成那个形式，而不是原样铺成文字（文字堆砌是最常见的失误）；内容单薄则按「视觉平衡」的出路增密或合并。逐页的形式选择连起来就是 deck 的节奏：节奏跟随叙事结构——章节转折、重点页、过渡页各有形态——而不是机械交替；节奏也需要对比才成立——满版图、大数字、图表、引用、不同背景色、纯文字，原型库要够开阔，页页同一骨架无节奏可言，那不叫一致，叫单调。用版式和可视化把画布用满不是「填充性内容」；凭空编造数据和板块才是。
+### slide 正文写成静态 HTML，不要用脚本生成
 
-### 素材与工艺
+这条最影响用户体验，理解**为什么**再执行：当一页正文是 `<deck-stage>` 里的普通静态标记时，用户在编辑态点任意标题 / 段落就能直接改字，编辑器会把改动即时 splice 回源文件；一旦这页由 `<script type="text/babel">`、React 组件或"遍历 JS 数组"渲染，这条直改路径就断了——每次微调都要通过 chat message 往返到你这里，更慢、也更难让用户自己打磨 deck。所以凡是静态页能表达的（文字、布局、背景、图片、表格），就把字面元素写进 HTML、用 CSS 定样式；只有当这页**真的**需要静态标记给不了的行为（交互图表、真实 demo、真实状态）才引入 babel / React 或额外 `<script>`。同样的渲染结果，静态版永远优先，因为它可直接编辑。
 
-- **字号与单位。** 使用大号字体（标题至少 48px）。当用户指定具体字号时，默认他们说的是**磅（points）**（PowerPoint/Keynote 的单位）而非像素——用 `px = pt × 1.333` 换算。所以"把标题设成 36pt" → 在 CSS 里设成约 48px。
+两个细节保住"可直接编辑"：
 
-- **中文字体。** 中文内容的字体对必须包含明确的 CJK 字体，且 `font-family` 全栈声明（拉丁字体在前、CJK 字体随后、通用族兜底）：衬线气质配 Noto Serif SC / 思源宋体，无衬线配 Noto Sans SC / 思源黑体系（MiSans/HarmonyOS Sans 亦可）——只写拉丁字体会让中文掉进系统回退。中文不用 italic（CJK 无真斜体，伪斜发虚）；强调用字重、颜色或引言竖线。标题拉开字重跨度（如正文 400、大标题 800-900）。
-
-- **素材来源。** 除非用户要求，绝不使用 emoji。使用 design system / 品牌中的图标、用户提供的图片，或图片生成工具产出的图片。
-
-- **图片呈现。** 务必先查看图片，再决定最佳展示方式。
-  - 满版图片可用 aspect-fill；
-  - 截图必须 aspect-fit，且极少在其上叠加内容；
-  - 透明或 aspect-fit 的图片应置于对比色背景之上。
-
-  在图片上叠加文字时，参照品牌惯常做法：根据你在其他地方看到的样式，酌情使用卡片、保护渐变或模糊效果。
-
-- **不 iframe 外站。** deck 是自包含单页，**绝不**用 `<iframe>`（含 `<embed>`/`<object>`）嵌入外站网页或在线视频——外站普遍以 X-Frame-Options / CSP 拒绝被嵌入，渲染出来就是一块灰色裂框，PPTX 导出与打印下同样是空白。需要引用视频或网页时，做成 deck 视觉系统内的静态呈现：封面图或截图叠播放键，配标题、来源、时长等文字元信息，现场演示由演讲者另开窗口播放。
-
-- **图表与数据可视化。** 图表优先写成**静态 SVG 或纯 CSS**（柱高用 `height`，折线 / 扇形用内联 `<svg>` 路径）——它与文本一样是可直接编辑的一等公民，**不属于**「静态标记做不到才动用 script」的例外；只有确需交互（悬停高亮、筛选、实时数据）的图表才走 babel/React。数字之间只要存在能被眼睛读出的关系（趋势、占比、对比、分布），就转成图表，而不是原样铺成文字。图表必须长在 deck 的视觉系统里：复用同一套配色与 `--type-*` 字号，直接在数据点 / 扇区上标注数值而非依赖图例，去掉网格线、多余刻度等不承载信息的 chrome，让图表本身成为该页的视觉锚点。
-
-- **动效。** 动效服务于叙事——引导视线、分层揭示信息、平滑衔接页面——而不是炫技或填空。默认克制，始终以不干扰阅读为底线。deck 动效的形态是**翻到该页时播放一次的入场 / 分步揭示**，不做环境循环——无限循环的装饰动画会持续争夺注意力。实现用 CSS 动画（幻灯片保持可直编的静态 HTML），两条契约（细节见 deck-stage.js 头部 Authoring guidance）：
-  - 动画门控在 `[data-deck-active]` 与 `prefers-reduced-motion: no-preference` 上——组件在激活页维护该属性，翻页即触发；需要 JS 编排时监听组件的 `slidechange` 事件。
-  - 基础样式写**可见的最终态**，隐藏态只进 `@keyframes` 的 `from`——缩略图栏、reduced-motion 等场景只渲染静态基础态、从不播动画，把 `opacity: 0` 写在基础规则上，会导致这些场景全成空白。
-
-- **层次靠版式，不靠特效。** 页内层级由字号、字重、色块、边框、分隔线和留白建立；内容卡片和区块默认平面化——不加 box-shadow、发光、玻璃拟态（backdrop-filter + 半透明底），渐变默认只用于图上文字的保护渐变（见「图片呈现」）和数据可视化的连续色带。深色底 + 紫蓝渐变 + 发光卡片的「科技感」组合是模型默认值而非设计选择（frontend-design 校准清单第 4 种长相），除非品牌 / brief 明确要求，不要用它。
-
-- **结构件。** 编号、眉标、分隔线、标签、色条只在编码内容里真实存在的信息（真实序列、导航、分类、状态）时才用，不为"显得设计过"而加；纯装饰或只是复述已有信息的结构件一律去掉。
-
-- **彩色边条。** 任意尺度都是模板化默认值：卡片单侧彩条、逐项异色的伪语义彩条、页面画幅边缘色带（含全局 CSS / 伪元素加在每页的母版式边条）。判据一条：删掉后读者不损失任何信息的即装饰，一律去掉，平行性不为装饰续命。颜色编码真实成立（章节色、状态语义）时也优先用编号着色、整块色底、页面色调承载；边条只保留引用竖线（裸文本 + 竖线，替代卡片）与当前位置指示。
-
-## 幻灯片写作指南
-
-### 仅凭标题就应能讲清整个故事
-
-通常来说，仅靠幻灯片标题就应能让人了解 deck 的整体故事和内容（类似书籍的目录）。
-
-幻灯片标题一般有以下几种结构类型：
-
-- **主题式**：名词短语，告诉听众这页讲什么（如「市场格局」「团队结构」「六大常见威胁」）
-- **论点式**：短陈述句，直接给出该页结论（如「亚洲是我们最大的市场」「弱密码是最常被利用的入口」）
-
-选定合适的标题结构后，始终保持一致。
-
-### 避免暴露 AI 生成痕迹的 "AI 味"
-
-避免以下常见的 "AI 味"——它们会暴露这个 deck 是 AI 生成的：
-
-- "宣判式"的标题和要点总结，过度戏剧化/简化，无缘由地制造张力（经典的 "It's not X. It's Y."），使用强祈使句，过度重新包装概念，或刻意悬念、故作洞察。
-- 类似 "The magic moment" 这样的标题
-- 总之，AI 倾向于把标题写成演讲者的金句，而非引导听众进入该页内容的**标题**——必须避免！
-
-## 规划步骤
-
-在常规规划之外，务必完成以下步骤：
-
-1. 如果不清楚受众、期望的品牌风格，先提问。
-2. 写出完整的标题序列。选择**一种**语法风格（例如短主题名词短语或简短陈述句），确保适合内容，并用该风格写出每一个标题。回头通读一遍，判断一个人**仅凭标题**能否跟上整个演示的脉络。标题应像书的章节——用直白的语言告诉读者接下来是什么。审阅这些标题并按需修订。将它们写入 scratchpad.md 文件。
-3. 在 scratchpad.md 里为每张幻灯片标注**版式原型**（满版图 / 大数字 / 图表 / 表格 / 引用 / 多栏卡片 / 时间线 / 纯文字……）与**视觉锚点**（这页视线的第一落点）。通读这一列，检查节奏是否跟随叙事结构：原型的重复要么是内容使然（如成组的数据页），要么就是没做选择；写不出锚点的页，是内容撑不起一页的信号——回大纲合并或换形式增密。
-4. 在写任何幻灯片**之前**，先在 `<head>` 的一个 `<style>` 块中将字号、行高和间距定义为 CSS custom properties——这会锁定适合投影的尺寸，防止不自觉退回网页密度。画幅恒为 1920×1080（deck-stage 的基准，输出尺寸由组件 letterbox 缩放解决），合理的起始体系为：`:root { --type-display: 120px; --type-title: 64px; --type-subtitle: 44px; --type-body: 34px; --type-small: 28px; --leading-title: 1.15; --leading-body: 1.4; --measure-body: 40em; --pad-top: 100px; --pad-bottom: 80px; --pad-x: 100px; --gap-title: 52px; --gap-item: 28px; }`。所有地方都引用这些变量——每个 font-size 都用 `--type-*`，每个 line-height 都用 `--leading-*`，每个 padding/gap 都用 `--pad-*` 或 `--gap-*`，通过 inline style 或 class 规则中的 `var(…)` 引用。取档跟着版式原型走：大数字 / 引用页的主角上 `--type-display`，表格单元格用 `--type-small`；连续文本块限宽 `max-width: var(--measure-body)`——行长超限会让达标的字号读起来又小又密，多出来的画幅宽度用双栏、图文并排消化，而不是让一行文字全宽跑。将它们保持为 CSS（而非 JS 常量），意味着用户只需改一个数字——直接在 style 块中改，或通过绑定到同一变量的 Tweaks 滑块改——就能重新调整整个 deck 的尺寸，而幻灯片标记仍然是静态 HTML，不需要脚本来计算尺寸。显式的 `--pad-bottom` 为每张幻灯片底部预留呼吸空间；那个留白是结构性的，不是空的。网页默认值（body 14-16px、padding 48-72px）对幻灯片太小；如果数值让你觉得不够大方，那就是还不够。任何文字不得小于 24px——这是下限不是目标。
-5. **把这套 token 当成每页的内容预算**：在上述数值下，一页正文区大约容纳 14 行正文、或 6 个两行 bullet——在 scratchpad 排内容时就按预算裁剪，而不是写完再看塞不塞得下。装不下的处置顺序是**拆页 > 删内容 > 换更省空间的版式**；缩小字号是最后手段，且绝不越过 24px 下限——靠缩字塞进去的页，只是把溢出换成了后排看不清。反过来，内容远少于预算的页按「视觉平衡」的出路增密或合并，而不是放大字号去撑面积。
-6. 构建幻灯片，牢记每张幻灯片既是设计练习也是文案练习。在版式、文字内容和语调方面给予每张幻灯片应有的关注。遵循上述原则，确保每张幻灯片能独立成立；一个只看这一页的人，应当无需其他上下文就能理解其高层含义。
-
-## 验证要点
-
-审阅时，用幻灯片构图规则——而非网页布局直觉——来检查截图。底部留白是不是缺陷，用「留白 ≠ 空洞」的归属判据：内容自身完整、下方是无边框的整块呼吸空间，这是正确的幻灯片构图——不要出于网页直觉把 `flex-start` 改成 `center`；空白被元素边界圈占的，是被动空洞，按「视觉平衡」的出路修。
-
-逐页核对以下各项：
-
-- 字号匹配你的 `--type-*` 体系（而非网页密度），没有为塞内容缩到 24px 以下
-- 连续文本块行长不超过 `--measure-body`，没有一行文字横穿整个画幅
-- 幻灯片边距匹配你的 `--pad-*` 值（而非网页紧凑间距）
-- 封面有统治画面的主视觉，标题位置有构图意图，不是「小图标 + 居中标题 + 居中副标题」三件套
-- 结构件（页码、眉标）全 deck 位置样式一致；章节页彼此外观一致
-- 没有任何尺度的装饰性彩色边条（判据见「彩色边条」）；没有 takeaway box
-- 内容区平面化：没有装饰性渐变背景、发光、玻璃拟态；渐变只出现在图上文字保护或数据色带上
-- 没有内容被画幅边缘裁切、显示不全
-- 没有元素相互压叠、遮挡到读不清
-- 没有被动空洞：边框 / 底色圈出的范围与其内容相称
-- 页面视觉重量在画布上分布均衡，没有大片区域读成「缺了东西」
-- 每页能指出视觉锚点；版式原型的重复经得起「内容使然还是没做选择」的追问
-- 带动效的元素在缩略图栏和打印视图下完整可见（基础样式即最终态，隐藏态只在 keyframes 的 `from` 里）
+- 每段可编辑文字放在自己的叶子节点里——把"Revenue"放进 `<h2>` 内它自己的 `<span>`，别写成 `<h2>Revenue <span class="sub">2025</span></h2>` 这种文本和子元素混在同一父节点。
+- 重复结构写出来、不要生成——三条 bullet 就写三个 `<li>`，不要用数组渲染一个 `<li>` 三次。重复正是重点：它让用户改第二条时不碰第一条。
+- 例外：`tweaks-panel.jsx` 是挨着 slide 的控制面板、不是 slide 正文，可以用 `<script type="text/babel">`；它不影响各静态 slide 各自走直改路径。
+
+## 交付前自检
+
+- 每页 16:9，无溢出 / 重叠 / 裁切；字号符合投影阅读（正文没有小到像网页）。
+- 留白均匀：同一页没有一处大空、一处拥挤；内容页主内容占版心高度约 2/3 以上；双栏视觉重量对等。
+- 只读标题能讲通故事；标题语法全程一致，没有 punchline / takeaway 盒子。
+- 已建立 page-type map，并通过页型轮换避免单一上下布局。
+- 章节分隔页推动叙事，而不是只做装饰。
+- 演讲型页面没堆太多字；阅读型页面没变成文档截图。
+- 同类页面布局、标题位置、页码、章节标识平行一致；图片没被不合理拉伸，截图 / 图表完整展示。
+- 多方案、教学练习、叙事案例、数据汇报等特定场景使用了稳定 scaffold。
+- slide 正文是静态可编辑 HTML，没用脚本循环生成；`data-label`、speaker-notes、打印分页完整。
+- deck-stage 外壳、导航、页码来自 starter component，没有手写重复实现。