Diagram templates
Diagram templates are reusable HTML output shells for diagram artifacts. They give each artifact a stable page frame, visual register, accessible SVG entry point, and export path while leaving the diagram-specific meaning to the author. The family supports light, dark, editorial, terminal, and motion-led presentations; the diagram asset library provides the wider context for choosing among them.
Template family
The template family separates the presentation shell from the diagram content. A new artifact normally starts from the closest shell, replaces its title and SVG content, and keeps the shell's page structure and accessibility contract intact.
Shared output contract
Each shell presents one diagram as a self-contained HTML page. The shared shape includes a viewport, a title area, an SVG with a viewBox, and SVG <title> and <desc> elements so the visual artifact also has a meaningful name and description. Fonts and color roles provide a common visual language across the light, dark, and editorial forms. The base and dark shells keep the same page structure while pairing their paper, ink, muted, accent, and link roles to the selected background. template.html template.html template-dark.html style-guide.md
The SVG is the portable product of the page. PNG and SVG exports keep the diagram and its accessible name while dropping page-only wrappers such as the full template's cards and footer. This lets the same source serve a browser page and a diagram-only artifact without changing the diagram's meaning. export.md export.md
References: skills/…/template.html• L1-18 skills/…/template.html• L20-64 skills/…/template-dark.html• L10-18 skills/…/style-guide.md• L83-97 skills/…/export.md• L20-43
Variant selection
The standard visual choices form a small set rather than separate product systems. Minimal light is the default for a clean screenshot-ready artifact. Minimal dark serves dark sites, slides, and high-contrast uses. Full editorial adds context around the diagram when the page itself is the presentation. Terminal is an optional replacement shell for developer-tool content and uses a command-line window style instead of the standard brand tokens. SKILL.md
The choice changes how readers meet the diagram, not what the diagram says. A visual variant should therefore be selected before the SVG is authored, while the diagram's relationships and labels remain independent of the surrounding shell.
References: skills/…/SKILL.md• L504-519 skills/…/SKILL.md• L521-527
Output shell variants
The five templates cover the main ways a diagram becomes a usable artifact. The first four establish page skins; the motion template adds an optional presentation behavior while preserving a complete static frame.
Base template
The base template is the minimal light shell for a single diagram. It centers a bounded frame on warm paper, places a small type label and a serif title above the SVG, and leaves the SVG as the main content area. Its placeholders make the diagram slug, title, and description explicit before export. template.html
Use this shell when the diagram should stand on its own with little page context. Its restrained frame makes it the normal starting point for a new static diagram.
References: skills/…/template.html• L20-64 skills/…/SKILL.md• L508-512
Dark template
The dark template keeps the base shell's compact structure and changes the page and SVG register to a deep charcoal field. Light text, muted lines, a brighter accent, and a lighter link color preserve the same visual roles against the dark background. template-dark.html template-dark.html
Use it when the surrounding destination needs a dark presentation or when contrast against a dark page is part of the artifact's purpose. It is a visual counterpart to the base template, not a different diagram model.
References: skills/…/template-dark.html• L10-18 skills/…/template-dark.html• L20-64 skills/…/SKILL.md• L510-512
Full template
The full template is the editorial shell for a diagram that acts as the hero of a longer page. It adds a descriptive header, a clean borderless diagram area, information cards, and a footer around the SVG. The cards give the page room for a small set of conclusions or supporting facts without placing that extra prose inside the diagram itself. template-full.html template-full.html template-full.html template-full.html
Use it when readers need context before or after the visual. The extra page material is presentation context, so diagram-only export can remove it and still retain the SVG artifact. export.md
References: skills/…/template-full.html• L36-83 skills/…/template-full.html• L85-163 skills/…/template-full.html• L166-181 skills/…/template-full.html• L363-409 skills/…/export.md• L20-25
Terminal template
The terminal template presents the diagram inside a dark command-line window shell. A title bar, prompt, monospace typography, and one red-orange accent make the artifact feel like output from a developer tool while keeping the SVG as the central payload. template-terminal.html template-terminal.html template-terminal.html
Use it as an optional replacement for the standard shells when the subject is a developer tool or command-driven workflow. It is intentionally a distinct visual treatment and is not the default onboarded output. SKILL.md
References: skills/…/template-terminal.html• L19-49 skills/…/template-terminal.html• L51-114 skills/…/template-terminal.html• L117-169 skills/…/SKILL.md• L515-517
Motion template
The motion template is a light shell for diagrams that explain a change over time. It provides a complete SVG source first, then adds an optional reveal or step presentation through marked semantic items, playback controls, status text, keyboard input, and URL-selected static or test states. The source remains complete until the motion enhancement starts, so the page still works when JavaScript is absent or motion is reduced. template-motion.html template-motion.html template-motion.html
Motion is a presentation layer rather than a fifth visual skin. The controller supports step navigation and playback, but static mode, reduced-motion mode, print, and export expose the complete diagram and remove controls or decorative movement. The template also pauses playback when the page is hidden and reports the current state to assistive technology. For animated artifacts, the canonical controller and its state attributes are part of the shared contract. See diagram animation for the behavior rules and diagram style and primitives for the visual building blocks. animation.md animation.md
References: skills/…/template-motion.html• L26-45 skills/…/template-motion.html• L47-170 skills/…/template-motion.html• L173-235 skills/…/animation.md• L85-109 skills/…/animation.md• L111-132
Artifact assembly
Template use follows a short path from shell choice to portable output. The shell supplies the page context, the authored SVG supplies the diagram meaning, and export reduces the page to the SVG when a diagram-only artifact is needed.
The relationship between the shell and the final artifact is shown below.
flowchart LR
A[Choose shell] --> B[Set title and description]
B --> C[Author SVG diagram]
C --> D[Browser page]
C --> E[Diagram-only SVG or PNG]
D --> F[Editorial context]
E --> G[Portable diagram artifact]
Authoring sequence
Start with template.html for a minimal diagram, template-dark.html for a dark presentation, template-full.html for editorial context, or template-motion.html only when motion is requested. Choose template-terminal.html when the terminal shell is the intended product surface. Then replace the shell's visible labels and SVG body, give the SVG a unique slug-based accessible name, and keep the complete static frame meaningful before any motion enhancement. SKILL.md
The shell choice and the SVG choice stay linked through the title, description, and visual tokens. If the shell changes, the diagram's semantic content should not need to change; if the SVG changes, its page and export forms should still describe the same artifact.
References: skills/…/SKILL.md• L521-527 skills/…/template.html• L57-83 skills/…/template-motion.html• L173-235
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the title, description, and slug-prefixed SVG IDs aligned across each page variant so accessible names remain local to the artifact.
- Preserve the SVG
viewBoxand first-child<title>/<desc>contract because diagram-only export depends on them. - When changing the motion shell, keep the complete source frame, reduced-motion and static states, print state, playback controls, status announcements, and canonical controller behavior aligned with diagram animation.
- When changing shared colors or fonts, review the light and dark token pairs together and check the visual primitives described in diagram style and primitives.
- When adding an example to the gallery, keep its variant filename aligned with the gallery's type and variant selection rules. See diagram example gallery.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A copied page keeps placeholder title, description, or slug IDs | Readers and assistive tools receive the wrong diagram name. Multiple inline exports can also resolve to the wrong accessible description. | Replace all placeholders and use unique slug-prefixed IDs before export. |
A diagram omits its viewBox or accessible SVG name | The export path cannot safely produce a portable diagram with stable meaning. | Keep the template SVG structure and preserve role="img", aria-labelledby, <title>, and <desc>. |
| Motion initialization hides the complete source or leaves playback active in a static state | A no-script page, reduced-motion view, printout, or static export shows incomplete content or unwanted motion. | Keep the source complete and preserve the template's static, reduced-motion, visibility-pause, and control-disable states. |
| A full-page wrapper is mistaken for the export artifact | Cards, headers, or footers are expected in a diagram-only SVG even though export removes them. | Treat the SVG as the portable product and use a full-page screenshot when the whole editorial page is required. |
| A terminal shell is used where standard brand tokens are required | The artifact has a command-line visual register that does not match the normal diagram set. | Use the terminal shell only for developer-tool content or an explicit terminal presentation. |
Key files
| File | Why to read it |
|---|---|
| skills/…/template.html | The default minimal light page shell and the baseline SVG accessibility shape. |
| skills/…/template-dark.html | The dark counterpart and its light-on-charcoal visual roles. |
| skills/…/template-full.html | The editorial page structure around a hero diagram. |
| skills/…/template-terminal.html | The optional command-line window presentation. |
| skills/…/template-motion.html | The static-first motion shell and its interaction surface. |
| skills/…/SKILL.md | The supported variants and the authoring path for new diagram artifacts. |
| skills/…/animation.md | The behavior and accessibility contract for motion-enabled pages. |
| skills/…/export.md | The boundary between a full HTML page and a portable SVG or PNG. |
| skills/…/index.html | The gallery's mapping between diagram types and visual variants. |