@lark-apaas/coding-steering 0.1.17 → 0.1.18-dev.1f9a8c4

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.17",
+  "version": "0.1.18-dev.1f9a8c4",
   "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/**'"
-  },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"
   },
@@ -20,5 +17,8 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  }
+}

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Guidance for establishing a distinctive, intentional visual direction for a design — palette, typography, and aesthetic choices that don't read as templated defaults. Applies across media (decks, reports, UI, prototypes), not just web UI.
 available-agents:
   - CreativeDesign
 ---

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

@@ -1,125 +1,132 @@
 ---
 name: make-a-deck
-description: 制作演示文稿 / PPT / pitch deck / slides / keynote。从零新建、从文档材料提炼重组、或对已有 PPTX 重新设计。触发词：presentation, slides, deck, PPT, PPTX, keynote, pitch, 演示文稿, 幻灯片, 路演
-available-agents:
-  - CreativeDesign
+description: 当用户要求制作演示文稿 / PPT / PPTX / pitch deck / slides / keynote / 路演材料时使用——即供演讲者现场演示、固定画幅 16:9 的自包含 HTML deck。
 ---
 
-# 制作演示文稿（deck）
+# Make a deck
 
-把演示文稿做成单个自包含的 HTML 页面。HTML 是输出载体，但设计判断按 PPT 来做：固定画幅、强叙事、可投影 / 可异步阅读、每页只承担一个清楚的沟通任务。
+把演示 deck 做成一个自包含的 HTML 单页。
 
-把自己当成演示文稿设计师，不是网页开发者：像顾问、分析师、高管准备董事会材料那样思考——清晰、叙事流、后排可读。每一页都同时是版式设计和文案写作。开始落 HTML 前，先写大纲；好的大纲本身就是一次叙事结构训练。
+进入这个角色：你是一名演示设计师（presentation designer）。你为演讲者制作用于现场演示的幻灯片 deck——HTML 只是你的输出介质，你的作品要经得起现场检验：清晰、叙事流畅、后排也能看清。你不是在做网站。
 
-## 信息密度
+**先判断场合，再定设计语气。** 判定场合后，代入该场合最专业的制作者身份——为这类场合做过上百场 deck 的人会怎么取舍——用它校准每一页的语气与密度。场合决定三件事：信息密度（听众扫读还是研读）、标题语法（论点式还是主题式）、节奏权重（哪类版式原型承担叙事高点）。动手前在 scratchpad 用一两句写明场合、代入的身份与这三项决策，全 deck 一致执行；工艺规则（构图、字号、平行性）不随场合变。
 
-选一种密度，不要停在模糊的中间态：
+每张幻灯片既是版式设计的练习，也是文案写作的练习。动手前先写大纲；好的大纲本身就是一次讲故事和叙事结构的练习。
 
-| 模式 | 场景 | 做法 |
-| --- | --- | --- |
-| 演讲型 / 低密度 | 发布会、公开演讲、keynote、现场 pitch | 一页一个观点，大标题强视觉、留白足、要点 1-3 条，必要时增加页数 |
-| 阅读型 / 高密度 | 内部汇报、评审、复盘、异步传阅 | 每页更自洽，可用表格 / 结构卡片 / 注释 / 图表，但层级要明确 |
+## 动手前先问
 
-无论哪种，都不要让页面滚动、溢出、重叠或用过小字体；放不下就拆页。**不要把整份文档直接贴进幻灯片**——这是最常见的失败模式。落 plan 时就想清楚：哪些内容更适合做成表格、图表、流程、引用页或图片页。
+- 如果用户没有说明想要的视觉风格，也没有提供 design system，就用提问工具（ask user）**主动询问**。绝不要直接给出一个通用设计！
 
-## 叙事与标题
+## 构建准备与技术契约
 
-- 先写完整标题序列放进 `scratchpad.md`。只读标题就应能看懂整份 deck 的逻辑（像书的目录）。检查是否形成清楚路径：背景 → 问题 → 洞察 → 方案 → 证据 → 下一步。
-- 选定一种标题语法并全程一致：要么名词短语（"市场机会""产品架构"），要么简短判断句（"新用户增长主要来自自然流量"）。
-- 每页正文只服务本页标题，不塞旁支。封面、章节页、转场页、结尾页也要服务故事，不做纯装饰。
+### deck-stage 组件
 
-避免这些"AI 味"标题（它们会暴露 deck 是 AI 生成的）——标题的任务是**定位页面、推进叙事**，不是替演讲者甩结论 / 喊 punchline：
+以 1920×1080（16:9）为基准构建。**绝不**手写 stage/缩放/翻页的脚手架——先调用 `copy_starter_component` 并传入 `kind: "deck-stage.js"`，然后将 deck HTML 写成 `<deck-stage width="1920" height="1080">`，每张幻灯片对应一个 `<section data-label="…">` 子元素。该组件负责：
 
