teaching-app-builder

intent

take raw teaching content (lecture notes, concept explanations, textbook passages, knowledge points) and transform it into a single self-contained .html file that runs instantly in any browser without server, build step, or external dependencies. the skill covers content analysis, interaction design, library selection, color theming, and assembly into a deliverable that makes abstract concepts tangible through charts, diagrams, step-by-step walkthroughs, formula visualizations, and interactive simulations. use this when a user wants to make content web-displayable, interactive, or visually explained, whether they explicitly say "teaching app" or just ask to "make a web demo of this," "visualize this section," or "turn this into an interactive slide."

inputs

• teaching content (text, markdown, or structured outline): the knowledge to be explained. can be lecture notes, textbook paragraphs, concept definitions, process descriptions, or data-driven narratives. accepts chinese or english.
• reference files (from skill knowledge base, auto-available):
  • references/skeleton.md: html/css/js boilerplate, ui atoms (card, button, callout, badge, grid), quality checklist.
  • references/cdn-catalog.md: verified cdn urls for all libraries (bootcdn, staticfile, 360, npmmirror) with fallback links, grouped by library name and version.
  • references/color-schemes.md: 6 professional color palettes (deep-space blue, academic paper, fresh mint, warm ochre, indigo business, dark neon) with css :root variables, 60-30-10 usage guidance.
  • references/libraries.md: initialization snippets, config examples, and common pitfalls for Chart.js, ECharts, Mermaid, KaTeX, MathJax, SVG.js, Rough.js, D3, anime.js, GSAP, Highlight.js, marked, Reveal.js.
  • references/components.md: zero-dependency interactive components (tabs, accordion, stepper, slider, quiz, glossary tooltip, toc navigation).
• output path (optional): where to write the .html file. defaults to current working directory if not specified.
• design preferences (optional): preferred color scheme, interaction complexity level (minimal/moderate/rich), target audience or subject domain.

procedure

1. analyze content and define teaching goals

read the input text. identify the core concept(s), what learners should understand or be able to do after encountering the app. scan the content for claims that are abstract, multi-step, parametric, or require comparison or hands-on trial. map each claim to one of: "static text plus an image is enough," "needs step-by-step reveal," "needs a chart," "needs a diagram," "needs a formula," "needs learner interaction." only apply interaction to the latter group. do not over-engineer; interaction should serve clarity, not decorate.

input: raw teaching text. output: list of knowledge points with interaction type assigned to each (or "no interaction needed").

2. map content to interaction form

use the decision table to assign each point to an interaction pattern:

input: list of knowledge points with interaction needs. output: list of (point, form, library) tuples and library set to acquire.

3. select libraries (minimal set)

prioritize zero-dependency: tabs, accordion, stepper, slider linking, quiz, toc, glossary tooltip are built-in html/css/js (see components.md). do not introduce a framework just for these. only add external libraries if you must: charts, formulas, complex diagrams, sophisticated animation. cross-reference each library with libraries.md to get correct init snippet and common gotchas. verify every library url in cdn-catalog.md before adding it to the html head. do not improvise cdn urls from memory. ensure all cdn urls point to mainland-china-accessible hosts (bootcdn, staticfile, 360, npmmirror) unless user explicitly allows international cdns.

input: library set from step 2, cdn-catalog.md, libraries.md. output: list of <script> and <link> tags with verified cdn urls, and init code snippets.

4. select color scheme

choose one of the 6 palettes from color-schemes.md based on subject domain and tone (deep-space blue for tech, academic paper for formal, fresh mint for friendly, warm ochre for creative, indigo business for corporate, dark neon for cutting-edge). copy its :root css block into the html <style>. all colors must use var(--name) references, never hard-code hex. observe 60-30-10: primary color and accent color are the "salt," do not carpet-fill the background with color. apply color scheme to mermaid, echarts, and other library outputs so they match the page.

input: subject/tone, color-schemes.md. output: :root variable block, color-matched component styles, library-specific color config.

5. assemble single file and self-check

use skeleton.md as the structural foundation (it includes generic ui atoms: card, button, callout, badge, grid). drop your content sections and interaction code into the body. ensure all js is inline (no external .js files). ensure all css is in a single <style> block. use the Write tool to write the final .html file to disk. do not paste the entire source into the conversation; instead, provide the file path and a one-sentence summary ("this app explains entropy using an interactive heat-map chart (ECharts) and a three-step process stepper, color scheme deep-space blue"). after assembly, run through the quality checklist at the end of skeleton.md: double-click opens the file, no console errors, all links (cdn and internal anchors) work, responsive on mobile, color contrast meets wcag aa, no fabricated data or citations.

