htmlify
Offline HTML rendering of superpowers-gstack Markdown artefacts (design docs, handoffs, plans) and per-directory dashboards, in the plugin's house style. Prefer the Artifact tool when it is available.
SKILL.mdskills/htmlify/SKILL.md
GitHub/htmlify
Two jobs:
- Explain mode (
/superpowers-gstack:htmlify explain <doc.md>): a visual explanation page for a spec or plan, written by hand, with inline SVG diagrams and as little text as possible. It runs after every spec and plan. See Explain mode. - Rendering (
bin/htmlify): a Markdown artefact to a styled HTML companion, and a dashboard page per directory. Since 3.0.0 this is the offline fallback: when the Artifact tool is available, publish the artefact as a page with it instead (load theartifact-designskill first). Reach for it when there is no Artifact tool, or when the user explicitly asks for a local HTML file.
styles/companion.css is the style of the rendering job (Liquid Glass surfaces,
gradient-mesh backgrounds, dual theme). Explain mode has its own style,
styles/explainer.css, and never uses companion.css.
Explain mode
A reader should understand the design from the pictures in two minutes, and open the document only for detail. The page explains the document; it never adds to it.
When. After a spec (docs/superpowers/specs/*.md) or a plan
(docs/superpowers/plans/*.md) is finished: after its own self-review, before the user
is asked to review it (and after the review lenses, when they run on it), so the user
reviews with the page in front of them. Run it
without asking. The plugin's PostToolUse hook reminds the session when such a file is
written, and again if the document changes after its page was made; re-run then. Not
for progress files, handoffs or vibe specs.
Start from the example. examples/explainer-example.html is the shape of a finished
page (its content is invented). Copy its skeleton: the head, the top bar with the theme
button, the card pattern and the theme script. Replace everything else. The first
<style> is styles/explainer.css unchanged, comments and all; rules the page needs
beyond it go in a second <style>. The page stands alone: no linked stylesheet, no
script but the theme button, no web fonts.
Shape. Take the parts the document has, in this order, and skip the ones it lacks: title (badge with the document type and date, the name, one line under), the problem (one headline number or fact), the whole (one flow diagram), one card per part of the design, the detail that is easy to get wrong, who does what, done when, worth knowing. Write in the document's language. Every claim comes from the document; the footer names the source file.
Design rules
- One accent per card, and a badge on top of every card. The card's first element
is
<span class="tag t-<accent>">, and the card's diagrams and.keyuse the same accent. Other colours inside a card carry meaning only: emerald for what works or is done, amber for caution, red only for the failure path. - SVG for anything with order, time or distribution: steps, flows, who hands what
to whom, timelines, sums and splits. A bulleted list of steps is the failure this
rule exists for. Every
<svg>hasrole="img"and anaria-labelthat says what it shows. A wide drawing has aviewBox960 wide and sits in.scroll. - One insight per card, in the highlighted box (
.key): the one thing the reader must take away from that card, never two. Cards that only list (who does what, done when, worth knowing) need none. - Tiles have an icon, a title and at most one line under it (
.chipwith.ic,<b>,<span>). Anything longer belongs in the document, not on the page. - No internal identifiers: no task or requirement ids, commit shas, function, class
or variable names, or paths the reader never meets. A command the reader types, or a
file they open, may appear in
<code>. - Light and dark theme. Colours come from the tokens (
var(--cyan),var(--line), …), never as hex values in an SVG or an inline style, so both themes work. Keep the theme button.
Where it goes
Read .gstack/explainer at the project root: local or artifact. No file means
local. /superpowers-gstack:adapt asks the question once and writes the file.
local: write<the document's folder>/<its name>.html, next to the document, and commit it with the document. After the check, open it withopen <page>.artifact: write the page to the scratchpad, check it, then publish it with the Artifact tool. Loadartifact-designfirst, as the tool requires: explainer.css already meets its page contract (tokens on:root, the dark-mode guards, a body background, phone width), so keep the explainer's look. Republish a changed document from the same file path, so the link stays.
Then give the user one line: the path or the link.
Last step, always: the check
"$SKILL_DIR/bin/explain-check" <page.html>
It reads the file against the rules above, then loads the page in gstack's headless browser at desktop and phone width and measures text that is clipped, runs out of its box, is cut by a drawing's edge, overlaps other text, or has a line drawn through it. It screenshots the whole page (light, dark, phone) and every card, and prints the paths.
| Exit | Meaning | Do this |
|---|---|---|
| 0 | Clean | Look at the screenshots, then open or publish |
| 1 | FINDING lines |
Fix every one and run it again |
| 4 | The page could not be read | Check the path |
| 5 | No browser (GSTACK_BROWSE unset and gstack's browse not installed), or it failed |
Say so; take full-page screenshots with another browser tool (for example Playwright's browser_take_screenshot with fullPage) and do the visual check on those |
A WARNING identifier line is either rewritten or confirmed as a word the reader
actually sees. Then read the screenshots: the full pages for the whole, the cards
for detail, for what measuring cannot see: a line through an icon, text unreadable in
the dark theme, a diagram that says nothing. The page is opened or published only after
a clean run and that look. A page whose check did not run is never presented as
checked.
How to invoke
The skill directory is the "Base directory for this skill" shown when the skill loads.
The wrapper bin/htmlify self-locates and runs from any cwd:
"$SKILL_DIR/bin/htmlify" <path-to-md> # → <dir>/.superpowers-html/<name>.html
"$SKILL_DIR/bin/htmlify" <path-to-md> --open # also open it in the default browser (macOS)
"$SKILL_DIR/bin/htmlify" dashboard <dir> # → <dir>/.superpowers-html/index.html
First run per install location: cd "$SKILL_DIR" && bun install (the wrapper prints
this exact command and exits 5 if deps are missing; exit 5 also means bun is absent).
The open flag opens the file in the user's default browser and touches nothing else. It never closes windows.
Flags
--plan <plan.json>— richer layout driven by a rendering plan (see below)--no-clobber— skip the render if the HTML is newer than the MD--force-rebuild— render even under--no-clobber
Rendering plan (optional)
Without --plan the default template renders the Markdown as structured cards. With a
plan you can map sections to components: comparison-matrix, flowchart-svg,
pullquote, callout-box, stats-bar, two-column, expandable, diff-card, and a
feedback_panel whose answers copy to the clipboard as a prompt for the next session.
Write the plan in this session (no API call), then pass it with --plan.
{
"version": 1,
"sections": [
{"heading": "Approaches Considered", "treatment": "comparison-matrix",
"data": {"items": [{"title": "Option A", "pros": ["…"], "cons": ["…"], "effort": "1d", "risk": "low"},
{"title": "Option B", "pros": ["…"], "cons": ["…"], "highlighted": true}]}},
{"heading": "Architecture", "treatment": "flowchart-svg",
"data": {"orientation": "LR",
"nodes": [{"id": "a", "label": "Input"}, {"id": "b", "label": "Process", "emphasis": true}],
"edges": [{"from": "a", "to": "b", "label": "transform"}]}}
],
"pullquotes": [{"text": "…", "attribution": "…", "after_section": "Problem Statement"}],
"feedback_panel": {"enabled": true, "premises": ["P1"], "approaches": ["A1"],
"custom_questions": [{"id": "q1", "label": "Did this layout help?", "type": "radio", "options": ["yes", "no"]}]}
}
| Treatment | Data |
|---|---|
comparison-matrix |
{items: [{title, summary?, pros?, cons?, effort?, risk?, highlighted?}]} |
flowchart-svg |
{nodes: [{id, label, shape?, emphasis?}], edges: [{from, to, label?}], orientation?: "TB"|"LR"} |
pullquote |
{text, attribution?} |
callout-box |
{level?: "info"|"warn"|"insight"|"danger", title?, body} |
stats-bar |
{items: [{label, value, delta?, trend?}]} |
two-column |
{left: {heading?, body}, right: {heading?, body}} |
expandable |
{summary, body, open?} |
diff-card |
{title?, before: {label?, content}, after: {label?, content}} |
Section headings in the plan match the Markdown H2s case- and whitespace-insensitively; a plan section with no matching H2 renders as a new section.
Frontmatter types
type: design-doc (office-hours), type: handoff (context-handoff), type: plan
(autoplan); anything else renders through the generic template with a banner.
Exit codes
0 success · 1 usage error · 2 schema validation failure · 3 Markdown parse error · 4 I/O error · 5 setup error (bun or deps missing)
Development
cd skills/htmlify && bun install && bun test