Create HTML Artifacts

Overview

Create a self-contained .html artifact when browser layout, interaction, or visual hierarchy will help a reader understand, decide, review, or hand off work. HTML is the medium; the goal is better cognition.

Prefer Markdown when the content is mostly linear prose, needs collaborative text diffs, or gains nothing from spatial layout.

Workflow

1. Identify the reader, their task, and the decision or handoff the artifact must support.
2. Choose the artifact shape from references/artifact-selection.md.
3. Use assets/templates/base.html as the starting shell when creating a new file.
4. Pull only needed snippets from references/recipes.md.
5. Build one portable .html file with inline CSS, inline SVG, and vanilla JS. Avoid CDNs, build steps, package installs, and external assets unless the user asks.
6. Put the highest-value readout above the fold: purpose, TL;DR, status, scope, sources, recommendation, or next decision.
7. Let layout carry meaning: comparisons side by side, flows as diagrams, risks as tables, sequences as timelines, states as contact sheets, and tunable decisions as controls.
8. Verify with scripts/check-html-artifact.py <file.html> and, when practical, open or screenshot the artifact at desktop and narrow widths.