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

package/package.json

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

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

@@ -42,23 +42,17 @@ deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**
 
 两个细节确保静态幻灯片可被直接编辑：每段文字都放在自己的叶子元素中（把 "Revenue" 放在 `<h2>` 内单独的 `<span>` 里，而不是写成 `<h2>Revenue <span class="sub">2025</span></h2>` 这样文本和子元素混在同一父节点的形式），重复结构要逐一写出而非生成——三条 `<li>` 直接写在标记里，而不是从数组渲染一个 `<li>` 三次。重复正是重点所在；它让用户能编辑第二条而不影响第一条。
 
-### 布局实现纪律
-
-- 每页 `<section>` 内用统一的**满高壳容器**（高度铺满画布），并在壳上**显式声明背景色**（含常规页的默认底色）——不依赖 body/舞台继承；所有垂直分布（居中、两端）声明在满高容器上，没有高度的容器上写居中是静默失效的。
-- 布局几何由布局系统产生：flex/grid + gap，行高列宽由内容撑出；**同行卡片不硬拉等高——grid/flex 默认 stretch 会把短卡拉到最高卡的高度、制造空腔，内容量差异大时用 `align-items: start`，或增密短卡内容使高度自然接近**；图标、序号等前缀元素与文字各占各的盒；架构图/分层图用 grid 行式布局，禁止绝对定位手排。
-- 短标签、术语、按钮文字禁止内部换行（`white-space: nowrap`，列宽 max-content）；中文段落避免单字孤行（`text-wrap: pretty`）。
-
 ## 幻灯片设计与构图
 
 先定方向：动手前先调用 `frontend-design` skill 立视觉方向框架，再结合主题、受众、场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；frontend-design 的通用设计规则与本 skill 的 deck / 构图规则冲突时，以本 skill 为准。保持清晰的层级与一致的视觉系统。
 
 ### 封面、章节页与目录规格
 
-三类页面共用一个写法：先职责，再结果约束；手段自定，只禁失败形态。**目录页与章节分隔页只在内容真实分章（≥3 章）且内容页 ≥8 时使用**；短 deck 封面后直入内容，章节感由眉标/序号承担。
+三类页面共用一个写法：先职责，再结果约束；手段自定，只禁失败形态。
 
-- **封面是海报，不是标题卡——职责：3 秒内传达主题气质，完成已定视觉系统（强调色、字体对、图形母题）的首次完整呈现。** 让一个主视觉统治画面：超大版式字、满版图像+文字叠于低信息区、大型图形场或超大数字/字母（不限于此，以不裁切为上限；不用汉字或单词的放大淡化版作背景装饰，文字字形一律由字体渲染、不用 SVG/色块拼画）。**标题位置是构图决策**——依主视觉重心选位（对角平衡/低信息区/居中统治），不沿用内容页的左上标题带；偏置构图须有配重收住画面。演讲者/日期等信息以小字层级收纳。**禁止**「小图标 + 居中标题 + 居中副标题」三件套。
+- **封面是海报，不是标题卡——职责：3 秒内传达主题气质，完成已定视觉系统（强调色、字体对、图形母题）的首次完整呈现。** 达成方式是让一个主视觉统治画面，常见手段（不限于此）：超大版式字（可跨行/出血，以不裁切为上限）、满版图像 + 标题叠于保护渐变或色块上、大型图形场或超大数字作背景结构。演讲者/日期等信息以小字层级收纳。**禁止**「小图标 + 居中标题 + 居中副标题」三件套。
 - **章节页是封面的简版回声——职责：一眼识别"进入新章"。** 复用封面母题（更克制的用量），超大序号 + 章节标题为主体，与内容页拉开明显视觉差，手段自定；全 deck 章节页外观完全一致，只换序号和标题。
