Visual Explainer · Full Synthesis

The Unreasonable Effectiveness of HTML

A full visual synthesis of Thariq’s article arguing that HTML is a better default artifact format than markdown for many agent workflows.
Core claim
The article’s real thesis is not just “HTML looks better.” It’s that artifact format changes whether humans stay meaningfully in the loop. As agents produce bigger specs, reviews, plans, and tools, markdown becomes too linear and too easy to ignore. HTML makes those outputs denser, more legible, more shareable, and sometimes interactive.
6
Main arguments
5
Major use patterns
2–4×
Slower than markdown
1
Emotional payoff
Source frame
Important nuance: the article is about using HTML as a communication surface for agent output, not just as a frontend technology.
1 — The Thesis, Precisely

Markdown became the default because it is simple, portable, mildly rich, and easy for humans to edit. But Thariq’s workflow has changed: he is increasingly not hand-editing the files himself. Instead, agents produce specs, planning documents, brainstorm outputs, reviews, and mockups. Once that happens, markdown’s biggest advantage weakens, and HTML’s expressive range starts to dominate.

Markdown default
  • Cheap to write
  • Portable
  • Easy to edit directly
  • Good for short linear documents
HTML default
  • Better at visual hierarchy
  • Better at comparison and dense information
  • Can be interactive
  • Easy to share as a link

Format is not cosmetic here. The format changes what people will actually read.

2 — Why HTML Wins

The article lays out several reasons. The first four are the structural core: information density, readability, sharing, and interaction. Then it adds two more: better data ingestion when used from Claude Code, and the simple fact that making these artifacts is more joyful.

Ctrl/Cmd + wheel to zoom. Scroll to pan. Drag to pan when zoomed. Double-click to fit.

Loading...
Information density
  • Tables instead of ASCII hacks
  • CSS and layout for structure
  • SVG for diagrams and illustrations
  • Script tags for richer snippets/behavior
Visual clarity
  • Large specs become navigable
  • Responsive layouts improve phone reading
  • Tabs, links, and sections reduce friction
Ease of sharing
  • Upload once, share a URL
  • No special markdown renderer needed
  • Higher chance coworkers actually open it
Two-way interaction
  • Sliders and knobs for tuning designs or algorithms
  • Controls that export changes back into prompts
  • Documents become lightweight playgrounds
Data ingestion
  • Claude Code can inspect files, git history, browser context, MCP tools
  • That context can be turned into a richer report artifact
  • This is one reason to use Claude Code over a plain chat surface
It’s joyful
  • The author explicitly says it is simply more fun
  • That emotional involvement matters
  • More engagement means more review, iteration, and trust
3 — The Workflow Shift Underneath It

This is the deeper layer: the article is really about a changed human-agent relationship. If humans are mostly steering, inspecting, comparing, and exporting rather than hand-authoring every line, then the artifact should optimize for review and interaction, not just editability.

Question Markdown-first workflow HTML-first workflow
Primary human role Edit and annotate the document directly Inspect, compare, tune, and steer the artifact
Artifact shape Single linear note/spec Page, dashboard, explainer, prototype, or mini-tool
Best for Short plain documents Dense, multi-modal, shareable artifacts
Human bottleneck Stops reading after ~100 lines Can navigate visually and actually finish reading
Key sentence the page should preserve: when you no longer directly edit these files much yourself, one of markdown’s largest benefits fades away.
4 — The Use Cases the Article Actually Names

The article is concrete, not abstract. It gives repeated examples across several categories. Those examples matter because they show HTML is not just for reports — it is useful anywhere the agent is trying to help a human compare, review, tune, or understand something complicated.

Specs, planning & exploration
  • Explore multiple implementation options
  • Compare visual designs side by side
  • Create an implementation plan with mockups, data flow, and code snippets
  • Build a web of related artifacts rather than one giant markdown file
Code review & understanding
  • Render actual diffs with margin annotations
  • Color-code findings by severity
  • Explain tricky logic with diagrams
  • Attach HTML explainers to PRs
Design & prototypes
  • Prototype components, interactions, and animations
  • Use HTML as a sketch layer even if the real app is Swift or React
  • Add tuning controls like sliders and knobs
Reports, research & learning
  • Synthesize info from code, Slack, git history, and the web
  • Turn it into a report, explainer, or deck
  • Use SVG diagrams to make hard topics readable once
