HTML Artifacts (ARTIFACTS.md)
HTML artifact conventions — when to prefer HTML over markdown, directory layout, artifact types, and two-way interaction patterns.
This file configures Claude to produce HTML artifacts — not markdown — for specs, reports, PR explainers, design prototypes, and custom editors. When this file exists, Claude follows the directory layout, naming, and patterns below.
Background: HTML carries far more signal than markdown (tables, CSS, SVG, interactions, copy-as-prompt buttons) and is easier to share. With 1MB context windows the extra tokens are noise. Markdown stays for files you edit by hand; HTML takes over for files you only read.
When HTML, when Markdown
Mental model (Shann Holmberg, building on Thariq):
Markdown for agents only. HTML for agents and humans.
Every rule below follows from this: the moment a human enters the loop — review gate, sharing, sign-off, browse-without-grep — switch to HTML. If only agents read and write the file, markdown is fine.
Karpathy's progression: raw text → markdown (current default) → HTML (the new forming default — flexibility on graphics, layout, interactivity) → eventually interactive neural simulations. We're aiming for the third rung.
Minimum invocation: end your prompt with "structure your response as HTML"
(or "as a slideshow", "as a single-page artifact"). That's it. No skill, no
scaffolding required.
Prefer HTML when one or more is true:
- Output will exceed ~100 lines (nobody reads a long markdown plan)
- The reader is someone other than you (sharing matters)
- The content benefits from layout, color, diagrams, side-by-side comparison
- Two-way interaction would help (sliders, knobs, "copy filled prompt" buttons)
- You want SVG flowcharts, not ASCII
Keep markdown for: tasks/lessons/, tasks/decisions.md, tasks/todo.md,
tasks/handoff-*.md, ADRs, short notes — anything edited by hand or grepped.
Directory
artifacts/
index.html # Catalog — links to every artifact, kept current
design-system.html # Reference tokens (colors, type, spacing) — Claude mirrors this
YYYY-MM-DD-<slug>.html # Generated artifactsConventions
- File names: date prefix + kebab-case slug →
2026-05-11-onboarding-spec.html - Every artifact mirrors
design-system.html's tokens (read it before generating) - After creating an artifact, append a row to
index.htmlwith title, date, type, link - Standalone files — embed CSS and JS inline. No external deps, no build step. An artifact must work when uploaded to S3 and opened by a colleague.
- Use inline SVG for diagrams, never ASCII
Artifact Types
| Type | Use for | Key elements |
|---|---|---|
spec | Implementation plan, design exploration | Mockups, code snippets, tradeoff tables, N-up grid |
pr-explain | PR or code review writeup | Diff blocks, inline annotations, severity colors |
report | Research, weekly recap, incident, deep-dive | SVG diagrams, sections, summary box |
slideshow | Decks, presentations, "show this to leadership" | One section per slide, keyboard nav, progress bar |
design | Component prototype, animation tuning | Sliders/knobs, live preview, copy-params button |
editor | Throwaway data editor (triage, config, prompt) | Copy-as-JSON / Copy-as-prompt export button |
Two-way Interaction
When an artifact accepts input, it must include an export button so the user's work returns to Claude Code as paste-able text:
| Artifact | Required button |
|---|---|
| Editor (any kind) | Copy as JSON or Copy as markdown |
| Design tuner | Copy params (JSON blob of slider values) |
| Prompt playground | Copy filled prompt |
| Triage/reorder | Copy as ordered list |
Implementation: a single button → navigator.clipboard.writeText(JSON.stringify(state)).
No frameworks needed.
Sharing
To share externally: upload the file to S3/CDN and send the link. Since every artifact is standalone, no build pipeline is required.
For local viewing: open artifacts/<file>.html (macOS) opens it in the default
browser. Claude can run this for you.
Anti-patterns
- No generic
/htmlskill — let the prompt's intent drive the artifact type - No multi-file artifacts — one file, one purpose, one open-in-browser action
- No build tooling — no React, no bundlers, no npm install
- No reusing a 500-line boilerplate — start from the prompt, not a template
- No omitting
design-system.html— artifacts will drift in style otherwise - No mixing tasks/ into artifacts/ — tasks/ stays markdown (edited by hand)
Index Maintenance
After creating any artifact, update artifacts/index.html:
- Add a row to the catalog table: date | type | title | link | one-line purpose
- Keep newest entries at the top
- If an artifact is superseded by a newer version, mark the old row as superseded (don't delete — history matters)
If index.html is missing or stale, regenerate it from the artifacts/*.html
files on disk (read each file's <title> and <meta name="artifact-*"> tags).
Artifact Metadata
Every artifact should declare itself in <head>:
<title>Onboarding Screen Spec — 2026-05-11</title>
<meta name="artifact-type" content="spec">
<meta name="artifact-date" content="2026-05-11">
<meta name="artifact-purpose" content="Compare 6 onboarding layouts">This makes index.html regeneration trivial.