The Unreasonable Effectiveness of HTML:
Why the Artifact Should Be the File You Keep

The default mental model for generated documents is the wrong one. We assume there is a canonical thing — a Markdown file, a database row, a notes doc — and that anything visual is a rendering of it: a preview, an export, a PDF-shaped courtesy for humans who can't read the source. Under that model the pretty version is disposable. You regenerate it; you don't edit it.

@trq212's argument in "The Unreasonable Effectiveness of HTML" inverts that. HTML is expressive enough to carry layout, type, color, state, interaction, and round-trip edits directly. So the artifact does not need a canonical document behind it. The HTML is the canonical document — the thing you read carefully, mutate, share with a non-CLI colleague, and revisit in six months. It is a file of record, not a screenshot of one.¹

render-as-html is an implementation of that thesis, not a rebrand of it. The borrowed claim is precisely the one above: the browser artifact becomes the working surface and the source of truth. What this skill adds on top is an opinionated design system and a set of page-shape contracts so the artifact stays useful past the first read instead of decaying into wall-of-text or generic-dashboard.

This has a sharp consequence for how the file is built. A converter that runs Markdown through a styler and stops has produced a preview, not an artifact. The interesting work is everywhere a browser is genuinely better than a text buffer: live filters, sortable headers, SVG generated from data, cross-highlighting, sliders, and the round-trip edit button. That is the rest of this briefing.

There is exactly one question that decides whether something earns the cost of being an HTML artifact: flatten it to static text — what disappears? If the answer is "the diagram, and the page is now ugly," you built styled prose. The styling is not the point; a paragraph that survives copy-paste into a plain editor was never an artifact in the first place.

The bar is concrete: a real artifact has at least three HTML-native features that die on flatten. Live filter that hides rows as you type. Click-to-cross-highlight. Inline SVG generated from data. Sortable headers. Toggles. And the load-bearing one — copy-as-prompt that round-trips state back to the file. Lose those and you lose function, not polish.²

The same discipline forces the shape decision before design. Prose-heavy briefing read paragraph-to-paragraph? document. Tabular ops data that wants filtering? dashboard. A sequential procedure being executed, not read? runbook. Picking the bones first is what stops every artifact from converging on the same identical-tile SaaS layout. The twelve shapes below are sortable by how interactive they inherently are; filter to the register you're working in.

Interaction Load is an editorial 1–8 estimate of how many HTML-native moves the shape's contract requires — higher means the shape cannot survive flattening. Color-scaled high → low within the column.

Filters and charts make an artifact pleasant. Copy-as-prompt makes it a workflow. This is the single feature @trq212 flags as load-bearing, and the reason render-as-html treats it as non-negotiable rather than nice-to-have.

The loop: you tune state in the browser — toggle items resolved, drag cards between buckets, move a weight slider — then press a button that emits a precise, paste-able instruction naming the .html file. You paste it into Claude Code, the file is rewritten, and you keep going. The artifact stopped being a thing you look at and became a thing you edit through.³

What separates a real round-trip from a "copy to clipboard" gimmick is the contract on the emitted text. It must name the artifact file so the agent knows what to edit. It must be specific deltas — "set --accent to hsl(18 70% 32%)", not "the user changed some things." It must be minimal: the changes, not the whole document restated. And it must read naturally as a user message when pasted.

// the load-bearing 20 lines
function copyPrompt() {
  const changes = collectChanges();   // read mutated DOM state
  const prompt =
    `In ${ARTIFACT_PATH}, apply these changes:\n` +
    formatAsInstructions(changes);    // deltas only, not the whole file
  const out = document.querySelector('#prompt-output');
  out.value = prompt;
  writeClipboard(prompt).catch(() => {
    out.focus(); out.select();        // visible fallback if clipboard blocked
  });
}

The cost is roughly twenty lines of vanilla JS per round-trip. The return is an artifact that participates in its own revision instead of being regenerated from scratch every time a number changes. That asymmetry — trivial cost, structural payoff — is why the skill refuses to ship "copy as markdown" buttons that imply some other format is canonical. The prompt targets the HTML file, because the HTML file is the thing.

