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>/* Optional tiny wrapping/SVG fixes only. Prefer deleted. */</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.
1---2name: birch-html3description: 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.4---56# Birch HTML78Create one complete, locally opening Birch HTML artifact. Optimize for complete9HTML, preserved Birch CSS placeholder, source-grounded claims, 390px mobile10safety, strict component contracts, and minimal page-local CSS.1112## Output contract1314- Return a full HTML document only: no prose, Markdown fences, or partial HTML.15- If writing to disk, validate and return only the artifact path.16- Keep the placeholder exactly until postprocessing:17 `<style data-birch-system>__BIRCH_SYSTEM_CSS__</style>`.18- Do not paste bundled Birch CSS or modify canonical CSS/scripts/resources.19- No network assets: no remote URLs, CDNs, fonts, iframes, images, scripts, or styles.20- Use `<main class="page stack" data-gap="lg">` as the outer visible shell.21- Do not replace the Birch shell with a custom app/dashboard shell. Do not make22 `body`, `.container`, `.report`, or `.dashboard` the visible page shell.23- Do not invent Birch classes/CSS variables or use Birchline-only classes. In24 particular, avoid custom path/helper classes such as `.file-path` and avoid25 variables such as `--color-*`, `--size-*`, `--s-*`, `--bg-alt`, or26 `--fg-muted` unless they are already defined by Birch.27- Use flat token surfaces only: no gradients, glassmorphism, glow backgrounds,28 decorative background images, or custom dashboard skins.29- Birch style forbids gradients for card, panel, page, and callout backgrounds30 and for body/page backgrounds (for example `linear-gradient`,31 `radial-gradient`, or `conic-gradient`). Use flat Birch token surfaces instead.32- For diffs, never paste raw unified-diff text into `<pre>` or code blocks.33 Represent patch lines with `.diff-row`; the only literal `+`/`-` marker should34 be inside `<span class="mark">`.3536## Workflow37381. Read sources first: files, diffs, data, logs, commands, screenshots, session39 notes, and local links before writing claims.402. Make a terse brief: audience, purpose, exact paths/values, caveats, unknowns,41 sections, and chart intent.423. Ask only if missing audience, scope, sources, or output path would materially43 change the result; otherwise proceed and label assumptions.444. Load only needed recipes: `numeric-data`, `code-review`, `pr-change-writeup`,45 `implementation-plan`, `module-explainer`, `process-explainer`,46 `design-directions`, `status-incident-report`, `flow-diagram`, `slide-deck`,47 `benchmark-comparison`, or `design-system-reference`.485. If no path is specified and filesystem access exists, write a descriptive49 kebab-case `.html` file in the current directory.506. Prefer copying `skill/resources/template.html`; replace body content only.51 Then run `uv run skill/scripts/finish_birch_html.py <output.html>`.527. Validate before returning: doctype, html/head/body, viewport, title, `.page`,53 Birch CSS placeholder/embedded CSS, closing `</html>`, no network assets, no54 unknown classes/variables, strict children, wrapped long content, no 390px55 overflow, and no raw patch marker lines. If available run:56 `uv run --with pillow python skill/scripts/check_birch_renderings.py --artifact <output.html>`.5758## Required shell5960```html61<!doctype html>62<html lang="en">63<head>64 <meta charset="utf-8" />65 <meta name="viewport" content="width=device-width, initial-scale=1" />66 <title>Clear artifact title</title>67 <style data-birch-system>__BIRCH_SYSTEM_CSS__</style>68 <style>/* Optional tiny wrapping/SVG fixes only. Prefer deleted. */</style>69</head>70<body>71 <main class="page stack" data-gap="lg">72 <header class="stack" data-gap="sm">73 <div class="eyebrow">Review artifact</div>74 <h1>Clear artifact title</h1>75 <p class="lede">One or two source-grounded sentences.</p>76 </header>77 <section class="section stack" data-gap="lg">...</section>78 </main>79</body>80</html>81```8283## Grounding8485- Put exact values, file paths, commands, caveats, and verification evidence near86 the claim they support.87- Use neutral uncertainty language: “observed”, “suggests”, “not verified”,88 “source not present”.89- Do not claim performance, risk, ownership, intent, or causality without source90 support. Label assumptions.91- Prefer captions citing paths/functions over broad narrative.9293## Birch primitives and local CSS9495Build with primitives, not custom boxes: `.section`, `.section-head`, `.stack`,96`.cluster`, `.card`, `.panel`, `.auto-grid`, `.section-rail`,97`.reference-panel`, `.chart-panel`, `.chart-svg`, `.chart-caption`,98`.stat-card`, `.stat-value`, `.metric-list`, `.metric-row`,99`.numeric-table-wrap`, `.numeric-table`, `.flow-list`, `.flow-step`,100`.code-block`, `.diff`, `.checklist`, `.plain-list`, `.insight-list`,101`.takeaway-list`, `.chip`, `.caption`, `.lede`, `.scroll-x`.102Use semantic primitives in every artifact: sections plus cards, lists, tables,103flow steps, diff rows, metric lists, or chart panels as relevant.104105Page-local CSS: ideally none; hard target under 30 lines / 1.5 KB. Use it only106for page-specific SVG sizing, chart sizing, tiny gaps, or wrapping. Do not107recreate shells/cards/grids/rails/tables/typography/badges/meters, redefine108Birch primitives, or use `linear-gradient`, `radial-gradient`, or109`conic-gradient`. Put local CSS after the Birch placeholder/link. Use only110Birch variables (`--bg`, `--surface`, `--text`, `--border-color`, `--accent`,111`--success`, `--danger`, `--info`, `--space-1`…`--space-8`, and documented112color tokens).113114## Mobile safety115116Design for 390px. Rows, chips, stat values, code, tables, and SVGs must wrap or117scroll inside their own container without page-level horizontal overflow.118119- If prose/list text wraps to one or two words per line in a wide card, remove120 custom grid/flex and stack it.121- Long paths, commands, hashes, identifiers, URLs, diff lines, numeric notes, and122 symbols must wrap or live inside `.scroll-x`.123- Use `data-wrap="true"` on every long `.code-block` and `.diff`.124- Do not use long paths/identifiers as headings; put them in captions, prose,125 `<code>`, wrapped blocks, or short chips.126- Keep chips and `<h1>` short; move long nouns to lede/captions.127- Numeric tables always use128 `<div class="numeric-table-wrap"><table class="numeric-table">...</table></div>`.129- Keep numeric tables to 3–5 columns. Split wide data into smaller tables plus130 KPI cards. Avoid all-in-one tables with long prose cells.131- If table cells contain paths, notes, code, commands, or long labels, add:132 `.numeric-table code, .numeric-table .note { white-space: normal; overflow-wrap: anywhere; word-break: break-word; }`133- Never put long paths, excerpts, or prose-heavy evidence in narrow table134 columns unless the table is wrapped and those cells can break anywhere; prefer135 stacked cards, lists, or `.code-block data-wrap="true"` for code-review136 evidence.137- Use `.scroll-x` only for truly wide comparisons; otherwise reduce columns.138- In side rails, avoid long `.metric-row` values; prefer KPI cards, lists, or139 compact metric CSS vars.140141## Layout rules142143- Prefer `.section-rail`: main content first, then `<aside class="reference-panel">`.144- Avoid `.split` for plans, source-vs-assumption blocks, or columns with headings145 on both sides; use `.section-rail` or stacked cards.146- KPI strips use `.auto-grid` with `style="--grid-min: 160px"`.147- Keep side rails short: caveats, sources, compact KPIs only.148- Numeric/data artifacts must show evidence in the first desktop viewport:149 compact hero, KPI strip, and chart/ranking/table start.150- Numeric/data and benchmark pages need KPI cards or valid metric rows, a chart151 or ranking, a numeric table, and source/caveat captions.152153## Strict components154155### Diff rows156157Never put raw patch text directly in HTML source or code blocks. No generated158source line may begin with `+`, `-`, or `@@` to represent a patch. Use159`.diff-row` with exactly three direct children: `.ln`, `.mark`, `.code`; mark160text is `+`, `-`, or one space; added rows use `.add`/`data-kind="add"`,161deleted rows use `.del`/`data-kind="del"`.162163```html164<div class="diff" data-wrap="true">165 <div class="diff-row add"><span class="ln">12</span><span class="mark">+</span><span class="code">added code</span></div>166</div>167```168169### Flow steps170171Every `.flow-step` has exactly two direct children: `.flow-num`, then one172content wrapper. Put titles, paragraphs, lists, and code inside the wrapper.173174```html175<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>176```177178### Metric rows179180Use `.metric-row` only for label + meter + short value; not for metadata,181timelines, work items, prose, or key/value rows. It has exactly three direct182children: `.caption`, `.meter`, `code`. Do not add extra children or `.metric`183inside `.metric-row`. Long labels/values belong in cards, lists, or tables.184185```html186<div class="metric-row"><span class="caption">Pass rate</span><div class="meter"><span style="--value: 98%"></span></div><code>0.98</code></div>187```188189### Lists and tables190191- `.checklist`: pass/done/validated items only; `.plain-list`: neutral bullets;192 `.insight-list`/`.takeaway-list`: key observations.193- In insight/takeaway lists, each `<li>` has exactly one direct wrapper child.194- Numeric `<th>` and `<td>` cells need `class="metric"` so headers and values align.195- Use short table headers; explain long meanings in captions.196197## SVG, charts, and reports198199- Put inline SVG inside `.panel.chart-panel.stack`; usually wrap the SVG with200 `.chart-svg` and add `.chart-caption`.201- Keep SVG text short, away from right edges; leave viewBox margin or move labels202 to captions/lists.203- Tiny hand-written SVG: 5–8 nodes max. Every data `path`/`polyline` sets204 `fill="none"`, a Birch-colored `stroke`, and restrained `stroke-width`.205- If SVG labels risk 390px overflow, stack vertically or use numbered nodes plus206 a following `.flow-list`.207- For real plotted data, prefer Python-generated inline SVG using208 `scripts/birch_mpl.py`; run a temporary driver as needed, inline SVG in a209 chart panel, and pair with exact values in narrow `.numeric-table`s.210211## Artifact patterns212213Module/runtime explainers: short transformation title, caveat paragraph, SVG214flow of 5–8 nodes, caption citing source files/functions, then ordered215`.flow-list` file tour or runtime walkthrough. Prefer flow steps, cards, and216captions over dense tables.217218Numeric/benchmark reports: inspect schema and rows; use KPI cards for headline219counts/totals/best/worst/pass/fail/cost/time; use valid `.metric-list` only for220true progress/ranking values; include charts when they clarify tradeoffs; pair221charts with exact values and source/caveat captions.
evalstate