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/explain-design-examples/module-brief-example.md.
• 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.

Everything below is the upstream skill content, preserved verbatim for design guidance.

---

Explainer Design System

Transform any codebase into a stunning, interactive course. The output is a directory containing a pre-built styles.css, main.js, per-module HTML files, and an assembled index.html — open it directly in the browser with no setup required (only external dependency: Google Fonts CDN). The course teaches how the code works through scroll-based modules, animated visualizations, embedded quizzes, and plain-English translations of code.

First-Run Welcome

When the skill is first triggered and the user hasn't specified a codebase yet, introduce yourself and explain what you do:

I can turn any codebase into an interactive course that teaches how it works — no coding knowledge required.

Just point me at a project:

• A local folder — e.g., "turn ./my-project into a course"
• A GitHub link — e.g., "make a course from https://github.com/user/repo"
• The current project — if you're already in a codebase, just say "turn this into a course"

I'll read through the code, figure out how everything fits together, and generate a beautiful single-page HTML course with animated diagrams, plain-English code explanations, and interactive quizzes. The whole thing runs in your browser — no setup needed.

If the user provides a GitHub link, clone the repo first (git clone <url> /tmp/<repo-name>) before starting the analysis. If they say "this codebase" or similar, use the current working directory.

Who This Is For

The target learner is a "vibe coder" — someone who builds software by instructing AI coding tools in natural language, without a traditional CS education. They may have built this project themselves (without looking at the code), or they may have found an interesting open-source project on GitHub and want to understand how it's built. Either way, they don't yet understand what's happening under the hood.

Assume zero technical background. Every CS concept — from variables to APIs to databases — needs to be explained in plain language as if the learner has never encountered it. No jargon without definition. No "as you probably know." The tone should be like a smart friend explaining things, not a professor lecturing.

Their goals are practical, not academic:

• Have enough technical knowledge to effectively steer AI coding tools — make better architectural and tech stack decisions
• Detect when AI is wrong — spot hallucinations, catch bad patterns, know when something smells off
• Intervene when AI gets stuck — break out of bug loops, debug issues, unblock themselves
• Build more advanced software with production-level quality and reliability
• Be technically fluent enough to discuss decisions with engineers confidently
• Acquire the vocabulary of software — learn the precise technical terms so they can describe requirements clearly and unambiguously to AI coding agents (e.g., knowing to say "namespace package" instead of "shared folder thing")

They are NOT trying to become software engineers. They want coding as a superpower that amplifies what they're already good at. They don't need to write code from scratch — they need to read it, understand it, and direct it.

Why This Approach Works

This skill inverts traditional CS education. The old model is: memorize concepts for years → eventually build something → finally see the point (most people quit before step 3). This model is: build something first → experience it working → now understand how it works.

The learner already has context that traditional students don't — they've used the app, they know what it does, they may have even described its features in natural language. The course meets them where they are: "You know that button you click? Here's what happens under the hood when you click it."

Every module answers "why should I care?" before "how does it work?" The answer to "why should I care?" is always practical: because this knowledge helps you steer AI better, debug faster, or make smarter architectural decisions.

The directory-based output is intentional: separating CSS/JS from content means AI never regenerates boilerplate, each module is written independently (keeping output size small and quality high), and the assembled index.html works offline with zero setup.

---

The Process

Phase 1: Codebase Analysis

Before writing course HTML, deeply understand the codebase. Read all the key files, trace the data flows, identify the "cast of characters" (main components/modules), and map how they communicate. Thoroughness here pays off — the more you understand, the better the course.

What to extract:

• The main "actors" (components, services, modules) and their responsibilities
• The primary user journey (what happens when someone uses the app end-to-end)
• Key APIs, data flows, and communication patterns
• Clever engineering patterns (caching, lazy loading, error handling, etc.)
• Real bugs or gotchas (if visible in git history or comments)
• The tech stack and why each piece was chosen

Figure out what the app does yourself by reading the README, the main entry points, and the UI code. Don't ask the user to explain the product — they may not be familiar with it either. The course should open by explaining what the app does in plain language (a brief "here's what this thing does and why it's interesting") before diving into how it works. The first module should start with a concrete user action — "imagine you paste a YouTube URL and click Analyze — here's what happens under the hood."

Phase 2: Curriculum Design

Structure the course as 4-6 modules. Most courses need 4-6. Only go to 7-8 if the codebase genuinely has that many distinct concepts worth teaching. Fewer, better modules beat more, thinner ones.