The flatten test is a yes/no, but the decision underneath it is graded. Most content is not all-prose or all-instrument; it leans. The honest way to make the call is to enumerate what the artifact actually needs to do and let the weight of those answers pick the shape — not to default to a dashboard because dashboards look busy and impressive.

The scorer below does exactly that. Check what the artifact genuinely needs, set how often it changes and who reads it, and it computes a 0–100 instrument score, a verdict, and the render-as-html shape that best fits the answers. Every weight is visible; nothing is hidden. This widget is the section's argument — flatten the page and the math, the verdict, and the recommendation all die, which is the whole point being made.

Score = sum of checked feature weights (copy-as-prompt is the heaviest at +20, mirroring the skill's "load-bearing" call), capped at 100. Frequent revisions and a wider audience nudge the verdict toward an artifact even at a mid score, because a static doc that gets re-edited weekly is the worst of both worlds.

The recommendation is internally consistent with the skill's contracts: pick spatial or graph features and it points at network-map; pick drag and bucketing and it points at triage-board; pick almost nothing and it tells you, honestly, that a static document is fine. The tool is willing to talk you out of an artifact. A scorer that always says "yes, build the fancy thing" would be marketing, not a bar.

The flatten test tells you whether to build an artifact. The eight information dimensions tell you whether you're actually using the medium once you have. @trq212's framing names eight things HTML can carry that plain text cannot, and the skill's self-check is blunt: name the four-plus you used; if you can only name two, you under-leveraged the medium.

Tables — real rows and columns, sortable. Design — color, type, and spacing as information, not decoration. Illustrations — inline SVG diagrams generated from the data. Code — highlighted with local CSS classes, no CDN. Interaction — sliders, toggles, JS-driven UI. Workflows — boxes, arrows, sequence, state. Spatial — coordinates with actual positional meaning. Images — embedded figures via data URI or local relative paths.⁴

This very page leans on at least five: the sortable shapes table, color and type doing semantic work, two SVG charts built from values, syntax-highlighted code with hand-written classes, and the live scorer. Count them honestly before saving — the dimension audit is a guardrail against shipping prettified prose that technically renders but carries nothing the medium uniquely affords.

Density is the other half of the discipline, and the counterintuitive rule is that progressive disclosure beats showing everything. The footnotes on this page are open by default — the full body is right there, no click required — but each keeps its collapse affordance so a reader skimming the argument can fold the apparatus away. Inline ^¹²³ references are keyboard-operable links that scroll to and flash their footnote. None of that survives flattening, and that is the point: the disclosure structure is information architecture, not chrome.

The reading register earns its restraint here. Seventeen-pixel serif body, a measure capped near 70 characters even when the chrome is wide, real horizontal rules between sections instead of boxed borders, and no left-handle accent bars — the visual fingerprint of generated layouts the skill explicitly bans. Emphasis comes from type, whitespace, rule, and position. An instrument-register artifact would make the opposite trades; the shape decides, not taste applied ad hoc.

There is a tell that separates a design system that believes its own thesis from one that merely documents it. render-as-html's canonical reference — the file that defines every token, shape contract, and primitive — is itself a single self-contained HTML artifact. The gallery is rendered in the system it specifies. The proof of the claim is the form the claim arrives in.⁵

This is not a cute flourish. It is the strongest available argument for the whole approach. If HTML-as-source-of-truth worked only for other people's reports and the system's own documentation needed a "real" canonical format behind it, the thesis would be self-refuting. Instead the design system eats its own cooking: one file, inspectable, editable, served however you like, no build step, no framework, no CDN.

The same constraints bind this very briefing, and you can verify them by flattening it. Single file. Inline CSS and vanilla JS. Zero external assets, fonts, or network requests. What dies on flatten is not cosmetic: the live shapes filter and sort, the flatten-test scorer's entire computation and recommendation, the footnote scroll-and-flash, the copy-as-prompt round-trip on every section. Strip the browser and you strip the function. That is the difference between an artifact and a screenshot of one.

Everything here is downstream of one borrowed idea, credited plainly: HTML is unreasonably effective, so let the artifact be the thing. The design system and shape contracts are this repo's contribution on top. The thesis is @trq212's, and the content-matched-shapes framing is from clockless-org/html-anything — both cited in the footnotes because attribution is part of the discipline too.