| name | create-doc |
| description | Author a self-contained, framework-free HTML document — a brief, report, or explainer — by reading the generated @butai/docs-kit catalog, composing its doc patterns (hero, section, callout, card grid, metric grid, table, comparison, decisions, timeline, code block, quote band, footer), and styling the whole page through the token contract with a chosen butai theme. Use when the user says '/create-doc', "make a page/doc/brief/report", "an explainer", "capture this as a browsable HTML artifact", "render this design / decision / comparison / plan as a page", or wants a themeable HTML document richer than markdown. One `.html` file, inline CSS, no external runtime deps — it opens and paints offline anywhere.
|
| argument-hint | <topic or what to explain, e.g. 'compare our two caching options'> |
butai HTML Page
What this does
Turns a design, decision, comparison, or plan into a single self-contained HTML
document — a brief, a report, or an explainer — built from the butai doc-pattern
kit. The output is one .html file with inline CSS and no external runtime
dependencies: it opens and paints anywhere, offline, and travels well beside the
work it documents.
The page is framework-free (plain HTML + CSS, no React, no build step) and
restyleable by any butai theme: you author it once in neutral token-contract
variables, and a theme repaints the whole document by supplying a different token
block — same HTML, different look. Nothing personal, no product message, and no
external service is baked in.
When to use
- The user wants a brief / report / explainer captured as a browsable HTML page.
- A design discussion, set of decisions, comparison, or plan is worth a richer
artifact than markdown.
- The user wants something laid out visually and themeable, not prose.
Do not use this for documents the user wants as markdown, or for diagrams.
The flywheel: read the generated catalog, never a hand table
The available patterns are not hand-maintained in this skill. They are
discovered from the docs-kit's generated catalog, so as the kit grows this skill
grows with it automatically:
- Read
packages/docs-kit/catalog/catalog.json (the committed, byte-stable
catalog gen produces) — or import the PATTERNS array from @butai/docs-kit
(the isomorphic root barrel) — to list every doc pattern, its id, category,
description, and tags.
- The full renderable fragment for a pattern is
packages/docs-kit/src/patterns/<id>.html;
the catalog's snippet is a short copy-ready excerpt, not the whole fragment.
- Never invent a pattern that is not in the catalog, and never hardcode a pattern
list here. If the page needs a component the kit lacks, add it to the kit (a new
pattern via the pattern-authoring flow), then re-read the catalog — capture
once, reuse forever.
The seed kit (categories in parentheses) covers the common doc shapes:
| Pattern id | Use it for |
|---|
doc-hero (header) | the opener — eyebrow, one tight headline, a one-line summary, a date + status meta row |
section-header (structure) | a section break — uppercase eyebrow + h2 with a hairline |
callout (emphasis) | the thesis — one line that matters, accent-washed |
card-grid (content) | a responsive grid of status-badged cards |
metric-grid (data) | a trio of counted stat cards (kicker + big number + caption) |
data-table (data) | a full-width comparison table, two tinted columns |
comparison (data) | a side-by-side before/after (or A/B) pair |
decisions (structure) | a numbered, ADR-style locked-decisions list |
timeline (structure) | a stepped vertical sequence (or a horizontal flow) |
code-block (code) | a terminal / console window + hand-highlighted code (no highlight.js, no CDN) |
quote-band (emphasis) | a full-bleed pull-quote / emphasis band |
doc-footer (closing) | a closing "what's next" CTA band that ends with momentum |
Always confirm the live list against the catalog; the table above is a map, not
the source of truth.
Pick patterns by intent
Choose components by what the page argues, then compose them top to bottom:
- A comparison →
comparison + data-table.
- Locked decisions →
decisions.
- A pipeline / sequence / steps →
timeline.
- A thesis or a strong closing line →
callout and/or quote-band.
- A group of options / items →
card-grid.
- Numbers / results →
metric-grid.
- "What it feels like" / a command session →
code-block.
Open with doc-hero, state the thesis in a callout, compose the body from the
patterns that fit, and end with doc-footer — forward momentum, not a summary.
Hard rules (the doc contract)
- Framework-free. Plain HTML + CSS only. No React, no Remotion, no bundler,
no build step. The file must open and paint on its own in a browser.
- Style only through the token contract. Use the contract variables, never
raw hex in the layout:
var(--bg), var(--bg-card), var(--text), var(--text-dim),
var(--accent), var(--accent-glow), var(--border),
var(--green), var(--yellow), var(--blue), var(--red), var(--orange),
var(--font-display), var(--font-body), var(--font-mono).
Status semantics map onto contract tokens: shipped/done → --green,
planned/caution → --yellow, info/next → --blue, critical/removed →
--red/--orange. A page that hardcodes hex in its layout will not restyle by
theme.
- Self-contained, inline CSS, no external runtime deps. One
.html file with
an inline <style>. Ship a fallback :root giving every token the page uses a
default value, plus the page-local design constants the contract does not name
(a deeper surface, a console surface, radii) derived from contract vars — so
the raw file renders standalone and offline. A theme later overrides these by
injecting its own token block.
- Offline-safe, no CDN. System-font fallback stacks in every
font-family;
pure-CSS motion only; no highlight.js (the code pattern hand-highlights via
span classes); no external <script src> or <link href="http…">. An offline
render must stay legible and log no external-fetch errors.
- Personal-data-clean and trademark-clean. Generic copy and
example.com
only. No real names, handles, product names, campaign lines, screenshots,
logos, brand characters, or proprietary provenance. The kit runs a
forbidden-strings guard; violations fail the build.
Steps
1. Settle the content and pick patterns
Identify what the page argues. Read the docs-kit catalog to see the available
patterns and choose the ones that fit the intent (above). Pull the substance from
the conversation; if key content is missing, ask briefly rather than inventing it.
Keep it honest — placeholder frames over invented data, badges for real status.
2. Choose a theme
Pick one of the 13 butai themes (from @butai/themes THEMES). The page is
authored in neutral token-contract variables; the theme supplies the concrete
token block. Inject the chosen theme's tokens as a :root (or [data-theme])
block so the theme's values win over the page's fallback :root. Docs reuse the
same 13 themes as scenes and slides — no page-specific theme layer.
3. Compose the HTML
Assemble one self-contained .html: the inline <style> (fallback :root +
the theme token block + the patterns' scoped styles), then the fragments in
order — doc-hero, the thesis callout, the body patterns, doc-footer. Copy
each pattern's fragment from packages/docs-kit/src/patterns/<id>.html and fill
in real (generic, example.com) copy. Put today's date in the hero's .meta
row, not in the filename.
4. Preview (free, no cost)
- In the Studio: open the
/docs route in apps/studio to see every pattern
in the themed preview gallery and try the theme switcher — a local render, no
network, no cost.
- From Node: call
renderPreviews from @butai/docs-kit/node to write a
per-pattern PNG for a chosen theme to a temporary, git-ignored directory. It is
a headless screenshot proxy — no network, no external service, no credit spend,
no mp4. Screenshots are not byte-stable across machines, so they are never
committed; treat them as throwaway previews.
import { renderPreviews } from "@butai/docs-kit/node";
await renderPreviews({ theme: "dark", outDir: "/tmp/butai-doc-preview" });
5. Save and report
Pick a kebab slug from the topic. Save as <slug>.html next to the work it
documents (no date prefix — the date lives inside the page). Report the saved
path.
Quality checklist
Non-goals
- No React / TSX doc components (framework-free is the architecture).
- No shared external stylesheet or CDN — each page is self-contained.
- No JS syntax-highlight dependency (
code-block hand-highlights via spans).
- No paid render, no mp4, no external render service; previews are local headless
screenshots only.
- No hand-maintained pattern table — read the generated catalog.
- No personal, product, proprietary, or campaign content; generic +
example.com.
- No plugin manifest (that packaging is a later phase).
