explainer-design-system

Provenance & Credits

This skill is vendored from zarazhangrui/codebase-to-course by Zara Zhang. The teaching primitives, content philosophy, design system tokens, and interactive-element HTML patterns documented here originate upstream — full credit for the pedagogical model goes to the original author. We renamed the local copy to explainer-design-system to better reflect its role as a design-system reference inside this plugin's single-module pipeline; the upstream URL is recorded in the YAML frontmatter for traceability. All upstream SKILL.md content below the adapter note is preserved verbatim.

Adapter note for agent-flow /explain

This skill is vendored from the upstream repo but wired into this plugin's single-module /explain pipeline, not its original multi-module directory output. Speedwagon (the authoring agent) treats this file as guidance, not as a generator. Concretely:

• Output shape — Speedwagon writes one <section class="module"> HTML fragment to .claude/explain-briefs/<slug>.fragment.html. The assembler (scripts/compile-explain.sh) concatenates it into explain-out/index.html. Do not create a course directory, styles.css, main.js, build.sh, _base.html, or _footer.html — those assets live under templates/explain/ and are owned by the pipeline, not by this skill.
• Code blocks inside <pre> get a class="language-*" so Prism (loaded by the assembler from CDN) highlights them; inline <code> outside <pre> stays bare. Diagrams come before prose — see references/content-philosophy.md 'Diagrams Before Prose'.
• Module count — exactly 1 module per /explain invocation (Senku picks 3–5 screens). Ignore the "4–6 modules" rule from Phase 2 below; treat the single module as Module 1.
• Phases that do not apply — Phase 1 (codebase analysis) is already done by Riko, Phase 2 (curriculum design) is already done by Senku, and Phase 2.5 (module briefs) collapses into the single brief Speedwagon writes. Speedwagon starts at Phase 3 "Build the module" with Riko's scope + Senku's curriculum as inputs.
• Reference files that apply — read these from skills/explainer-design-system/references/ when authoring the fragment:
  • content-philosophy.md — metaphor rules, tone, visual density, quiz design
  • design-system.md — warm palette, typography, spacing tokens
  • interactive-elements.md — HTML patterns for translator blocks, chat animations, flow animations, quizzes, callouts, glossary tooltips
  • gotchas.md — failure-mode checklist to run before declaring done
• Reference files that do NOT apply — module-brief-template.md is superseded by the brief shape illustrated in ${CLAUDE_PLUGIN_ROOT}/templates/explain/module-brief-example.md. Reader language and the plain-language restatement contract are defined in commands/explain.md (canonical source).
• Mandatory interactive elements, adapted — the upstream skill requires all five element types across the whole course. For a single module, aim for at least: one code↔English translator (already required by /explain), one quiz or callout, glossary tooltips on technical terms, and one of {group chat animation, flow animation, architecture diagram} if the topic has any actor-to-actor communication. Skip elements that would feel forced.