explainer-kit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explainer Kit

Explainer Kit（讲解页套件）

The shared look and plumbing for all explainer pages. The

explain-with-*

skills say what to show; this kit decides how it looks and how the parts fit together, so every explainer is consistent and no agent has to invent CSS, colours or players.

所有讲解页面共享的视觉样式和底层机制。

explain-with-*

skill 决定展示什么；本套件决定视觉呈现方式以及各部分如何组合，从而确保所有讲解页面风格一致，无需任何 Agent 自行设计 CSS、配色或播放器。

Use this skill when

何时使用此 skill

Building a chapter with any
```
explain-with-*
```
skill (storytelling, code walkthrough, preview, section clips, slides, video).
Assembling several chapters into one page for
```
explain-visually
```
.
Changing the explainer themes or adding a shared component.

使用任意
```
explain-with-*
```
skill 构建章节（叙事、代码讲解、预览、章节短片、幻灯片、视频）。
将多个章节组装为一个页面，供
```
explain-visually
```
使用。
修改讲解页面主题或添加共享组件。

Files

文件

All in

assets/

next to this file:

File	What it is
`FRAGMENT-CONTRACT.md`	The rules every fragment follows and the component cheat sheet. Read it before writing a fragment; it is the whole API.
`SCRIPTS-AND-TABS.md`	Only for fragments with their own script (clips, slides, video, code walkthrough) and tabbed pages
`assemble.py`	Builds the final page from an overview and fragments, and validates the contract
`preview.py`	Generates a decision (options) or before/after chapter from JSON
`check.py`	Opens the assembled page on a desktop and a phone and lists only what to fix
`kit.css` , `kit.js` , `shell.html`	The styles, behaviour and page template the assembler inlines. Don't read them to write a page

以下文件均位于本文件旁的

assets/

中：

文件	用途
`FRAGMENT-CONTRACT.md`	所有 fragment 都必须遵循的规则及组件速查表。编写 fragment 前务必阅读；它就是完整的 API。
`SCRIPTS-AND-TABS.md`	仅适用于包含独立脚本的 fragment（短片、幻灯片、视频、代码讲解）以及带标签页的页面
`assemble.py`	根据概览和 fragment 构建最终页面，并验证 fragment 是否符合约定
`preview.py`	根据 JSON 生成决策（选项）章节或前后对比章节
`check.py`	在桌面端和手机端打开组装后的页面，并仅列出需要修复的问题
`kit.css` 、 `kit.js` 、 `shell.html`	组装器会内联注入的样式、行为和页面模板。编写页面时无需读取这些文件

Themes

主题

Four themes: Violet (default; dark-first, near-black with one violet accent, Geist type), Ocean, Amber and Aurora, each with a light and/or dark variant. The viewer can switch; the choice is remembered.
Choose a first-load theme with
```
assemble.py --theme
```
. Don't add per-page palettes or fonts.
Colours, fonts and radii come only from
```
var(--ev-…)
```
tokens, never literal values, because the page must work in every theme and in light and dark.
Semantic colours have fixed meanings and always come with a glyph: new
```
+
```
, removed
```
−
```
, risk
```
!
```
, decision
```
◆
```
, ok
```
✓
```
. The accent marks "this is the point", not status.

共提供四种主题：Violet（默认；深色优先，近黑色背景搭配单一紫色强调色，使用 Geist 字体）、Ocean、Amber 和 Aurora，每种主题均提供浅色和/或深色变体。用户可以切换主题；选择会被记住。
使用
```
assemble.py --theme
```
选择首次加载时使用的主题。不要为单个页面添加额外的调色板或字体。
颜色、字体和圆角只能使用
```
var(--ev-…)
```
token，绝不能使用字面值，因为页面必须能够在所有主题以及浅色和深色模式下正常工作。
语义颜色具有固定含义，并且始终配有字形标记：新增
```
+
```
、移除
```
−
```
、风险
```
!
```
、决策
```
◆
```
、正常
```
✓
```
。强调色用于标记“重点所在”，而不是表示状态。

How a page is built

页面的构建方式