The arc always starts from what the learner already knows (the user-facing behavior) and moves toward what they don't (the code underneath). Think of it as zooming in: start wide with the experience, then progressively peel back layers.

Module Position	Purpose	Why it matters for a vibe coder
1	"Here's what this app does — and what happens when you use it"	Start with the product (what it does, why it's interesting), then trace a core user action into the code. Grounds everything in something concrete.
2	Meet the actors	Know which components exist so you can tell AI "put this logic in X, not Y"
3	How the pieces talk	Understand data flow so you can debug "it's not showing up" problems
4	The outside world (APIs, databases)	Know what's external so you can evaluate costs, rate limits, and failure modes
5	The clever tricks	Learn patterns (caching, chunking, error handling) so you can request them from AI
6	When things break	Build debugging intuition so you can escape AI bug loops
7	The big picture	See the full architecture so you can make better decisions about what to build next

This is a menu, not a checklist. Pick the modules that serve the codebase — a simple CLI tool needs 4, not 7. Adapt the arc to the codebase's complexity.

The key principle: Every module should connect back to a practical skill — steering AI, debugging, making decisions. If a module doesn't help the learner DO something better, cut it or reframe it until it does.

Each module should contain:

• 3-6 screens (sub-sections that flow within the module)
• At least one code-with-English translation
• At least one interactive element (quiz, visualization, or animation)
• One or two "aha!" callout boxes with universal CS insights
• A metaphor that grounds the technical concept in everyday life — but NEVER reuse the same metaphor across modules, and NEVER default to the "restaurant" metaphor (it's overused). Pick metaphors that organically fit the specific concept. The best metaphors feel inevitable for the concept, not forced.

Mandatory interactive elements (every course must include ALL of these):

• Group Chat Animation — at least one across the course. These are the iMessage/WeChat-style conversations between components. They're one of the most engaging elements and must always appear, even if you have to creatively frame a module's concept as a conversation between actors.
• Message Flow / Data Flow Animation — at least one across the course. The step-by-step packet animation between actors. If the codebase has any kind of request/response, data pipeline, or multi-step process, animate it. Every codebase has data flowing somewhere — find it.
• Code ↔ English Translation Blocks — at least one per module (already required above, but reiterating: this is non-negotiable).
• Quizzes — at least one per module (multiple-choice, scenario, drag-and-drop, or spot-the-bug — any quiz type counts).
• Glossary Tooltips — on every technical term, first use per module.

These five element types are the backbone of every course. Other interactive elements (architecture diagrams, layer toggles, pattern cards, etc.) are optional and should be added when they fit. But the five above must ALWAYS be present — no exceptions.

Do NOT present the curriculum for approval — just build it. The user wants a course, not a planning document. Design the curriculum internally, then go straight to building. If they want changes, they'll tell you after seeing the result.

After designing the curriculum, decide which build path to use:

• Simple codebase (single-purpose CLI, small web app, library, one clear entry point, 5 or fewer modules) → go directly to Phase 3 Sequential.
• Complex codebase (full-stack app, multiple services, content-heavy site, monorepo, or 6+ modules) → go to Phase 2.5 first, then Phase 3 Parallel.

Phase 2.5: Module Briefs (complex codebases only)

For complex codebases, write a brief for each module before writing any HTML. This is the critical step that enables parallel writing — each brief gives an agent everything it needs without re-reading the codebase.

Read references/module-brief-template.md for the template structure. Read references/content-philosophy.md for the content rules that should guide brief writing.

For each module, write a brief to course-name/briefs/0N-slug.md containing:

• Teaching arc (metaphor, opening hook, key insight)
• Pre-extracted code snippets (copy-pasted from the codebase with file paths and line numbers)
• Interactive elements checklist with enough detail to build them
• Which sections of which reference files the writing agent needs
• What the previous and next modules cover (for transitions)

The code snippets are the critical token-saving step. By pre-extracting them into the brief, writing agents never need to read the codebase at all.

Phase 3: Build the Course

The course output is a directory, not a single file. All CSS and JS are pre-built reference files — never regenerate them. Your job is to write only the HTML content.

Output structure:

course-name/
  styles.css       ← copied verbatim from references/styles.css
  main.js          ← copied verbatim from references/main.js
  _base.html       ← customized shell (title, accent color, nav dots)
  _footer.html     ← copied verbatim from references/_footer.html
  build.sh         ← copied verbatim from references/build.sh
  briefs/          ← module briefs (complex codebases only, can delete after build)
  modules/
    01-intro.html
    02-actors.html
    ...
  index.html       ← assembled by build.sh (do not write manually)

Step 1 (both paths): Setup — Create the course directory. Copy these four files verbatim using Read + Write (do not regenerate their contents):

• references/styles.css → course-name/styles.css
• references/main.js → course-name/main.js
• references/_footer.html → course-name/_footer.html
• references/build.sh → course-name/build.sh

Step 2 (both paths): Customize _base.html — Read references/_base.html, then write it to course-name/_base.html with exactly three substitutions:

• Both instances of COURSE_TITLE → the actual course title
• The four ACCENT_* placeholders → the chosen accent color values (pick one palette from the comments in _base.html)
• NAV_DOTS → one <button class="nav-dot" ...> per module

Step 3: Write modules — This is where the paths diverge.

Sequential path (simple codebases)

Read references/content-philosophy.md and references/gotchas.md. Then write modules one at a time. For each module, write course-name/modules/0N-slug.html containing only the <section class="module" id="module-N"> block and its contents. Do not include <html>, <head>, <body>, <style>, or <script> tags.

Read references/interactive-elements.md for HTML patterns for each interactive element type. Read references/design-system.md for visual conventions.

Parallel path (complex codebases)

Dispatch modules to subagents in batches of up to 3. Each agent receives:

• Its module brief (from course-name/briefs/)
• references/content-philosophy.md and references/gotchas.md
• Only the sections of references/interactive-elements.md and references/design-system.md listed in the brief

Each agent writes its module file(s) to course-name/modules/. Short modules (3 screens, one quiz) can be paired — two briefs given to one agent.

What agents do NOT receive: the full codebase (snippets are in the brief), SKILL.md, other modules' briefs, or unneeded reference file sections.

After all agents finish, do a quick consistency check in the main context: nav dots match modules, transitions between modules are coherent, no obvious tone shifts.

Step 4 (both paths): Assemble — Run build.sh from the course directory:

cd course-name && bash build.sh

This produces index.html. Open it in the browser.

Critical rules:

• Never regenerate styles.css or main.js — always copy from references
• Module files contain only <section> content — no boilerplate
• Use CSS scroll-snap-type: y proximity (NOT mandatory)
• Use min-height: 100dvh with 100vh fallback on .module
• Interactive element JS is in main.js; wire up via data-* attributes and CSS class names as shown in references/interactive-elements.md
• Chat containers need id attributes; flow animations need data-steps='[...]' JSON on .flow-animation

Phase 4: Review and Open

After running build.sh, open index.html in the browser. Walk the user through what was built and ask for feedback on content, design, and interactivity.

---

Design Identity

The visual design should feel like a beautiful developer notebook — warm, inviting, and distinctive. Read references/design-system.md for the full token system, but here are the non-negotiable principles:

• Warm palette: Off-white backgrounds (like aged paper), warm grays, NO cold whites or blues
• Bold accent: One confident accent color (vermillion, coral, teal — NOT purple gradients)
• Distinctive typography: Display font with personality for headings (Bricolage Grotesque, or similar bold geometric face — NEVER Inter, Roboto, Arial, or Space Grotesk). Clean sans-serif for body (DM Sans or similar). JetBrains Mono for code.
• Generous whitespace: Modules breathe. Max 3-4 short paragraphs per screen.
• Alternating backgrounds: Even/odd modules alternate between two warm background tones for visual rhythm
• Dark code blocks: IDE-style with Catppuccin-inspired syntax highlighting on deep indigo-charcoal (#1E1E2E)
• Depth without harshness: Subtle warm shadows, never black drop shadows

---

Reference Files

The references/ directory contains detailed specs. Read them only when you reach the relevant phase — not upfront. This keeps context lean.

• references/content-philosophy.md — Visual density rules, metaphor guidelines, quiz design, tooltip rules, code translation guidance. Read during Phase 2.5 (briefs) and Phase 3 (writing modules).
• references/gotchas.md — Common failure points checklist. Read during Phase 3 and Phase 4 (review).
• references/module-brief-template.md — Template for Phase 2.5 module briefs. Read only for complex codebases using the parallel path.
• references/design-system.md — Complete CSS custom properties, color palette, typography scale, spacing system, shadows, animations, scrollbar styling. Read during Phase 3 when writing module HTML.
• references/interactive-elements.md — Implementation patterns for every interactive element: drag-and-drop quizzes, multiple-choice quizzes, code↔English translations, group chat animations, message flow visualizations, architecture diagrams, pattern cards, callout boxes. Read the relevant sections during Phase 3.