---
name: composing-html
description: Composes single-file HTML artifacts (PR review writeups, status reports, incident postmortems, slide decks, design systems, prototypes, flowcharts, module maps, feature explainers, kanban boards, prompt tuners) from a small JSON spec instead of hand-written HTML/CSS/JS. Use when the user asks to "compare options side-by-side", requests an HTML version of a report or review or deck, asks for a flowchart, status update, postmortem, design system reference, interactive prototype, custom editor — or explicitly says "HTML artifact", "single HTML file", "self-contained HTML". Skip for ad-hoc HTML snippets (forms, emails, embedded widgets) where there's no template fit.
metadata:
version: 0.5.0
---
# composing-html
Produce single-file HTML artifacts without hand-writing the page chrome. The
composer supplies ``, ``, inlined CSS, `base.js`, design
tokens, masthead, and colophon. You supply a title and the body content.
The product is the **chrome and inventory below** — primitives you can drop
into any artifact without re-deriving what a card, badge, or eyebrow looks
like. Templates are shortcuts on top of this, useful when the same artifact
shape repeats; see [Templates](#templates-shortcuts-for-repeat-structure)
near the end.
## Default workflow: freeform
`freeform` gives you the whole chrome with one content slot — `body_html` —
for the page body. Reach for it first. Reach for a template only when the
structure repeats across artifacts (see [Templates](#templates-shortcuts-for-repeat-structure)
near the end).
There are two ways to invoke it. **Use the `--set` flow for anything with a
substantial body** — it sidesteps the JSON-string escaping that bites
heredoc-style spec writing (newlines, quotes, `<`/`&` inside multi-line
HTML).
### Recommended: HTML in a file, metadata via `--set`
```
1. Write the body to a .html file directly (no JSON, no escaping).
2. python scripts/build.py build freeform \
--set title='My Page' \
--set subtitle='Optional subhead' \
--set body_html=@body.html \
--out artifact.html
```
`--set KEY=VALUE` assigns a literal string; `--set KEY=@FILE` loads the file
contents verbatim into that spec field. Repeat for any field. Works for
`body_html`, `extra_css`, `extra_js`, `eyebrow`, `page_class`, and the same
`*_html` fields in any other template (`summary_html`, `intro_html`,
`details_html`, …).
### Spec-file workflow (best for structured templates)
```
1. python scripts/build.py describe # required keys + skeleton
2. write spec.json
3. python scripts/build.py build --spec spec.json --out artifact.html
```
For templates with typed slots (`pr_review.findings[]`, `slide_deck.slides[]`,
`status_report.metrics[]`), the spec file is the right shape — the template
reasons over the structure. For `freeform`, the spec is mostly a thin config
wrapper around one HTML string; the `--set` flow above is usually less
friction.
You can mix both: small `spec.json` for metadata, `--set body_html=@body.html`
for the heavy bit. `--set` overrides any matching field from `--spec`.
### Pitfall: don't inline multi-line HTML into a JSON heredoc
`cat > spec.json <\n..." } EOF` does not
produce valid JSON — JSON strings can't contain raw newlines or unescaped
quotes. Either:
- use `--set body_html=@body.html` (recommended), or
- assemble the spec in Python with `json.dump(spec, f)` so escaping is automatic.
## Inventory
Everything in this section is loaded into every artifact via inlined CSS and
`base.js`. Use these tokens and classes inside `body_html` (or any
template's `*_html` field) without re-declaring them.
### Color tokens
| Token | Hex | Use |
|---|---|---|
| `--ivory` | `#FAF9F5` | Page background |
| `--paper` | `#FFFFFF` | Card background |
| `--slate` | `#141413` | Headings, inverted background |
| `--clay` | `#D97757` | Brand accent (lines, primary actions) |
| `--clay-d` | `#B85C3E` | Hover/dark variant |
| `--oat` | `#E3DACC` | Soft contrast surface |
| `--olive` | `#788C5D` | Success, secondary accent |
| `--rust` | `#B04A3F` | Errors, destructive |
| `--moss` | `#4A6B3A` | Success text |
| `--g100` … `--g700` | grays | Surfaces, borders, body text |
Semantic aliases: `--ok`, `--warn`, `--err`, `--info`.
### Type stacks
- `--serif` — display headings (h1, h2, big numerics).
- `--sans` — body text (default).
- `--mono` — code, eyebrows, badges, captions.
### Geometry
`--radius-sm` (6px) · `--radius` (10px) · `--radius-lg` (16px) ·
`--border` · `--border-soft` · `--shadow-card` · `--shadow-pop`.
### Layout primitives
- `.page` — main column (1080px max). Variants: `.page--wide` (1280px),
`.page--narrow` (720px). Set via the `page_class` spec key.
- `.masthead` — header strip with `.eyebrow` + `
` — small all-caps label
with a leading clay rule.
- **Badge**: `v1.0`.
- **Kbd**: `⌘K`.
- **Bullets**: `
…
` — clay dots.
- **Code**: inline `` and block `
`. Block code gets a
`copy` button automatically via `base.js`.
- **Details**: native `……` styled.
### Tabs
```html
…
…
```
`base.js` wires this automatically and selects the first tab by default.
### Drag-to-reorder
```html
…
…
```
Optional cross-zone drops: add `data-zone=""` to each container.
### Live parameter bindings
```html
```
The CSS custom property `--bind-` is updated on every input event,
and any `[data-out=""]` element receives the formatted value.
## Output rules
Spend output tokens on **content**, not chrome:
1. **Never write ``, ``, `