HTML as the New Markdown

Sources#

How I AI: Thariq Shihipar on Replacing Markdown with HTML for AI-Powered Development

Summary#

Thariq Shihipar's thesis, delivered to Claire Vo at Code with Claude (May 2026): "HTML is the new markdown." Markdown has been the lingua franca for human–LLM interaction — simple, structured, readable by both sides. But as models get more capable and projects more complex, thousand-line markdown plans overwhelm the human. We glaze over, stop reading, stop engaging, and collaboration quality collapses. The fix is a richer communication medium: HTML artifacts that are visual, scrollable, and interactive, pulling the human back in from passive reviewer to active collaborator.

The load-bearing observation: the model isn't the limiter — human attention is.

"It's not that the models struggle with Markdown — they're brilliant at it — but that HTML makes it easier for us, the humans in the loop, to visualize, interact with, and stay connected to the work being done."

The failure mode it fixes#

Thariq's own confession names the problem precisely: faced with a plan thousands of lines long, "he'd just ask Claude to edit the plan instead of reading it himself." A plan the human no longer reads is a plan the human no longer steers — the alignment that planning exists to produce evaporates. The goal becomes "create a plan you actually want to read."

This is the human-attention analog of the model's Context Window Smart Zone: just as a model degrades past ~100K tokens regardless of advertised window, a human reviewer degrades past some volume of undifferentiated markdown regardless of how complete it is. HTML raises the human's effective smart zone by spending tokens on legibility (mockups, structure, color, interaction) rather than raw text.

What HTML buys#

Asked to "brainstorm some ideas in HTML file," Claude returns not a list but a visual, scrollable page — eight demo ideas, each with a mockup, description, and risk assessment. The full-plan prompt:

create a HTML file as a plan that helps me visualize what the implementation plan is.
Include excerpts, mockups, code, whatever is needed to give me like maximum context

yields a single-file website: scripted intro, file-structure diagrams, code snippets, a visual mood board. A document you can read, explore, and share with a teammate — who is far more likely to engage with it than with a giant markdown file. The artifact bridges not just human↔AI but engineering↔the rest of the company.

The prompting move: constraint plus latitude#

Two details from the plan prompt are deliberate:

He misspelled "excerpts" and it didn't matter — models are robust to surface noise.
"whatever is needed to give me like maximum context" gives the model an out. The philosophy: provide enough constraint to get what you want, but leave room for the model to surprise you. As Thariq puts it, "I always needed to be like, 'Hey, Claude, like I trust you here.'"

This is a small, repeatable instance of The Bitter Lesson applied at the prompt level — under-specify the structure and let scaled capability fill it — and it pairs with the Compute Allocator role: the human sets direction and trusts the model with the rest.

The harness tension this resolves#

At first glance this contradicts the wiki's running Harness Shrinkage as Models Improve thesis (Cat Wu / Boris Cherny: scaffolding shrinks each release) and Interaction Models (Thinking Machines Lab: the harness dissolves into the model). Thariq says the opposite — only ~1% of his tokens ship; 99% go to scaffolding.

The resolution: these are two different harnesses.

The shrinking harness is model-facing — prompts, instructions, verification that exist to make the model behave. As models improve, this contracts.
The growing harness is human-facing — artifacts (HTML plans, micro-apps, design systems) that exist to keep the human aligned, engaged, and able to decide. As models improve, this expands, because the binding constraint shifts from "can the model do it" to "can the human stay in the loop and allocate compute well."

The Bitter Lesson dissolves model-facing structure; it does not dissolve the human-facing structure whose entire purpose is human comprehension. That's the side of the line HTML artifacts sit on. See Compute Allocator for the role this implies.

The three workflows#

Brainstorming and planning in interactive HTML (this page) — visual plans you want to read.
Disposable Micro-Apps — throwaway custom UIs to edit parts of the plan, answering the "HTML isn't editable" objection.
Living Design System — a design_system.html as a portable, human- and machine-readable source of truth.

All three center the human; none is about automating the developer away.

Connections#

Thariq Shihipar — author of the thesis
Claire Vo — interviewer; runs a parallel component-visualization practice
Claude Code — the product these HTML-artifact workflows run in, demonstrated from inside the Claude Code team
Compute Allocator — the role this medium serves: human as decider, 99% of tokens spent on scaffolding like this
Disposable Micro-Apps — the editability answer to HTML plans
Living Design System — the same HTML-first move applied to design
Harness Shrinkage as Models Improve — the model-facing harness shrinks while this human-facing harness grows; the key contrast
Interaction Models — a sibling answer to "better human–AI collaboration": dissolve the real-time interface into the model, where this enriches the asynchronous artifact; opposite mechanisms, same goal of keeping humans in the loop
The Bitter Lesson — "leave room for the model to surprise you" is the prompt-level form; the caveat is that human-facing legibility doesn't migrate inward
Context Window Smart Zone — HTML raises the human's effective smart zone the way clearing context restores the model's
Design Concept Grilling — brainstorm → let Claude interview you → plan is the grilling shape; the HTML plan is the richer destination artifact
AI Native Product Cadence — Cat Wu makes PRDs lighter; Thariq makes them richer — different bets on what keeps the human aligned at speed
Software 3.0 — HTML-first plans and Disposable Micro-Apps are Software-3.0-native: per-task UIs spun up from a prompt, MenuGen-style "apps that barely exist"

Open questions#

Does the human-facing harness keep growing without bound, or does it hit its own bloat ceiling (an HTML plan too elaborate to read, like the markdown it replaced)? Answered: Does the Human-Facing Harness (HTML Artifacts) Hit Its Own Bloat Ceiling? — yes; HTML raises and reshapes the human-attention ceiling but can't remove it, and the bloat relocates from document-length to artifact-sprawl/rubber-stamping.
HTML is heavier to diff and version than markdown — what happens to plan history and review when artifacts are single-file websites? (Disposable Micro-Apps copy-back-to-markdown is one patch.)
Does this generalize past one expert practitioner, or does it require Thariq-level fluency with Claude to be worth the overhead?

Derived#

Does the Human-Facing Harness (HTML Artifacts) Hit Its Own Bloat Ceiling? — whether this human-facing harness hits its own bloat ceiling (it does; the ceiling moves and reshapes but doesn't vanish)

Sources#

How I AI: Thariq Shihipar on Replacing Markdown with HTML for AI-Powered Development