Diagrams Skill — Page Builder Pipeline

How the diagrams skill builds self-contained HTML pages for the motorthings/diagrams GitHub Pages repo. Every page is a single .html file with Gulf Stream Racing theme, Fraunces typography, sticky nav, theme toggle, and fixed backlinks.

flowchart TD
    START["User asks for diagram"]
    START --> ASK{"Ask: Gulf Stream
or custom colors?"}
    ASK --> MODE{"Determine mode"}

    MODE -->|"Topology / branching"| MERMAID["Mermaid Diagram"]
    MODE -->|"Executive overview"| PORTFOLIO["Portfolio / Overview"]
    MODE -->|"Linear A→B→C"| CSSFLOW["Pure CSS Flowchart"]

    MERMAID --> DELEGATE["Delegate to visual-explainer"]
    PORTFOLIO --> DELEGATE
    CSSFLOW --> DELEGATE

    DELEGATE --> CONSTRAINTS["Apply diagrams-skill constraints:
Gulf Stream colors, Fraunces + Mono fonts,
html.dark toggle, fixed backlink,
no emoji, NEVER elk layout,
zoom controls, favicon"]

    CONSTRAINTS --> BUILD["visual-explainer generates HTML"]
    BUILD --> BACKLINK["Add backlink
Parent-relative or ../index.html"]
    BACKLINK --> INDEX["Add entry to index.html
Correct section + card-link format"]
    INDEX --> VERIFY["Run verification checklist"]
    VERIFY --> GIT["git add, commit, push"]
    GIT --> LIVE["Verify at
motorthings.github.io/diagrams"]

    class MERMAID,PORTFOLIO,CSSFLOW mode
    class ASK,MODE choice
    class DELEGATE,BUILD,BACKLINK,INDEX,GIT,LIVE action
    class CONSTRAINTS rule
    class START phase

Layout mode

Decision

Action

Non-negotiable rule

Three Layout Modes

The skill picks the mode based on content type, not personal preference. Each mode has a distinct template, max-width, and hero treatment.

Mermaid Diagram

Flowcharts & Architecture

Use when: Branching, diamonds, decisions, complex graphs with many edges, topology-focused architecture

Template: template-diagram.html

Container: 1000px max-width

Hero: h1 44px/800 + badge, text color

JS: Mermaid init + zoom/pan + theme toggle

Portfolio / Overview

Executive Pages & Showcases

Use when: Numbered stages, subpanels, metric lines, executive framing with Smart Brevity format

Template: template-portfolio.html

Container: 920px max-width

Hero: h1 48px/700 + primary color, no badge

JS: Theme toggle only

Pure CSS Flowchart

Linear A → B → C Flows

Use when: Linear flow (any length), no branching, perfect vertical alignment needed, zero JS dependencies

Pattern: Flexbox column + ↓ arrows + flow nodes with actor tags

Container: 1100px max-width

Hero: Centered, serif, italic optional

JS: Theme toggle only

Non-Negotiable Design Constraints

These rules override visual-explainer defaults. Every page must comply.

Typography & Color

Fonts: Fraunces (headings/body) + Source Code Pro (mono)

Palette: Gulf Stream Racing — orange primary, blue secondary, teal metric

Dark mode: html.dark class toggle, NOT @media prefers-color-scheme

Storage key: diagram-theme in localStorage

No emoji: Unicode entities only

Mermaid Rules

Import: mermaid@11/dist/mermaid.esm.min.mjs

Config: startOnLoad: true, theme: 'base', look: 'classic'

NEVER: layout: 'elk' — causes blank diagrams

classDef: Hardcoded rgba/hex, NOT CSS variables

CSS bridge: Override fill/stroke per class for dark mode

Layout & Navigation

Nav: Sticky, blur backdrop, brand link + theme toggle

Backlink: Fixed top-left, parent-relative path

Favicon: ../icon.svg (adjust depth)

Reduced motion: @media (prefers-reduced-motion: reduce) block

Zoom & Interactivity

Zoom controls: +/−/reset buttons on every .mermaid-wrap

Ctrl+scroll: Zoom in/out on diagram container

Click-drag: Pan when zoomed in

Cursor: grab when zoomed, grabbing while panning

Verification Checklist

Run before committing. Every item must pass.

Check	What to Look For
Dark mode	All text readable, gradients work, Mermaid nodes have correct fill/stroke
Light mode	Same checks in light — toggle back and verify
Backlink	Click it — goes to the right parent page
Mobile	Resize to 375px — no horizontal scroll, grids stack, h1 doesn't overflow
Mermaid renders	Diagram visible, not blank, all nodes labeled, zoom buttons work
No broken links	Click every link in footer and body
Title tag	`[Project] — [Page Name]` format, matches h1
Meta description	Present, 120-155 chars, describes this page
No emoji	Search for emoji — Unicode entities only
html.dark not @media	Dark mode uses `html.dark { }` block, not media query
Reduced motion	`@media (prefers-reduced-motion: reduce)` block present

Overrides to visual-explainer Defaults

Colors: Gulf Stream Racing palette, not visual-explainer’s aesthetic picks.
Theme: html.dark class toggle with localStorage, not @media prefers-color-scheme.
Nav: Sticky blur-backdrop nav with brand + toggle, not visual-explainer’s default nav.
Backlink: Fixed-position per the backlink rules above.
Mermaid: Never ELK layout, always look: 'classic'.
Flowcharts: Linear flows = pure CSS, branching = Mermaid.
Fonts: Always Fraunces + Source Code Pro, not visual-explainer’s font picker.