Summary
This article describes the practice of using HTML files (rather than Markdown) as the primary artifact format when working with agents like Claude Code. HTML offers richer information density—tables, SVG diagrams, interactive controls, CSS styling, and more—making it easier for both humans and models to read, share, and iterate on plans, specs, designs, reports, and custom editing interfaces.
Key Points
- HTML can convey richer information than Markdown: tables, CSS, SVG, interactive elements, code snippets, spatial layouts, and images.
- HTML documents are more visually scannable and easier to navigate (tabs, responsive layouts) than long Markdown files, increasing the likelihood that humans actually read them.
- HTML files are natively shareable in browsers without plugins, making collaboration smoother than with Markdown attachments.
- Interactive HTML (sliders, knobs, drag-and-drop) allows two-way tweaking and direct copy-back of results into the chat.
- Claude Code can ingest file system, MCPs (Slack, Linear), web browser context, and git history to generate rich HTML artifacts.
- No special setup is needed—simply prompt “make an HTML file” or “make an HTML artifact.”
- Common use cases: specification and planning, code review, design prototyping, reports and explainers, and custom throwaway editors for structured data.
Concepts
- HTML as a universal canvas: HTML is expressive enough to represent almost any set of information (tabular, spatial, interactive, visual) that an AI can generate and a human can review.
- Two-way interactions: HTML files can include interactive controls (sliders, knobs, buttons) and an export function to copy results back into a prompt, creating a tight feedback loop.
- Data ingestion for artifact generation: Claude Code can pull context from the filesystem, MCP integrations, browser, and git history to produce HTML artifacts that synthesize disparate information.
- Throwaway editors: Single-purpose HTML files built for a specific editing task (reordering tickets, tuning prompts, curating datasets) with a copy button to export changes.
Details
Why HTML over Markdown?
HTML is a better fit than Markdown for complex AI-assisted work because it handles higher information density and provides visual structure that keeps human reviewers engaged.
HTML can represent tabular data (tables), design data (CSS), illustrations (SVG), code snippets (<script> tags), interactions (JavaScript + CSS), workflows (SVG + HTML), spatial data (absolute positioning, canvases), and images. In Markdown, the model may resort to ASCII diagrams or approximated color swatches.
Visual clarity and ease of reading
As Claude Code tackles larger specs and plans, Markdown files over 100 lines tend to go unread. HTML documents can be organized with tabs, illustrations, links, and responsive layouts, making them far easier to navigate and actually read.
Ease of sharing
HTML files render natively in browsers, so sharing a link is straightforward. Recipients don’t need special viewers; they can open the file easily in any browser and reference it directly.
Two-way interactions
HTML can include interactive controls (sliders, knobs, drag-and-drop). Users can tweak parameters or reorder items in the artifact and then copy the changes back as a prompt or JSON.
Data ingestion for context-rich artifacts
Claude Code can read the codebase, MCP integrations (Slack, Linear), web browser tabs, and git history to gather context. For example, when generating this article, the author asked Claude Code to scan his HTML files, categorize them, and produce diagrams representing each type.
Getting started
No special setup is required—simply prompt Claude Code to “make an HTML file” or “make an HTML artifact.” Starting with a simple prompt and iterating is recommended before building reusable skills for recurring patterns.
Use cases
Specs, planning, and exploration
HTML is a rich canvas for brainstorming and comparing options. A typical workflow: ask Claude Code to explore different approaches in HTML files, expand on the best one with mockups and interface examples, then write an implementation plan. Pass these files to a new session for implementation.
Example prompts:
- “Generate 6 distinctly different approaches for the onboarding screen in a single HTML grid, labeling each with tradeoffs.”
- “Create a thorough implementation plan in an HTML file with mockups, data flow, and annotated code snippets.”
Code review and understanding
HTML can render diffs, annotations, flowcharts, and module structures, making code easier to review than in Markdown. Use for PR creation, PR review, or understanding a codebase.
Example prompt: “Create an HTML artifact that describes this PR. Focus on the streaming/backpressure logic. Render the diff with inline margin annotations, color-code findings by severity.”
Design and prototypes
HTML is expressive for design, even if the final surface is not HTML. Claude can prototype interactions (animations, knobs, sliders) and tune parameters.
Example prompt: “Prototype a checkout button animation. Create an HTML file with sliders for different animation options and a copy button to export the winning parameters.”
Reports, research, and learning
Claude Code synthesizes information from Slack, codebase, git history, or the web into HTML reports, interactive explainers, or slide decks with SVG diagrams.
Example prompt: “Explain our rate limiter in a single HTML page: diagram of token-bucket flow, key code snippets annotated, and a gotchas section.”
Custom editing interfaces
For tasks that are hard to describe purely in text, ask Claude to build a throwaway HTML editor purpose-built for the data. Always include an export button (“copy as JSON” or “copy as prompt”) to bring results back into the chat.
Example prompts:
- “Reprioritize these 30 Linear tickets. Make draggable cards across Now/Next/Later/Cut columns. Add a 'copy as Markdown' button with rationale per bucket.”
- “Build a form editor for our feature flag config, with dependency warnings and a 'copy diff' button.”
- “Make a side-by-side editor: editable prompt on left, sample inputs on right, live preview, token counter, and copy button.”
Frequently asked questions
- Isn’t it less efficient? Although HTML uses more tokens than Markdown, the added expressiveness and higher readability lead to better overall output. With large context windows, the token increase is barely noticeable.
- When do you use Markdown? The author reports stopping Markdown use almost entirely for AI artifact generation.
- Is this how you’ve replaced planning? Instead of a single plan, multiple HTML files are used for different stages (exploration, UI design, component lists). These files are kept as references for future sessions and verification.
See also: Claude Design, Agentic Engineering Hacks