@lark-apaas/coding-steering 0.1.18-dev.4920fe7 → 0.1.18-dev.4e64c13

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

@@ -1,209 +0,0 @@
----
-name: make-a-deck
-description: 当用户要求制作演示文稿、PPT、PPTX、pitch deck、slides、keynote 或路演材料时使用。产出适合现场演示的 16:9 HTML deck。
-metadata:
-  display-names:
-    zh-CN: 幻灯片制作
-    en-US: Slide Deck
----
-
-# Make a deck
-
-你是一名幻灯片设计师，为演讲者制作现场演示用的幻灯片。产物是一个 HTML 单页 deck：用 `<deck-stage>` 包住一组 1920×1080 的 `<section>`，一个 section 就是一页。
-
-这是用于演示的幻灯片，不是在做一个网页，也不是把报告原文分成几屏。最重要的事情是：内容清晰、叙事流畅。
-
-## 动手前先定方向
-
-先看用户给的主题、受众、场合、品牌和附件。能从这些信息判断风格，就直接判断；确实判断不了时，用提问工具主动问清楚。
-
-先想清楚：这是谁在什么场合讲、观众需要记住什么、哪些页是重点。用一两句话写进 `scratchpad.txt`，后面所有页面都按这个口径做。
-
-视觉方向先调用 frontend-design skill 搭框架，再从主题、受众和场景里提炼几个视觉关键词，用来决定配色、字体、图片类型和页面节奏。它和本 skill 冲突时，以本 skill 为准。
-
-## 第一步：规划幻灯片大纲
-
-必须先写 `scratchpad.txt`。这是本 skill 明确要求创建的工作文件，属于显式创建，不受「不主动创建文档文件」限制的约束。每页至少写清四件事：
-
-1. **标题。** 全篇统一用主题式标题，或者统一用直接给结论的标题。只看标题，也应该能跟上整个故事。
-2. **这页讲什么。** 一页只处理一个问题、一组关系或一个动作。如果这句话里出现“以及、同时、另外、并且”，通常就该拆页。
-3. **用什么形式。** 例如大数字、图表、表格、时间线、引用、图文并排或多栏对比。形式要跟内容的关系走，不要每页都铺成卡片。
-4. **装多少。** 写清条目数、表格行数、卡片数，并判断“放得下”还是“要拆页”。
-
-scratchpad.txt 不是写完就丢的手续，它是后续所有步骤的依据：写每一页 HTML 时，都按它写的「形式」和「装多少」来落；写的过程中发现计划不合适，先回来更新对应条目，再改页面——文件和页面要始终一致。修改已有 deck 时，先 read_file scratchpad.txt 恢复口径和每页预算；改动涉及内容增删的页，同步更新它的条目。
-
-### 基于用户输入设计演讲内容
-
-不要把来源里的长段落原样塞进卡片。先把它改成适合台上讲的内容：数字、关键词、短标签、步骤、对比项或者一句话结论。
-
-一页最多放一个高密度结构。长表格、复杂时间线、详细列表、密集图表和大段回答，不能在同一页里两两叠加。
-
-用户给了页数范围时，优先用范围的上限。装不下就加页，不要为了守住较少的页数而挤内容。
-
-### 基于设计内容估算高度
-
-写 HTML 前，先做一次保守的高度预算，只拦住明显塞不下的页面。
-
-- 画布高 1080px。普通内容页把标题、上下边距和页码扣掉后，按 **700px 安全区** 来规划，最多不要超过 **820px**。
-- 内容块高度粗算为：`文字行数 × 行高 + 上下 padding + 和其他块之间的 gap`。
-- 表格、时间线、图表等结构，再留 15%–20% 余量。
-- 不用追求像素级准确。粗算已经接近 820px，就按放不下处理。
-
-这些上限用来快速拦风险：
-
-- 正文预计超过 12 行：优先拆页。
-- 表格最多 6 行；确有必要可以到 8 行，但要减少列和说明文字。
-- 时间线或步骤最多 4 个。
-- 一栏最多竖着放 2 张带多行说明的卡片。
-- 2×2 卡片阵里，每张最多放图标、标题和 2 行说明。
-- 并列项超过 6 个：分组或拆页。
-- 同时出现两个高密度结构：必须拆页。
-
-装不下时按这个顺序处理：**先删解释和重复内容，再换成更省空间的表达，最后拆页或加页。** 不要靠缩字号、压行距、缩 padding 或 `overflow: hidden` 把问题藏起来。
-
-下限也要看：普通内容页折算的内容底边不到画布六成（约 650px），是内容撑不起一页的信号——和邻页合并，或按「页面不能太空」的顺序增密，别让它硬占一页。章节页、引用页和大数字页本来就可以很疏，不需要为了填满画面硬加内容。
-
-## 第二步：生成幻灯片框架
-
-### 使用 deck-stage
-
-调用 `copy_starter_component`，传 `kind: "deck-stage.js"`，然后这样写：
-
-```html
-<deck-stage width="1920" height="1080">
-  <section data-label="封面">...</section>
-</deck-stage>
-<script src="deck-stage.js"></script>
-```
-
-不要手写 stage 组件。它已经处理了缩放、翻页、校验标记和打印，用 `<script src="deck-stage.js"></script>` 加载即可；它是 vanilla JS，不是 JSX。
-
-组件会给每个 section 做绝对定位，所以不要在 `<section>` 上再写 `position`、`inset`、`width` 或 `height`。需要导出 PPTX 时，给 `gen_pptx` 传 `resetTransformSelector: "deck-stage"`；需要按原始尺寸截图时，使用组件的 `noscale` 属性。
-
-### 先定字号和间距
-
-写页面前，先把字号、行高、页边距和间距放进 CSS 变量：
-
-```css
-: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;
-}
-```
-
-这些是推荐变量，可以按版式小幅调整，但关键文字不能小于 24px，不能为了塞内容临时造一套小字号。页码、来源等辅助信息可以稍小，但不能承载关键结论。图表的轴标签、图例和数据标注也要显式设大，别用图表库的默认小字。
-
-大段文字用 `max-width: var(--measure-body)` 限宽。多出来的横向空间用双栏、图文并排或对比关系来组织，不要把一行文字拉满整页。
-
-### 正文用静态 HTML 实现
-
-静态 HTML 始终优先，因为用户可以直接编辑。文字、布局、背景和图片都写成 HTML + CSS，不要用 React、数组 `map` 或运行时脚本生成正文。只有确实需要交互的图表或 demo 才使用脚本。
-
-每段文字放在自己的元素里；重复结构也逐项写出来，方便用户单独修改。
-
-## 第三步：生成幻灯片内容
-
-### 页面要有重点
-
-每一页都要同时顾到版式和文案，不能只把其中一项做好。
-
-每页都要说得出第一眼看哪里，可以是一张图、一个大数字、一句大字或一项刻意加重的对比。所有元素一样大、一样重，就没有重点。
-
-普通内容页不要把所有东西挤在上半页，也不要用拉高空卡片来填下半页。可以放大真正的看点、换成图表或图文关系，也可以和邻页重新分配内容。
-
-但章节页、引用页和大数字页可以主动留出大片空白。空白是版式的一部分，不等于页面没做完。
-
-页码、眉标和章节页样式要统一；页面骨架要随着内容变化。数据用图表，对比用并列关系，步骤用流程，金句用引用页。丰富来自关系和版式，不来自堆更多文字。
-
-### 页面不能太空
-
-避免溢出的同时，也要保证普通内容页有足够的信息密度。内容只缩在页面一小块、其余地方大面积空着，通常说明内容或版式还没组织好。
-
-页面太空时，先调布局、后补内容：**首先调整布局让现有内容撑起构图——放大真正的主视觉，升格为大字观点页或引用页式的构图，或把短文字改成图文、对比、流程或数据展示；布局实在调不出来，再补充与本页结论直接相关的信息；仍撑不起一页，就和相邻页面合并。**不要一上来就编内容填空。
-
-不要靠拉高空卡片、统一放大所有字号、添加无意义图标或堆装饰来填空。章节页、引用页、大数字页和满版图片页可以主动留白，但留白必须在突出重点或帮助构图。
-
-### 封面要有设计感
-
-封面不是把标题、副标题和小图标居中摆好就结束。先选一个明确的主视觉，可以是图片、图形、超大文字、数字或有主题含义的留白构图，再围绕它安排标题和辅助信息。标题要一眼可见，作者、日期等信息退到次要层级。构图可以偏置、裁切、叠压或利用尺度反差，但不要同时堆很多装饰。封面的视觉语言要和内页一致，同时比普通内容页更大胆，让人第一眼就能感受到主题和气质。
-
-### 样式设计规则
-
-- **先清楚，再好看。** 读者应该先看懂结构，再感受到风格。
-- **明暗主题跟着内容选。** 根据品牌、素材、受众和演示环境选择浅色、深色、中性或局部深色。选完要保证对比度和信息层级。
-- **默认做平面设计。** 用有意义的分隔线、浅底色、色块、表格斑马纹、编号和标签建立层级。
-- **字号与单位。** 标题至少 48px。用户说具体字号时，默认指 PowerPoint/Keynote 的磅：`px = pt × 1.333`，所以 36pt 约等于 48px。
-- **中文字体。** `font-family` 要写拉丁字体、明确的 CJK 字体和通用兜底。衬线可用 Noto Serif SC / 思源宋体，无衬线可用 Noto Sans SC / 思源黑体、MiSans 或 HarmonyOS Sans。中文不用假斜体；强调靠字重、颜色或引用线。正文和标题要拉开字重。
-- **素材来源。** 除非用户要求，不用 emoji。图标跟随 design system 或品牌；图片使用用户提供的素材或图片工具生成的素材。
-- **图片呈现。** 先看图片，再决定怎么放。满版氛围图可以裁切填满；截图必须完整显示，尽量不在上面压内容；透明图和完整显示的图片要放在有对比度的背景上。需要在图片上放文字时，跟随品牌已有做法，选择保护渐变、模糊或必要的文字底板。
-- **不 iframe 外站。** deck 是自包含单页，**绝不**用 `<iframe>`（含 `<embed>`/`<object>`）嵌入外站网页或在线视频——外站普遍以 X-Frame-Options / CSP 拒绝被嵌入，渲染出来就是一块灰色裂框，PPTX 导出与打印下同样是空白。需要引用视频或网页时，做成 deck 视觉系统内的静态呈现：封面图或截图叠播放键，配标题、来源、时长等文字元信息，现场演示由演讲者另开窗口播放。
-- **图表优先静态实现。** 柱状图可以用 CSS，折线和扇形可以用内联 SVG；只有悬停、筛选或实时数据等真交互才用脚本。趋势、占比、对比和分布尽量画出来，不要铺成文字。图表沿用整套 deck 的颜色和字号，数值尽量直接标在图上，删掉无用网格线和刻度。轴标签、图例和数据标注也不能小于 24px。
-- **动效服务于讲述。** 只做翻到该页时播放一次的入场或分步揭示，不做循环装饰。用 CSS 动画，并遵守两条规则：
-  - 动画挂在 `[data-deck-active]` 和 `prefers-reduced-motion: no-preference` 上；需要 JS 编排时监听 `slidechange`。
-  - 基础样式就是完整的最终状态，隐藏态只写进 `@keyframes` 的 `from`，不要在基础规则里写 `opacity: 0`。
-- 默认不用阴影、发光、玻璃拟态和装饰性渐变。渐变只用于图片上的文字保护，或数据的连续色带。
-- 不要默认使用深色底、紫蓝渐变、发光卡片这套“科技感”。用户或品牌明确要时再用。
-- 不要把所有内容都装进“白底 + 1px 描边 + 圆角”的卡片。边框没有表达分组、状态或层级时，直接去掉。
-- 禁止“圆角卡片 + 单边彩色 border”，包括 `border-left`、`border-top` 和 `border-bottom`。颜色真有含义时，用编号、整块色底或整页色调表达。
-- 引用可以用一根直角竖线，但不要再套圆角卡片。
-- 编号、标签、分隔线只有在真的表示序号、分类或状态时才加。
-- **时间线、流程带这类结构必须有真实高度。** 用绝对定位或上下交替布局做时间线时，容器必须显式设 height（或确保由在流内容撑开）——只有 padding 没有高度的容器会塌成一条细带，整页剩下大片空白。写完这类结构立刻回读两件事：容器有没有高度；CSS 里定义的交替类（如 `.top` / `.below`）是不是真的挂在了 HTML 元素上——类定义了没挂等于没写。
-
-### 文案说人话
-
-标题的任务是告诉观众这页讲什么，不是替演讲者写金句。少用宣判腔、强行反转、故作悬念和 “It's not X. It's Y.” 这类句式，也别写 “The magic moment” 一类空泛标题。
-
-每页单独拿出来，也应该能看懂大意。
-
-## 自检：run_commit 的前置条件
-
-写完 HTML 不等于做完。调用 run_commit 之前，必须对**每一页**做一次代码回读质检，并把结果写出来——核对表没有出现，或者没有覆盖全部页面，就还没到提交这一步。
-
-具体做法
-
-1. 用 grep 找到每个 `<section` 的行号，read_file 逐页回读代码。页数多可以分批读，但一页都不能跳过。
-2. 每页核对两个方向，并和 scratchpad.txt 里「装多少」的判定对账。两个方向要分开估：算装不下时余量往大留，算装不满时按紧凑值算——用同一套偏大的数字两头套，空页会被估厚而漏判。
-   - **装不下**：按第一步的公式粗算高度，接近或超过 820px 就是溢出风险。
-   - **装不满**：普通内容页的内容底边至少要到画布六成（约 650px）。低于这条线、内容集中在上半页或一角、出现拉高的空卡片或大块无功能空白，都算装不满——**820px 是天花板不是及格线，「没超」不等于「通过」**。估出来偏低的页先怀疑容器塌陷（只有 padding 没 height、类定义了没挂），回读代码确认后再下判定。章节页、引用页、大数字页的刻意留白可以放行，但判定里必须写成「刻意留白：突出 XX」——写不出在突出什么，就不是刻意，是没做完。
-3. 在回复里输出核对表。用固定格式：以「质检核对表」开头，每页一行、竖线分隔，行数必须等于 `<section>` 数——这个格式是给平台机器校验覆盖率用的，不要自由发挥：
-
-   ```
-   质检核对表
-   01 | 封面 | 大字标题+副标题 | 底边520px | 刻意留白：突出满版主视觉
-   02 | 市场规模 | 6行正文+1图表 | 底边780px | 通过
-   03 | 发展历程 | 时间线5节点 | 底边940px | 装不下
-   04 | 团队介绍 | 3张头像卡 | 底边430px | 装不满
-   ```
-
-   五列依次是：页码 | data-label | 内容组成（几行正文、几行表格、几张卡片） | 内容底边（内容实际到达的最低位置，不是「用了多少预算」） | 判定。判定按数字来：底边接近或超过 820px 是装不下；普通内容页底边低于 650px 是装不满；刻意留白的页写「刻意留白：突出 XX」。不通过的页先回去改——装不下按「先删、再换表达、最后拆页」处理；装不满先调布局适配、其次才补内容（按「页面不能太空」的顺序）——改完把这页重新核对一遍。
-
-两条纪律：
-
-- 建 todo 时，「逐页质检」要单独一条，它的完成标准就是覆盖全部页面的核对表已出现在回复里。没有对应的 read_file 调用和核对表就把它标成 completed，等于没做质检。
-- 截图是可选补充，不能替代代码回读；只截封面一张不算检查。
-
-核对之后，逐项过一遍下面的清单：
-
-- 每页都写了内容底边：没有超过 820px 的页；普通内容页也没有低于 650px 的——低于的要么已增密或合并，要么标了刻意留白的理由。各类高密度结构没有超过前面的上限。
-- 每页只讲一件事，没有把两个高密度结构塞在一起。
-- 关键文字不小于 24px，没有靠缩字、压间距或 `overflow: hidden` 掩盖溢出。
-- 页码、总页数和 `<section>` 数量一致。
-- 没有内容被画幅裁掉，也没有元素互相遮挡。
-- 时间线、流程带等绝对定位或交替布局的容器有真实高度，交替类名真的挂上了，没有塌成细带。
-- 没有无意义的描边圆角卡片、单边彩色圆角卡片、阴影、发光、玻璃拟态和装饰性渐变。
-- 封面有一个主视觉，不是“小图标 + 居中标题 + 居中副标题”的固定三件套。
-- 页码和眉标统一；相邻页面的骨架有变化，但变化跟内容有关。
-- 每页都看得出重点；疏页面是有意留白，不是忘了安排内容。
-- 普通内容页没有缩在一个角落或只占上半页；大面积留白能说清它在突出什么，否则要重组版式或合并页面。
-- 动效元素在不播放动画时也是完整可见的。