The Unreasonable Effectiveness of HTML in Claude Code: Why HTML Beats Markdown for AI Output

A blog post by Thariq (@trq212), a Claude Code engineer at Anthropic, has accumulated 8 million views on X after making a clear case that HTML has replaced Markdown as his preferred output format for AI agent work.

The original post and article sparked intense discussion—and for good reason. The argument is simple but has significant implications for anyone building with Claude Code or other AI coding tools.

This post is a detailed breakdown of Thariq's argument, the use cases he covers, and the practical workflow changes that follow from taking it seriously.

The core argument: why Markdown is increasingly limiting

Markdown became the default AI output format for understandable reasons: it's simple, portable, human-editable, and models render it cleanly. But Thariq identifies a structural shift in how he actually uses AI-generated documents:

He's no longer editing them himself. The documents Claude generates are increasingly used as specs, reference files, and brainstorming outputs—read and passed into subsequent Claude sessions, not manually edited line by line.

When that's true, Markdown loses its main advantage (easy human editing) while retaining its main limitation (constrained expressiveness). The tradeoff no longer makes sense.

The second problem: Markdown doesn't scale past ~100 lines. Thariq says he doesn't actually read Markdown files longer than 100 lines—and he certainly can't get colleagues to read them. The format that's supposed to communicate information stops communicating because no one processes it.

What HTML gives you that Markdown can't

The information density difference is significant:

Thariq's summary: "I would go so far as to say that there is almost no set of information that Claude can read that you cannot fairly efficiently represent with HTML."

The five use cases (with example prompts)

1. Specs, planning, and exploration

Rather than a flat Markdown plan, Thariq generates a web of HTML files for complex problems:

1. Ask Claude to brainstorm and create explorations of different approaches
2. Expand into promising directions with mockups or code snippets
3. Write an implementation plan when the direction is clear
4. Pass all of these files into a new session for implementation
5. Have a verification agent read the files for full context

Example prompt:

"I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches—vary layout and density—and lay them out as a single HTML file in a grid so I can compare them side by side. Label each with the tradeoff it's making."

Why it works: Six design directions in one HTML file, visually comparable, labeled with tradeoffs. A Markdown equivalent would be six bullet-point descriptions that you have to imaginatively render.

2. Code review and understanding

Code is difficult to read in Markdown. HTML enables rendered diffs, inline annotations, flowcharts, and module maps. Thariq attaches an HTML code explainer to every PR he makes—and finds it often works better than GitHub's default diff view.

Example prompt:

"Help me review this PR by creating an HTML artifact that describes it. I'm not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity and whatever else might be needed to convey the concept well."

Why it works: Color-coded severity, inline annotations, and actual diff rendering in a format colleagues can open in any browser—no GitHub login, no special tooling.

3. Design and prototypes

HTML is exceptionally expressive for design work, even if the final surface isn't HTML. Claude can sketch a design in HTML and then implement it in React, Swift, or any target platform. The critical trick: adding interactive controls to tune the design precisely.

Example prompt:

"I want to prototype a new checkout button. When clicked, it does a play animation and then turns purple quickly. Create an HTML file with several sliders and options for me to try different options on this animation. Give me a copy button to copy the parameters that worked well."

Why it works: Instead of describing animations in text and asking Claude to implement them blind, you get a live playground—adjust until it's right, export the parameters, implement with confidence.

4. Reports, research, and learning

Claude Code can synthesize information across multiple data sources—Slack (via MCP), codebase, git history, the internet—and generate highly readable HTML reports. The format can be a long document, an interactive explainer, or a slideshow.

Thariq's example: for blog posts on prompt caching, he asked Claude to prepare an in-depth research HTML file by reading the full git history on prompt caching changes.

Example prompt:

"I don't understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3–4 key code snippets annotated, and a 'gotchas' section at the bottom. Optimize it for someone reading it once."

Why it works: A token-bucket diagram in SVG, annotated code snippets with color, and a structured reading experience—not a wall of monospace text in a Markdown code block.

5. Custom editing interfaces

This is the most creative use case. When describing what you want purely in text is too imprecise, ask Claude to build a throwaway HTML editor for the exact problem you're solving—then export the result back to Claude Code.

