Jonathon's AI Wiki

The Unreasonable Effectiveness of HTML (Thariq) — When the Agent Should Skip Markdown

10 min read

Source: ai-research/html-effectiveness-thariq-2026-05-11.md — thariqs.github.io/html-effectiveness/ (fetched 2026-05-11). Companion gallery to a blog post by Thariq (handle thariqs on GitHub Pages) showcasing 20 self-contained .html files an agent produced instead of a wall of markdown, grouped into 9 use-case sections.

A short, opinionated argument — backed by 20 working examples — that the default “agent returns a wall of markdown” output mode wastes the medium. Spatial information (diffs, module maps, design tokens, timelines, flowcharts, animation curves, multi-pane comparisons) is flattened by markdown but rendered natively by HTML. The companion gallery lays out concrete demos: “ask the agent for this instead, and you’ll actually read it.” Pairs naturally with Claude Design (which makes the same argument as a productized canvas), frontend-slides (one HTML preset family for decks), beautiful-html-templates (30-template AGENTS.md gallery), and Impeccable v3 (37-pattern AI-slop catalog for what NOT to do when generating HTML).

Key Takeaways

  • Thesis in one line. “Twenty self-contained .html files an agent produced instead of a wall of markdown. Each one trades a document you’d skim for one you’d actually read.” The gallery itself is the evidence — open any of the 20 files in a browser; none of them require a build step.
  • 9 use-case sections × 20 demos total. Each section opens with a one-paragraph rule of thumb explaining when HTML beats markdown for that kind of work. The categories are: Exploration & Planning (3), Code Review & Understanding (3), Design (2), Prototyping (2), Illustrations & Diagrams (2), Decks (1), Research & Learning (2), Reports (2), Custom Editing Interfaces (3).
  • Spatial-information argument. “Diffs and call-graphs are spatial information; markdown flattens them.” The pitch is structural — anything with side-by-side comparison, dependency arrows, motion, timestamps, or interactive controls loses information when serialized as a single linear scroll.
  • One-file artifacts, no toolchain. Every demo is a single .html file. No bundler, no React framework, no asset pipeline — the agent emits one file you double-click in Finder. The footer underscores it: “Everything on this page is itself a single .html file.”
  • HTML as the design-system medium. The Design section makes a load-bearing point: “HTML is the medium your design system ships in, so it’s the natural format for talking about it. Tokens become swatches, components become contact sheets, and the artifact can be fed straight back into the next prompt.” HTML closes the loop between design discussion and design output.
  • Custom editors as a category. The most underused: ask the agent for a throwaway editing UI for the specific thing you’re working on (ticket triage board, feature-flag toggles, prompt-template tuner) and end with a “copy back as markdown / JSON / diff” button. You stay in the loop and the loop gets tighter.
  • HTML where motion is the point. “Motion and interaction can’t be described, only felt. A throwaway page with the real easing curve or the real click-through tells you in five seconds what a paragraph of prose never could.” Animation sandboxes and clickable flows are five-second decisions in HTML, paragraphs of speculation in markdown.
  • SVG as the agent’s pen. “Inline SVG gives the agent a real pen.” Diagrams, figure sheets, and flowcharts where the LLM produces vector art directly — no Mermaid handoff, no DOT export, no Excalidraw round-trip.
  • No claimed metrics, no benchmarks. This is an aesthetic and informational-density argument, not a benchmark study. The “unreasonable effectiveness” framing borrows from the Wigner essay tradition — the point is that a default behavior most people overlook turns out to dominate when measured by did the reader actually consume it.
  • Visual taste signature is itself the demo. Thariq’s masthead pairs an ivory/slate/clay/oat/olive palette + serif headline (italic emphasized in clay) + mono microtype against a hero figure that literally draws “markdown pane” (tilted grey lines) vs “HTML pane” (cards, bar chart). The page is its own first example.

The 9 categories — when to ask for HTML

CategoryDemosWhen HTML wins
Exploration & Planning3Fan out 2-3 approaches; place them side-by-side; let the operator point at one. Then turn the pick into an implementer-ready plan (timeline + data-flow + mockups + risk table).
Code Review & Understanding3Annotated diffs, PR writeups with the why, and module maps drawn as boxes-and-arrows. Diffs and call-graphs are spatial; markdown flattens them.
Design2Living design system (tokens → swatches, type scale → live samples) and component variant sheets. HTML is already the medium the design system ships in.
Prototyping2Animation sandboxes with tunable sliders; clickable 4-screen interaction flows. Motion can’t be described, only felt.
Illustrations & Diagrams2Inline SVG figure sheets for blog posts; annotated flowcharts where you can click any step. The agent’s actual pen.
Decks1Arrow-key navigable slide deck as one HTML file. No Keynote, no build step.
Research & Learning2Feature explainers (TL;DR + collapsible request-path steps + tabbed config snippets + FAQ); concept explainers with live interactive simulations (consistent-hashing ring, comparison table, hover-glossary).
Reports2Weekly status with a small chart; incident timelines with log excerpts and follow-up checklists. Recurring documents that benefit from structure.
Custom Editing Interfaces3Ticket triage board (drag across Now/Next/Later/Cut → copy out as markdown), feature-flag editor (dependency warnings + diff button), prompt tuner (template + live-render samples).

The 20 demos (verbatim filenames)

Exploration & Planning: 01-exploration-code-approaches.html, 02-exploration-visual-designs.html, 16-implementation-plan.html · Code Review: 03-code-review-pr.html, 17-pr-writeup.html, 04-code-understanding.html · Design: 05-design-system.html, 06-component-variants.html · Prototyping: 07-prototype-animation.html, 08-prototype-interaction.html · Diagrams: 10-svg-illustrations.html, 13-flowchart-diagram.html · Decks: 09-slide-deck.html · Research: 14-research-feature-explainer.html, 15-research-concept-explainer.html · Reports: 11-status-report.html, 12-incident-report.html · Editors: 18-editor-triage-board.html, 19-editor-feature-flags.html, 20-editor-prompt-tuner.html.