-- "不是 X，而是 Y"式过度反转。
-- "关键时刻""魔法时刻"式空泛或故作深刻。
-- 过度夸张的行动号召、为制造张力而制造张力。
-- 每页固定一个 takeaway 盒子，导致标题和正文重复。
+- letterbox 缩放
+- 键盘 + 触控翻页
+- speaker-notes 的 postMessage 协议
+- `data-screen-label` / `data-miaoda-validate` 标记
+- print-to-PDF（每张幻灯片一页）
 
-## 页面类型与节奏
+用 `<script src="deck-stage.js"></script>` 加载它——它是 vanilla JS，不是 JSX。（为了之后导出 PPTX：向 gen_pptx 传入 `resetTransformSelector: "deck-stage"`——该组件支持 `noscale` 属性来禁用 shadow-DOM 缩放，使截图拿到原始尺寸的几何信息。）
 
-写第一页前先做 page-type map：为每页标注页型、叙事作用和需要承载的素材。避免所有页面都变成"标题 + 三栏卡片"。
+deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**在幻灯片 `<section>` 元素上自行设置 position/inset/width/height。
 
-常用页型包括：
+### 把幻灯片内容写成静态 HTML，而不是 React
 
-- 封面 / 目录 / 使用说明：建立主题、范围、读法和关键承诺。
-- 章节分隔页：承载章节编号、主题、过渡判断或下一段问题，不做纯装饰页。
-- 观点 / 结论页：一句话 thesis + 1-3 个证据或影响。
-- 数据 / 指标页：KPI strip、图表或表格、口径 / 来源、短结论必须在同屏闭环。
-- 对比 / 选项页：A/B/多方案使用稳定代号、颜色和评价维度，贯穿方案封面、详情、排期和最终建议。
-- 流程 / 日程 / 预算 / 清单页：优先用表格、矩阵、时间轴、泳道或 checklist，不要把结构化信息改写成散文卡片。
-- 教学 / 练习页：保持稳定 scaffold，例如"编号 / 题型 / 进度 + 题干 + 条件 / 选项 + 答案 / 考点 / 易错点"。
-- 叙事 / 案例页：可以使用 prologue、chapter、turning point、proof、epilogue 等章节节拍，让情绪和判断同步推进。
+幻灯片内容应写成静态 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 路径。
 
-每 3-5 页安排一次节奏变化：章节页、全屏观点页、数据页、对比页、表格页、案例页之间轮换。同层级的并列内容（成组案例、系列练习、多个方案）保持同一 scaffold，利于跨页比较——此时节奏变化靠在块之间插入章节页或小结页，而不是改动系列内页面的版式。不要把叙事功能不同的页面压平成同一个版式。变化来自页型和信息结构，不靠堆装饰。
+### 两个细节保持静态幻灯片可直接编辑
 
-## 内容组织与版式策略
-deck 每页先判断它要让观众完成什么阅读动作：抓结论、看证据、比较差异、理解过程、记住模型、看到风险、做选择，还是进入下一章节。版式、文字、图形和动效都只是表达手段，选择最能讲清这一页的组合。
-- 根据当前页内容现场生成结构，不局限于常见页型。可以保留强文字页，也可以把材料转成模型图、关系图、流程、对比矩阵、时间线、象限、分层结构、地图、系统图、路径图、图表注释、截图标注或视觉隐喻；还可以把重要句子放大成观点页。示例只是启发，不是清单。
-- 同一章节内可以有连续叙事，但每页的结构不必一样。核心页给足面积和视觉重量，支撑页可以更密集；重要概念可以用图形和标注解释，也可以用排版、引用、数字、对照文本或图文组合解释。
-- 单页可以承载“小型演示过程”：先出现结论，再让支撑内容逐步显现，最后高亮关键判断。支撑内容可以是文字、数字、图形、数据、截图或关系结构；是否使用动效由表达目的决定。
-- 如果一页只有少量概念，不要机械铺成几张卡片。先判断概念之间有没有关系：并列、递进、因果、闭环、漏斗、分层、坐标、路径、前后对比或组合模型。关系明确时可以画出来；关系不明确时，可以改成更有力量的文字观点页、引用页，或合并到相邻页。
-- 版式变化来自内容关系，不来自凑组件。不要为了“丰富”而加无依据内容、无意义图标或装饰图形；图形、图片和动效只有在能帮助观众理解时才使用。
+两个细节确保静态幻灯片可被直接编辑：每段文字都放在自己的叶子元素中（把 "Revenue" 放在 `<h2>` 内单独的 `<span>` 里，而不是写成 `<h2>Revenue <span class="sub">2025</span></h2>` 这样文本和子元素混在同一父节点的形式），重复结构要逐一写出而非生成——三条 `<li>` 直接写在标记里，而不是从数组渲染一个 `<li>` 三次。重复正是重点所在；它让用户能编辑第二条而不影响第一条。
 