-- **目录页——职责：几秒内看清全场结构（几章、各讲什么、顺序如何）。** 章节序号与标题是绝对主角，说明至多一行，每项高度由内容撑出；形态可在视觉系统内自由变奏（纵向/横向/分栏/图形化序号/与章节页同构）——约束的是读取效率与系统一致性，不是形态。**禁止**等高空卡片阵列——它摊平层级、稀释结构感。目录样式与章节页呼应。
+- **目录页——职责：几秒内看清全场结构（几章、各讲什么、顺序如何）。** 章节序号与标题是绝对主角，说明至多一行，每项高度由内容撑出；编号列表（纵向或两栏）通常最能达成。**禁止**等高空卡片阵列——它摊平层级、稀释结构感。目录样式与章节页呼应。
 
 ### 构图原则
 
@@ -66,30 +60,28 @@ deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**
 
 - **视觉锚点。** 每页要能回答：视线第一眼落在哪里，为什么是那里。锚点可以是一个大数字、一张图表、一句大字陈述，也可以是并列结构中被刻意加重的一项。所有元素等面积、等字号、等色彩权重的页面，是把第一落点交给了随机——那不是中性，是没做构图决策。
 
-- **视觉即陈述。** 每一个视觉差异——位置、面积、颜色、容器、字重——都在向读者陈述一个信息差异，两个方向都必须诚实：**有信息差异就给它视觉编码**——分类给色点/编号/图标，要点给字重，并列短语用 chips 而非顿号串；强调的排序严格等于重要性的排序，整页级内容（总结、核心判断）占整页级位置（全宽），元信息（范围/方法/免责）永远页脚级。**没有信息差异就不制造视觉差异（作用域：同一组内的同级元素；页与页之间的变化归版式节奏管，不受此限）**——同一组里的同级节点/卡片不换色相，同一个状态已用图标或颜色编码过就不再用边框复读；装饰感来自对必要元素的精心处理（对齐、字距、色彩），而不是添加元素。
-
-- **视觉平衡。** 视觉重量要在整幅画布上分布均衡，不要全压在画幅一角。**内容只占上半画布、下半大面积空置的页面直接违规。** 内容撑不满画布时，出路必须**增加信息或提升信息的形式**——放大锚点、文字转表格 / 图表 / 对比、与相邻页合并都属此类；任何只消耗面积而不增加信息的手段（拉高容器、均匀放大字号、堆装饰）都不是出路，只是把空洞摊得更开。空间的分配次序**由内向外**：留白富余时，先放大组内间距（字距、行距、条目间），再把剩余留给外围——内容挤成一团而留白堆在外围，是分配错位。单一横带主体（时间线、步骤条）要么垂直居中、上下对称留白，要么用节点交错、大字底纹、配图长出身高；贴着标题排布、底部大片裸露，不属于任何合法构图。
+- **视觉平衡。** 视觉重量要在整幅画布上分布均衡，不要全压在画幅一角。**内容只占上半画布、下半大面积空置的页面直接违规。** 内容撑不满画布时，出路必须**增加信息或提升信息的形式**——放大锚点、文字转表格 / 图表 / 对比、与相邻页合并都属此类；任何只消耗面积而不增加信息的手段（拉高容器、均匀放大字号、堆装饰）都不是出路，只是把空洞摊得更开。
 
-- **平行性。** 相同与不同的判断标准是**信息结构**：信息层级相同的成组内容（系列页、清单、兄弟页）用同一副骨架，只换内容与配图——对称即秩序；信息角色不同的页面才求变化。结构件（页码、眉标）在所有页面位置样式一致；章节页彼此一致。不约束非成组内容页的版式——那归版式节奏管。
+- **平行性。** 平行性很重要：章节标题页外观必须一致；页码、眉标等结构件在所有页面位置样式一致；同类页面处理一致。不约束内容主体的版式——那归版式节奏管。
 
