Using Claude Code: The Unreasonable Effectiveness of HTML

Markdown has become the dominant file format used by agents to communicate with us. It's simple, portable, has some rich text capability and is easy for you to edit. Claude has even gotten surprisingly good at using ASCII to make diagrams inside of markdown files.

But as agents have become more and more powerful, I have felt that markdown has become a restricting format. I find it difficult to read a markdown file of more than a hundred lines. I want richer visualizations, color and diagrams and I want to be able to share them easily.

I'm also increasingly not editing these files myself, but using them as specs, reference files, brainstorming outputs, etc. When I do make edits, I'm usually prompting Claude to edit them, which removes one of markdown's largest benefits.

I've started preferring HTML as an output format instead of Markdown and increasingly see this being used by others on the Claude Code team, this is why.

Examples: thariqs.github.io/html-effectiveness

Information Density

HTML can convey much richer information compared to markdown — simple document structure, but also:

• Tabular data using tables
• Design data with CSS
• Illustrations with SVG
• Code snippets with script tags
• Interactions using HTML elements with javascript + CSS
• Workflows using SVG and HTML
• Spatial data using absolute positions and canvases
• Images using image tags

There is almost no set of information that Claude can read that you cannot fairly efficiently represent with HTML. Without it, the model resorts to inefficient things like ASCII diagrams or estimating colors with unicode characters.

Visual Clarity & Ease of Reading

In practice, I've found I tend not to actually read more than a 100-line markdown file, and I certainly can't get anyone else in my organization to read it. HTML documents are much easier to read — Claude can organize the structure visually with tabs, illustrations, links, etc. It can even be mobile responsive.

Ease of Sharing

Markdown files are fairly hard to share since most browsers do not render them natively. With HTML, upload to S3 and share the link. The chance of someone actually reading your spec, report or PR writeup is much higher if it's in HTML.

Two-way Interaction

HTML lets you interact with the document — add sliders or knobs to adjust a design, tweak algorithm options, copy changes back into a prompt for Claude Code. See: playgrounds post.

Data Ingestion

Claude Code can ingest far more context than ClaudeAI or Claude Design — the file system, MCPs (Slack, Linear, etc.), Claude in Chrome, git history, etc. This makes it uniquely powerful for generating HTML from real project data.

It's Joyful

Making HTML documents with Claude is just more fun and makes me feel more involved and invested in the creation, and that by itself is enough.

How to Get Started

You don't need a skill or special setup. Just ask Claude to "make a HTML file" or "make a HTML artifact". The trick is knowing what you want the artifact to do and how you might use it.

Use Cases

Specs, Planning & Exploration

Start with brainstorming explorations, expand into mockups or code snippets, then write an implementation plan. Pass all these HTML files into a new session for implementation. Ask the verification agent to read them in for broader context.

Example Prompts I'm not sure what direction to take the onboarding screen. Generate 6 distinctly different approaches — vary layout, tone, 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.

Create a thorough implementation plan in a HTML file, be sure to make some mockups, show data flow and add important code snippets I might want to review. Make it easy to read and digest.

Code Review & Understanding

With HTML we can render diffs, annotations, flowcharts, modules, etc. Often works better than the default GitHub diff view. I attach an HTML code explainer to every PR I make.

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.

Design & Prototypes

HTML is incredibly expressive at design even if your end surface is not HTML. Claude can sketch a design in HTML then write it in React, Swift, etc. Prototype interactions with sliders and knobs to tune exactly what you're looking for.

Example Prompt I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a 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.

Reports, Research & Learning

Claude Code is incredibly good at synthesizing information across multiple data sources. Prompt it to search Slack, the codebase, git history, the internet — and generate readable reports as long HTML documents, interactive explainers or slideshows.

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.

Custom Editing Interfaces

Build a throwaway editor for the exact thing you're working on — not a product, just a single HTML file purpose-built for one piece of data. Always end with an export: a "copy as JSON" or "copy as prompt" button.

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.

FAQ

Isn't it less token efficient?

While markdown often uses fewer tokens, the added expressiveness and much higher likelihood of actually reading it means better overall output. With the 1MM context window in Opus 4.7, the increased token usage is not really noticeable.

When do you use markdown?

I have honestly stopped using markdown altogether for almost everything, but I'm probably far on the HTML maximalist side of things.

How do I view the HTML file?

Open it in a browser locally (you can ask Claude to open it), or upload to S3 for a shareable link.

Doesn't this take longer to generate?

Yes — HTML can take 2–4x longer than Markdown, but the results are worth it.

What about version control?

HTML diffs are noisy and hard to review compared to Markdown. Honest downside.

How do I get Claude to match my taste / not make it ugly?

The frontend design plugin helps. To match your company's style, create a single design system HTML file by pointing Claude at your codebase, then use that as a reference for other HTML files.

Stay in the Loop

The real reason I use HTML is that I feel much more in the loop with Claude. 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 feel more in the loop than ever before when using HTML. I hope you do too.