Using Claude Code: The Unreasonable Effectiveness of HTML  🔗 **Source:** [Using Claude Code: The Unreasonable Effectiveness of HTML](https://twitter.com/trq212/status/2052809885763747935/?rw_tt_thread=True) > [!note]+ Document Notes > tags: [html, agents, developer-experience] > author: Thariq > source: Twitter > reference: [https://twitter.com/trq212/status/2052809885763747935/?rw_tt_thread=True] > date created: 2026-05-11 00:00 > > # 🏷️ Title: Using Claude Code: The Unreasonable Effectiveness of HTML > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - Include links cited in or relevant to the article. ## 📝 Summary - The author argues that HTML is a far better medium than Markdown for working with powerful agents like Claude Code, especially for specs, plans, designs, and reports. - It matters because richer, interactive visualizations increase the odds humans actually read and understand what agents produce. - Key stakeholders: developers, teams using AI copilots, engineering leaders, and tool builders. - Risks/tradeoffs: more tokens, slower generation, noisy diffs, extra hosting/viewing steps. - Bottom line: treat HTML as the default artifact format for serious agent work, using Markdown only sparingly. ## 📖 Main Content - Markdown is simple and portable, but becomes hard to read at scale; long markdown specs are often ignored. HTML can encode structure, layout, color, interactivity, and diagrams, making dense information more digestible. - HTML supports tables, CSS-based design, SVG diagrams, JS-powered interactions, spatial layouts, and images, so “there is almost no set of information that Claude can read that you cannot fairly efficiently represent with HTML.” - Visual clarity: HTML artifacts can use tabs, navigation, responsive layouts, and illustrations so people actually read specs, plans, and reports. - Sharing: HTML hosted on the web (e.g., S3) is easier to open and share than raw markdown files or attachments. - Two-way interaction: HTML artifacts can expose sliders, knobs, and controls for tweaking algorithms, designs, or parameters, then exporting changes back into prompts or JSON. - Claude Code shines because it can ingest large contexts (filesystem, MCPs like Slack/Linear, browser, git history) and then synthesize them into rich HTML artifacts. - Use cases: - Specs, planning, exploration: generate webs of HTML files for brainstorming options, mockups, and implementation plans. - Code review & understanding: HTML diffs, annotations, flowcharts, and explainers attached to PRs. - Design & prototypes: interactive UI sketches, animation playgrounds, design system views, then translating to frameworks like React or Swift. - Reports & research: multi-source syntheses, technical explainers, incident reports, and SVG-based diagrams. - Custom editing interfaces: one-off UIs for reprioritizing tickets, editing configs, tuning prompts, curating datasets, and annotating. - Getting started: you mostly just ask Claude Code to “make an HTML file/artifact”; the real skill is in specifying what the artifact should do. - FAQ tradeoffs: - Token efficiency: HTML uses more tokens but yields more effective reading, and large context windows make this acceptable. - Time: HTML generation can be 2–4× slower but worth it for quality. - Version control: HTML diffs are noisy; this is a major downside. - Aesthetics: use frontend design helpers or a custom design-system HTML file as a style reference for Claude. - Core motivation: using HTML keeps the human “in the loop”—the author now actually reads and understands agent-generated work. ### 🗒️ Notes - Markdown has become the default interface between humans and agents, but its simplicity now limits rich communication as agents produce complex outputs. - Long markdown files (>100 lines) are hard for teams to read; they lack visual hierarchy and interactivity. - HTML offers: - Structural richness (headings, layout, tabs, grids). - Data representations (tables, SVG diagrams, spatial canvases). - Interactivity (JS-driven controls, sliders, knobs). - Visual design via CSS and responsive layouts. - In practice, Claude will otherwise resort to ASCII diagrams or clever Unicode hacks to convey structure inside Markdown, which is suboptimal compared to native HTML/SVG. - Visual clarity: - HTML pages can be navigated via sections, internal links, tabs, and responsive design, improving comprehension and engagement. - This is especially important for specs, plans, and PR explainers that must be read by multiple stakeholders. - Sharing benefits: - Browsers render HTML natively; no special viewer is needed. - Hosting on generic storage (e.g., S3) turns artifacts into simple, shareable URLs. - This dramatically increases the probability that others will read the material. - Two-way interaction: - HTML artifacts can be small “playgrounds” that let the user manipulate parameters and immediately see results. - A crucial pattern is “throwaway editor with export”: a temporary UI that ends in a button like “copy as JSON/markdown/prompt” to re-ingest results into Claude Code. - Data ingestion with Claude Code: - Claude can scan your codebase, find prior HTML artifacts, categorize them, and generate higher-level diagrams summarizing them. - It can also pull from Slack, Linear, browser context, and git, then synthesize findings into explainers or reports. - Typical workflows: - Start with brainstorming explorations in HTML. - Expand favored options with mockups and code snippets. - Consolidate into implementation plans and verification documents. - Feed those artifacts back into Claude for implementation or verification. - Code review: - HTML can show diffs with inline annotations, color coding by severity, and explanatory diagrams. - Authors attach HTML explainers to PRs to improve reviewers’ understanding beyond GitHub’s default diff UI. - Design: - Claude Design relies on HTML as an expressive canvas; HTML prototypes can later be translated to platform-specific code. - Interactive prototypes allow tuning animations, colors, and states via sliders/controls before final implementation. - Reports & learning: - Claude can gather evidence from multiple sources (Slack, git, internet) and produce polished HTML reports with diagrams and annotated code. - These artifacts can serve as internal documentation and onboarding material. - Custom editing UIs: - Temporary HTML tools for reprioritizing tickets, editing feature flags, tuning prompts, or curating datasets. - Always end with a robust “export” mechanism to preserve results. - FAQ themes: - Efficiency vs expressiveness: HTML is heavier but more effective in practice. - Viewing: open locally in a browser or host to share. - Version control pain: HTML diffs are noisy and harder to review than Markdown. - Aesthetics: steer Claude via a design-system reference document or frontend design plugin. - Overall, HTML becomes the default medium for serious agent collaboration, letting the human remain deeply involved rather than skimming or ignoring long markdown outputs. ## 📚 References - Thariq’s examples: https://thariqs.github.io/html-effectiveness - Claude “playgrounds” / two-way interaction thread: https://x.com/trq212/status/2017024445244924382 - Original X/Twitter thread: https://twitter.com/trq212/status/2052809885763747935 ## 🗣️ Paraphrase - The author argues that Markdown, while convenient, fails to scale as a medium for complex agent-produced work because people don’t actually read long, text-only documents. HTML, with its richer structure, visuals, and interactivity, better supports understanding and collaboration. - Using Claude Code to generate HTML artifacts—from specs and code reviews to prototypes, reports, and custom editors—keeps humans in the loop despite larger token usage and noisier diffs, making HTML a more effective default interface with powerful agents. ## 📰 Newsletter In this week’s WordPress-adjacent AI roundup, we’re looking beyond Markdown. Thariq makes a strong case for using HTML as the primary canvas for agent-generated work—think interactive specs, visual PR explainers, and custom “throwaway” editors you can paste back into your tools. For WordPress builders, it’s a nudge to lean on HTML+CSS+JS as a shared language between AI copilots and your projects: imagine Claude assembling HTML-based reports from your plugin repo, or generating interactive playgrounds that eventually become Gutenberg blocks. If you’re experimenting with AI-assisted workflows, try asking your copilot for “a single HTML page with diagrams, tabs, and export buttons” instead of yet another markdown wall of text—and see if your team’s engagement improves. ## ✅ Action Items #### DevRel - Document patterns for HTML-based agent artifacts (specs, explainers, playgrounds) and share sample prompts. - Run workshops showing how to turn agent-generated HTML into reusable docs, demos, and tutorials. - Maintain example repos with HTML artifacts for code review explainers, incident reports, and design explorations. - Produce content (blog posts, talks) demonstrating before/after of Markdown vs HTML for complex topics. - Gather community feedback on which HTML artifact patterns are most useful and refine guidance. #### OSPO - Define guidelines for storing and versioning agent-generated HTML artifacts alongside code. - Clarify license considerations when HTML artifacts embed third-party assets or generated diagrams. - Ensure security review of any interactive HTML artifacts before they are hosted or shared. - Track where HTML artifacts are used in incident response, design reviews, and architecture decisions. #### Community - Encourage maintainers to attach HTML explainers to major PRs and releases. - Provide templates for HTML-based RFCs, incident reports, and design proposals. - Offer pairing sessions on designing small, disposable HTML tools for triaging issues or curating data. - Share success stories where HTML artifacts improved understanding or reduced miscommunication. #### WordPress - Core: experiment with HTML-based design docs and PR explainers for complex changes. - Core Performance: use HTML dashboards and SVG diagrams for profiling and performance reviews. - Core AI: standardize patterns for AI-generated HTML artifacts (prompt-tuning UIs, explainer pages). - **Core Program Team:** coordinate guidelines on where HTML artifacts should live and how to review them. - Mobile: use HTML prototypes to validate flows before native implementation. - Playground: showcase HTML-based agent artifacts as reproducible labs within the browser. - Community: ship meetup kits that include prompts for creating HTML explainers of WordPress concepts. - Training: build lessons showing how to move from HTML prototypes to blocks, themes, and plugins. - Marketing: experiment with interactive HTML explainers for major launches or feature tours. - Support: curate HTML explainers for recurring complex support topics. - Design: maintain a reference HTML design system that agents can target when generating artifacts. - Documentation: accept HTML-based diagrams and interactive widgets as first-class doc assets. - Photos/TV/Openverse/etc.: explore HTML tools for curation, annotation, and review workflows. #### The WPOCC - Fund experiments where contributors use AI-generated HTML artifacts for governance docs and release planning. - Sponsor documentation sprints to convert dense text docs into interactive HTML explainers. - Support maintainers in building small HTML curation/editing tools for their projects. ### FAIR - Promote HTML artifacts that are self-contained, locally viewable, and signed where appropriate. - Provide reusable governance templates (charters, MoUs) as HTML that agents can extend or annotate. - Treat HTML-based scorecards and operator agreements as productized governance tools. ## 🧪 Hypotheses - H1: Teams are significantly more likely to read and act on specs when they are presented as interactive HTML artifacts rather than plain Markdown. - H2: HTML-based PR explainers reduce review time and increase reviewer confidence compared to code diffs alone. - H3: Custom HTML editing/playground interfaces improve prompt, config, and dataset quality relative to text-only editing. - H4: The extra token and generation cost of HTML is offset by fewer miscommunications and rework cycles. - H5: Providing agents with a design-system HTML reference yields more on-brand, visually consistent artifacts. ### 📊 Methodology - For H1: Run an A/B study where half of specs are produced in Markdown and half as HTML; measure open rates, completion of review, and defect rates. - For H2: Compare PR review durations, number of review cycles, and post-merge incidents between PRs with/without HTML explainers. - For H3: Have users perform editing tasks (prompt tuning, config changes) in text vs agent-generated HTML tools; measure error rates and time-on-task. - For H4: Track total compute cost plus human time spent per feature for HTML vs Markdown workflows; compare end-to-end efficiency. - For H5: Evaluate visual quality and consistency of HTML artifacts with/without a design-system reference in blinded design reviews. ### ❓ Questions - When does the overhead of generating and hosting HTML outweigh its benefits? - How should teams organize and version-control large numbers of HTML artifacts over time? - What minimum accessibility bar should agent-generated HTML artifacts meet? - Can we define standard prompt “recipes” for common HTML artifact types (PR explainer, incident report, research digest)? - How do these practices transfer into WordPress-focused workflows (e.g., block development, theme design)? ### 🔮 Future Research - Investigate libraries or tooling that normalize diffs for HTML artifacts, making version control more manageable. - Explore automatic conversion pipelines from HTML artifacts into long-lived documentation within platforms like WordPress. - Study accessibility of agent-generated HTML and how to steer agents toward semantic, standards-compliant output. - Examine impact of interactive editing tools on data and prompt governance in larger organizations. ### 💡 Implications - Practice: Teams can raise the quality of communication with AI by treating HTML as the primary medium for complex artifacts. - Policy: Engineering orgs may want guidelines on where and how HTML artifacts are stored, reviewed, and retired. - Security: Interactive HTML introduces potential risks; review and hosting standards are needed. - Education: Training materials can be made more engaging and accessible through HTML diagrams and playgrounds. - Funding: Supporting ecosystem tools for HTML artifact workflows (diffing, hosting, templating) may have outsized impact. ### 🧠 Learning Styles Assessment - Reading level estimate: The text is roughly at an upper high-school to early college level (Flesch–Kincaid Grade ≈ 11–13), with technical jargon. #### 👀 Visual learners - Present: Emphasis on diagrams, SVG, layout, and visual structure within HTML artifacts. - Improve: Include more explicit before/after mockups of the same content in Markdown vs HTML with annotations. #### 🔊 Aural learners - Present: No explicit audio support described. - Improve: Add short audio summaries or screencast walkthroughs of HTML artifacts. #### 🗣️ Verbal learners - Present: Clear prose explanations and example prompts; strong emphasis on narrative use-cases. - Improve: Add glossaries for terms like MCPs, artifacts, and design-systems. #### 🧩 Kinesthetic learners - Present: Encourages hands-on use of HTML playgrounds and custom editors. - Improve: Provide step-by-step mini-labs (“build this HTML explainer from scratch with Claude”). #### 🧠 Logical learners - Present: Structured arguments contrasting Markdown vs HTML; lists of use-cases and tradeoffs. - Improve: Add explicit decision trees or matrices for when to choose each format. #### 🧑‍🤝‍🧑 Social learners - Present: Focus on collaboration (PR reviews, leadership reports, team specs). - Improve: Offer facilitation guides for using HTML artifacts in meetings and reviews. #### 🧘‍♀️ Solitary learners - Present: Encourages individual exploration of HTML examples and personal workflows. - Improve: Include reflection prompts (“which artifacts do you currently skim?”). #### 🌿 Naturalistic learners - Present: No explicit environmental analogies or sustainability framing. - Improve: Draw parallels between ecosystems and interconnected HTML artifacts; mention sustainability of reducing rework. ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Conceptually, HTML can provide headings and landmarks. - Improve: Emphasize semantic HTML, alt text for diagrams, and avoiding div-only layouts. #### Keyboard navigation - Present: Not addressed. - Improve: Recommend focus management, logical tab order, and visible focus styles in generated artifacts. #### Contrast and readability - Present: No explicit guidance. - Improve: Suggest default styles that meet 4.5:1 contrast and adequate line spacing. #### Text resizing and reflow - Present: Mentions responsive layouts generally. - Improve: Explicitly prompt agents to support zooming and reflow without horizontal scroll. #### Media and captions - Present: Uses images and diagrams conceptually. - Improve: Encourage captions and text equivalents for all diagrams and interactive elements. #### Forms and interactions - Present: Discusses custom editors and interactive controls. - Improve: Add guidance on labeling, error messages, and target sizes. #### Standards reference - Map recommended practices to WCAG 2.2 AA (e.g., contrast, keyboard access, focus visibility, reflow, input assistance). ### 🌍 DEIB Assessment #### Cultural breadth - Present: Content is largely US/tech-industry centric. - Improve: Include examples from different org sizes, regions, and sectors. #### Inclusive language - Present: Neutral, non-gendered, and professional. - Improve: Add more definitions for jargon to support non-native speakers and newcomers. #### Neurodiversity support - Present: HTML artifacts can support chunking and visual structure. - Improve: Promote consistent layouts, icon+text labels, and options for reduced complexity views. #### Representation - Present: No explicit human imagery or identity references. - Improve: When adding visuals, ensure diverse representation and descriptive alt text. #### Psychological safety - Present: Encourages being “in the loop,” reducing anxiety about opaque automation. - Improve: Provide guidance on using HTML artifacts in blameless postmortems and constructive feedback. ### ✅ Logical Validity #### Strong reasoning - Clear causal reasoning: richer, more interactive artifacts → higher likelihood of being read → better oversight and outcomes. - Inductive support from personal practice: the author reports switching nearly everything to HTML and seeing improved engagement. #### Fallacies - Possible selection bias: examples and observations come mainly from the author’s context and team. - Mitigation: propose collecting broader empirical data from other teams and domains. #### Tone of voice - Tone is pragmatic, optimistic, and experience-driven—part technical guide, part personal reflection, with an undercurrent of enthusiasm for HTML as a medium. ### 🛡️ DARVO Analysis - Deny: No denial of problems; the author openly acknowledges downsides like noisy diffs and slower generation. - Attack: No attacks on people or communities; critique is aimed at Markdown’s limitations as a medium. - Reverse victim/offender: Not present; the piece frames the author as regaining agency by changing tools, not as a victim. ## 🎯 Conclusion HTML is positioned as a more expressive, human-friendly medium for collaborating with powerful agents than Markdown—especially for specs, reviews, designs, reports, and custom editors. Despite higher token and time costs and weaker diffs, HTML artifacts increase comprehension and keep humans genuinely “in the loop.” Practical next steps: start asking your agent for HTML artifacts for your next spec, PR explainer, or report, and iterate toward patterns that fit your team. ## 🧱 Refactor Appendix (append after 🎯 Conclusion) ```markdown ### 📚 Literature Split Pad - Purpose: Stage Konik CEE units that become per-source Literature notes. - Split level: **H3**. - Include verbatim quotes under 25 words and a [view highlight] link. ### [H1] 5–10-word present-tense claim > [!quote] [{Title or entity}]({ARTICLE_URL}) by [[{Author or [MISSING]}]] via [[{Site or [MISSING]}]]. Published {DATE_OR_[MISSING]}. Accessed . > “Short quote, verbatim, ≤25 words.” Two lines: context and use. Cite data if relevant. [view highlight]({ARTICLE_URL}#H1) #xref #articleseed ID:rw_[MISSING] ### [H2] 5–10-word present-tense claim > [!quote] [{Title or entity}]({ARTICLE_URL}) > “Short quote, verbatim, ≤25 words.” Two lines: context and use. [view highlight]({ARTICLE_URL}#H2) #xref ID:rw_[MISSING] --- ### 🔖 Atomic Split Pad (Zettel Candidates) - Purpose: Promote reusable claims into Atomic notes. - Split level: **H4**. - Each item: one idea, present tense, specific, testable. #### [Z1] 5–10-word present-tense claim - Scope/condition in one line. - Pointer to page/time or dataset. - Links: [[Parent-Concept]] [[Related-Idea]] #### [Z2] 5–10-word present-tense claim - Scope/condition in one line. - Pointer to page/time or dataset. - Links: [[Parent-Concept]] [[Related-Idea]] --- ### ✏️ Fleeting Queue (Extract by Selection) - Purpose: Capture quick actions or sparks for Fleeting notes. - Extraction: **Select one line** → “Refactor: Extract selection to new note (content only).” - Keep each line short and self-contained. - [F1] Short action — context/{ARTICLE_URL} #fleeting #inbox - [F2] Short action — context/{ARTICLE_URL} #fleeting #inbox - [F3] Short action — context/{ARTICLE_URL} #fleeting #inbox --- <!-- deep-read:sections end --> 📄 **Full text:** ![[Full Document Contents/Tweets/Using Claude Code The Unreasonable Effectiveness of HTML.md|Using Claude Code: The Unreasonable Effectiveness of HTML by Thariq]] ## Highlights - Sometimes it’s hard to describe what you want purely in a text box. In this case, I'll ask Claude to build me a throwaway editor for the exact thing I'm working on. Not a product, or a reusable tool, but a single HTML file, purpose-built for this one piece of data. ([View Highlight](https://read.readwise.io/read/01krbqqztpfe3d7g8msjmpt4gt)) - Tags: 👻 ai highlighted - The frontend design plugin helps Claude make good HTML files. But to match your own companies style, you can create a single design system HTML file by pointing Claude at your codebase. You can then use that design system file as a reference for other html files. ([View Highlight](https://read.readwise.io/read/01krbqqzvtkdbnshfw1dpgd5cc)) - Tags: 👻 ai highlighted