| name | page-template |
| description | Scaffold a sitemap-organized HTML showcase site (provenance reports, contractor showcases, telemetry dashboards, weekly digests, audit results). |
| allowed-tools | Read, Write, Edit, Bash |
HTML Showcase — Page Template
Self-Evolving Skill: This skill improves through use. If instructions
are wrong, parameters drifted, or a workaround was needed — fix this file
immediately, don't defer. Only update for real, reproducible issues.
A static HTML mini-site whose navigation structure is the filesystem
layout itself. Every page links to a shared CSS kernel served from
jsDelivr; an auto-discovered nav rail and a master site-map.html are
generated by scripts/build-nav.py from whatever directories you create
under the site root. Pages are pure HTML with optional per-page CSS
overrides. The architecture is built on five principles — read
references/principles.md first to
internalize the WHY before extending or forking, and
references/sitemap.md for the navigation
contract.
The sitemap is the default
Every site this skill produces has the same shape:
<site-root>/
index.html ← site home (recommended)
overrides.css ← optional per-site tweaks
auto-nav.css ← generated by build-nav.py
auto-nav.js ← generated by build-nav.py
site-map.html ← generated by build-nav.py
<section-1>/ ← any subdirectory becomes a "section"
index.html
page-a.html
page-b.html
<2026-05-02-audit>/ ← YYYY-MM-DD- prefix sorts sections newest-first
index.html
findings.html
You don't hand-write the nav. You add HTML files in the directory shape
you want, then run scripts/build-nav.py --root <site-root>. The script
walks the tree, generates site-map.html, writes the rail's CSS/JS, and
injects the same nav rail into every page using comment markers. Re-runs
are idempotent.
For the architecture and trade-offs, see
references/sitemap.md.
Read this skill at the principle level, not the instruction level
Every concrete artifact in this skill (class names, file paths, the
specific CDN URL, the commit-message conventions, even the "section"
naming) is an instance of a small set of underlying principles. If you
understand the principles, you can deviate intelligently from any
specific instance without breaking the architecture. If you only follow
the instructions, you'll bend the system out of shape the first time
something doesn't fit your case.
The principles are catalogued in references/principles.md:
- Single source of truth — every visual decision lives in one file
- Semantic over atomic — class names describe what an element is
- Token-driven — every concrete value flows from a CSS custom property
- Cascade discipline —
@layer ordering enforces specificity globally
- No hidden state — no JS, no inline CSS, no scattered overrides
- Filesystem-as-sitemap — directory layout IS the navigation graph
Plus AI-collaboration patterns (why this design is LLM-friendly), and
the rationale for using a CDN rather than copies.
Three-layer hierarchy
| Layer | Mutability | What it controls | Where it lives |
|---|
| H1 — Kernel | Edit once → ripples everywhere | Tokens (color, spacing, type), reset, base elements, components | assets/showcase.css (jsDelivr CDN) |
| H2 — Composition | Per-page | Section order, content, semantic markup | The HTML file itself |
| H3 — Overrides | Per-page (optional) | Color or density tweaks for ONE page | overrides.css next to the HTML |
The kernel is the SSoT for every visual decision. HTML never invents
styles; it only arranges components defined by the kernel. To customize
one page, drop a few CSS variables into overrides.css. To customize
EVERY page, edit the kernel.
The auto-nav rail is generated, not hand-written. Its styling lives in
auto-nav.css (written by build-nav.py); its content is injected
between <!-- AUTO-NAV-START --> and <!-- AUTO-NAV-END --> markers in
each page's <body>.
The rail and the master site-map.html are always dark (slate-950
surface, slate-300 text, indigo-400 accents), regardless of the host
page's theme. The rail is the constant element across every page; pinning
its theme keeps it visually stable whether the page it overlays is a
light contractor showcase or a dark telemetry dashboard.
Pages within a section render in creation order, not alphabetical:
index.html always first.- Pages following the
index_iter_<N>_<slug>.html naming convention sort
by N numerically (so iter_10 comes after iter_9, not after iter_1).
- Other top-level pages sort by filesystem birthtime (
st_birthtime on
macOS — never moved by edits or rebuilds).
- Nested pages fall back to the original subdir + index-first + alpha grouping.
The rail's runtime behavior:
- First load: width auto-fits to the longest unwrapped link (uses
width: max-content to measure each link's true intrinsic width,
independent of the rail's current size), clamped to [220, 760]px.
- Drag the right-edge handle: resize manually within
[220, 1200]px;
the chosen width is persisted in localStorage.
- Double-click the handle: clears the saved width and re-runs
auto-fit (semantically: "reset to smart default").
- The handle is a 14px hit zone with an always-visible 2px indicator
line and a hover tooltip explaining the dual gesture.
- Within-section Prev/Next: pages inside a section get compact
‹ ›
buttons on the "Site" header row (zero added height) plus a Chrome-safe
bare [ / ] keyboard shortcut. ‹ / [ goes to the sibling above
(newer), › / ] to the one below (older); both are greyed out at the
ends of the list. The keys ignore presses while a modifier is held or
while focus is in the search box, so they never interrupt typing.
Search is on by default
Every rail (and the master site-map.html) gets a Search section
mounted at the top, powered by Pagefind — a
Rust-built static-search tool that produces a self-contained index with
no server, no build pipeline, and a ~70KB client UI.
How it's wired:
build-nav.py injects 4 tags into every page's <head> in strict
order: pagefind CSS → auto-nav CSS → pagefind JS → auto-nav JS.- The rail's first section is
<div id="auto-nav-search"></div>;
auto-nav.js calls new PagefindUI({...}) once Pagefind has loaded.
- The actual index lives at
<site-root>/pagefind/, generated by
running pagefind --site <site-root>.
scripts/site.sh nav runs build-nav.py AND pagefind --site —
search refreshes automatically every time the rail is rebuilt.
If pagefind isn't installed, the rail still renders with the search
input present but inert; auto-nav.js's mountSearch() short-circuits
when window.PagefindUI is undefined. Install via brew install pagefind (or follow the official install docs).
Push-as-hook auto-resync
install.sh --hook installs a pre-push git hook at .githooks/pre-push
and wires git config core.hooksPath .githooks. After that, every
git push main automatically:
- Auto-detects every site dir in your repo (any directory containing a
site-map.html)
- Runs
scripts/site.sh nav <site-dir> (rebuilds rail + search index)
- Runs
scripts/site.sh push <site-dir> (rsync to bigblack via
Tailscale)
The hook is non-blocking — if rsync fails (cellular, coffee shop,
bigblack down), the push continues to GitHub anyway. Skip env vars:
| Variable | Effect |
|---|
NO_HTMLSHOWCASE_HOOK=1 | Skip the hook entirely |
NO_HTMLSHOWCASE_SYNC=1 | Run nav + search but skip the rsync |
NO_HTMLSHOWCASE_SEARCH=1 | Skip the pagefind regen step |
HTMLSHOWCASE_SITES="a b c" | Override auto-detection with explicit list |
Four contributor stances
Pick the role that matches your task. Full workflow for each in
references/contributing.md.
| Role | Example task | Edits | Affects |
|---|
| Consumer | "Make me a contractor showcase site" | Your HTML | Just your site |
| Customizer | "Re-theme this site with our brand teal" | overrides.css | Just your site |
| Contributor | "Add a .timeline component to the kernel" | Kernel CSS upstream | Every site using this kernel |
| Publisher | "Our team forks the kernel and publishes from our own GitHub" | Your fork's kernel | Sites that pin to your CDN URL |
When to use this skill
- Creating a static HTML site (one page or many) that records structured
work: audits, commits, metrics, reports, contractor showcases,
telemetry views, weekly digests
- Replacing inline-CSS pages with the shared design system + auto-nav
- Bootstrapping a multi-page mini-site that grows into a contractor
portfolio, weekly-digest archive, or release-notes hub — without ever
hand-maintaining the navigation
Do NOT use for: blog posts, marketing landing pages, interactive web apps.
What ships in this skill
| Path | Role |
|---|
templates/index.html | Site home skeleton (hero + 3 example sections + footer + markers) |
templates/section-index.html | Section landing-page skeleton |
templates/overrides.css.example | Reference for per-site customization (rename to overrides.css) |
templates/lychee.toml | Link-checker config |
scripts/build-nav.py | Universal sitemap builder — auto-nav + site-map.html generator |
scripts/check-orphan-pages.py | Pure-stdlib orphan-page graph validator |
scripts/site.sh | Build nav + validate + push to bigblack via Tailscale (see below) |
scripts/install.sh | One-shot bootstrap: install all 3 scripts into any repo |
references/principles.md | The WHY — five principles + AI patterns |
references/sitemap.md | The HOW — filesystem-as-sitemap contract, rail rendering |
references/contributing.md | The HOW — four stances with full workflows |
references/publishing.md | The WHERE — delivery surfaces (CDN vs tailnet) + bigblack setup |
The CSS kernel itself lives at the plugin level
(plugins/html-showcase/assets/showcase.css) and is served from jsDelivr —
the skeleton HTML references the public CDN URL, not a local file.
Where finished sites get hosted
Two surfaces, two roles:
| Surface | What goes there | When to use |
|---|
| jsDelivr CDN (public) | The kernel CSS only | Always — every page imports the kernel from one shared URL |
| bigblack on the tailnet | Your rendered sites | Default for internal audiences (no DNS, no auth UI, no public exposure) |
| jsDelivr / Pages / Workers | Your rendered sites | Only when an external reader genuinely needs the page |
For internal-audience sites (audit reports, contractor showcases,
telemetry views, weekly digests), the bigblack tailnet path is the
lowest-friction option. Adopting it in any repo is one command:
ROOT="$(cc-plugin-root html-showcase)"
bash "$ROOT/skills/page-template/scripts/install.sh"
That installs all three pipeline scripts (build-nav.py,
check-orphan-pages.py, site.sh) into <repo>/scripts/ and
appends **/.published.json to .gitignore. The installer is
idempotent (re-running it is a no-op) and non-destructive
(--force to overwrite). To also seed a starter site directory:
bash "$PLUGIN/skills/page-template/scripts/install.sh" --site contractor-site
Then scripts/site.sh push <site-dir> regenerates the sitemap, validates
locally (lychee + orphan check), and rsyncs to
bigblack:~/sites/<repo>/<site-dir>/, served at
https://bigblack.tail0f299b.ts.net:8448/<repo>/<site-dir>/. Push-side
gating (build-nav + lychee + orphan check) is the only gate. Full
mechanics, the URL formula, when NOT to use bigblack, and the bigblack
one-time setup are in references/publishing.md.
Universal density knobs
Two CSS custom properties at the top of showcase.css control the entire
visual rhythm. Override either in overrides.css to retune one site:
:root {
--density: 0.85;
--font-scale: 0.94;
}
Every padding, gap, margin, and section rhythm in the kernel derives from
the spacing scale; the spacing scale derives from --density. Body font
size derives from --font-scale. There are no scattered magic numbers in
component CSS — see Principle 3 in references/principles.md.
Component vocabulary
The kernel defines these semantic classes; HTML uses them. To inspect the
full set, open the kernel CSS and search for class selectors.
| Class | Purpose |
|---|
.hero + .hero__inner / __eyebrow / __title / __lede / __cta-row | Top banner with gradient |
.chip--solid / .chip--ghost | Hero CTA buttons |
.metric-grid + .metric-card | At-a-glance number panel; modifiers --accent, --success, --warning |
.phase-grid + .phase-card | Phased timeline cards; modifiers --audit, --fix, --perf |
.commit-stack + .commit-card | Detailed commit cards with SHA chip + details grid |
.bug-grid + .bug-card (--high modifier) | Compact issue cards |
.feature-grid + .feature-card | Generic 4-column showcase grid with icon |
.reco-list + .reco-item (--p0 / --p1 / --p2) | Priority-ordered recommendations |
.badge (--high / --medium / --low / --success / --info / --neutral / --accent) | Severity / status labels |
.section-head / .section-intro | Per-section title row + framing paragraph |
.shell | Centered content shell with max-width and responsive padding |
.site-footer + .site-footer__grid / __legal | Provenance footer |
The auto-nav rail uses its own non-kernel classes (.auto-nav-rail,
.rail-link, .rail-section, etc.) defined in auto-nav.css so the
nav stays self-contained and a repo can adopt the rail without adopting
the kernel.
If your page needs a content component not in this table, you have two
choices — both legitimate, both documented in references/contributing.md:
- Add it to the kernel (Stance 3): semantic class name in the
components @layer, token-referenced values, BEM modifier variants.
- Use a local override for one-off cases (Stance 2): only if the
pattern is genuinely unique to one page; recurring patterns belong in
the kernel.
Quick start (Consumer stance, sitemap-organized)
The fastest path: run the installer to bootstrap the pipeline scripts +
a starter site, then iterate.
ROOT="$(cc-plugin-root html-showcase)"
bash "$ROOT/skills/page-template/scripts/install.sh" --site contractor-site
mkdir -p contractor-site/2026-05-02-first-section
ROOT="$(cc-plugin-root html-showcase)"
cp "$ROOT/skills/page-template/templates/section-index.html" \
contractor-site/2026-05-02-first-section/index.html
cp "$ROOT/skills/page-template/templates/index.html" \
contractor-site/2026-05-02-first-section/page-a.html
scripts/site.sh nav contractor-site
scripts/site.sh check contractor-site
open contractor-site/index.html
open contractor-site/site-map.html
Or, if you'd rather copy the templates by hand without the installer:
ROOT="$(cc-plugin-root html-showcase)"
DEST=/path/to/your-site
mkdir -p "$DEST"
cp "$ROOT/skills/page-template/templates/index.html" "$DEST/"
cp "$ROOT/skills/page-template/templates/lychee.toml" "$DEST/"
python3 "$ROOT/skills/page-template/scripts/build-nav.py" --root "$DEST"
site.sh falls back to the plugin-shipped build-nav.py when no copy
is present in <repo>/scripts/, so even without the installer you can
push to bigblack from any repo using the plugin-shipped script directly.
For the other three stances (Customizer, Contributor, Publisher), see
references/contributing.md. For the
publishing path to bigblack via Tailscale, see
references/publishing.md.
CDN versioning
The kernel URL pins to the @main branch during early iteration, then
to a tagged release once the kernel stabilizes:
@main → always-latest → use during development; jsDelivr cache flushed automatically on each release
@v<X.Y.Z> → immutable, content-locked → use for production-stable pages
@<sha> → immutable, commit-locked → use for forensic-grade pinning
The release flow auto-purges @main and smoke-tests @v<X.Y.Z> after
each release. To force-refresh @main between releases (e.g., during
heavy iteration on the kernel), run mise run release:cdn-purge from
the cc-skills repo. To bypass cache entirely on a single page, append
?v=$(date +%s) to the kernel link.
The auto-nav assets (auto-nav.css, auto-nav.js) are generated locally
by build-nav.py and live next to your HTML — they are not CDN-served.
The ?v=N query string on those URLs is also a cache-bust knob; bump
--asset-version when you change the rail's CSS or JS body inside
build-nav.py.
Hard rules
These are baked into the kernel and templates; if you find yourself
wanting to break them, fix the kernel instead (see Stance 3 in
references/contributing.md).
- No inline
<style> blocks.
- No
style="" attributes on HTML elements.
- No utility-class soup in HTML — class names are semantic
(
.metric-card, .badge--high), never atomic
(flex p-4 bg-blue-500).
- The kernel is the single source of truth for every visual decision.
- HTML only arranges components; it never invents them.
- The filesystem layout IS the navigation graph; never hand-author the
rail HTML between
<!-- AUTO-NAV-START --> and <!-- AUTO-NAV-END -->.
Re-run scripts/build-nav.py after any structural change.
- Every site must pass Lychee link-check and the orphan-page detector
before it's considered shipped.
Post-Execution Reflection
After this skill completes, reflect before closing the task:
- Locate yourself. — Find this SKILL.md's canonical path before editing.
- What failed? — Fix the instruction. If a kernel component was missing, add it (Stance 3). If the sitemap rail rendered something surprising, fix
build-nav.py AND references/sitemap.md. If a principle was unclear, fix references/principles.md.
- What worked better than expected? — If a new section pattern recurs, distill it into a kernel component or into
templates/section-index.html.
- What drifted? — Keep CDN URL pins, override examples, component vocabulary, and the rail HTML markers aligned across
SKILL.md, the templates, and build-nav.py.
- Log it. — Evolution-log entry with trigger, fix, evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.