Each chapter is one fragment: a single
```
<section class="ev-tab-content" data-tab="NAME">
```
with its own scoped
```
<style>
```
and an IIFE
```
<script>
```
that builds inside
```
EV.onShow(NAME, …)
```
.
The coordinator writes the overview (
```
<header class="ev-overview">
```
): eyebrow, a headline that states the answer, one sentence, one hero visual, one key line with at most one "Decide" callout. No grid of info boxes.
```
assemble.py
```
inlines the kit, inserts the overview and fragments, and refuses to write the page if a fragment breaks the contract.

bash

undefined

每个章节都是一个 fragment：一个
```
<section class="ev-tab-content" data-tab="NAME">
```
，包含自己的作用域样式
```
<style>
```
，以及在
```
EV.onShow(NAME, …)
```
内部构建内容的 IIFE
```
<script>
```
。
协调器负责编写概览（
```
<header class="ev-overview">
```
）：眉题、点明答案的标题、一句话说明、一个主视觉图，以及一行关键内容，其中最多包含一个“Decide”标注。不要使用信息卡片网格。
```
assemble.py
```
会内联注入套件、插入概览和 fragment；如果 fragment 违反约定，该脚本将拒绝写出页面。

bash

undefined

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


- `NAME` in `--section NAME=FILE` must equal the fragment's `data-tab`.
- Set `data-label`, `data-hint`, `data-part-title` and `data-part-lede` on the fragment's `<section>` for the
  chapter heading; give elements `id` + `data-toc="Short label"` to list them in the chapter list.
- The output is one self-contained HTML page, ready to publish as an artifact.

python assets/assemble.py --standalone frag-slides.html --title "Short name" --out index.html


- `--section NAME=FILE` 中的 `NAME` 必须与 fragment 的 `data-tab` 相同。
- 在 fragment 的 `<section>` 上设置 `data-label`、`data-hint`、`data-part-title` 和 `data-part-lede`，用于定义章节标题；为元素设置 `id` 和 `data-toc="Short label"`，使其出现在章节目录中。
- 输出结果是一个自包含的 HTML 页面，可以直接作为 artifact 发布。

Shared rules for every chapter

每个章节的共享规则

Concise first: takeaway headline → one concrete visual → at most 2–3 short sentences → details.
Details sit behind
```
ev-more
```
toggles whose summary names what they contain (e.g. "Tick trace · Why 5 rows"). Never show a bare "More" or "Show details".
Make details visual too: highlighted code lines, diff gutter, groups, status chips, compact tables, small bars.
Text meant to be read is never faded or hidden while it is on screen.
Motion explains something or it goes. Respect
```
prefers-reduced-motion
```
; a page must be complete at rest.
Keep everything in one page. Don't link between separate pages inside one artifact.

始终先简洁表达：结论型标题 → 一个具体视觉示例 → 最多 2～3 个简短句子 → 详细信息。
详细信息放在
```
ev-more
```
切换控件之后，其 summary 必须明确说明所包含的内容（例如“调用追踪 · 为什么是 5 行”）。不要仅显示“更多”或“显示详情”。
详细信息也应采用可视化方式：高亮代码行、diff 边缘栏、分组、状态标签、紧凑表格、小型条形图。
需要阅读的文本在显示于屏幕时，绝不能以淡化或隐藏方式呈现。
动效必须用于解释内容，否则应将其移除。遵循
```
prefers-reduced-motion
```
；页面在静止状态下也必须完整可用。
所有内容都放在同一个页面中。不要在同一个 artifact 内链接到其他独立页面。

Changing the kit

修改套件

Only when the user asks for a kit change, not while building one page: a page uses the kit as it is.
Add new components to
```
kit.css
```
/
```
kit.js
```
with the
```
ev-
```
prefix and to the cheat sheet in
```
FRAGMENT-CONTRACT.md
```
, then re-run
```
assemble.py
```
and
```
check.py
```
on an existing page.

只有用户明确要求修改套件时才能修改，不能在构建页面时顺手改动；页面应按套件当前形态使用。
使用
```
ev-
```
前缀向
```
kit.css
```
/
```
kit.js
```
添加新组件，并同步更新
```
FRAGMENT-CONTRACT.md
```
中的速查表，然后在现有页面上重新运行
```
assemble.py
```
和
```
check.py
```
。