HTML Output

HTML Output

Purpose

Produce HTML when browser-native structure improves cognition, auditability, presentation, or exploration. Treat HTML as an artifact format, not decoration.

For research-learning deliverables, HTML is the Canonical Reading Surface. It should contain the main substance as a textbook chapter, mini-textbook, or complete course page. Markdown, notebooks, source matrices, and Obsidian notes can support the HTML, but they must not be where the real lesson hides.

When the Canonical Reading Surface is a substantial lesson, chapter, course, or field guide, use learning-session and apply its canonical textbook lesson contract as the content specification. html-output remains responsible for semantic implementation, interaction, accessibility, evidence display, artifact equivalence, and render verification.

Workflow

1. Decide whether HTML is the right medium.

   • Prefer a concise chat answer for small questions.
   • Prefer Markdown for durable text-first notes.
   • Prefer HTML when layout, tables, diagrams, charts, progressive disclosure, interaction, or simulation would materially improve the result.
   • If the medium is ambiguous and the artifact will take meaningful effort, state the tradeoff or ask.

2. Choose the artifact shape before writing code.

   • Purpose: audit, learn, compare, decide, present, explore, or simulate.
   • Shape: report, dashboard, explainer, timeline, map, table, notebook-style page, simulation, textbook chapter, mini-textbook, or course.
   • Verification: identify what must render or work before calling the artifact done, including any artifact equivalence checks against source Markdown or notebooks.

3. Build a self-contained artifact by default.

   • Before creating HTML, read references/style.md unless the user provides a conflicting one-off style.
   • Use semantic HTML: header, main, section, nav, figure, figcaption, table, button, input, and labels where appropriate.
   • Use responsive CSS with stable dimensions and no text overlap.
   • Use minimal JavaScript. Add interactivity only when it helps the user's task.
   • Avoid external assets and CDN libraries unless they materially reduce risk or complexity.
   • If external resources are used, explain the dependency and prefer integrity/version pinning when practical.

4. Make evidence visible inside the artifact.

   • For research-based artifacts, include source notes, citation links, uncertainty labels, or a source matrix.
   • Separate facts, interpretation, and recommendations.
   • Do not let visual polish hide weak evidence.

5. For dense research or learning artifacts, make the HTML teach.

   • Include the actual lesson body in the HTML, not just a hero, table of contents, source spine, or links to a Markdown course.
   • Apply the learning-session textbook contract for chapter architecture, exposition, field-appropriate rigor, worked reasoning, counterexamples, progressive exercises, synthesis, and transfer.
   • It is fine to point to original sources for deeper study, but the user should be able to learn the core material from the HTML alone.
   • Run an artifact equivalence check when source Markdown, notebook text, or a memo exists: compare headings, core claims, key examples, exercises, and representative phrases.
   • Record rendered text length or another substance metric for large artifacts so a short shell cannot masquerade as a full lesson.

6. Verify the artifact.

   • Open/render the HTML when visual correctness matters.
   • Check desktop and narrow widths for nontrivial layouts.
   • Inspect for blank canvases, missing assets, hidden overflow, overlapping text, and console errors.
   • For interactive elements, click/type/operate the main controls.
   • Run accessibility checks when feasible, especially for tabs, dialogs, forms, or custom widgets.
   • Check semantic rendering fidelity: math, code, figures, captions, cross-references, citations, footnotes, tables, and generated anchors must survive conversion and render as intended.
   • Search for placeholders or conversion artifacts such as missing equations, ??, doubled labels, empty sections, broken source references, and suspiciously short lesson sections.

Design Standards

• Use native HTML controls before custom widgets.
• Keep typography readable; do not use tiny text to force dense content.
• Use progressive disclosure for dense sections, but keep the core answer visible.
• Do not hide the main teaching substance behind collapsed sections only; a reader should be able to scan the page and see that it is a substantive lesson.
• Choose charts from the data and task, not novelty.
• Prefer simple tables and small multiples over clever but unclear visualizations.
• Keep animation purposeful, brief, and nonessential.
• Make the page usable without relying on color alone.

Safety Standards

• Treat untrusted text as data, not executable markup.
• Do not inject user-provided HTML or script into the page without sanitization.
• Avoid remote scripts for private or sensitive artifacts.
• If the HTML may be shared or hosted, be stricter about CSP, sandboxing, dependency integrity, and data exposure.

Final Response

Report:

• The HTML file path.
• What was verified.
• Whether the HTML was the Canonical Reading Surface and what substance/equivalence checks passed.
• Any dependencies or limitations.
• Any parts not verified.