-## 版式系统（写第一页前先定）
+## 幻灯片设计与构图
 
-- 用 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）。
-- 规划页面类型：封面、章节页、观点页、数据页、对比页、流程页、图片页、结束页各有稳定样式。同类页面的标题位置、页码、章节名、脚注、来源、关键数字、图片位置要**平行对齐**，方便观众跨页比较。
-- 为每种页型固定布局锚点：标题、章节号、页码、来源、图表、主视觉和关键数字的位置不要随机漂移。相同页型要像同一个系统，不同页型再负责制造节奏。
+先定方向：动手前先调用 `frontend-design` skill 立视觉方向框架，再结合主题、受众、场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；frontend-design 的通用设计规则与本 skill 的 deck / 构图规则冲突时，以本 skill 为准。保持清晰的层级与一致的视觉系统。
 
-## 视觉设计
+### 构图原则
 
-视觉服务演示场景，不是网页首页。
+- **留白 ≠ 空洞。** 判据是空白的**归属**：属于页面的空白（页边距、分组间隙、无边框的呼吸空间）是构图资产；被某个元素圈占的空白——边框、底色或阴影划出的范围远大于其内容——是未完成的构图，读者会把它读成「这里本来该有东西」。元素的边界应由内容撑出来，而不是由要填的空间决定；画布填不满时，把空间留在元素**之间**，或按「视觉平衡」的出路增密。
 
-- **明暗按需求选择**：根据品牌 / 主题 / 图片素材 / 演示场景选择浅色、暗色或混合背景。无论选择哪种，都要保证投影、截图和后排阅读的对比度。明暗切换应落在叙事节点上（章节转换、关键强调），不要无来由地跳变。
-- 字体克制（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>
-  ```
+- **平行性。** 平行性很重要：章节标题页外观必须一致；页码、眉标等结构件在所有页面位置样式一致；以此类推。不约束内容主体的版式——那归版式节奏管。
 
-### slide 正文写成静态 HTML，不要用脚本生成
+- **版式节奏。** 与平行性互为对偶：平行性守住不变的东西，节奏经营变化的东西。每页先为内容选对形式——最适合表格、图表、引用或图片的内容就转成那个形式，而不是原样铺成文字（文字堆砌是最常见的失误）；内容单薄则按「视觉平衡」的出路增密或合并。逐页的形式选择连起来就是 deck 的节奏：节奏跟随叙事结构——章节转折、重点页、过渡页各有形态——而不是机械交替；节奏也需要对比才成立——全图、大数字、图表、引用、不同背景色、纯文字，原型库要够开阔，页页同一骨架无节奏可言，那不叫一致，叫单调。用版式和可视化把画布用满不是「填充性内容」；凭空编造数据和板块才是。
 
-这条最影响用户体验，理解**为什么**再执行：当一页正文是 `<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。
 