Example prompts from the article’s spirit
- “Generate 6 distinctly different onboarding directions and lay them out in one HTML grid so I can compare the tradeoffs side by side.” - “Create a thorough implementation plan in an HTML file. Make mockups, show data flow, add important code snippets, and optimize it for digestion.” - “Help me review this PR by creating an HTML artifact. Focus on the streaming/backpressure logic and render the actual diff with annotations.” - “I don’t understand our rate limiter. Produce a single HTML explainer page with one token-bucket diagram, key code snippets, and a gotchas section.”
5 — Custom Editing Interfaces: One of the Strongest Ideas

This section was easy to miss if you skim, but it is one of the sharpest ideas in the whole article. Sometimes text prompts are the wrong interface. In those cases, ask the agent to make a throwaway HTML editor for the exact data you’re working on — not a product, not a framework, just a one-off operational UI.

Ticket reprioritizer
  • Draggable cards across Now / Next / Later / Cut
  • Pre-sorted by the model’s best guess
  • Copy final ordering back out as markdown
Feature flag editor
  • Form-based editing UI
  • Grouped by area
  • Warn on dependency violations
  • Export only the changed keys
Prompt tuner
  • Editable prompt on the left
  • Sample inputs with live rendering on the right
  • Variable slot highlighting
  • Character/token counter and copy button
The trick, in the author’s words: always end with an export. “Copy as JSON,” “copy diff,” or “copy as prompt” turns the UI back into something that can be pasted into Claude Code.
Why this matters
  • Some decisions are painful to express in pure text
  • Drag/drop, sliders, and forms externalize cognition
  • You don’t need to productize the tool for it to be useful
What these editors can handle
  • Reordering tickets or feedback
  • Editing config with constraints
  • Tuning prompts and templates
  • Curating datasets or annotations
6 — Costs, Downsides, and FAQ

The article explicitly addresses objections. That matters because the argument is not “HTML is universally superior.” It is “the benefits are often worth more than people assume.”

Costs & downsides
  • HTML is less token-efficient than markdown
  • It usually takes longer to generate
  • HTML diffs are noisy and harder to review in version control
  • Bad design quality can make artifacts ugly or distracting
Why the author still prefers it
  • He is more likely to actually read the result
  • Other people are more likely to read the result
  • The added expressiveness dominates the cost for many tasks
  • With large context windows, token overhead matters less
FAQ distilled from the article
  • Isn’t it less token efficient? Yes, often. But the author argues the increase is outweighed by expressiveness and by the fact that he actually reads the result.
  • When do you still use markdown? The author says he has largely stopped using markdown for almost everything, while admitting he is on the maximalist end.
  • How do you view the HTML? Usually just open it locally in a browser, or upload it to somewhere like S3 for link sharing.
  • Does it take longer? Yes — explicitly called out as 2–4× slower than markdown.
  • What about version control? This is called one of the biggest downsides: HTML diffs are noisy and hard to review.
  • How do you make it match your taste? Use a frontend design plugin or build a design-system reference file from your own codebase.
7 — How to Get Started, According to the Article

The article’s advice here is deliberately anti-ceremonial. Don’t overengineer a `/html` ritual too early. Don’t treat the format as magic. Start by asking for a real HTML artifact and be explicit about what the artifact should help you do.

Good mental model
  • Ask what the artifact should enable: compare, explain, tune, review, share
  • Prompt from scratch at first
  • Develop a skill later if patterns repeat
  • Think in terms of pages and interfaces, not just documents
Bad mental model
  • Turning it immediately into a cargo-cult slash command
  • Using HTML for everything without a human-readability reason
  • Focusing on prettiness over utility
  • Forgetting to define an export path when interactivity is involved
A good prompt shape: “Make a single HTML explainer page for this system. Include one diagram, the key snippets I need to inspect, and a gotchas section. Optimize it for someone reading it once.” A stronger version for comparison: “Generate 6 distinctly different approaches and lay them out side by side in one HTML file with labels explaining each tradeoff.”
8 — The Emotional Core: Staying in the Loop

This is the part most summaries flatten, but it is the real ending. The author had begun to fear that because he had stopped reading plans deeply, he would have to leave Claude alone to make choices. HTML changed that feeling. It made him feel more in the loop than ever before.

HTML is valuable here because it increases the odds that the human will actually look, understand, react, and steer.

Before
  • Long markdown plans get skimmed
  • Human trust becomes passive
  • Agent choices feel more opaque
After
  • Artifacts become readable enough to inspect
  • Controls and visual structure invite steering
  • The human remains engaged in decisions
Why that matters
  • Better review loops
  • Higher trust grounded in inspection
  • More effective collaboration with stronger agents
Bottom line: the article is arguing for HTML as a higher-bandwidth human interface for agent output. The technical benefits matter, but the decisive outcome is behavioral: people actually engage with the artifact.