| name | birchline-html |
| description | Create polished standalone single-file HTML engineering artifacts in the Birchline design language. Use for session summaries, module/process explainers, implementation plans, design direction comparisons, PR/change writeups, findings-first code reviews, incident/status reports, slide decks, flow diagrams, and compact numeric/data briefs where the output should be a beautiful local HTML document with embedded CSS and no external assets. |
| metadata | {"short-description":"Standalone Birchline HTML artifacts"} |
Birchline HTML
Use this skill when the user wants a beautiful standalone HTML artifact, report,
summary, explainer, plan, or dashboard in the Birchline visual language.
The goal is a single .html file that opens locally, embeds all CSS, uses no
network resources, and reads like a serious engineering artifact rather than a
generic web page.
Workflow
-
Gather the source facts first.
Read files, session notes, data, diffs, commands, and screenshots as needed.
Do not ask the renderer/layout phase to discover facts that the calling agent
can already provide.
-
Build a renderer brief.
Make it self-contained: audience, purpose, known facts, evidence, file paths,
commands, data values, caveats, unknowns, suggested sections, and chart intent.
Mark uncertain details as unknown instead of inventing them.
-
Choose an artifact type.
Use the nearest recipe from references/templates/:
module-explainer.mdprocess-explainer.mdimplementation-plan.mddesign-directions.mdcode-review.mdpr-change-writeup.mdstatus-or-incident-report.mdslide-deck.mdflow-diagram.mdnumeric-data.md
-
Write one complete standalone HTML document.
Start from assets/templates/standalone-shell.html if useful. Inline both:
assets/birchline-core.cssassets/birchline-components.css
-
Validate before finishing.
Check that the file has <!doctype html>, <style>, <body>, closing
</html>, no external scripts/styles/fonts, and responsive layouts for
tables or wide content. If possible, render a desktop and mobile screenshot.
Birchline Rules
- Use ivory/paper backgrounds, slate text, restrained clay accents, serif display
headings, and quiet sans/mono supporting text.
- Favor sections, panels, matrices, stat strips, timelines, code panels, badges,
callouts, and comparison grids.
- Keep cards for repeated items, modals, or framed tools. Avoid nested cards.
- Do not use generic gradient blobs, decorative orbs, stock imagery, CDN fonts,
external CSS, or JavaScript unless the user explicitly needs interaction.
- Keep first viewport useful: title, purpose, status/caveat, and strongest facts.
- Wrap long paths and symbols aggressively; prefer matrices or code panels over
dense paragraphs.
- Exact values should appear as text near charts, not only as shape height/width.
- For large source material, produce a shorter complete artifact rather than an
ambitious incomplete one.
Numeric/Data Guidance
For arbitrary data, inspect the shape before choosing the visualization:
- KPI strip: headline counts, totals, best/worst, pass/fail, cost/time.
- Delta card: before/after or baseline/current comparisons.
- Ranking bars: sorted categories with exact values.
- Grouped bars: compare the same measures across a few categories.
- Progression line: ordered/time progression.
- Small multiples: repeated mini charts for multiple entities.
- Comparison matrix: exact values, statuses, or tradeoffs.
- Distribution strip: spread, range, buckets, or concentration.
- Annotated table: when exact reading matters more than visual drama.
Use CSS or hand-written inline SVG only for tiny charts, simple bars, sparklines,
or diagram-like marks. For plotted numeric data, default to Python-generated SVG
so axes, ticks, labels, scales, legends, and statistical views are handled
reliably. Avoid fitting the design to one fixed data schema; choose the simplest
honest view for the supplied data.
For charts, prefer this route:
- Use Matplotlib as the default renderer for real plotted data. Use Seaborn
when it makes a distribution, regression, heatmap, or grouped statistical
view clearer without fighting the Birchline theme.
- Use the bundled helper
scripts/birchline_mpl.py for theme and SVG export.
Create a temporary or artifact-local driver script that imports or copies that
helper, loads the specific data, builds the figure, and writes the SVG/HTML.
Run the driver with uv, for example:
uv run --with matplotlib --with numpy python /tmp/build_chart.py
or, when useful:
uv run --with matplotlib --with seaborn --with pandas python /tmp/build_chart.py.
- Export SVG and inline it into the HTML inside a
.panel or chart container.
- Pair the chart with exact values in a numeric table/matrix and a source/caveat
note.
- Use PNG only for raster-heavy plots where SVG is impractical.
Reference Loading
Only load extra references when needed:
- Read
references/system.md for the canonical full design-system prompt.
- Read
references/patterns.md for detailed component and layout patterns.
- Read
references/recipe-catalog.md when choosing among packaged recipes or
checking known gaps.
- Read a specific file in
references/templates/ when the artifact type is clear.
- Read or reuse
scripts/birchline_mpl.py when generating Matplotlib charts.
Slash Command Alternative
If working inside the fast-agent environment that has the Birchline plugin
installed, prefer /birchline when the user wants automated generation from
session context. Use this skill when you want the current agent to create or edit
the artifact directly.
