| name | birch-html |
| description | 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-*, --bg-alt, or
--fg-muted unless they are already defined by Birch.
- 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>.
Required shell
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Clear artifact title</title>
<style data-birch-system>__BIRCH_SYSTEM_CSS__</style>
<style></style>
</head>
<body>
<main class="page stack" data-gap="lg">
<header class="stack" data-gap="sm">
<div class="eyebrow">Review artifact</div>
<h1>Clear artifact title</h1>
<p class="lede">One or two source-grounded sentences.</p>
</header>
<section class="section stack" data-gap="lg">...</section>
</main>
</body>
</html>
Grounding
- 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".
<div class="diff" data-wrap="true">
<div class="diff-row add"><span class="ln">12</span><span class="mark">+</span><span class="code">added code</span></div>
</div>
Flow steps
Every .flow-step has exactly two direct children: .flow-num, then one
content wrapper. Put titles, paragraphs, lists, and code inside the wrapper.
<li class="flow-step"><span class="flow-num">1</span><div class="stack" data-gap="sm"><h3 class="flow-title">Read inputs</h3><p class="flow-detail">Detail.</p></div></li>
Metric rows
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.
<div class="metric-row"><span class="caption">Pass rate</span><div class="meter"><span style="--value: 98%"></span></div><code>0.98</code></div>
Lists and tables
.checklist: pass/done/validated items only; .plain-list: neutral bullets;
.insight-list/.takeaway-list: key observations.- 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.