The key design principle: always end with an export button. A "copy as JSON" or "copy as prompt" button turns the UI interaction back into text you can paste into Claude Code.

Example prompts:

"I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a 'copy as markdown' button that exports the final ordering with a one-line rationale per bucket."

"Here's our feature flag config. Build a form-based editor for it, group flags by area, show dependencies between them, warn me if I enable a flag whose prerequisite is off. Add a 'copy diff' button that gives me just the changed keys."

"I'm tuning this system prompt. Make a side-by-side editor: editable prompt on the left with the variable slots highlighted, three sample inputs on the right that re-render the filled template live. Add a character/token counter and a copy button."

Why it works: For tasks where the output is hard to specify in text—ticket ordering, config editing, prompt tuning—a bespoke UI is more expressive and produces better results than back-and-forth text clarification.

The Claude Code advantage over Claude.ai and Claude Design

Thariq specifically addresses why to use Claude Code for HTML generation rather than Claude.ai or Claude Design:

Claude Code can ingest dramatically more context. It can read your entire codebase, search for specific files, read git history, and pull from MCP-connected sources (Slack, Linear, databases). This makes it possible to generate HTML reports that synthesize information Claude.ai can't access.

For the blog post you're currently reading, Thariq literally asked Claude Code to "read through my code folder and find all the HTML files I've generated, group and categorize them, and then make an HTML file with all diagrams representing each type"—producing the categorized examples visible in his article.

That kind of synthesis requires filesystem access and pattern recognition across a real codebase—something Claude.ai artifacts can't provide without manual context uploading.

Practical answers to common questions

"Isn't it less token efficient?" Yes—HTML takes 2-4x longer to generate than Markdown. But with Claude Opus 4.7's 1M token context window, the overhead is minimal. And output you actually read (and share) produces better outcomes than output that's technically token-efficient but never processed.

"When do you still use Markdown?" Thariq has "honestly stopped using markdown altogether for almost everything." Though he acknowledges being "far on the HTML maximalist side."

"How do I view the HTML file?" Open in a browser locally (Claude Code can open files for you), or upload to S3/similar storage for a shareable link. No special software required.

"What about version control?" This is the genuine downside: HTML diffs in git are noisy and hard to review compared to Markdown. For files that need precise tracking in version control with meaningful diffs, Markdown may still be better. This is the tradeoff Thariq acknowledges.

"How do I get Claude to match my style?" The frontier.design plugin helps Claude make well-designed HTML. To match your company's style, ask Claude to generate a single design system HTML file by reading your codebase—then reference that file when generating other HTML documents.

The "staying in the loop" argument

Thariq's closing argument is worth quoting directly:

"I had begun to fear that because I had stopped reading plans in depth I would simply have to leave Claude to make its choices. But I am happy to say instead that I feel more in the loop than ever before when using HTML. I hope you do too."

This is the deepest part of the case. As AI agents become more capable and autonomous, one risk is that developers become passive observers rather than active participants. HTML output—richer, more interactive, more visually engaging—keeps humans legibly in the loop on what the AI is doing and why.

That's not a minor aesthetic preference. It's a safety and quality argument: developers who can actually understand and evaluate what their agent has produced will catch more errors, make better decisions, and build better products.

Getting started: the minimal viable approach

Thariq explicitly warns against immediately creating a complex /html skill. His recommendation:

Just ask. Use phrases like:

• "make an HTML file"
• "make an HTML artifact"
• "create an HTML explainer"

Focus on knowing what you want the artifact to do and how you'll use it. Start with one of the five use cases above that maps to your current work. Build intuition for what HTML gives you over Markdown before codifying it into a skill.

The examples at thariqs.github.io/html-effectiveness are worth reviewing to see what the output actually looks like across different use cases.

Related reading on ExplainX

• HTML Canvas complete guide
• Modern CSS features guide for 2026
• React Server Components guide 2026
• What are agent skills? Complete guide
• Karpathy on Claude Code and developer skills
• Context engineering and clean prompts

This post is a summary and analysis of Thariq's original article at x.com/trq212/status/2052809885763747935. HTML generation capabilities, token costs, and Claude Code features evolve with each Claude release—verify current behavior in your own sessions.