input: content, interaction code, styles, cdn tags, color scheme. output: single .html file, path, summary.

decision points

• if user provides chinese teaching content: default ui language to chinese (labels, headings, button text). preserve content tone and terminology. if text mixes languages, follow the majority.

• if user asks for "slides" or "ppt" or "flipbook": use Reveal.js (only then). otherwise, do not include reveal; a teaching app is typically a single scrolling page with sections, not a slide deck.

• if content has multiple scenarios or "what-if" branches: use tabs, accordion, or side-by-side comparison (zero-dependency components.md) to show alternatives without clutter.

• if user specifies a color scheme by name or preference: use that. else pick one that fits the subject (science/math → deep-space blue, formal lecture → academic paper, kids/friendly → fresh mint).

• if a library url fails to load (cdn timeout, mainland-china block): fall back to the secondary url listed in cdn-catalog.md, or prompt user to provide a vpn/proxy. do not attempt to bundle libraries locally; this breaks the single-file constraint.

• if the content is mathematical or formula-heavy: default to KaTeX (faster, lighter, works well for standard math). use MathJax only if content includes complex amsmath environments or non-standard symbols.

• if the content describes a sequential process or multi-step algorithm: use a stepper component (zero-dependency, see components.md) with visual aids (svg or diagram) at each step. do not use reveal.js for this; steppers are more appropriate.

• if the user only provides a vague brief ("make it interactive" without specifying what form): ask clarifying questions: "what's the hardest part for learners to grasp?" "would learners benefit more from seeing a visualization, or stepping through a process?" base interaction choice on the answer, not on impulse.

• if the content includes code snippets: use Highlight.js (library.md) for syntax highlight. if user wants markdown rendering of code blocks, also include marked. strip any sensitive credentials from example code.

• if result set is empty or data is sparse: communicate this in the app (e.g., "no data available for this scenario" callout). never fabricate placeholder data or statistics to fill white space.

• if a chart or diagram has no natural data: simplify to a conceptual svg or a text diagram (mermaid); do not force a chart where a simple illustration suffices.

output contract

deliverable: one .html file, written to disk via the Write tool.

file naming: kebab-case reflecting the topic (e.g., entropy-explained.html, photosynthesis-steps.html, supply-demand-curves.html). no timestamps or version numbers in filename.

file format: valid html5, all css and js inlined, no external stylesheets or script files except cdn <link> and <script> tags in the <head>. doctype is <!DOCTYPE html>. charset is utf-8.

location: user-specified path, or current working directory if not specified. response must include full path (e.g., /Users/alice/teaching-apps/entropy-explained.html).

cdn urls: all external resources loaded via mainland-china-accessible cdn (bootcdn, staticfile, 360, npmmirror). urls verified against cdn-catalog.md. fallback urls included in comments if primary cdn is blocked.

color variables: all colors via :root css custom properties, never hard-coded hex or rgb. color scheme applied to library outputs (mermaid, echarts, highlight.js) so they match page palette.

responsive design: app adapts to mobile (320px width minimum) without horizontal scroll. fonts, spacing, chart height scale appropriately.

interaction code: all interactive components either zero-dependency (pure html/css/js) or via verified cdn library. no build step, no node_modules, no preprocessor.

accessibility: color contrast wcag aa or higher, semantic html5 tags, alt text on images and diagrams, keyboard navigation for interactive elements (tab order, arrow keys for steppers/tabs).

no fabricated content: all data, citations, examples, and formulas come from the input text or common knowledge. uncertain claims marked with "[citation needed]" or omitted entirely.

quality checklist (from skeleton.md): double-click on the file opens it in browser, no console errors, all cdn links load (test in incognito mode), responsive on iphone 6 and desktop, no missing fonts or broken layout, color scheme consistent, interaction responsive (no lag, no dead buttons).

outcome signal

• file successfully written: response includes a concrete file path and confirmation message ("written to /path/to/file.html").
• user can open the app: double-clicking the .html file in file explorer opens it in the default browser, fully rendered, no build step or server required.
• content is clear and accurate: the app explains the teaching concept faithfully, using the interaction forms chosen in step 2. abstract becomes tangible; multi-step becomes clickable; parametric becomes slidable.
• interaction works: charts respond to clicks/hovers, steppers advance on button press, sliders drive formula updates, tabs switch instantly, quizzes give feedback, accordion expands/collapses smoothly. no errors in browser console.
• design is professional: colors follow 60-30-10, typography is readable, spacing is consistent, no jarring combinations, layout does not break on phone or desktop.
• learning goal is met: after using the app, a learner can articulate or demonstrate the concept better than from the original text alone. interaction deepens understanding, not distraction.