Twenty self-contained .html files an agent produced instead of a wall of markdown. Each one trades a document you'd skim for one you'd actually read, open any of them directly in a browser. Grouped by the kind of work they replace.
When you're not sure what you want yet. Ask the agent to fan out across several directions and lay them next to each other so you can point at one: instead of reading three sequential walls of text. Once you've picked, turn the pick into a plan the implementer can read.
Side-by-side comparison of three ways to solve the same problem, with trade-offs called out inline.
A handful of layout and palette options rendered live so you can react to them, not imagine them.
Milestones on a timeline, a data-flow diagram, inline mockups, the risky code, and a risk table: the plan you hand off.
Diffs and call-graphs are spatial information; markdown flattens them. Let the agent render the change as an annotated diff, draw the module as boxes and arrows, or write the PR description your reviewers actually want, so the shape of the code is visible at a glance.
A diff rendered with margin notes, severity tags and jump links: easier to scan than scrolling a terminal.
The author's side: motivation, before/after, a file-by-file tour with the why, and where to focus the review.
An unfamiliar package drawn as boxes and arrows, with the hot path highlighted and entry points listed.
HTML is the medium your design system ships in, so it's the natural format for talking about it. Tokens become swatches, components become contact sheets, and the artifact can be fed straight back into the next prompt.
Colors, type scale and spacing tokens pulled from a repo and rendered as swatches you can copy from.
Every size, state and intent of one component laid out on a single sheet for review.
Motion and interaction can't be described, only felt. A throwaway page with the real easing curve or the real click-through tells you in five seconds what a paragraph of prose never could.
The transition in isolation with sliders for duration and easing, so you can tune it before wiring it in.
Four screens linked together: enough fidelity to feel whether the interaction is right.
Inline SVG gives the agent a real pen. Ask for the figures for a post or a flowchart of a process and get vector art you can tweak by hand or paste straight into the final document.
The diagrams for a blog post, drawn inline so they can be tweaked and copied out one by one.
A deploy pipeline drawn as a real flowchart: click any step to see what runs, timings, and failure paths.
A handful of <section> tags and twenty lines of JS is a slide deck. Point the agent at a Slack thread or a design doc and get something you can arrow-key through in a meeting, no Keynote, no export step.
An explainer with collapsible sections, tabbed code samples and a glossary in the margin reads very differently from the same words dumped linearly. The agent can build the scaffolding that makes a new topic navigable.
"Explain rate limiting in this repo" · TL;DR box, collapsible request-path steps, tabbed config snippets, and an FAQ.
Consistent hashing taught with a live ring you can add/remove nodes from, a comparison table, and a hover-linked glossary.
Recurring documents: status updates, post-mortems: benefit most from a bit of structure and color. A small chart and a colored timeline turn something people skim into something they actually read.
Sometimes it's hard to describe what you want in a text box. Ask for a throwaway editor for the exact thing you're working on, and always end with an export button that turns whatever you did in the UI back into something you can paste into the agent or commit. You stay in the loop; the loop gets tighter.
Drag thirty tickets across Now / Next / Later / Cut, then copy the final ordering out as markdown.
Toggles grouped by area, dependency warnings when a prerequisite is off, and a "copy diff" button for just the changed keys.
Editable template on the left with variable slots highlighted; three sample inputs on the right re-render live as you type.
No build step. No framework. View source on any of these: they were generated by an agent, in a single shot, in response to a paragraph of intent. The format is the point: HTML is a richer canvas than markdown for the kind of work agents are starting to do.
The original gallery and the essay it accompanies live at thariqs.github.io/html-effectiveness.