Each file is reachable as a relative link from the index page (e.g. https://thariqs.github.io/html-effectiveness/03-code-review-pr.html).

Implementation

Tool/Service: None — the gallery is a static GitHub Pages site. The artifact this article reflects on is a pattern for agent output, not a runnable tool. Apply it inside Claude Code, Claude Cowork, or Claude Design by asking for HTML where you would have asked for markdown.

Setup: Add to your CLAUDE.md or system prompt a rule like:

When the answer involves any of:
- side-by-side comparison of 2+ options,
- spatial relationships (diffs, call graphs, dependency maps),
- motion or interaction,
- design-system content (tokens, components, swatches),
- a recurring report (weekly status, post-mortem),
- a throwaway editing UI tied to my current task,

prefer a single self-contained .html file over a markdown wall.
Include inline CSS + SVG; no build step. End custom editors with a
"copy back as markdown / JSON" export button.

Cost: Pure HTML output adds nothing measurable to token cost vs equivalent markdown; the output token count is comparable. The win is in operator-side time-to-decision and information density, not API economics.

Integration notes:

  • Pairs with Claude Design — Claude Design is the productized canvas version of this thesis. Use Claude Design when the artifact needs iteration through five input modes (chat, voice, hover, draw, screenshot); use raw HTML output when the operator just needs the file once and gone.
  • Pairs with frontend-slides — the Decks category here is one demo; frontend-slides is the 12-preset productized version of the same idea for Karpathy-style wiki decks.
  • Pairs with beautiful-html-templates — 30-template AGENTS.md gallery by zarazhangrui. Same shape (single-file HTML), broader visual range, opinionated 6-step shortlisting flow with 3-preview comparison.
  • Pairs with Impeccable v3 — Jay Yang’s 37-pattern AI-slop catalog tells the agent what NOT to do when generating HTML; this gallery tells it what TO do.
  • Anti-pattern guard rail. Don’t ask for HTML when the actual answer is short and linear (a one-line fix, a yes/no, a quick summary). The thesis is for information-dense output where structure is load-bearing. The wall of markdown is itself a tell — if the agent is about to write 2000 words with three side-by-side sections, intercept and ask for the HTML.

Try It

  • One-click test on your next code review. Next time you ask Claude to summarize a diff, append “render this as a single-file HTML annotated PR review with margin notes, severity tags, and jump links — exactly like thariqs.github.io/html-effectiveness/03-code-review-pr.html.” Compare reading time and decision speed against the markdown version.
  • Replace your next weekly status with 11-status-report.html. Ask Claude to take your week’s git log + Linear ticket close-outs + KPI snapshot and emit a single-file weekly status with a small inline chart. Skim it once and decide whether it’s faster than the markdown version you usually send.
  • The custom-editor recipe. Pick one task this week where you wish you had a 10-minute throwaway UI — sorting 30 backlog items, tuning a prompt template, picking among 5 visual directions for a hero. Ask Claude for it as a single-file HTML editor with an export button. The pattern from 18-editor-triage-board.html / 19-editor-feature-flags.html / 20-editor-prompt-tuner.html is reusable.
  • Pair with Impeccable v3’s /critique skill. Generate a candidate HTML artifact, then run it through the Impeccable 37-pattern catalog to catch AI-slop visual defaults (gradient overuse, soft-shadow Stripe-clone aesthetics, lazy emoji icons). The combination gets you better-looking artifacts faster than either tool alone.
  • For WEO Marketly client comms. Replace plain-markdown audit deliverables with HTML status reports (a single-file site audit, an incident timeline of a deployment regression, a competitive teardown rendered as a side-by-side comparison). The artifact is more polished, but the cost is the same prompt.
  • For the karpathy wiki publication layer. Most wiki articles want to stay markdown for editability + Quartz portability. But specific high-density artifacts — Claude Code surface comparisons, the weekly digests feature matrices, the claude-vision vs claude-video comparison table — could ship as <topic>/decks/<name>.html artifacts living next to the markdown. The companion-file pattern would extend slot.

Open Questions

  • Where is the companion blog post? The page eyebrow says “Companion to the blog post” but the HTML contains no link to the originating essay. The blog post itself was not fetched in this ingest — a follow-up fetch on Thariq’s primary site (x.com handle, personal blog) would close that loop.
  • Token-cost calibration. No measurement here on whether HTML output costs more output tokens than equivalent markdown. Anecdotally similar for the same information density, but worth a 5-run benchmark on a representative task (e.g. a weekly status report) to confirm.
  • When does HTML lose? The article argues for HTML in 9 categories but doesn’t articulate the anti-cases. Inferred anti-cases: short linear answers, code-only outputs that get pasted into an editor, anything destined for grep/copy-paste-into-CLI workflows. Worth a future article documenting the explicit “use markdown here” guardrails.
  • Author scope. Thariq’s broader stack and prior work weren’t probed by this ingest. Whether the gallery is part of a larger LLM-engineering body of work is open. ^[inferred] Based on the GitHub Pages handle alone, no other context fetched.
  • No measurement of operator decision speed. The qualitative claim “a document you’d actually read” is the load-bearing argument but lacks A/B data. A small in-team experiment (5 operators, 1 markdown variant vs 1 HTML variant of the same content, measure time-to-decision) would either calibrate or refute the thesis.

Graph View

Backlinks