-- **版式节奏。** 与平行性互为对偶：平行性守住不变的东西，节奏经营变化的东西。**先读内容的结构——数量、关系（顺序/分类/主次/等权）、层级、体量——再选形式，形式沿阶梯随信息结构升级：并列短语→chips/短列表；异量纲数据组→统一骨架的指标卡；有结构关系→信息图；有数量关系→图表。先画容器再填内容，是所有单调版式与空卡的病根。** 逐页的形式选择连起来就是 deck 的节奏：节奏跟随叙事结构——章节转折、重点页、过渡页各有形态——而不是机械交替；节奏也需要对比才成立——全图、大数字、图表、引用、不同背景色、纯文字，原型库要够开阔，页页同一骨架无节奏可言。用版式和可视化把画布用满不是「填充性内容」；凭空编造数据和板块才是。**两条硬配额（只约束内容页）：①采用等宽等高卡片网格版式的页数不超过内容页总数的 20%（例：15 页内容页最多 3 页用网格），且任意两页网格页不相邻；②相邻两页禁止同一版式骨架——但成组页面（系列/清单型兄弟页）应当同构，属平行性而非重复，在 scratchpad 标注「成组」即可连排。本文所说「卡片网格」指的是版式结果——3 个以上等宽等高、同样式的信息卡片排成阵列（俗称"麻将块"）；与实现手段无关，`display: grid` 和栅格系统是任何版式都该用的好工具，不在限制之列。**
+- **版式节奏。** 与平行性互为对偶：平行性守住不变的东西，节奏经营变化的东西。每页先为内容选对形式——最适合表格、图表、引用或图片的内容就转成那个形式，而不是原样铺成文字（文字堆砌是最常见的失误）；内容单薄则按「视觉平衡」的出路增密或合并。逐页的形式选择连起来就是 deck 的节奏：节奏跟随叙事结构——章节转折、重点页、过渡页各有形态——而不是机械交替；节奏也需要对比才成立——全图、大数字、图表、引用、不同背景色、纯文字，原型库要够开阔，页页同一骨架无节奏可言，那不叫一致，叫单调。用版式和可视化把画布用满不是「填充性内容」；凭空编造数据和板块才是。**两条硬配额（只约束内容页）：①采用等宽等高卡片网格版式的**页数**不超过内容页总数的 20%（例：15 页内容页最多 3 页用网格），且任意两页网格页不相邻；②相邻两页禁止同一版式骨架（成组数据页确需连排时在 scratchpad 注明「内容使然」并变化锚点位置）。本文所说「卡片网格」指的是版式结果——3 个以上等宽等高、同样式的信息卡片排成阵列（俗称"麻将块"）；与实现手段无关，`display: grid` 和栅格系统是任何版式都该用的好工具，不在限制之列。**
 
 ### 素材与工艺
 
-- **字号、字重与单位。** 使用大号字体（标题至少 48px）。当用户指定具体字号时，默认他们说的是**磅（points）**（PowerPoint/Keynote 的单位）而非像素——用 `px = pt × 1.333` 换算。所以"把标题设成 36pt" → 在 CSS 里设成约 48px。**字重随字号反比**：display 级可用 300-400，正文 ≥400、small 级 ≥500；文字与背景对比度按投影标准（正文 ≥4.5:1），弱化文字靠降一档字号 + 中灰，不靠调到极浅。**内容放不下时，按信息损失从小到大依次尝试：换更合适的版式原型 → 拆成两页 → 最后才精炼文案（且只压缩表述、不删信息点）——禁止把字号压到 24px 以下或压缩边距硬塞。**
+- **字号与单位。** 使用大号字体（标题至少 48px）。当用户指定具体字号时，默认他们说的是**磅（points）**（PowerPoint/Keynote 的单位）而非像素——用 `px = pt × 1.333` 换算。所以"把标题设成 36pt" → 在 CSS 里设成约 48px。**内容放不下时，按信息损失从小到大依次尝试：换更合适的版式原型 → 拆成两页 → 最后才精炼文案（且只压缩表述、不删信息点；确需删信息点须极其克制）——禁止把字号压到 24px 以下或压缩边距硬塞。**
 
