Skip to content

HTML First

Josemalyson Oliveira edited this page Jun 27, 2026 · 1 revision

HTML First

Self-contained HTML artifacts for spatial, visual, and interactive tasks.


Overview

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.

When to Use

  • 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

Trigger Phrases

  • "Compare X approaches"
  • "Review this PR"
  • "Create a mockup"
  • "Draw an architecture diagram"
  • "Make a status report"
  • "Create a slide deck"

Universal Rules

  1. Single-file, self-contained — All CSS/JS inline, no CDN dependencies
  2. Mobile-responsive — CSS Grid/Flexbox, clamp(), touch targets ≥ 44px
  3. Accessible — Semantic HTML, WCAG AA contrast, aria-labels
  4. No "AI aesthetic" — No purple-blue gradients, no glassmorphism
  5. Respect existing design systems if present
  6. Round-trip first — Export buttons for JSON/Markdown

Templates

_base.html

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>

comparison-grid.html

2-6 options side-by-side with trade-offs.

Use when: "Compare X, Y, and Z"

implementation-plan.html

Timeline + mockups + code + risk table.

Use when: "Create an implementation plan"

pr-review.html

Diff annotated + margin notes + severity tags.

Use when: "Review this PR"

status-report.html

What shipped / what slipped / metrics.

Use when: "Create a status report"

concept-explainer.html

TL;DR + collapsibles + glossary hover.

Use when: "Explain concept X"

slide-deck.html

<section> + arrow-key navigation + speaker notes.

Use when: "Create a presentation"

custom-editor.html

Toggle/drag/form + "copy as JSON/Markdown".

Use when: "Build a triage tool"


Anti-Patterns

Don't use HTML when:

  • Short responses (1-2 paragraphs)
  • Code snippets only
  • Terminal commands
  • Quick chat messages

Design Tokens

Token Light Dark
--bg #ffffff #1a1a1a
--text #1a1a1a #ffffff
--primary #0066cc #4da6ff
--border #e0e0e0 #333333
--muted #666666 #999999

References


Last updated: June 2026

Clone this wiki locally