Claude skill · how it actually works

Diagrams Skill — Page Builder

The diagrams skill builds self-contained HTML explainer pages for the motorthings/diagrams GitHub Pages repo. Theme comes from the repo; structure from visual-explainer; process flows are drawn as custom-SVG maps. Pages are light-only Ledger.

The builder pipeline

StartUser asks
for a page

A request arrives for a visual explainer.

1Pick the palette

Gulf Stream Racing (default) or a per-category custom Ledger palette — e.g. coldprint indigo, oxblood + steel. Every category restyled as light-only.

2Pick the structure

Ledger (argument / portfolio / process), or measurement/data-table. Content pages backlink to their category page.

3Decide the renderer

Linear flows = pure CSS. Branching / parallel / merge process diagrams = custom-SVG (or inline-SVG) process map. Data = real tables. Mermaid stays out of process maps.

REDRAW RULE A source diagram is reproduced node-for-node in the new style — never flattened into a list.

4Delegate

Hand structure to visual-explainer; hand any diagram to custom-svg-diagram.

5Apply constraints

The non-negotiables. Light-only, palette from the repo, display + mono fonts, fixed backlink, no emoji, no JS on restyled pages.

6Verify

Run the checklist — including the diagram-fidelity check (a source diagram means the page still draws one).

7Ship

git add, commit, push — verify it renders live at motorthings.github.io/diagrams.

Rendering decisions

Pick the renderer by content type, not preference. The diagram is a real drawing, not a list.

LinearA → B → C

Pure-CSS flow. Linear flow, any length, no branching, perfect vertical alignment, zero JS. Centered nodes with arrow connectors.

Process mapBranch / parallel /
merge

Custom-SVG map. Decision gates, fan-outs, joins. Drawn node-for-node with the palette colors, rules and connectors; machine-verified or hand-checked geometry.

Ledger argumentRecap / portfolio /
case

Ruled sheet. Masthead, numbered sections, .pmap detail rows, tables. Rows are for detail, not for drawing a flow.

DataInventories /
matrices

Real tables. Semantic <table>, not CSS grids pretending.

Sequence / ERRare

Mermaid only here. Sequence, entity-relationship, state-machine. Not used for architecture or process maps.

Design rules

These override visual-explainer defaults. Every page complies.

Typography
& color

Fonts: Instrument Serif (display) + Public Sans (body) + JetBrains Mono (mono)
Palette: from the repo — Gulf Stream Racing default, or the category’s custom Ledger palette
Light-only: restyled categories carry no dark mode and no theme toggle
No emoji — Unicode entities only

Diagram
fidelity

Redraw a source process map node-for-node in the new style
Never condense many nodes into one, never flatten a diagram into rows or a list
Every diagram carries its palette colors and connectors; no Mermaid in process maps

Layout &
navigation

Spine + masthead Ledger sheet with a rule spine label
Backlink: fixed top-left to the category page (../<category>.html)
Favicon: ../icon.svg, adjusted for depth
Reduced motion: a @media (prefers-reduced-motion: reduce) block

Verification checklist

Run before committing — every item must pass.

Check	What to look for
No Mermaid / no JS	Restyled pages are `mermaid 0`, no `<script>`, no theme toggle.
Light-only	No dark mode, no `html.dark`, no `prefers-color-scheme`.
Diagram fidelity	If the source had a flow/process diagram, the page still draws one (an SVG map) — it isn’t restated as a list.
Backlink	Click it — goes to the right category page.
Mobile	Resize to 375px — no horizontal scroll, grids stack, h1 doesn’t overflow.
Palette & contrast	Every node/row/text readable against the sheet; colors from the category palette.
No broken links	Click every link in the footer and body.
Title tag	`[Project] — [Page Name]`, matches the h1.
Meta description	Present, 120–155 chars, describes this page.
No emoji	Unicode entities only.
Reduced motion	`@media (prefers-reduced-motion: reduce)` block present.

The core splitTheme from the repo; structure from visual-explainer; diagrams from custom-svg-diagram. Pages are Ledger and light-only. A process flow is a drawn process map, reproduced node-for-node — a rules sheet is for detail, not for drawing. When restyling a page whose source drew a diagram, the new page draws it again.