Use this skill when the user wants a polished, shareable, source-grounded, self-contained HTML artifact in the Birch visual system for engineering, product, planning, review, status, incident, process, codebase, data, or benchmark communication. Trigger for one-pagers, visual summaries, reports, dashboards, module/process explainers, implementation plans, design-direction comparisons, PR/change writeups, findings-first code reviews, incident/status reports, briefing decks, flow diagrams, numeric/data briefs, model/run/token/ time/cost reports, and design-system references. Do not use it for editing production web apps, React/Vue components, or ordinary chat answers.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use this skill when the user wants a polished, shareable, source-grounded, self-contained HTML artifact in the Birch visual system for engineering, product, planning, review, status, incident, process, codebase, data, or benchmark communication. Trigger for one-pagers, visual summaries, reports, dashboards, module/process explainers, implementation plans, design-direction comparisons, PR/change writeups, findings-first code reviews, incident/status reports, briefing decks, flow diagrams, numeric/data briefs, model/run/token/ time/cost reports, and design-system references. Do not use it for editing production web apps, React/Vue components, or ordinary chat answers.
Birch HTML
Create one complete, locally opening Birch HTML artifact. Optimize for complete
HTML, preserved Birch CSS placeholder, source-grounded claims, 390px mobile
safety, strict component contracts, and minimal page-local CSS.
Output contract
Return a full HTML document only: no prose, Markdown fences, or partial HTML.
If writing to disk, validate and return only the artifact path.
Keep the placeholder exactly until postprocessing:
<style data-birch-system>__BIRCH_SYSTEM_CSS__</style>.
Do not paste bundled Birch CSS or modify canonical CSS/scripts/resources.
No network assets: no remote URLs, CDNs, fonts, iframes, images, scripts, or styles.
Use <main class="page stack" data-gap="lg"> as the outer visible shell.
Do not replace the Birch shell with a custom app/dashboard shell. Do not make
body, .container, .report, or .dashboard the visible page shell.
Do not invent Birch classes/CSS variables or use Birchline-only classes. In
particular, avoid custom path/helper classes such as .file-path and avoid
variables such as --color-*, --size-*, --s-*, , or
unless they are already defined by Birch.
--bg-alt
--fg-muted
Use flat token surfaces only: no gradients, glassmorphism, glow backgrounds,
decorative background images, or custom dashboard skins.
Birch style forbids gradients for card, panel, page, and callout backgrounds
and for body/page backgrounds (for example linear-gradient,
radial-gradient, or conic-gradient). Use flat Birch token surfaces instead.
For diffs, never paste raw unified-diff text into <pre> or code blocks.
Represent patch lines with .diff-row; the only literal +/- marker should
be inside <span class="mark">.
Workflow
Read sources first: files, diffs, data, logs, commands, screenshots, session
notes, and local links before writing claims.
Make a terse brief: audience, purpose, exact paths/values, caveats, unknowns,
sections, and chart intent.
Ask only if missing audience, scope, sources, or output path would materially
change the result; otherwise proceed and label assumptions.
Load only needed recipes: numeric-data, code-review, pr-change-writeup,
implementation-plan, module-explainer, process-explainer,
design-directions, status-incident-report, flow-diagram, slide-deck,
benchmark-comparison, or design-system-reference.
If no path is specified and filesystem access exists, write a descriptive
kebab-case .html file in the current directory.
Prefer copying skill/resources/template.html; replace body content only.
Then run uv run skill/scripts/finish_birch_html.py <output.html>.
Validate before returning: doctype, html/head/body, viewport, title, .page,
Birch CSS placeholder/embedded CSS, closing </html>, no network assets, no
unknown classes/variables, strict children, wrapped long content, no 390px
overflow, and no raw patch marker lines. If available run:
uv run --with pillow python skill/scripts/check_birch_renderings.py --artifact <output.html>.
Put exact values, file paths, commands, caveats, and verification evidence near
the claim they support.
Use neutral uncertainty language: “observed”, “suggests”, “not verified”,
“source not present”.
Do not claim performance, risk, ownership, intent, or causality without source
support. Label assumptions.
Prefer captions citing paths/functions over broad narrative.
Birch primitives and local CSS
Build with primitives, not custom boxes: .section, .section-head, .stack,
.cluster, .card, .panel, .auto-grid, .section-rail,
.reference-panel, .chart-panel, .chart-svg, .chart-caption,
.stat-card, .stat-value, .metric-list, .metric-row,
.numeric-table-wrap, .numeric-table, .flow-list, .flow-step,
.code-block, .diff, .checklist, .plain-list, .insight-list,
.takeaway-list, .chip, .caption, .lede, .scroll-x.
Use semantic primitives in every artifact: sections plus cards, lists, tables,
flow steps, diff rows, metric lists, or chart panels as relevant.
Page-local CSS: ideally none; hard target under 30 lines / 1.5 KB. Use it only
for page-specific SVG sizing, chart sizing, tiny gaps, or wrapping. Do not
recreate shells/cards/grids/rails/tables/typography/badges/meters, redefine
Birch primitives, or use linear-gradient, radial-gradient, or
conic-gradient. Put local CSS after the Birch placeholder/link. Use only
Birch variables (--bg, --surface, --text, --border-color, --accent,
--success, --danger, --info, --space-1…--space-8, and documented
color tokens).
Mobile safety
Design for 390px. Rows, chips, stat values, code, tables, and SVGs must wrap or
scroll inside their own container without page-level horizontal overflow.
If prose/list text wraps to one or two words per line in a wide card, remove
custom grid/flex and stack it.
Long paths, commands, hashes, identifiers, URLs, diff lines, numeric notes, and
symbols must wrap or live inside .scroll-x.
Use data-wrap="true" on every long .code-block and .diff.
Do not use long paths/identifiers as headings; put them in captions, prose,
<code>, wrapped blocks, or short chips.
Keep chips and <h1> short; move long nouns to lede/captions.
Numeric tables always use
<div class="numeric-table-wrap"><table class="numeric-table">...</table></div>.
Keep numeric tables to 3–5 columns. Split wide data into smaller tables plus
KPI cards. Avoid all-in-one tables with long prose cells.
If table cells contain paths, notes, code, commands, or long labels, add:
.numeric-table code, .numeric-table .note { white-space: normal; overflow-wrap: anywhere; word-break: break-word; }
Never put long paths, excerpts, or prose-heavy evidence in narrow table
columns unless the table is wrapped and those cells can break anywhere; prefer
stacked cards, lists, or .code-block data-wrap="true" for code-review
evidence.
Use .scroll-x only for truly wide comparisons; otherwise reduce columns.
In side rails, avoid long .metric-row values; prefer KPI cards, lists, or
compact metric CSS vars.
Layout rules
Prefer .section-rail: main content first, then <aside class="reference-panel">.
Avoid .split for plans, source-vs-assumption blocks, or columns with headings
on both sides; use .section-rail or stacked cards.
KPI strips use .auto-grid with style="--grid-min: 160px".
Keep side rails short: caveats, sources, compact KPIs only.
Numeric/data artifacts must show evidence in the first desktop viewport:
compact hero, KPI strip, and chart/ranking/table start.
Numeric/data and benchmark pages need KPI cards or valid metric rows, a chart
or ranking, a numeric table, and source/caveat captions.
Strict components
Diff rows
Never put raw patch text directly in HTML source or code blocks. No generated
source line may begin with +, -, or @@ to represent a patch. Use
.diff-row with exactly three direct children: .ln, .mark, .code; mark
text is +, -, or one space; added rows use .add/data-kind="add",
deleted rows use .del/data-kind="del".
Use .metric-row only for label + meter + short value; not for metadata,
timelines, work items, prose, or key/value rows. It has exactly three direct
children: .caption, .meter, code. Do not add extra children or .metric
inside .metric-row. Long labels/values belong in cards, lists, or tables.
In insight/takeaway lists, each <li> has exactly one direct wrapper child.
Numeric <th> and <td> cells need class="metric" so headers and values align.
Use short table headers; explain long meanings in captions.
SVG, charts, and reports
Put inline SVG inside .panel.chart-panel.stack; usually wrap the SVG with
.chart-svg and add .chart-caption.
Keep SVG text short, away from right edges; leave viewBox margin or move labels
to captions/lists.
Tiny hand-written SVG: 5–8 nodes max. Every data path/polyline sets
fill="none", a Birch-colored stroke, and restrained stroke-width.
If SVG labels risk 390px overflow, stack vertically or use numbered nodes plus
a following .flow-list.
For real plotted data, prefer Python-generated inline SVG using
scripts/birch_mpl.py; run a temporary driver as needed, inline SVG in a
chart panel, and pair with exact values in narrow .numeric-tables.
Artifact patterns
Module/runtime explainers: short transformation title, caveat paragraph, SVG
flow of 5–8 nodes, caption citing source files/functions, then ordered
.flow-list file tour or runtime walkthrough. Prefer flow steps, cards, and
captions over dense tables.
Numeric/benchmark reports: inspect schema and rows; use KPI cards for headline
counts/totals/best/worst/pass/fail/cost/time; use valid .metric-list only for
true progress/ranking values; include charts when they clarify tradeoffs; pair
charts with exact values and source/caveat captions.
