explainer-kit

说明工具包

为所有说明页面提供统一的外观和基础设施。explain-with-* 技能说明要展示什么；本工具包决定外观以及各部分如何组合，确保所有说明页面风格一致，也不必让任何 Agent 自行设计 CSS、配色或播放器。

适用场景

• 使用任何 explain-with-* 技能构建章节（讲故事、代码讲解、预览、分段片段、幻灯片、视频）。
• 将多个章节组合成一个页面，用于 explain-visually。
• 修改说明页面主题或添加共享组件。

文件

所有文件都在本文件旁边的 assets/ 目录中：

文件	内容
FRAGMENT-CONTRACT.md	每个片段都必须遵循的规则和组件速查表。编写片段前请先阅读；它就是完整的 API。
SCRIPTS-AND-TABS.md	仅适用于带有自有脚本的片段（片段剪辑、幻灯片、视频、代码讲解）和带标签页的页面
assemble.py	根据概览和片段构建最终页面，并验证契约
preview.py	根据 JSON 生成决策（选项）章节或前后对比章节
check.py	在桌面端和手机上打开组装完成的页面，并仅列出需要修复的问题
kit.css、kit.js、shell.html	组装器内嵌的样式、行为和页面模板。编写页面时无需阅读这些文件

主题

• 共四种主题：Violet（默认；优先深色，近黑底色搭配一种紫色强调色，Geist 字体）、Ocean、 Amber 和 Aurora；每种都有浅色和／或深色变体。查看者可以切换主题；选择会被记住。
• 使用 assemble.py --theme 选择首次加载的主题。不要为单个页面添加调色板或字体。
• 颜色、字体和圆角只能来自 var(--ev-…) 令牌，不能使用字面值，因为页面必须兼容所有主题以及浅色和深色模式。
• 语义颜色含义固定，并且始终配有字形：新增 +、移除 −、风险 !、决策 ◆、正常 ✓。强调色表示“这是重点”，不表示状态。

页面构建方式

1. 每个章节都是一个片段：一个独立的 <section class="ev-tab-content" data-tab="NAME">，带有自己的作用域 <style>，以及一个在 EV.onShow(NAME, …) 中构建内容的 IIFE <script>。
2. 协调器编写概览（<header class="ev-overview">）：眉题、直接给出答案的标题、一句话、一个主视觉，以及一条关键句（最多带一个“决策”提示框）。不要使用信息框网格。
3. assemble.py 会内嵌工具包、插入概览和片段；如果片段违反契约，就不会写入页面。

# One scrollable page with a sticky chapter list (default for explain-visually)
python assets/assemble.py --page --toc --title "Short name" --overview overview.html \
  --section story=frag-story.html --section code=frag-code.html --section decide=frag-decide.html \
  --out index.html

# One fragment on its own page
python assets/assemble.py --standalone frag-slides.html --title "Short name" --out index.html

• --section NAME=FILE 中的 NAME 必须与片段的 data-tab 相同。
• 在片段的 <section> 上设置 data-label、data-hint、data-part-title 和 data-part-lede，用于章节标题；为元素添加 id 和 data-toc="短标签"，以便将其列入章节列表。
• 输出是一个完整的独立 HTML 页面，可直接作为制品发布。

所有章节通用规则

• 先简洁表达：结论式标题 → 一个具体视觉元素 → 最多 2–3 句短句 → 详细内容。
• 详细内容放在 ev-more 折叠控件后，其摘要要说明其中包含什么（例如“Tick 轨迹 · 为什么是 5 行”）。 绝不要只写“更多”或“显示详情”。
• 详细内容也要可视化：高亮代码行、差异栏、分组、状态标签、紧凑表格、小型柱状图。
• 面向阅读的文字在显示时绝不能淡化或隐藏。
• 动画必须有助于解释内容，否则就移除。遵循 prefers-reduced-motion；页面静止时也必须完整。
• 内容全部放在一个页面中。一个制品内不要链接到其他独立页面。

修改工具包

• 仅在用户要求修改工具包时才进行修改；构建单个页面时不要修改：页面应直接使用现有工具包。
• 使用 ev- 前缀，在 kit.css／kit.js 中添加新组件，并将其加入 FRAGMENT-CONTRACT.md 的速查表，然后在现有页面上重新运行 assemble.py 和 check.py。