mirror of
https://github.com/plannotator/effective-html.git
synced 2026-09-19 01:11:19 +08:00
Michael Ramos
71 lines
3.2 KiB
Plaintext
71 lines
3.2 KiB
Plaintext
---
|
|
title: Effective HTML guide
|
|
description: Use context-rich HTML artifacts to understand, review, and direct agent work.
|
|
---
|
|
|
|
Effective HTML is a field guide to making visual, interactive artifacts with
|
|
agents. It is for developers and for anyone who needs to understand, review, or
|
|
direct agent work.
|
|
|
|
This guide collects ideas from Anthropic engineer Thariq Shihipar's [essay on
|
|
effective HTML](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html)
|
|
and [examples](https://thariqs.github.io/html-effectiveness/), Geoffrey Litt's
|
|
[work on understanding](https://www.geoffreylitt.com/2026/07/02/understanding-is-the-new-bottleneck),
|
|
and [Frontend Slides](https://github.com/zarazhangrui/frontend-slides) in one
|
|
place.
|
|
|
|
## Start without a skill
|
|
|
|
You do not need to install a skill to use these patterns. Ask an agent to make
|
|
an HTML artifact, provide the source context and the decision it needs to
|
|
support, then review the result.
|
|
|
|
The working bias is **fat artifacts + fat context**. Give the agent the real
|
|
brief, source material, constraints, examples, and accepted decisions. Let the
|
|
artifact carry the working detail through realistic content, annotations,
|
|
states, and interactions. The prompt and skills can stay thin. Use a skill when
|
|
a pattern recurs or a team needs shared defaults; once the pattern is familiar,
|
|
the skill may stop adding value.
|
|
|
|
HTML is useful with agents because it can combine structure, visual form, and
|
|
interaction in one inspectable thing.
|
|
|
|
The point is not to replace Markdown. The point is to recognize the decisions
|
|
that become easier when the artifact can show layout, compare alternatives,
|
|
respond to input, or expose relationships directly.
|
|
|
|
## Start with the decision
|
|
|
|
Ask what the next human judgment actually is:
|
|
|
|
- **What belongs, and where?** Start with a wireframe.
|
|
- **How should this feel and look?** Make a more resolved mockup.
|
|
- **Does this flow behave correctly?** Build a prototype.
|
|
- **How do these parts relate?** Draw a diagram.
|
|
- **What story needs deliberate sequence and pacing?** Build a browser-native deck.
|
|
- **What sequence preserves the source commitments?** Write a plan.
|
|
|
|
Higher fidelity is not automatically better. The right artifact is the lowest
|
|
fidelity that answers the current question without creating a new distraction.
|
|
|
|
## The working loop
|
|
|
|
1. Name the decision the artifact needs to support.
|
|
2. Choose the form and fidelity that make that decision visible.
|
|
3. Make one self-contained artifact with realistic content.
|
|
4. Inspect it at real desktop and mobile sizes.
|
|
5. Review the structure, behavior, and boundaries that matter at this stage.
|
|
6. Revise or advance the fidelity only when the next decision requires it.
|
|
|
|
## What this guide covers
|
|
|
|
The guide covers wireframes, prototypes, diagrams, browser-native decks, and
|
|
plans. It also includes a generic [artifact design
|
|
approach](/docs/designing-artifacts) that can sit above any of those forms. The
|
|
examples stay inspectable and source-grounded. They demonstrate the patterns;
|
|
they are not prerequisites for using them.
|
|
|
|
Continue with [why HTML](/docs/why-html), learn the generic approach to
|
|
[designing artifacts](/docs/designing-artifacts), or go directly to [choosing
|
|
fidelity](/docs/choosing-fidelity).
|