@lark-apaas/coding-steering 0.1.16-dev.a4b57cd → 0.1.16-dev.eef2d6c

package/package.json

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

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

@@ -1,148 +1,153 @@
 ---
 name: make-a-deck
-description: 当用户要求制作演示文稿 / PPT / PPTX / pitch deck / slides / keynote / 路演材料时使用——即供演讲者现场演示、固定画幅 16:9 的自包含 HTML deck。
+description: 制作演示文稿 / PPT / pitch deck / slides / keynote。从零新建、从文档材料提炼重组、或对已有 PPTX 重新设计。触发词：presentation, slides, deck, PPT, PPTX, keynote, pitch, 演示文稿, 幻灯片, 路演
+available-agents:
+  - CreativeDesign
 ---
 
-# Make a deck
+# 制作演示文稿（deck）
 
-把演示 deck 做成一个自包含的 HTML 单页。
-
-进入这个角色：你是一名演示设计师（presentation designer）。HTML 只是你的输出介质，你的作品要经得起现场检验：清晰、叙事流畅、后排也能看清。你不是在做网站。
-
-**先判断场合，再定设计语气。** 判定场合后，代入该场合最专业的制作者身份——为这类场合做过上百场 deck 的人会怎么取舍——用它校准每一页的语气与密度。场合决定三件事：信息密度（听众扫读还是研读）、标题语法（论点式还是主题式）、节奏权重（哪类版式原型承担叙事高点）。动手前在 scratchpad 用一两句写明场合、代入的身份与这三项决策，全 deck 一致执行；工艺规则（构图、字号、平行性）不随场合变。
-
-每张幻灯片既是版式设计的练习，也是文案写作的练习。动手前先写大纲；好的大纲本身就是一次讲故事和叙事结构的练习。
-
-## 动手前先问
-
-- 如果用户没有说明想要的视觉风格，也没有提供 design system，就用提问工具（ask user）**主动询问**。绝不要直接给出一个通用设计！**不要空问**：先从主题、素材、场合推导 2-3 个候选风格方向（各配一句推荐理由），让用户确认或选择，并保留自由输入的余地。
-- 无法询问时：从**主题语义**推导 2-3 个候选配色方向再选定其一（写进 scratchpad），禁止套习惯默认（典型：深色底 + 青/蓝 accent 的"科技风"）。深浅底是设计选择，给出场景理由即可用深底；推导无明确倾向时优先浅底——带色温的白（oklch chroma ≤ 0.02）配 1-2 个同明度同 chroma、仅变 hue 的强调色。全 deck 背景色最多 2 种。
-
-## 构建准备与技术契约
-
-### deck-stage 组件
-
-以 1920×1080（16:9）为基准构建。**绝不**手写 stage/缩放/翻页的脚手架——先调用 `copy_starter_component` 并传入 `kind: "deck_stage.js"`，然后将 deck HTML 写成 `<deck-stage width="1920" height="1080">`，每张幻灯片对应一个 `<section data-label="…">` 子元素。该组件负责：
-
-- 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 缩放，使截图拿到原始尺寸的几何信息。）
-
-deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**在幻灯片 `<section>` 元素上自行设置 position/inset/width/height。
-
-### 把幻灯片内容写成静态 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 路径。
-
-### 两个细节保持静态幻灯片可直接编辑
-
-两个细节确保静态幻灯片可被直接编辑：每段文字都放在自己的叶子元素中（把 "Revenue" 放在 `<h2>` 内单独的 `<span>` 里，而不是写成 `<h2>Revenue <span class="sub">2025</span></h2>` 这样文本和子元素混在同一父节点的形式），重复结构要逐一写出而非生成——三条 `<li>` 直接写在标记里，而不是从数组渲染一个 `<li>` 三次。重复正是重点所在；它让用户能编辑第二条而不影响第一条。
-
-## 幻灯片设计与构图
-
-先定方向：动手前先调用 `frontend-design` skill 立视觉方向框架，再结合主题、受众、场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；frontend-design 的通用设计规则与本 skill 的 deck / 构图规则冲突时，以本 skill 为准。保持清晰的层级与一致的视觉系统。
-
-### 封面、章节页与目录规格
-
-三类页面共用一个写法：先职责，再结果约束；手段自定，只禁失败形态。
-
-- **封面是海报，不是标题卡——职责：3 秒内传达主题气质，完成已定视觉系统（强调色、字体对、图形母题）的首次完整呈现。** 达成方式是让一个主视觉统治画面，常见手段（不限于此）：超大版式字（可跨行/出血，以不裁切为上限）、满版图像 + 标题叠于保护渐变或色块上、大型图形场或超大数字作背景结构。演讲者/日期等信息以小字层级收纳。**禁止**「小图标 + 居中标题 + 居中副标题」三件套。
-- **章节页是封面的简版回声——职责：一眼识别"进入新章"。** 复用封面母题（更克制的用量），超大序号 + 章节标题为主体，与内容页拉开明显视觉差，手段自定；全 deck 章节页外观完全一致，只换序号和标题。
-- **目录页——职责：几秒内看清全场结构（几章、各讲什么、顺序如何）。** 章节序号与标题是绝对主角，说明至多一行，每项高度由内容撑出；编号列表（纵向或两栏）通常最能达成。**禁止**等高空卡片阵列——它摊平层级、稀释结构感。目录样式与章节页呼应。
-
-### 构图原则
-
-- **留白 ≠ 空洞。** 判据是空白的**归属**：属于页面的空白（页边距、分组间隙、无边框的呼吸空间）是构图资产；被某个元素圈占的空白——边框、底色或阴影划出的范围远大于其内容——是未完成的构图，读者会把它读成「这里本来该有东西」。元素的边界应由内容撑出来，而不是由要填的空间决定；画布填不满时，把空间留在元素**之间**，或按「视觉平衡」的出路增密。
-
-- **视觉锚点。** 每页要能回答：视线第一眼落在哪里，为什么是那里。锚点可以是一个大数字、一张图表、一句大字陈述，也可以是并列结构中被刻意加重的一项。所有元素等面积、等字号、等色彩权重的页面，是把第一落点交给了随机——那不是中性，是没做构图决策。
-
-- **视觉平衡。** 视觉重量要在整幅画布上分布均衡，不要全压在画幅一角。**内容只占上半画布、下半大面积空置的页面直接违规。** 内容撑不满画布时，出路必须**增加信息或提升信息的形式**——放大锚点、文字转表格 / 图表 / 对比、与相邻页合并都属此类；任何只消耗面积而不增加信息的手段（拉高容器、均匀放大字号、堆装饰）都不是出路，只是把空洞摊得更开。
-
-- **平行性。** 平行性很重要：章节标题页外观必须一致；页码、眉标等结构件在所有页面位置样式一致；同类页面处理一致。不约束内容主体的版式——那归版式节奏管。
-
-- **版式节奏。** 与平行性互为对偶：平行性守住不变的东西，节奏经营变化的东西。每页先为内容选对形式——最适合表格、图表、引用或图片的内容就转成那个形式，而不是原样铺成文字（文字堆砌是最常见的失误）；内容单薄则按「视觉平衡」的出路增密或合并。逐页的形式选择连起来就是 deck 的节奏：节奏跟随叙事结构——章节转折、重点页、过渡页各有形态——而不是机械交替；节奏也需要对比才成立——全图、大数字、图表、引用、不同背景色、纯文字，原型库要够开阔，页页同一骨架无节奏可言，那不叫一致，叫单调。用版式和可视化把画布用满不是「填充性内容」；凭空编造数据和板块才是。**两条硬配额（只约束内容页）：①采用等宽等高卡片网格版式的**页数**不超过内容页总数的 20%（例：15 页内容页最多 3 页用网格），且任意两页网格页不相邻；②相邻两页禁止同一版式骨架（成组数据页确需连排时在 scratchpad 注明「内容使然」并变化锚点位置）。本文所说「卡片网格」指的是版式结果——3 个以上等宽等高、同样式的信息卡片排成阵列（俗称"麻将块"）；与实现手段无关，`display: grid` 和栅格系统是任何版式都该用的好工具，不在限制之列。**
-
-### 素材与工艺
-
-- **字号与单位。** 使用大号字体（标题至少 48px）。当用户指定具体字号时，默认他们说的是**磅（points）**（PowerPoint/Keynote 的单位）而非像素——用 `px = pt × 1.333` 换算。所以"把标题设成 36pt" → 在 CSS 里设成约 48px。**内容放不下时，按信息损失从小到大依次尝试：换更合适的版式原型 → 拆成两页 → 最后才精炼文案（且只压缩表述、不删信息点；确需删信息点须极其克制）——禁止把字号压到 24px 以下或压缩边距硬塞。**
-
-- **素材来源。** 除非用户要求，绝不使用 emoji。使用 design system / 品牌中的图标、用户提供的图片，或图片生成工具产出的图片。
-
-- **图片呈现。** 务必先查看图片，再决定最佳展示方式。
-  - 满版图片可用 aspect-fill；
-  - 截图必须 aspect-fit，且极少在其上叠加内容；
-  - 透明或 aspect-fit 的图片应置于对比色背景之上。
-
-  在图片上叠加文字时，参照品牌惯常做法：根据你在其他地方看到的样式，酌情使用卡片、保护渐变或模糊效果。
-
-- **图表与数据可视化。** 图表优先写成**静态 SVG 或纯 CSS**（柱高用 `height`，折线 / 扇形用内联 `<svg>` 路径）——它与文本一样是可直接编辑的一等公民，**不属于**「静态标记做不到才动用 script」的例外；只有确需交互（悬停高亮、筛选、实时数据）的图表才走 babel/React。数字之间只要存在能被眼睛读出的关系（趋势、占比、对比、分布），就转成图表，而不是原样铺成文字。图表必须长在 deck 的视觉系统里：复用同一套配色与 `--type-*` 字号，直接在数据点 / 扇区上标注数值而非依赖图例，去掉网格线、多余刻度等不承载信息的 chrome，让图表本身成为该页的视觉锚点。
-
-- **概念可视化（信息图）。** 与数字→图表对偶：**文字之间只要存在结构关系——顺序/流程、因果、层级、循环、包含、对比、矩阵——就转成信息图**（静态 SVG / CSS），而不是 bullet list。原型库：步骤条、时间线、金字塔、同心圆、漏斗、四象限矩阵、环形循环、双栏 VS 对比、路径图。判据：凡是想写 3 条以上并列 bullet 的地方，先问这几条之间是什么关系——**关系本身就是版式**。信息图复用 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 的输出语言 = 用户请求的语言**；请求与素材语言不一致时，以请求语言为准（英文请求 + 中文材料 → 英文 deck，翻译内容）。标题、正文、图表标注、说明全部使用同一语言，禁止混杂。当 deck 为中文时，英文只允许两种情况：专有名词/术语，以及刻意作为视觉元素的眉标或标签（如 "01 / OVERVIEW"）——后者属设计决策，全 deck 用法必须一致。
-
-### 仅凭标题就应能讲清整个故事
-
-通读全部标题应能了解 deck 的整体故事（类似书籍的目录）。标题结构二选一，选定后全程一致：
-
-- **主题式**：名词短语，告诉听众这页讲什么（如「市场格局」「团队结构」「六大常见威胁」）——适合培训、课件、综述类内容。
-- **论点式**：短陈述句，直接给出该页结论（如「亚洲是我们最大的市场」「弱密码是最常被利用的入口」）——适合汇报、路演等有明确主张的内容。
-
-### 避免暴露 AI 生成痕迹的 "AI 味"
-
-避免以下常见的 "AI 味"——它们会暴露这个 deck 是 AI 生成的：
-
-- "宣判式"的标题和要点总结，过度戏剧化/简化，无缘由地制造张力（经典的 "It's not X. It's Y." / 「不是……而是……」），强祈使句，过度重新包装概念，刻意悬念、故作洞察。
-- 中文特有的：排比三连、「重新定义/颠覆」、冒号金句式标题（「安全意识：一场没有终点的战役」）。
-- 总之，AI 倾向于把标题写成演讲者的金句，而非引导听众进入该页内容的**标题**——必须避免！
-
-## 规划步骤
-
-在常规规划之外，务必完成以下步骤：
-
-1. 如果不清楚受众、期望的品牌风格，先提问。
-2. 写出完整的标题序列。选择**一种**语法风格（例如短主题名词短语或简短陈述句），确保适合内容，并用该风格写出每一个标题。回头通读一遍，判断一个人**仅凭标题**能否跟上整个演示的脉络。标题应像书的章节——用直白的语言告诉读者接下来是什么。审阅这些标题并按需修订。将它们写入 scratchpad.md 文件。
-3. 在 scratchpad.md 里为每张幻灯片标注**版式原型**与**视觉锚点**（这页视线的第一落点）。原型必须写出具体名字——常用原型可参考：全幅大字、大数字、图表、信息图、表格、满版图、引用、左右分栏、时间线、卡片网格；不限于这十种，但**每页都要做出并写下明确的版式选择**，写不出名字的页就是还没做构图决策。通读这一列做两项核对：①配额——网格页数 ≤ 内容页总数的 20% 且互不相邻，相邻页不同原型；②节奏是否跟随叙事结构——原型的重复要么是内容使然（如成组的数据页），要么就是没做选择；写不出锚点的页，是内容撑不起一页的信号——回大纲合并或换形式增密。
-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; }`（hero 用于封面主标题与全幅大字页，display 用于目录/章节序号、大数字、引用，均以不裁切为上限）。在 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` 来“居中救空”）。
-
-底部留白的判法（最常见的误判点）：
-
-- 量级在 `--pad-bottom` 上下 → 呼吸空间，合法，保留。
-- 多元素内容页底部空置接近半幅 → 违规，按「视觉平衡」的出路增密。
-- 单主体页（全幅大字、引用、章节页）→ 大留白即其形态，只看主体字号够不够大、构图有无意图。
-
-逐页核对以下各项（不要用「已检查全部通过」一句带过）：
-
-- 字号匹配你的 `--type-*` 体系（而非网页密度）
-- 幻灯片边距匹配你的 `--pad-*` 值（而非网页紧凑间距）
-- 封面符合封面规格三形态之一，不是「图标 + 居中标题」三件套
-- 目录几秒内可读出章节结构，不是等高空卡片阵列
-- 结构件（页码、眉标）全 deck 位置样式一致；章节页彼此外观一致
-- 网格页数 ≤ 内容页总数的 20% 且互不相邻；相邻页版式原型不同
-- 没有使用 accent-border 卡片或 takeaway box
-- 没有内容被画幅边缘裁切、显示不全
-- 没有元素相互压叠、遮挡到读不清
-- 没有被动空洞：边框 / 底色圈出的范围与其内容相称
-- 页面视觉重量在画布上分布均衡；底部留白按开头三条判法检查
-- 每页能指出视觉锚点；版式原型的重复经得起「内容使然还是没做选择」的追问
-- 无指定风格时不是无理由默认的深色科技蓝配色
-- 带动效的元素在缩略图栏和打印视图下完整可见（基础样式即最终态，隐藏态只在 keyframes 的 `from` 里）
+把演示文稿做成单个自包含的 HTML 页面。HTML 是输出载体，但设计判断按 PPT 来做：固定画幅、强叙事、可投影 / 可异步阅读、每页只承担一个清楚的沟通任务。
+
+把自己当成演示文稿设计师，不是网页开发者：像顾问、分析师、高管准备董事会材料那样思考——清晰、叙事流、后排可读。每一页都同时是版式设计和文案写作。开始落 HTML 前，先写大纲；好的大纲本身就是一次叙事结构训练。
+
+## 信息密度与结构饱满度
+
+不要先把 deck 归类成预设模式，也不要用单个标签决定页面长相。根据受众、演示方式、内容复杂度和页面任务确定信息密度，先判断用户目标、材料形态和读者场景，再为每页设计具体的信息结构。好的 deck 不是字越少越高级，也不是字越多越专业，而是**结构饱满、层级清楚、文字克制、证据可扫读**。核心页可以更聚焦，分析与参考页可以更完整。
+
+同时避开两个失败极端：
+
+- **欠填充**：主体撑不起页面，只靠放大标题、拉高卡片、拉开列距、把来源压到底部或增加空白来撑版面。
+- **过填充**：页面被长句和大段正文塞满，缺少图、表、矩阵、路径、标注、层级和视觉转译。
+
+页面应该被图、表、矩阵、KPI strip、路径图、截图标注、对比框架或稳定卡片 scaffold 撑住，而不是被大字号正文撑满。图表如果是本页主要证据，就必须成为主视觉，不是塞在角落里的小配件。经验标尺：普通内容页通常 80-160 个中文字符 / 英文数字词就足够；复杂矩阵、前后对比、案例拆解页可以到 200+，但必须用表格或分层结构承载；转场、封面、结尾页可以低文字密度。超过约 180 个可读文本单位时，先把散文压成短标签、表格单元、图表注释或拆页，而不是继续堆句子。
+
+不要让页面滚动、溢出、重叠或用过小字体。放不下时先重构信息：合并相邻弱页、把散文改成表格 / 矩阵 / 时间线 / 注释图、压缩非关键留白；仍放不下再拆页。**不要把整份文档直接贴进幻灯片**——这是最常见的失败模式。落 plan 时就想清楚：哪些内容更适合做成表格、图表、流程、引用页或图片页。每页都要预留安全底边：页脚、页码、来源和正文之间必须有明确间距，主体元素不能贴到画布底部或被页面边界裁掉。
+
+## 叙事、标题与 Storyboard
+
+- 先写完整标题序列放进 `scratchpad.md`。只读标题就应能看懂整份 deck 的逻辑（像书的目录）。检查是否形成清楚路径：背景 → 问题 → 洞察 → 方案 → 证据 → 下一步。
+- 紧接着写 storyboard。为每页记录：本页阅读动作、关键判断、可用证据、信息关系、表达结构、是否足以独立成页、与前后页的节奏关系。不要给页面贴固定类型标签；用自然语言说明这一页为什么存在。
+- 选定一种标题语法并全程一致：要么名词短语（"市场机会""产品架构"），要么简短判断句（"新用户增长主要来自自然流量"）。
+- 大字号标题需要换行时，按语义短语断行，避免单字成行、标点出现在行首或拆开固定短语；可通过调整文本区、字号或断行位置修正失衡。
+- 每页正文只服务本页标题，不塞旁支。封面、章节页、转场页、结尾页也要服务故事，不做纯装饰。
+- 文字要有明确功能：保留承担信息、导航、出处或真实品牌识别作用的文字；不为营造风格或填补空间而编造、重复无信息价值的辅助文字。
+
+避免这些"AI 味"标题（它们会暴露 deck 是 AI 生成的）——标题的任务是**定位页面、推进叙事**，不是替演讲者甩结论 / 喊 punchline：
+
+- "不是 X，而是 Y"式过度反转。
+- "关键时刻""魔法时刻"式空泛或故作深刻。
+- 过度夸张的行动号召、为制造张力而制造张力。
+- 每页固定一个 takeaway 盒子，导致标题和正文重复。
+
+## 页面规划与节奏
+
+页面由材料和叙事需要长出来，不从预设模板或页型清单里挑。先在 storyboard 中写明每页的叙事作用、核心内容关系、视觉主角和需要承载的素材，再看信息关系决定版式：
+
+- 并列 / 分类：用矩阵、分组卡片、标签云或多列清单，保持同层级内容可比较。
+- 前后变化 / 方案对比：用 before-after、对照矩阵、差异表、评分表或坐标图。
+- 过程 / 时间 / 执行动作：用时间线、泳道、步骤图、甘特式条带或 checklist。
+- 因果 / 转化 / 漏斗：用链路图、漏斗、树状拆解、输入输出图或指标归因。
+- 层级 / 系统 / 架构：用分层结构、系统图、地图、嵌套框或模块关系图。
+- 数据 / 证据集合：用 KPI strip、图表、表格、标注数字和口径说明，而不是只摆大数字。
+- 案例 / 场景：用情境、机制、动作、结果的组合结构；可以加入真实图片、截图或局部标注。
+- 选择 / 决策 / 下一步：用决策矩阵、优先级地图、路线图、风险清单或行动表。
+
+根据叙事阶段和整套缩略图轮廓安排节奏变化。同层级的并列内容保持平行 scaffold，利于跨页比较；叙事功能或内容关系不同但缩略图轮廓高度相似时，应重新选择构图。变化来自信息结构，不靠堆装饰。
+
+## 内容组织与版式策略
+deck 每页先判断它要让观众完成什么阅读动作：抓结论、看证据、比较差异、理解过程、记住模型、看到风险、做选择，还是进入下一章节。版式、文字、图形和动效都只是表达手段，选择最能讲清这一页的组合。
+- 同时判断内容关系、视觉主角和信息量，再决定构图。可以用图片、图表、关键数字、结构图或核心结论建立视觉中心，其余元素为它服务；不要默认把信息拆成若干大小相近的卡片。
+- 主动做视觉转译：定量数据适合用趋势、对比、分布或构成图表达；流程、因果、层级、系统和时间关系适合用流程图、关系图、矩阵、时间线或信息图表达；产品、人物、地点和场景适合用有信息价值的图片表达。不要把适合可视化的信息重新写成一组文字卡片。图表和图示应表达明确结论，没有可靠数据时不虚构定量图表。
+- 数据页先确定主图表。标题若在讲规模增长、区域分布、结构占比、趋势轨迹、驱动因素或方案对比，主图表 / 主表格必须成为有效视觉中心；KPI strip、说明文字、来源和注释只能辅助它。不要用固定宽度比例机械判断好坏，重点检查图表周围是否出现大块无功能留白，或图表是否被旁边的文字列表、脚注、装饰和空白压成小配件。可用全宽图、纵向大图、图表 + 侧栏、图表 + 注释带、矩阵或小倍数图，选择能让主体区域被有效利用的构图。
+- 让内容容量决定版式。布局应适应真实信息量：内容少时放大核心表达并重组构图，可升格为观点页、图解页、图片页或并入相邻页；内容多时建立层级、图解、表格、矩阵或拆页。不要把内容硬塞进固定卡片，也不要让小块内容漂浮在大片空白中。
+- 先算垂直预算再排纵向内容。表格、时间线、融资里程碑、排行榜、横向条形图、评分条和 checklist 都要按“标题区 + KPI 区 + 主体行数 × 行高 + 组间距 + 来源页脚安全区”估算高度。超过可用高度时减少行数、压缩文案、改成两列 / 矩阵 / 小倍数图，或拆页；不要让最后几行延伸到页脚或画布外。
+- 根据当前页内容现场生成结构，不局限于常见页型。可以保留强文字页，也可以把材料转成模型图、关系图、流程、对比矩阵、时间线、象限、分层结构、地图、系统图、路径图、图表注释、截图标注或视觉隐喻；还可以把重要句子放大成观点页。示例只是启发，不是清单。
+- 同一章节内可以有连续叙事，但每页的结构不必一样。核心页给足面积和视觉重量，支撑页可以更密集；重要概念可以用图形和标注解释，也可以用排版、引用、数字、对照文本或图文组合解释。
+- 单页可以承载“小型演示过程”：先出现结论，再让支撑内容逐步显现，最后高亮关键判断。支撑内容可以是文字、数字、图形、数据、截图或关系结构；是否使用动效由表达目的决定。
+- 如果一页只有少量概念，不要机械铺成几张卡片。先判断概念之间有没有关系：并列、递进、因果、闭环、漏斗、分层、坐标、路径、前后对比或组合模型。关系明确时可以画出来；关系不明确时，可以改成更有力量的文字观点页、引用页，或合并到相邻页。
+- 如果一页出现“少量文字 + 大面积固定高度卡片 / 巨大页脚空白”，视为欠填充，不要交付。优先补上结构性证据（口径、来源、对比基准、趋势、影响、风险、下一步），但表达要短：用数字、标签、表格单元、图表注释或路径节点，不要把每个证据都扩成一整句。没有足够内容支撑独立成页时，合并到相邻页。
+- 如果一页出现“两列大段文字 + 底部 KPI 条 / 来源脚注”的组合，也视为过密且缺少设计转译。应改成对比矩阵、雷达/坐标、产品拆解图、流程图、截图标注、分层卡片或拆成两页；不要把竞品分析、案例复盘、风险应对写成左右两块说明书。
+- 卡片高度应由内容和网格共同决定，不要用等高大卡片撑满版面。三栏卡片里每张只有 1-2 段短文时，改用横向流程、对照矩阵、双层信息卡或紧凑清单；每张卡如果超过 4-5 行正文，优先压缩成标签 / 表格 / 分组小项。只有内容确实接近等量时才使用大面积等高卡片。
+- 版式变化来自内容关系，不来自凑组件。不要为了“丰富”而加无依据内容、无意义图标或装饰图形；图形、图片和动效只有在能帮助观众理解时才使用。
+
+## 版式系统（写第一页前先定）
+
+- 用 CSS 变量定义字号 / 间距，放在 `<head>` 的 `<style>` 里，**先于任何 slide**。这让整份 deck 改一个数（直接改变量，或用 Tweaks 滑块绑同一变量）就能统一缩放，slide 本体保持无脚本的静态 HTML。下面只是一套适中起点；实际要根据 storyboard 里的信息结构微调，不要所有 deck 都套同一组大字号 / 大留白参数。1920×1080 起点：
+  ```css
+  :root {
+    --type-title: 52px; --type-subtitle: 36px; --type-body: 28px; --type-small: 24px;
+    --pad-top: 72px; --pad-bottom: 56px; --pad-x: 84px;
+    --gap-title: 30px; --gap-item: 18px;
+  }
+  ```
+  1280×720 时整体 ×0.67。每个 font-size 都用 `--type-*`，每个 padding / gap 都用 `--pad-*` / `--gap-*`。`--pad-bottom` 是结构性的底部呼吸空间，不是空白；如果底部只是空着，应把空间交还给正文、图表、注释或合并页。
+- 每页先定义一个安全内容区，而不是让元素各自漂浮。推荐在 slide 内使用一个 `.content` / `.layout` 容器承载主体，尺寸由 `inset: var(--pad-top) var(--pad-x) var(--pad-bottom)` 或等价 padding 控制；主体布局用 CSS grid / flex 的正常流、`minmax(0, 1fr)`、`min-height: 0` 和明确 gap 管理空间。只有装饰、页码、来源这类固定元素才适合绝对定位；表格、图表、列表、时间线不要用 absolute bottom / fixed height 去硬塞。
+- 网页默认（14-16px 正文、48-72px 边距）对投影太小。标题 ≥ 48px，正文 / 注释**不得小于 24px**（验证器会对 < 24px 抛错）。用户说字号一般指 pt，按 PowerPoint / Keynote 换算：`px = pt × 1.333`（"标题 36pt" → CSS 设 ~48px）。
+- 建立稳定布局锚点：标题、章节号、页码、来源、图表、主视觉和关键数字的位置不要随机漂移。规律来自章节、信息关系和跨页比较需要，不来自预设标签。
+- 同一信息关系的页面要保持平行 scaffold，方便观众比较；不同信息关系再负责制造节奏。
+
+## 视觉设计
+
+视觉服务演示场景，不是网页首页。
+
+- **主题与风格**：根据主题、受众和演示场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；不把“干净、专业”默认等同于大量留白或通用企业风。
+- **明暗按需求选择**：根据品牌 / 主题 / 图片素材 / 演示场景选择浅色、暗色或混合背景。无论选择哪种，都要保证投影、截图和后排阅读的对比度。明暗切换应落在叙事节点上（章节转换、关键强调），不要无来由地跳变。
+- **字体与排版角色**：根据主题建立标题、正文、数字 / 数据和注释的排版角色，角色可以共享字体。综合使用字体气质、字重、字宽、行长、语义换行、数字样式和文字位置形成层级，而不只是改变字号或统一使用粗黑体；展示文字可以有个性，正文必须稳定可读。
+- 图片先判断内容和用途：摄影 / 氛围图可满版裁切；截图、图表、产品界面、架构图必须完整展示（aspect-fit），不能裁掉关键边界或文字；透明图 / 细线图放到有对比的底色上。图上压字用品牌常见方式保护可读性（遮罩、渐变、模糊或文字容器）。
+- 视觉要有节奏变化：全图页、大数字页、表格页、引用页、流程页、文字页交替出现；不要整套都是同一种卡片。也不要每页硬加描边卡片、固定结论框或装饰分割线——只有内容需要分组时才用容器。
+- 扁平基线：好的 deck 不依赖阴影和悬浮卡片堆叠。优先用全页背景、色带、分隔线、编号、表格网格、图片裁切、对比色块和尺度差建立层次。只有在需要表达真实物件、票券、照片或舞台层次时才少量使用阴影。
+- 不用 emoji、不临时手绘复杂假图；优先用用户素材、品牌资产、图标库或真实图片。
+- **空间重心**：页面元素应形成完整构图：留白有明确作用，独立元素与主体有可感知的关系，多栏内容在视觉重量和内容关系上协调。内容可以集中在上方并保留底部呼吸空间，这通常是正确的 slide 构图；但留白必须均匀、有意、有下界。内容页主内容应占版心高度约 2/3 以上；同一页一处大空、一处拥挤要重排。允许不对称构图，不要求左右元素数量、尺寸完全相等；通过面积、色彩、留白、位置和视觉重量形成平衡，避免机械平分页面。双栏 / 多栏失衡时改不对称栅格、调整主次关系或并回单栏。内容不足以独立成页时，合并、重构或升格为确有价值的观点页，不单纯放大数字、卡片或增加留白撑页。
+- **信息重心**：主内容区应显得有事可读，来源、页码和装饰不能成为主要视觉重量；证据说明应尽量靠近对应内容，避免制造无意义的纵向空洞。
+- **容量与边界**：重复排列卡片、指标、步骤或图表前，先根据条目数量、文字长度、间距和可用区域判断能否容纳。空间不足时调整构图、压缩或合并信息、减少非必要元素或拆页，不得依靠 `overflow: hidden` 裁掉内容。最终按实际渲染尺寸检查完整元素和元素组是否仍在页面安全区域内。
+- **底部安全区**：正文、图表、表格、条形图和列表必须整体落在安全区域内，和页脚 / 来源 / 页码保持可感知间距。不要把条形图最后一行、表格最后一行或长标签压到页面底边；不要用 `position:absolute` 把元素硬钉在底部来“刚好塞下”。如果底部空间不足，优先减少行数、合并组、拆页或重新选择横向构图。
+- **图表尺度**：图表、表格、结构图和截图标注要按“可阅读的分析对象”设计，不按“装饰素材”缩小。主图表应形成明确视觉中心，并有足够轴线、标签、图例和注释空间；如果图表周围留白过多，优先放大图表、增加与图表直接相关的标注 / 口径 / 对比基准，或重排为更紧凑的图表 + 侧栏 / 注释带结构。如果放大后其他信息放不下，先减少旁支、改成侧栏 / 脚注 / 下一页，而不是缩小主图表。多个小图同时出现时，必须有一个主图或改为矩阵 / 表格，避免所有图都小而轻。
+- **图表优先**：工作汇报、客户案例、趋势观察、竞品分析这类 deck，连续 2-3 页纯文本卡片后必须切换到图表 / 表格 / 矩阵 / 图片标注 / 流程或 KPI strip。文本卡片可以存在，但不能成为整套 deck 的主要填充方式。
+
+## 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>
+  ```
+- 交付前必须做一次渲染级边界审计，而不是只看截图。打开生成的 HTML 后，逐页检查每个 slide 的 `section[data-label]` 及其正文元素的 `getBoundingClientRect()`：任何可见文字、图表、表格、图片、图例、数值标签、来源、页码或父级元素组，只要超出 slide 边界、进入页脚安全区、互相重叠或被裁切，就必须回到版式层面重排。不要把失败元素简单设成 `overflow:hidden`、缩小到不可读、或用负 margin / absolute bottom 硬塞。
+
+### slide 正文写成静态 HTML，不要用脚本生成
+
+这条最影响用户体验，理解**为什么**再执行：当一页正文是 `<deck-stage>` 里的普通静态标记时，用户在编辑态点任意标题 / 段落就能直接改字，编辑器会把改动即时 splice 回源文件；一旦这页由 `<script type="text/babel">`、React 组件或"遍历 JS 数组"渲染，这条直改路径就断了——每次微调都要通过 chat message 往返到你这里，更慢、也更难让用户自己打磨 deck。所以凡是静态页能表达的（文字、布局、背景、图片、表格），就把字面元素写进 HTML、用 CSS 定样式；只有当这页**真的**需要静态标记给不了的行为（交互图表、真实 demo、真实状态）才引入 babel / React 或额外 `<script>`。同样的渲染结果，静态版永远优先，因为它可直接编辑。
+
+两个细节保住"可直接编辑"：
+
+- 每段可编辑文字放在自己的叶子节点里——把"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，无溢出 / 重叠 / 裁切；不仅检查文字，也检查卡片、图表、图片及其父级元素组的完整边界；字号符合投影阅读（正文没有小到像网页）。
+- 构图完整：留白与主体关系明确，没有孤立漂浮、局部拥挤或失衡的多栏布局。
+- 边界溢出检查：逐页确认所有文本、表格行、条形图、图例、数值标签、来源和页码都在画布安全区内；元素组的底边不得低于页脚安全线。凡是需要 `overflow: hidden` 才不露馅、或最后一行贴底 / 被裁切 / 与页脚碰撞，都必须重排。
+- 实测边界检查：以浏览器实际渲染结果为准检查 bounding box，不以设计意图或静态 CSS 推断为准。每页所有可见元素的 `top/left/right/bottom` 都必须落在 slide 可视区域内；主要内容还要避开页脚 / 页码 / 来源所在的安全带。若任一元素超界、被父容器裁切、被 transform 推出画面、或与固定页脚碰撞，不允许交付。
+- 欠填充检查：主内容视觉占用明显低于页面可用区域 60%，或卡片内部空白超过约 45%，或一屏只有 2-4 个孤立数字 / 短段落时，必须重构；不能用放大卡片、拉开列距、把来源压到底部来撑页。
+- 过密检查：正文如果主要由长句组成、单页超过约 180-220 个可读文本单位、或单个卡片连续 5 行以上正文，必须先压缩文案并转成表格 / 矩阵 / 图表注释 / 视觉节点；不要通过缩小字体硬塞。
+- 信息密度检查：每页应包含结论、证据和上下文中的至少两类，但证据可以是数字、图、表、来源、对比基准、趋势箭头或截图标注，不要求都写成句子。指标不能只有大数字，还要有口径 / 来源 / 对比基准 / 趋势 / 影响说明中的必要项。流程不能只有“动作 / 结果”两段短文塞进大卡片，优先用表格、泳道、时间线或 checklist。
+- 图表主视觉检查：如果本页结论依赖趋势、对比、构成、分布或表格证据，主图表 / 主表格是否形成明确视觉中心；图表周围是否有大块无功能留白；KPI strip、文字列表、来源和装饰不得比主图表更抢视觉重量。若图表看起来像角落里的小配件，必须放大、补充相关标注或重排构图。
+- 内容容量检查：布局是否适应真实信息量；内容少时有没有重组为更强核心表达、图解或合并页，内容多时有没有建立层级、图解、表格或拆页；不能硬塞进固定卡片，也不能让小块内容漂浮在大片空白中。
+- 页码、来源和固定页脚不与正文争用空间；逐页检查文字、图片和固定元素没有遮挡或碰撞。
+- 留白与平衡：同一页没有一处大空、一处拥挤；内容页主内容占版心高度约 2/3 以上；允许不对称，但左右 / 多栏应通过面积、色彩、留白、位置和视觉重量取得平衡，避免机械平分。
+- 只读标题能讲通故事；标题语法全程一致，没有 punchline / takeaway 盒子。
+- 已建立 storyboard，并从整套缩略图检查页面轮廓；不同内容关系没有被连续压成相似的卡片网格或单一上下布局。
+- 转场页推动叙事，而不是只做装饰。
+- 页面既没有靠留白撑场，也没有变成长文档截图。
+- 同类页面布局、标题位置、页码、章节标识平行一致；图片没被不合理拉伸，截图 / 图表完整展示。
+- 需要跨页比较的成组内容使用了稳定 scaffold。
+- slide 正文是静态可编辑 HTML，没用脚本循环生成；`data-label`、speaker-notes、打印分页完整。
+- deck-stage 外壳、导航、页码来自 starter component，没有手写重复实现。