Repository navigation
HTML First
Self-contained HTML artifacts for spatial, visual, and interactive tasks.
Based on the thesis "HTML is the new Markdown" — when a task benefits from layout, color, real diagrams, or interactivity, produce a single-file HTML artifact instead of linear Markdown.
- Comparing multiple options side-by-side
- Code reviews with annotations
- Design mockups and prototypes
- Architecture diagrams
- Status reports and post-mortems
- Slide presentations
- Custom interactive editors
- "Compare X approaches"
- "Review this PR"
- "Create a mockup"
- "Draw an architecture diagram"
- "Make a status report"
- "Create a slide deck"
- Single-file, self-contained — All CSS/JS inline, no CDN dependencies
-
Mobile-responsive — CSS Grid/Flexbox,
clamp(), touch targets ≥ 44px - Accessible — Semantic HTML, WCAG AA contrast, aria-labels
- No "AI aesthetic" — No purple-blue gradients, no glassmorphism
- Respect existing design systems if present
- Round-trip first — Export buttons for JSON/Markdown
Foundation with CSS custom properties and dark mode support.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<style>
:root {
--bg: #ffffff;
--text: #1a1a1a;
--primary: #0066cc;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #1a1a1a;
--text: #ffffff;
}
}
</style>
</head>
<body>
<main>Content here</main>
</body>
</html>2-6 options side-by-side with trade-offs.
Use when: "Compare X, Y, and Z"
Timeline + mockups + code + risk table.
Use when: "Create an implementation plan"
Diff annotated + margin notes + severity tags.
Use when: "Review this PR"
What shipped / what slipped / metrics.
Use when: "Create a status report"
TL;DR + collapsibles + glossary hover.
Use when: "Explain concept X"
<section> + arrow-key navigation + speaker notes.
Use when: "Create a presentation"
Toggle/drag/form + "copy as JSON/Markdown".
Use when: "Build a triage tool"
Don't use HTML when:
- Short responses (1-2 paragraphs)
- Code snippets only
- Terminal commands
- Quick chat messages
| Token | Light | Dark |
|---|---|---|
--bg |
#ffffff |
#1a1a1a |
--text |
#1a1a1a |
#ffffff |
--primary |
#0066cc |
#4da6ff |
--border |
#e0e0e0 |
#333333 |
--muted |
#666666 |
#999999 |
- HTML-First-Exploration — Comparison grids and planning
- HTML-First-Code-Review — PR review patterns
- HTML-First-Design — Mockups and prototypes
- HTML-First-Diagrams — Architecture and sequence diagrams
- HTML-First-Reports — Status reports and post-mortems
- HTML-First-Decks — Slide presentations
- HTML-First-Editors — Custom interactive editors
- HTML-First-Tokens — Design token baseline
- HTML-First-Design-System — Extracting design systems
Last updated: June 2026