-- 每段可编辑文字放在自己的叶子节点里——把"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，没有手写重复实现。
+- **中文字体。** 中文内容的字体对必须包含明确的 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 的图片应置于对比色背景之上。
+
+  在图片上叠加文字时，参照品牌惯常做法：根据你在其他地方看到的样式，酌情使用卡片、保护渐变或模糊效果。
+
+- **图表与数据可视化。** 图表优先写成**静态 SVG 或纯 CSS**（柱高用 `height`，折线 / 扇形用内联 `<svg>` 路径）——它与文本一样是可直接编辑的一等公民，**不属于**「静态标记做不到才动用 script」的例外；只有确需交互（悬停高亮、筛选、实时数据）的图表才走 babel/React。数字之间只要存在能被眼睛读出的关系（趋势、占比、对比、分布），就转成图表，而不是原样铺成文字。图表必须长在 deck 的视觉系统里：复用同一套配色与 `--type-*` 字号，直接在数据点 / 扇区上标注数值而非依赖图例，去掉网格线、多余刻度等不承载信息的 chrome，让图表本身成为该页的视觉锚点。
+
+- **概念可视化（信息图）。** 与数字→图表对偶：**文字之间只要存在结构关系——顺序/流程、因果、层级、循环、包含、对比、矩阵——就转成信息图**（静态 SVG / CSS），而不是 bullet list。原型库：步骤条、时间线、金字塔、同心圆、漏斗、四象限矩阵、环形循环、双栏 VS 对比、路径图；内容使用命名框架（波特五力、SWOT、飞轮等）时直接用该框架的经典图式。判据：凡是想写 3 条以上并列 bullet 的地方，先问这几条之间是什么关系——**关系本身就是版式**。图形语言：同一图内同级节点同形态同尺寸、不换色相，差异用主色深浅表达；连接线用 SVG 真图形对齐节点锚点，不用字符箭头；节点等距。信息图复用 deck 配色与 `--type-*` 体系，节点上直接标注文字。
+
+- **动效。** 动效服务于叙事——引导视线、分层揭示信息、平滑衔接页面——而不是炫技或填空。默认克制，始终以不干扰阅读为底线。deck 动效的形态是**翻到该页时播放一次的入场 / 分步揭示**，不做环境循环——无限循环的装饰动画会持续争夺注意力。实现用 CSS 动画（幻灯片保持可直编的静态 HTML），两条契约（细节见 deck-stage.js 头部 Authoring guidance）：
+  - 动画门控在 `[data-deck-active]` 与 `prefers-reduced-motion: no-preference` 上——组件在激活页维护该属性，翻页即触发；需要 JS 编排时监听组件的 `slidechange` 事件。
+  - 基础样式写**可见的最终态**，隐藏态只进 `@keyframes` 的 `from`——缩略图栏、reduced-motion 等场景只渲染静态基础态、从不播动画，把 `opacity: 0` 写在基础规则上，会导致这些场景全成空白。
+
+- **结构件。** 编号、眉标、分隔线、标签只在编码内容里真实存在的信息（真实序列、导航、分类）时才用，不为"显得设计过"而加；纯装饰或只是复述已有信息的结构件一律去掉。
+
+## 幻灯片写作指南
+
+### 仅凭标题就应能讲清整个故事
+
+通常来说，仅靠幻灯片标题就应能让人了解 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 下，合理的起始体系为：`:root { --type-hero: 160px; --type-display: 96px; --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-*` 变量，通过 inline style 或 class 规则中的 `var(…)` 引用。将它们保持为 CSS（而非 JS 常量），意味着用户只需改一个数字——直接在 style 块中改，或通过绑定到同一变量的 Tweaks 滑块改——就能重新调整整个 deck 的尺寸，而幻灯片标记仍然是静态 HTML，不需要脚本来计算尺寸。显式的 `--pad-bottom` 为每张幻灯片底部预留呼吸空间；那个留白是结构性的，不是空的。网页默认值（body 14-16px、padding 48-72px）对幻灯片太小；如果数值让你觉得不够大方，那就是还不够。如果你用了小于 24px 的尺寸，你的校验器（validator）会抛出错误。
+5. 构建幻灯片，牢记每张幻灯片既是设计练习也是文案练习。在版式、文字内容和语调方面给予每张幻灯片应有的关注。遵循上述原则，确保每张幻灯片能独立成立；一个只看这一页的人，应当无需其他上下文就能理解其高层含义。
+
+## 验证要点
+
+审阅时，用幻灯片构图规则——而非网页布局直觉——来检查截图。底部留白是不是缺陷，用「留白 ≠ 空洞」的归属判据：内容自身完整、下方是无边框的整块呼吸空间，这是正确的幻灯片构图——不要出于网页直觉把 `flex-start` 改成 `center`；空白被元素边界圈占的，是被动空洞，按「视觉平衡」的出路修。
+
+逐页核对以下各项：
+
+- 字号匹配你的 `--type-*` 体系（而非网页密度）
+- 幻灯片边距匹配你的 `--pad-*` 值（而非网页紧凑间距）
+- 封面有统治画面的主视觉，标题位置有构图意图，不是「小图标 + 居中标题」三件套
+- 结构件（页码、眉标）全 deck 位置样式一致；章节页彼此外观一致
+- 没有使用 accent-border 卡片或 takeaway box
+- 没有内容被画幅边缘裁切、显示不全
+- 没有元素相互压叠、遮挡到读不清
+- 没有被动空洞：边框 / 底色圈出的范围与其内容相称
+- 页面视觉重量在画布上分布均衡，没有大片区域读成「缺了东西」
+- 每页能指出视觉锚点；版式原型的重复经得起「内容使然还是没做选择」的追问
+- 带动效的元素在缩略图栏和打印视图下完整可见（基础样式即最终态，隐藏态只在 keyframes 的 `from` 里）