Diagram asset library
The diagram asset library is the shared starting point for producing and reviewing self-contained diagram pages. It brings together reusable HTML output shells, rendered examples for visual comparison, and a vendored icon catalog so an engineer can choose a presentation form and reuse a consistent visual language without rebuilding the page frame each time. See Diagram templates, Diagram example gallery, Diagram taxonomy and semantics, and Diagram animation.
Asset library structure
The library supports a simple path from choosing a shell to reviewing a rendered result and selecting optional visual assets. The files live under the diagram-design skill's assets/ directory and are designed to remain usable as standalone HTML documents.
flowchart LR
A[Choose output shell] --> B[Build inline SVG diagram]
B --> C[Review rendered example]
C --> D[Reuse icon when useful]
D --> E[Export or publish self-contained page]
The gallery page ties the examples together. Its type tabs cover core diagram forms, chart forms, data and platform views, specialized subtypes, imported forms, and animated forms. Variant controls load the matching light, dark, or full editorial example in a preview frame, while single-form entries disable the extra variant choices. The gallery groups exploded axonometric examples and axonometric plan examples with their phone, unboxing, AI agent stack, keyboard, campus, coffee shop, and warehouse subtypes. A separate link opens the icon catalog. This makes visual review a comparison task rather than a search through individual files. References: skills/…/index.html• L181-207, skills/…/index.html• L210-445, skills/…/index.html• L447-501
HTML template family
The HTML templates define the outer presentation shell for a diagram artifact. Each shell leaves the diagram content as inline SVG and keeps the page usable in a modern browser without a build step; the choice of shell sets the amount of editorial framing around that SVG.
| Shell | Purpose | Presentation choice |
|---|---|---|
| Minimal light | Default diagram page | A title, type label, and diagram on a light paper background |
| Minimal dark | Dark presentation | The same focused page shape with dark colors |
| Full editorial | Long-form or hero diagram | Header, diagram area, optional information cards, and footer |
| Terminal | Tool or developer presentation | Terminal window chrome and monospace treatment |
| Motion | Optional time-based explanation | A complete static diagram plus progressive reveal or playback controls |
Use the shell that matches the intended context, not one that adds decoration by default. The minimal templates keep the diagram central, the full shell adds room for supporting explanation, and the terminal and motion shells change the presentation mode for specific needs. References: skills/…/SKILL.md• L504-527, skills/…/template.html• L20-83, skills/…/template-dark.html• L20-82, skills/…/template-full.html• L28-83, skills/…/template-terminal.html• L32-169, skills/…/template-motion.html• L26-45
Rendered example collection
The rendered examples are reference artifacts for supported diagram types and presentation variants. They show how the same visual system adapts to architecture, process, data, relationship, chart, security, import, motion, exploded, and plan-oriented subjects without turning the library into a collection of abstract samples. The exploded examples explain parts that separate along one axis, while the axonometric plan examples explain spaces or sites from a raised view.
Examples use a predictable naming relationship: example-<type>.html is the light form, while -dark and -full identify the dark and full editorial forms. Some subjects also have a named special form, such as terminal or animated examples, and single-form examples do not offer the normal variant switch. The gallery groups related subtypes under a parent subject while keeping their example names distinct.
The exploded family provides a general app-stack example plus phone, unboxing, AI agent stack, and keyboard subtypes. The phone, unboxing, AI agent stack, and keyboard animated forms are single-form entries because motion is part of their subject variant. The axonometric plan family provides an office plan plus campus, coffee shop, and warehouse subtypes, with separate animated examples for those subtypes. These entries demonstrate both ordinary variant review and a static-first motion review. References: skills/…/index.html• L397-443, skills/…/example-exploded.html• L63-79, skills/…/example-exploded-full.html• L37-45, skills/…/example-exploded-phone.html• L63-79, skills/…/example-exploded-phone-animated.html• L54-80, skills/…/example-exploded-unboxing.html• L63-79, skills/…/example-exploded-unboxing-animated.html• L54-80, skills/…/example-axonometric-plan.html• L63-79, skills/…/example-axonometric-plan-campus-full.html• L37-46, skills/…/example-axonometric-plan-campus-animated.html• L54-80
The collection is for visual review as well as onboarding. A reader can compare density, type treatment, layout, and semantic emphasis across examples before creating a new artifact. The examples remain complete HTML pages with accessible SVG names and descriptions, so they also demonstrate the expected relationship between a page shell and its diagram content. The gallery's iframe and raw-file link make the same chosen example available for close review or direct opening. References: skills/…/index.html• L447-501, skills/…/example-axonometric-plan-campus.html• L61-70, skills/…/example-axonometric-plan-campus-dark.html• L61-70, skills/…/example-axonometric-plan-campus-full.html• L34-46, skills/…/example-exploded-phone.html• L61-70, skills/…/example-exploded-phone-dark.html• L61-70, skills/…/example-exploded-phone-full.html• L34-46
Vendored icon catalog
The icon catalog provides small, reusable symbols for common IT and data concepts. It is both a source of inline SVG snippets and a browsable visual reference at skills/…/icons.html; the icons are monochrome so their parent diagram can set the color through currentColor.
The catalog groups icons by the concept they represent rather than by a diagram type. Its groups cover compute, people, network, data, Kubernetes, actions, DevOps, brand systems, data tools, languages, statistical tools, and file formats. Generic symbols use stroked paths, while brand silhouettes use filled shapes. References: skills/…/primitive-icons.md• L1-9, skills/…/primitive-icons.md• L11-20, skills/…/primitive-icons.md• L67-114, skills/…/primitive-icons.md• L179-215, skills/…/primitive-icons.md• L430-610, skills/…/primitive-icons.md• L612-827
Copy an icon by its catalog name and place it inside the diagram's SVG. Keep it decorative when it only supports recognition; the catalog's specimen icons are marked aria-hidden so they do not add noise to the accessible name of the diagram. The source notes preserve the license family for each icon group: Tabler Icons uses MIT and Simple Icons uses CC0. References: skills/…/primitive-icons.md• L3-9, skills/…/icons.html• L107-115
Asset selection flow
Asset selection connects product intent to a reviewable output. The process starts with the page context and ends with a single diagram artifact whose shell, example reference, and optional icons support the same message.
- Select a light, dark, full, terminal, or motion shell based on the delivery context.
- Find an example with a similar diagram type or presentation need.
- Reuse an icon only when it adds meaning that shape and text do not already provide.
- Replace the example content while keeping the artifact self-contained and accessible.
- Review the result in the gallery or as a standalone page before export.
The export command operates on a specific diagram HTML file and extracts its SVG for SVG or PNG output. The gallery itself is not an export source because it contains multiple previews. References: prompts/export-diagram.md• L6-13, prompts/export-diagram.md• L22-31, commands/export-diagram.md• L12-18, commands/export-diagram.md• L28-36
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the gallery's type names, parent-subtype relationships, variant suffixes, and special single-form entries aligned with the example filenames it constructs.
- Keep exploded and axonometric plan parent entries aligned with their subtype entries and with the light, dark, full, and animated files that exist.
- Keep new template shells compatible with the self-contained HTML and inline SVG output contract.
- Keep icon names, category placement, source attribution, and the browsable icons.html specimen aligned.
- Keep examples used for visual review consistent with the template family and with the style and primitive guidance.
- Keep README preview thumbnails and their manifest aligned with the full-size screenshots and README links.
- Keep export guidance clear that assets/index.html is a gallery and requires a specific diagram file.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A gallery tab points to a missing or differently named example | The preview fails to load or shows the wrong variant | Preserve the example-<type><variant>.html naming contract when adding or renaming examples |
| A subtype is treated as a standalone example or loses its parent grouping | The gallery presents the wrong label or requests the wrong example path | Keep parent-subtype metadata and the constructed example name aligned |
| A single-form animated entry is given a dark or full variant | The gallery requests a file that does not exist | Mark animated entries with data-single and disable the extra variant choices |
| An exploded or axonometric plan family gains a file without a matching gallery entry | The example is hard to find and its visual relationship to sibling variants is lost | Add the type, parent, and variant relationship to the gallery with the file family |
| The gallery page is passed to the export flow | The output request is ambiguous because the page contains many diagrams | Refuse assets/index.html and ask for one specific diagram file |
| An icon is copied without its catalog meaning or source note | A symbol can mislead readers or lose its license context | Choose icons by their defined concept and retain the catalog attribution |
| A motion shell hides the only meaningful content before motion starts | Static review and reduced-motion users see an incomplete diagram | Keep the static frame complete and treat motion as an optional presentation layer |
| A screenshot changes without rebuilding its committed preview | README review shows stale or missing visual content | Run python scripts/build-readme-thumbs.py --check and rebuild the thumbnails when the source image changes |
Key files
| File | Why to read it |
|---|---|
| skills/…/index.html | Shows how types, parent subtypes, variants, special examples, and the icon-library link form the visual review surface. |
| skills/…/template.html | Shows the focused light shell used as the default starting point. |
| skills/…/template-dark.html | Shows the dark presentation counterpart. |
| skills/…/template-full.html | Shows the editorial shell for diagrams that need supporting context. |
| skills/…/template-terminal.html | Shows the terminal presentation for developer-tool contexts. |
| skills/…/template-motion.html | Shows the static-first shell for optional motion. |
| skills/…/primitive-icons.md | Defines the reusable icon meanings, usage model, and source licenses. |
| skills/…/icons.html | Provides the visual browser for the vendored icon catalog. |
| skills/…/example-exploded.html | Demonstrates the base exploded axonometric form. |
| skills/…/example-exploded-phone.html | Demonstrates a phone teardown as an exploded subtype. |
| skills/…/example-exploded-unboxing-full.html | Demonstrates an editorial packaging example with supporting explanation. |
| skills/…/example-exploded-phone-animated.html | Demonstrates a single-form animated exploded example with a complete static frame. |
| skills/…/example-axonometric-plan.html | Demonstrates the base axonometric plan form. |
| skills/…/example-axonometric-plan-campus.html | Demonstrates a plan subtype with a site and phase message. |
| skills/…/example-axonometric-plan-campus-full.html | Demonstrates the editorial campus plan with supporting context. |
| skills/…/example-axonometric-plan-campus-animated.html | Demonstrates a single-form animated plan example. |
| scripts/build-readme-thumbs.py | Defines the committed preview-image workflow used to keep README visual review fast and current. |
| scripts/test-build-readme-thumbs.py | Shows the checks that reject stale, corrupt, wrongly sized, orphaned, or miswired preview images. |