Html theme

Standalone HTML pages

Self-contained .html the user can open locally. Theme is fixed — copy the template; do not invent a new look. Content is a briefing: answer first, prove it, act—visuals only when they earn space.

When

Yes: multi-section briefing, status report, decision write-up, runbook, comparison, or a small multi-page site when one scroll would be too long.

No: ordinary Q&A, short answers, repo docs that should stay .md, app UI, emails.

If unsure, ask once — or default to markdown.

One page vs many

Choose	When
Single file	Fits a short skim (~one sitting). Default.
Multi-page folder	Complex topic, distinct audiences, or clear chapters (overview / detail / runbook).

Prefer 2–5 pages. Each still skims in ~2 minutes. No mini-app (no router, no build). Plain files + relative links.

Map pages to who uses them when useful: owner → verdict/ask; operator → steps/rollback; peer → evidence/tradeoffs. Don’t repeat the same essay on every page—hub summarizes; depth links back.

Cross-page links

No fixed chrome. Place links where the journey fits (hub map, inline, .page-turn, optional .site-nav, footer, or a mix). Don’t default to a top tab bar. Mark current page with aria-current="page" on repeated nav.

How

1. Resolve this skill’s directory (folder with this SKILL.md).
2. Before filling content: who is this for, and what should they decide or do after ~2 minutes?
3. Copy template (keep CSS/JS):

   # single
   cp "<skill-dir>/assets/template.html" "./<slug>.html"
   # multi: folder + one copy per page (index.html + siblings)
   

   User-named path wins; else ./<slug>.html or ./<slug>/ (kebab-case from title).
4. Fill content (below). Replace every {{…}} and stub. Identical CSS/JS on every multi-page file.
5. Report full output path (and index.html for multi-page).

Samples: copy template only. Open assets/sample.html or sample-site/ only if you need a layout reference for one component—never load all demos by default.

Content

Answer first

• Lede / first screen = conclusion + why it matters + what to do. Not background.
  • Shape: [Verdict]. [Stakes in one clause]. [Next step].
• Each section’s first sentence is that section’s point; detail follows.
• Prefer live sources (repo, metrics, docs, gh) over memory. Non-obvious claims need a hook (number, path, quote, link) or mark unknown / inferred.
• Separate facts (tables, metrics) from judgment (callouts). End with Notes / sources when anything was looked up—or state gaps honestly.
• End with actions (who / what / when if known) or a clear link to the page that has them.

Page shape (pick one primary)

Pattern	Spine
Status	State → drivers → actions
Decision	Options → criteria → pick → risks
Diagnosis	Symptom → evidence → cause → fix → prevent
Runbook	Goal → prechecks → steps → verify → rollback
Comparison	Axes → matrix → winner → caveats

Default section order when unsure: title/lede/meta → summary → body → next steps → notes. Drop empties. ~2–3 short sections → skip on-page TOC links.

Readable

• One idea per short paragraph; lists for 3+ parallel items.
• Headings that say the point (Authz dominates p95), not Overview.
• Numbers always with context (vs target, vs prior, window).
• Expand acronyms once; define jargon only if needed.
• Cut filler. If a section is a prose wall, split the page or delete it.

Visuals (only if they earn it)

Add a chart/diagram only if it shows structure, comparison, change over time, or a fail-safe procedure better than a sentence. Skip decoration and second visuals that retell the first.

Every visual needs a one-line takeaway (caption or sentence above). Prefer:

Need	Prefer
Contribution / rank	Bars or table
Process / order	Steps, timeline, sequence
Topology	Flow / layers SVG
Decision	Matrix + recommendation callout
Exact values	Table

Familiar encodings over clever ones. Readable gaps; labels outside nodes; color only on the hot path. Not a checklist—choose what explains this content; invent on-theme components if needed.

Components (prefer these)

Pattern	Use
.metrics / .metric	KPIs
.callout.ok|warn|bad|info	Judgment / status
.kv	Facts
.table-wrap + table	Data (sticky headers)
.tag	Chips
.chart / .bar-row	Relative bars
.spark-grid	Tiny trends
.timeline / .steps / .checklist	Process
.endpoint	API surface
.split / .panel	Side-by-side
.diagram	SVG + caption
.code-block + [data-copy]	Code
.site-nav / .page-turn	Multi-page (optional)

Invent components only when none fit—same tokens, spacing, borders, semantic color. Extend existing patterns first.

Code block

<div class="code-block">
  <div class="code-head">
    <div class="code-head-meta">
      <span class="code-lang">Shell</span>
      <span class="code-label">optional label</span>
    </div>
    <button type="button" class="code-copy" data-copy>Copy</button>
  </div>
  <pre><code class="language-bash">echo hello</code></pre>
</div>

ts / js / bash / json / py. Keep samples short.

Theme

• Black/gray/white; system fonts; color only for ok · warn · bad · info.
• Keep template CSS/JS. No CDN, webfonts, or restyled chrome.
• TOC control as-is (hidden by default, fixed gutter, never reflows; t to open).

Done when

• Path correct; opens offline; no {{…}} / stubs / freestyle theme
• First screen states the answer a stranger could repeat
• Claims have evidence or are marked unverified; actions are specific enough to act on
• Each visual has a takeaway; no filler sections
• TOC ids match (if used); multi-page links work; complexity matches the topic