-- **素材来源与视觉承诺。** 除非用户要求，绝不使用 emoji。使用 design system / 品牌中的图标、用户提供的图片，或图片生成工具产出的图片。**内容本身是视觉性的（地点、产品、菜品、人物、场景）时，图片就是论据——必须配图或图片占位，缺图即缺论据；配图是 deck 级规划（见规划步骤 3），不是逐页即兴。**
+- **素材来源。** 除非用户要求，绝不使用 emoji。使用 design system / 品牌中的图标、用户提供的图片，或图片生成工具产出的图片。
 
 - **图片呈现。** 务必先查看图片，再决定最佳展示方式。
   - 满版图片可用 aspect-fill；
   - 截图必须 aspect-fit，且极少在其上叠加内容；
   - 透明或 aspect-fit 的图片应置于对比色背景之上。
 
-  裁切与叠字必须保护焦点主体（人脸、产品、关键物）：主体完整可见，不被画幅边缘、面板或叠加元素切遮（`object-position` 调焦点，保不住就换 aspect-fit 或换版式）；叠字落在图片的低信息区（虚化背景、天空、暗部），参照品牌惯常做法酌情使用卡片、保护渐变或模糊。
+  在图片上叠加文字时，参照品牌惯常做法：根据你在其他地方看到的样式，酌情使用卡片、保护渐变或模糊效果。
 
 - **图表与数据可视化。** 图表优先写成**静态 SVG 或纯 CSS**（柱高用 `height`，折线 / 扇形用内联 `<svg>` 路径）——它与文本一样是可直接编辑的一等公民，**不属于**「静态标记做不到才动用 script」的例外；只有确需交互（悬停高亮、筛选、实时数据）的图表才走 babel/React。数字之间只要存在能被眼睛读出的关系（趋势、占比、对比、分布），就转成图表，而不是原样铺成文字。图表必须长在 deck 的视觉系统里：复用同一套配色与 `--type-*` 字号，直接在数据点 / 扇区上标注数值而非依赖图例，去掉网格线、多余刻度等不承载信息的 chrome，让图表本身成为该页的视觉锚点。
 
