| name | html-design-examples |
| description | Reference gallery of polished single-file HTML artifacts demonstrating effective ways to communicate ideas through HTML. Use when the user wants to explain, showcase, demo, plan, review, or present an idea within an HTML file. |
| metadata | {"source":"Adapted from https://x.com/trq212/status/2052809885763747935"} |
HTML Design Examples
A library of self-contained .html files showing how a static HTML artifact can carry more signal than the same content as markdown. Use them as visual and structural references when building an HTML deliverable for a similar task.
Why HTML, not markdown
The bottleneck is human attention, not what the agent can produce. A 500-line markdown plan goes unread; the same content as one HTML page with diagrams, tables and inline controls gets engaged with. HTML carries tables, SVG, CSS layout, scripts and spatial composition in a single file, opens in any browser, and shares as a URL rather than an attachment. The token and latency cost is real, and worth it for any artifact that needs to be read by a human.
Prefer HTML for human-facing, ephemeral artifacts (specs, plans, reports, writeups, prototypes, throwaway editors). Stay with markdown or source for things that need durable, line-by-line review in a repo (RFCs, ADRs, runbooks) - HTML diffs are noisy.
How to use this skill
- Pick the example that most closely matches the user's intent (catalogue below).
- Read that file in full before writing your own. The reference's style, density, and structure are the point.
- Match the shared conventions (see "Conventions").
- Adapt to the user's real content. The examples use a fictional "Birchline" brand and fixture data - do not carry that across.
- If the artifact is an editor or any interactive surface, end it with a "copy as JSON" or "copy as prompt" button so the user's work flows back into the agent loop.
