edu-chem-tutorial

Interactive chemistry course → interactive web page

What this skill produces

A single-page HTML that can be opened directly in a browser: a step-by-step course (5-15 steps) that progressively presents knowledge points, with each step equipped with Canvas 2D animated scenes(reaction diagrams, microscopic schematics, charts, comparison cards, etc.) + sidebar knowledge point panel (rich text explanations + key point lists) + top info cards(overview) + stepper/player controls. The format is consistent with 化学教程新例子/index.html .

Core architecture

Single-page HTML, no external dependencies (pure CSS + Canvas 2D + JS)
Data injection：__TUTORIAL_DATA__ placeholder mode (same as edu-chem-reaction's template injection)
Step data：STEPS array + scene drawing functions + configuration
Canvas 2D scene library: built-in common chemistry drawing primitives

Workflow

Step 1: Design the course spec

Determine the course topic, step-by-step content, the visual scene type corresponding to each step, and the color scheme language (Chinese/English).

Step 2: Write build_* to construct the spec

Refer to the example of scripts/generate.py to edit the tutorial spec (step list + scene configuration + metadata):

spec = {
    "meta": {"title": "...", "subtitle": "...", "language": "zh-CN", "accent": "..."},
    "cards": [...],          # 顶部概览卡片
    "steps": [...],          # 步骤数组（tag, name, body, points, scene）
    "scenes": {...},         # 场景绘制函数（可选动画参数）
}

Step 3: Inject the template

from pathlib import Path
out = Path.cwd() / "tutorial-<课程主题>.html"
render_html(spec, out)   # 将 spec 注入 template/tutorial.html

Step 4: Self-check

Open the HTML and confirm: no console errors, step switching works normally, scene rendering works normally
Verify: all steps can be displayed, the animation loop works normally, and play/pause/step work
Close the preview port

Step 5: Deliver

The finished product is written to the user's cwd, named like tutorial-<主题>.html。

Data format

meta (required)

{
  "title": "氧化还原方程式配平",
  "subtitle": "化合价升降法 · 电子守恒 · 双线桥",
  "language": "zh-CN",
  "accent": "amber"  // 强调色
}

cards (top overview cards, 1-4 cards)

[
  {"num": 1, "title": "概念", "body": "化合价升降<br>电子守恒"},
  {"num": 2, "title": "方法", "body": "标价→找升降<br>求最小公倍数"}
]

steps (step array, 5-15 steps)

[
  {
    "tag": "基础",           // 分类标签
    "name": "化合价概念",    // 步骤标题
    "body": "<p>富文本讲解 HTML</p>",
    "points": {              // 要点列表（侧栏展示）
      "title": "化合价规则",
      "items": ["<strong>单质</strong>：化合价为 0", "..."]
    },
    "scene": "equation",     // 场景类型名，对应 scenes 中的 key
    "sceneArgs": {...}       // 可选，传给场景绘制函数的参数
  }
]

scenes (scene drawing function mapping)

Each scene type corresponds to a JS drawing function, function signature (ctx, W, H, time, args). For built-in scene types, see template/tutorial.html in SCENE_DRAWERS。