-- **概念可视化（信息图）。** 与数字→图表对偶：**文字之间只要存在结构关系——顺序/流程、因果、层级、循环、包含、对比、矩阵——就转成信息图**（静态 SVG / CSS），而不是 bullet list。原型库：步骤条、时间线、金字塔、同心圆、漏斗、四象限矩阵、环形循环、双栏 VS 对比、路径图。判据：凡是想写 3 条以上并列 bullet 的地方，先问这几条之间是什么关系——**关系本身就是版式**。**图形语言纪律（专业感所在）**：同一图内节点同形态同尺寸，状态差异用强调色深浅/描边表达、不换色相；连接件用真图形（SVG 线/箭头）而非字符，锚点对齐节点；节点等距、中轴对齐；整图只有一个视觉高点。信息图复用 deck 配色与 `--type-*` 体系，节点上直接标注文字。
+- **概念可视化（信息图）。** 与数字→图表对偶：**文字之间只要存在结构关系——顺序/流程、因果、层级、循环、包含、对比、矩阵——就转成信息图**（静态 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` 事件。
@@ -103,10 +95,6 @@ deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**
 
 **deck 的输出语言 = 用户请求的语言**；请求与素材语言不一致时，以请求语言为准（英文请求 + 中文材料 → 英文 deck，翻译内容）。标题、正文、图表标注、说明全部使用同一语言，禁止混杂。当 deck 为中文时，英文只允许两种情况：专有名词/术语，以及刻意作为视觉元素的眉标或标签（如 "01 / OVERVIEW"）——后者属设计决策，全 deck 用法必须一致。
 
-### 每页两条阅读路径
-
-3 秒扫读拿走要点（标题 + 要点行 + 锚点），细读获得支撑（正文、数据、注释）。高密度页的每个内容块要有能独立成立的一句话要点——从正文**提炼**（小标题或加重首句），不是另写金句；正文是要点的证据。只有细读一条路的页面，对现场听众等于没有设计。
-
 ### 仅凭标题就应能讲清整个故事
 
 通读全部标题应能了解 deck 的整体故事（类似书籍的目录）。标题结构二选一，选定后全程一致：
@@ -128,7 +116,7 @@ deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**
 
 1. 如果不清楚受众、期望的品牌风格，先提问。
 2. 写出完整的标题序列。选择**一种**语法风格（例如短主题名词短语或简短陈述句），确保适合内容，并用该风格写出每一个标题。回头通读一遍，判断一个人**仅凭标题**能否跟上整个演示的脉络。标题应像书的章节——用直白的语言告诉读者接下来是什么。审阅这些标题并按需修订。将它们写入 scratchpad.md 文件。
-3. 在 scratchpad.md 里为每张幻灯片标注**版式原型**、**视觉锚点**（这页视线的第一落点）、**配图**（是否需图及图的内容——视觉性内容必配图或占位）与**成组关系**（属于哪个系列——成组页面同骨架）。原型必须写出具体名字——常用原型可参考：全幅大字、大数字、指标卡组、图表、信息图、表格、满版图、引用、左右分栏、时间线、卡片网格；不限于这些，但**每页都要做出并写下明确的版式选择**，写不出名字的页就是还没做构图决策。通读这一列做两项核对：①配额——网格页数 ≤ 内容页总数的 20% 且互不相邻，相邻页不同原型（成组页面同构不算重复）；②节奏是否跟随叙事结构——原型的重复要么是内容使然，要么就是没做选择；写不出锚点的页，是内容撑不起一页的信号——回大纲合并或换形式增密。
+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. 构建幻灯片，牢记每张幻灯片既是设计练习也是文案练习。在版式、文字内容和语调方面给予每张幻灯片应有的关注。遵循上述原则，确保每张幻灯片能独立成立；一个只看这一页的人，应当无需其他上下文就能理解其高层含义。
 
@@ -140,19 +128,19 @@ deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**
 
 - 量级在 `--pad-bottom` 上下 → 呼吸空间，合法，保留。
 - 多元素内容页底部空置接近半幅 → 违规，按「视觉平衡」的出路增密。
-- 单主体页（全幅大字、引用、大数字、章节页）→ 大留白即其形态，只看主体字号够不够大、构图有无意图。
+- 单主体页（全幅大字、引用、章节页）→ 大留白即其形态，只看主体字号够不够大、构图有无意图。
 
 逐页核对以下各项（不要用「已检查全部通过」一句带过）：
 
 - 字号匹配你的 `--type-*` 体系（而非网页密度）
 - 幻灯片边距匹配你的 `--pad-*` 值（而非网页紧凑间距）
-- 封面有统治画面的主视觉，标题位置有构图意图，不是「小图标 + 居中标题」三件套
+- 封面符合封面规格三形态之一，不是「图标 + 居中标题」三件套
 - 目录几秒内可读出章节结构，不是等高空卡片阵列
 - 结构件（页码、眉标）全 deck 位置样式一致；章节页彼此外观一致
 - 网格页数 ≤ 内容页总数的 20% 且互不相邻；相邻页版式原型不同
 - 没有使用 accent-border 卡片或 takeaway box
 - 没有内容被画幅边缘裁切、显示不全
-- 没有元素相互压叠、遮挡到读不清；图片焦点主体完整可见，未被边缘或面板切遮
+- 没有元素相互压叠、遮挡到读不清
 - 没有被动空洞：边框 / 底色圈出的范围与其内容相称
 - 页面视觉重量在画布上分布均衡；底部留白按开头三条判法检查
 - 每页能指出视觉锚点；版式原型的重复经得起「内容使然还是没做选择」的追问