Why HTML?
Use HTML when the medium makes the decision easier to understand.
Markdown is excellent for linear explanation. HTML becomes more useful when space, comparison, state, or participation carry part of the meaning.
The medium earns its place when it removes translation work.
Confirm the owner, resolve blockers, validate the build, then release.
- Resolve blocking checks
- Confirm ownership
- Run validation
HTML · spatial evidenceBoth artifacts can be correct. Use the HTML version only when seeing hierarchy, width, state, or interaction changes the review.
HTML can show the thing
A layout discussion changes when reviewers can see the hierarchy at the target width. A behavior discussion changes when they can operate the control. A system discussion changes when relationships occupy a shared visual field.
The artifact reduces translation work between an agent's description and a human's judgment.
HTML can hold multiple forms of evidence
A single page can combine:
- prose that explains the constraint;
- a wireframe that exposes the hierarchy;
- a diagram that clarifies the relationship;
- a control that demonstrates the state change;
- an annotation that names the unresolved decision.
That combination is valuable when each form contributes something different. It becomes noise when HTML is used only to decorate information that would be clearer as a short document.
HTML can be reviewed as a real boundary
A self-contained artifact can be opened at real viewport sizes, navigated with a keyboard, inspected for contrast, and tested in loading, empty, failure, and success states. Those checks turn a proposal into something concrete enough to redirect.
Keep Markdown when it is enough
Prefer Markdown for a linear plan, short explanation, or source-grounded list of commitments unless visual or interactive structure adds meaningful leverage. HTML is not the default. It is a medium chosen for a particular kind of understanding.
Choose the lowest useful fidelityMatch the artifact's finish to the decision being made now.