HTML Beats Markdown for AI Specs at 2-4x Token Cost

DIY Smart Code2026-05-09go watch the original →

the gist

Switch specs, plans, PRs from Markdown to HTML for tables, SVG diagrams, JS interactions—8x richer density. Claude Opus 4.7's 1M context absorbs 2-4x tokens; outputs boost readability so humans stay in the loop.

HTML Delivers 8x Information Density Markdown Lacks

Prompt Claude Code to output self-contained HTML files instead of Markdown for specs, plans, and PR writeups. HTML embeds tables, CSS styling, SVG diagrams, code snippets in

5 Production Workflows Transformed by HTML Outputs

(1) Specs/Planning: Claude fans out 6 problem approaches side-by-side in one HTML, labeling trade-offs with mockups/code snippets; select one to evolve into full plan. (2) Code Review: Attach HTML explainer to PRs with diff annotations, severity colors, jump links—beats GitHub's default view. (3) Design/Prototypes: Sketch in HTML (Claude Design's native format), add sliders/knobs for tuning animations, copy params back to prompts for React/Swift. (4) Reports/Research: Feed codebase, Git history, Slack/internet; get annotated flow diagrams, key snippets, gotchas in one explainer page. (5) Custom Editors: Build throwaway HTML interfaces—drag 30 Linear tickets into now/next/later/cut buckets, edit configs with warnings, tune prompts with live re-renders—export as Markdown/diff/next prompt.

Claude Code's Context Stack Powers Informed HTML

Use Claude Code specifically: it ingests filesystem (all prior HTMLs visible), MCP servers (Slack/Linear), browser (Claude in Chrome), Git history—synthesizing from real work, not generic chat. Prompt: $ claude code "Generate this spec as self-contained HTML with SVG diagram, code snippets, margin-annotated review." Same prompt in plain Claude yields pretty but uninformed artifacts. Thariq Shihipar (Anthropic Claude Code) switched because Markdown walls went unread, leaving Claude to solo decisions—losing plot. HTML lets humans click/read/suggest, restoring 'in the loop' control. His thesis (750k views) predicts HTML in specs/PRs/reports everywhere; test his 20 examples to see why.