@lark-apaas/coding-steering 0.1.23 → 0.1.24-alpha.20260729134517

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 托管（源码即产物） | — | _（占位，待补）_ | [`coding-template-design-html`](../../templates/design-html) |
+| `design-html` | **无构建**纯静态 HTML 托管（源码即产物，类 Claude Design） | — | _（占位，待补）_ | [`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,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.23",
+  "version": "0.1.24-alpha.20260729134517",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

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

@@ -9,7 +9,7 @@ metadata:
 
 # Animated video
 
-Create an animated video or motion design piece rendered as an HTML page. Build a timeline-based animation with smooth transitions. Design frame-by-frame sequences with playback controls (play/pause, scrubber). Focus on visual storytelling. Export-ready at a fixed aspect ratio (16:9 or 9:16). If you need to know the position of an element (eg to move a cursor or character between elements) use refs to grab the position.
+Create an animated video or motion design piece rendered as an HTML page. Build a timeline-based animation with smooth transitions. Design frame-by-frame sequences with playback controls (play/pause, scrubber). Focus on visual storytelling with the Anthropic brand palette. Export-ready at a fixed aspect ratio (16:9 or 9:16). If you need to know the position of an element (eg to move a cursor or character between elements) use refs to grab the position.
 
 START by calling `copy_starter_component` with `kind: "animations.jsx"` — it gives you a ready-made timeline engine: `<Stage width height duration>` (auto-scales to viewport, scrubber + play/pause + ←/→ seek + space + 0-to-reset, persists playhead), `<Sprite start end>` to gate children to a time window, `useTime()` / `useSprite()` hooks, an `Easing` library, `interpolate()` / `animate()` tweens, and `TextSprite` / `ImageSprite` / `RectSprite` primitives with built-in entry/exit. Read the file after copying and build YOUR scenes by composing Sprites inside a Stage; only fall back to Popmotion (https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/popmotion@11.0.5/dist/popmotion.min.js) if the starter genuinely can't do what you need.
 

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

@@ -48,7 +48,7 @@ metadata:
 
 5. **编写 ECharts 代码。** 挂载模式和 API 约束见下方技术参考。
 
-6. **自检。** 按文末清单验证渲染结果。然后回到视觉编码步骤：渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？
+6. **自检。** 截图检查结果。按文末清单验证。然后回到视觉编码步骤：渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？
 
 ## 图表类型映射
 
@@ -77,44 +77,6 @@ metadata:
 - **表达覆盖**：把用户需求拆成需要被回答的信息关系；每个被承诺的关系都要有对应的图表、表格、矩阵或文字证据承载。不要用少量通用指标和默认图表替代所有分析任务。
 - **小容器防崩**：小尺寸图表优先用 bar / line / number strip。饼图、雷达图、词云和外部标签很容易挤压重叠；空间不足时换图表类型，而不是缩小到不可读。
 
-## 窄屏适配
-
-图表出现在报表或看板中时，移动端（≤768px）的容器宽度可能压到 300px 以下。盲目把桌面端图表原样塞进窄容器，会导致 axis label 堆叠、legend 遮盖绘图区、饼图标签溢出。以下是在窄屏容器中保证可读性的规则：
-
-### 布局容器
-
-报表中承载图表的网格必须在窄屏时折叠为单列。写多列网格时，用 `auto-fit` + `minmax()` 让浏览器自动折叠，或配合 `@media` 断点显式切换：
-
-```css
-/* 自动折叠：每列最小 320px，不够就换行 */
-.chart-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
-  gap: 16px;
-}
-
-/* 或显式断点 */
-@media (max-width: 768px) {
-  .chart-grid { grid-template-columns: 1fr; }
-}
-```
-
-不要写死 `grid-template-columns: 1.2fr 2fr` 而不提供窄屏回退——390px 视口下，1.2fr 只有 146px，放不下任何图表。
-
-### ECharts option 适配
-
-在窄容器（宽度 <400px）中调整 ECharts option：
-
-- **legend**：改为 `orient: 'horizontal'` + `type: 'scroll'`，放在图表底部（`bottom: 0`），不要放在侧面挤占绘图区。
-- **grid**：增大 `left` / `right` 留白到 `'12%'` 以上，防止 axis label 被裁切。
-- **x 轴 label**：长文本加 `axisLabel: { rotate: 30, interval: 0 }` 或截断 formatter；分类超过 8 个时用 `interval: 'auto'` 让 ECharts 自动跳标签。
-- **tooltip**：窄屏下 tooltip 容易超出视口，设 `confine: true`。
-- **图表类型降级**：桌面端的并排双图在移动端改为上下堆叠；桌面端的 Pie 在容器宽度 <250px 时考虑改为横向 Bar。
-
-### 容器尺寸监听
-
-用 `ResizeObserver` 而非 `window.resize` 监听图表容器（见下方「技术参考 · 挂载」的封装代码）。当网格从双列折叠为单列时，window 尺寸不变但容器变宽，`resize` 事件不触发，图表不会重绘。
-
 ## 技术参考
 
 ### 加载 ECharts
@@ -132,24 +94,23 @@ metadata:
 <script>
   const chart = echarts.init(document.getElementById('chart'));
   chart.setOption({ /* ... */ });
-  new ResizeObserver(() => chart.resize()).observe(document.getElementById('chart'));
+  window.addEventListener('resize', () => chart.resize());
 </script>
 ```
 
 ### 挂载——React 封装
 
-定义一次，复用。**不要**添加 echarts-for-react。用 `ResizeObserver` 而非 `window.resize` 监听容器尺寸变化（见「窄屏适配」说明）。
+定义一次，复用。**不要**添加 echarts-for-react。
 
 ```jsx
 function EChart({ option, style }) {
   const ref = React.useRef(null);
   React.useEffect(() => {
-    const el = ref.current;
-    const chart = echarts.init(el);
+    const chart = echarts.init(ref.current);
     chart.setOption(option);
-    const ro = new ResizeObserver(() => chart.resize());
-    ro.observe(el);
-    return () => { ro.disconnect(); chart.dispose(); };
+    const onResize = () => chart.resize();
+    window.addEventListener('resize', onResize);
+    return () => { chart.dispose(); window.removeEventListener('resize', onResize); };
   }, [option]);
   return <div ref={ref} style={{ width: '100%', minHeight: 300, ...style }} />;
 }
@@ -191,8 +152,6 @@ Object.assign(window, { EChart });
 | 17 | 双 Y 轴零点未对齐 | 匹配 `\|min\| / max` 比例 |
 | 18 | 图表 series 或容器使用阴影/发光效果 | 移除 `shadowBlur`、`shadowColor`、容器 `box-shadow`，改用线宽、透明度、注释或面积大小表达层级 |
 | 19 | 图表或标签挤压、重叠、被容器裁切 | 增大容器、减少标签、改用 tooltip / inside label，或换成更稳的图表类型 |
-| 20 | 图表容器的父级网格在窄屏（≤768px）下没有折叠为单列 | 用 `auto-fit + minmax(320px, 1fr)` 或 `@media` 断点，保证每个图表容器至少 320px 宽 |
-| 21 | 使用 `window.addEventListener('resize', ...)` 监听图表尺寸 | 改用 `ResizeObserver`——网格列折叠时 window 尺寸不变但容器变宽，`resize` 事件不触发 |
 
 ### 不建议
 

package/steering/design-html/skills/{data-viz → data-report}/SKILL.md

@@ -1,15 +1,15 @@
 ---
-name: data-viz
-description: "数据可视化设计。从数据分析到版面规划、信息层级组织，适用于用户有数据文件或明确指标，需要产出结构化报表、看板或可视化页面的场景。图表绘制部分由 charts skill 承担。触发词：数据可视化, 数据报表, 数据看板, 数据分析报表, BI, 经营报表, 指标看板, 周报, 月报, 数据大盘, KPI, 报表设计, data visualization, data report, dashboard report, analytics report"
+name: data-report
+description: "数据驱动的报表与看板设计。从数据分析到报表规划、信息层级组织，适用于用户有数据文件或明确指标，需要产出结构化数据报表的场景。图表绘制部分由 charts skill 承担。触发词：数据报表, 数据看板, 数据分析报表, BI, 经营报表, 指标看板, 周报, 月报, 数据大盘, KPI, 报表设计, data report, dashboard report, analytics report"
 metadata:
   display-names:
-    zh-CN: 数据可视化
-    en-US: Data Visualization
+    zh-CN: 数据看板
+    en-US: Data Dashboard
 ---
 
-# 数据可视化
+# 数据报表
 
-你是数据可视化设计者。你的工作是把原始数据变成一份读者能直接用来做判断的可视化页面——不只是画几张图，而是回答"这份数据在说什么、读者应该关注什么"。
+你是数据报表设计者。你的工作是把原始数据变成一份读者能直接用来做判断的报表——不只是画几张图，而是回答"这份数据在说什么、读者应该关注什么"。
 
 报表的价值不在图表数量，而在信息层级：读者能在 5 秒内抓到主要结论，30 秒内理解支撑证据，需要时能下钻到明细。
 
@@ -19,9 +19,7 @@ metadata:
 
 布局必须比普通上下堆叠更丰富。先根据数据任务选择版式骨架，再写代码：监控型、复盘型、诊断型、对比型、明细型、汇报型可以有完全不同的扫描路径。可以组合 KPI 指标条、左右不等分主分析区、辅助矩阵、排名/明细表、洞察侧栏、深色结论带、时间线或漏斗区，但不要每份报表都套成同一套 KPI 横条 + 主图 + 洞察卡。不要把每个章节都做成同宽标题加一张满宽卡片；核心模块占更大面积，支撑模块用不同宽度、密度和位置服务它。
 
-报表不是产品原型。内容型或分析型交付服务阅读和决策，不默认生成多页面后台导航、可下拉应用名、无意义返回按钮或设置菜单。标题、范围、口径、结论、图表、洞察和明细都是可用的信息部件，不是每份报表都必须同时出现的固定章节。
-
-看板中的筛选器、标签页切换（如"今日/近7天/近30天"、"库存量/库存金额"、"30天/90天"）、下拉选择等控件如果出现在页面上，必须用 JavaScript 实现真实的切换逻辑——点击后切换数据视图、过滤图表或改变显示内容。不实现功能的控件不得使用 `<button>`、`cursor:pointer` 或 active/hover 样式暗示可点击；纯标注用 `<span>` 或静态文字呈现。
+报表不是产品原型。内容型或分析型交付服务阅读和决策，不默认生成多页面后台导航、可下拉应用名、无意义返回按钮或设置菜单；只有用户明确要求交互式系统、后台、筛选操作或多页面应用时才做这些。标题、范围、口径、结论、图表、洞察和明细都是可用的信息部件，不是每份报表都必须同时出现的固定章节。
 
 不要让页面全是文字，也不要把所有章节都做成同一种"结论 + 指标 + 图表 + 洞察"结构。长材料先判断每段内容在当前报表里的作用：它是在给背景、定义口径、证明结论、展示变化、比较对象、解释异常、列明细，还是提出行动。每段只选择最适合的表达方式，可以是短结论、关键数字、对比、时间顺序、表格、矩阵、引用、图表、注释或截图。重要内容不能被塞进附录或角落；如果一个章节是汇报目标的核心，就给它相称的版面面积和区别于其他章节的版式处理。
 
@@ -52,13 +50,6 @@ metadata:
 
 产出：维度-指标清单，以及一句话叙事重点。
 
-**数据忠实度约束。** 在此步完成后，明确标注哪些指标可以直接从源数据计算、哪些缺少必要数据（如历史期、目标值、预算基线）。后续步骤中：
-
-- 可直接计算的指标：使用真实值。
-- 源数据不含的派生指标（同比/环比变化率、完成率、差额等需要两期或多源数据而只有单期的）：不编造数值，用"—"占位或省略该指标。
-- 超出数据时间范围的外推值：不补齐，图表只覆盖数据实际跨度。
-- 确需补充示例数据时：必须在页面上用视觉标记（虚线边框、"示例数据"标签、灰色斜体）明确区分。
-
 ### 3. 报表规划
 
 在写代码之前，先确定报表由哪些组件构成：
@@ -68,7 +59,7 @@ metadata:
 - **候选部件**：标题 / 范围 / 口径、摘要、KPI、主图表、辅助图表、文字洞察、明细表、时间线、矩阵、截图或注释都只是候选。需要哪个用哪个，不要为了"完整"把它们凑齐。
 - **核心承载**：只给真正承载核心问题的模块更大面积。核心可能是一张趋势图、一张排名表、一段异常解释、一个流程漏斗，也可能是一组明细，不固定。
 - **版式差异**：为不同信息角色安排不同形态，例如紧凑指标条、宽图、窄侧栏、表格区、注释带、对比矩阵或分段背景。避免每个章节都重复同一张满宽白卡。
-- **布局骨架**：明确每个模块的相对面积和扫描路径，例如 `1.2fr 2fr`、`1fr 1.6fr`、`repeat(4,1fr)`、`auto 1fr` 等混合栅格。多列网格必须提供窄屏回退（`auto-fit + minmax()` 或 `@media` 断点），不要写死 fr 比例而不处理移动端——详见下方「移动端适配」。
+- **布局骨架**：明确每个模块的相对面积和扫描路径，例如 `1.2fr 2fr`、`1fr 1.6fr`、`repeat(4,1fr)`、`auto 1fr` 等混合栅格；移动端再自然折叠。
 
 组件取舍由读者任务、数据复杂度和材料内容决定。
 
@@ -93,53 +84,12 @@ metadata:
 - 表格用于精确查数和比较对象，不要把长表伪装成密集柱状图。
 - KPI 用于概览，不要把每个字段都做成指标卡。
 - 没有真实依据时不编造结论；可写"待补充口径"或使用中性描述。
-- 页面中每个数值必须可溯源：源数据直读、或从源数据可验证计算得出。缺少计算所需数据时（如同比需要上期数据但只有本期），用"—"占位或省略，不编造。
-- 所有视觉上暗示可交互的控件（标签页、筛选器、按钮、下拉、日期切换）必须绑定真实 JS 逻辑。不实现切换功能就不画成可点击样式。
 
 产出：完整报表页面。
 
-### 5.5 移动端适配
-
-报表在桌面端的复杂网格不会自动适配移动端。写完桌面布局后，必须为 ≤768px 视口补充响应式处理：
-
-**页面基础**：HTML 必须包含 `<meta name="viewport" content="width=device-width, initial-scale=1">`，否则移动浏览器用 980px 默认视口渲染再缩小，所有字都变成蚊子大小。
-
-**模块折叠策略**：
-
-- **KPI 指标条**：桌面端横排 4 个时，移动端折叠为 2×2 网格。用 `repeat(auto-fit, minmax(160px, 1fr))` 自动处理，或 `@media (max-width: 768px)` 显式切到两列。
-- **主分析区（左右不等分）**：`1.2fr 2fr` 或 `auto 1fr` 这类侧栏 + 主区布局，移动端必须折叠为单列——侧栏内容移到主区上方或下方。
-- **并列图表**：两图并排在移动端改为上下堆叠，每个图表独占一行。图表容器的窄屏处理由 charts skill 的「窄屏适配」规则覆盖。
-- **明细表格**：宽表在窄屏下加 `overflow-x: auto` 让表格可横向滚动，不要压缩列宽到不可读。
-- **洞察侧栏 / 注释带**：移动端折叠到对应图表下方，不要浮动遮盖内容。
-
-**断点写法**（二选一）：
-
-```css
-/* 方式 A：auto-fit 自动折叠 */
-.report-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
-  gap: 16px;
-}
-
-/* 方式 B：显式断点 */
-.report-layout {
-  display: grid;
-  grid-template-columns: 1.2fr 2fr;
-  gap: 24px;
-}
-@media (max-width: 768px) {
-  .report-layout {
-    grid-template-columns: 1fr;
-  }
-}
-```
-
-**字号底线**：移动端正文不低于 14px，KPI 数字不低于 20px，图表标题不低于 13px。
-
 ### 6. 自检
 
-检查渲染结果，验证以下几点：
+截图检查结果，验证以下几点：
 
 - 报表是否回答了步骤 1 确定的核心问题。
 - 信息层级是否清晰（读者能在 5 秒内抓到主要结论）。
@@ -151,11 +101,5 @@ metadata:
 - 文字洞察是否与图表数据互相支撑。
 - 图表部分是否通过了 charts skill 的自检清单。
 - 口径和单位是否全报表一致。
-- 页面中展示的每个数值是否可溯源到用户提供的数据；同比/环比/完成率等派生指标是否有对应的基准数据支撑，没有的是否已用"—"占位而非编造。
-- 所有视觉上可点击的控件（标签页、筛选器、按钮、下拉）是否都绑定了真实 JS 逻辑，点击后确实切换数据或视图；没有功能的元素是否已改为静态文字样式。
-- HTML 是否包含 `<meta name="viewport" content="width=device-width, initial-scale=1">`。
-- 多列网格是否提供了窄屏回退（`auto-fit + minmax()` 或 `@media` 断点），在 390px 视口下是否折叠为单列且无横向滚动。
-- 宽表格是否有 `overflow-x: auto` 容器包裹。
-- 移动端字号是否达到底线（正文 ≥14px、KPI 数字 ≥20px、图表标题 ≥13px）。
 
 产出：确认或修正。

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

@@ -1,27 +1,10 @@
 ---
 name: interactive-prototype
-description: 创建具备真实交互的可运行应用原型。触发词：interactive prototype, 交互原型, 可交互原型, 动态原型, 原型演示, 交互演示, working app
+description: Working app with real interactions
 metadata:
   display-names:
     zh-CN: 交互原型
     en-US: Interactive Prototype
 ---
 
-# 交互原型
-
-创建一个完全可交互的原型，具备真实的状态管理和页面切换。用 React 的 useState/useEffect 实现动态行为。包含悬停状态、点击交互、表单验证、动画过渡和多步导航流程。用起来要像真正能运行的应用，而不是静态效果图。
-
-## 响应式适配
-
-先判断 brief 的目标场景，走不同策略：
-
-**面向终端用户的产品**（官网、营销页、C 端应用、展示型页面）——必须适配移动端。用 `@media (max-width: 768px)` 做断点，375px 宽度下无水平滚动、无内容不可读、无元素互相遮挡：
-
-- **侧边栏**：窄屏默认收起，汉堡按钮切换；展开时 `position: fixed` + 半透明遮罩覆盖内容，不挤压主区域。
-- **顶部导航**：导航项超出视口宽度时折叠为汉堡菜单，不允许换行堆叠或水平溢出。
-- **网格与卡片**：用 CSS Grid `auto-fit` / `minmax()` 或 Flexbox `flex-wrap`，窄屏自动堆叠为单列；卡片内数字和文字不因容器变窄而截断。
-- **固定定位元素**：浮动按钮、悬浮面板等 `position: fixed/absolute` 元素用 `right: 16px` 等安全边距约束在视口内，不允许超出屏幕边缘。
-
-**面向桌面的场景**（管理后台、内部工具、数据密集型仪表盘）——不需要重排为移动端布局，但必须设 `min-width`（通常 1024px–1200px），窄于此宽度时整体水平滚动，而不是让布局被挤压变形。
-
-brief 未指明时默认按终端用户产品处理。
+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

@@ -0,0 +1,209 @@
+---
+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>` 数量一致。
+- 没有内容被画幅裁掉，也没有元素互相遮挡。
+- 时间线、流程带等绝对定位或交替布局的容器有真实高度，交替类名真的挂上了，没有塌成细带。
+- 没有无意义的描边圆角卡片、单边彩色圆角卡片、阴影、发光、玻璃拟态和装饰性渐变。
+- 封面有一个主视觉，不是“小图标 + 居中标题 + 居中副标题”的固定三件套。
+- 页码和眉标统一；相邻页面的骨架有变化，但变化跟内容有关。
+- 每页都看得出重点；疏页面是有意留白，不是忘了安排内容。
+- 普通内容页没有缩在一个角落或只占上半页；大面积留白能说清它在突出什么，否则要重组版式或合并页面。
+- 动效元素在不播放动画时也是完整可见的。