Diagrams
Diagrams should answer a specific question. Use consistent labels, visible direction, and only the detail required to explain the relationship, flow, or boundary being documented.
Shared diagram tokens#
Diagrams use the diagram.* component-token collection: canvas, node, node label, node line, accent, radius, shadow, padding, and label size. Those roles resolve through the same semantic colours, spacing, and motion foundations as the sites, so a theme change does not create a separate diagram palette.
The generated diagram export is the portable hand-off for canvas tools. It contains resolved values and a Mermaid themeVariables mapping. Regenerate it with npm run tokens:diagrams after a token change; do not maintain a second colour list in a diagram application.
Tool guidance#
| Tool | Use the collection |
|---|---|
| Mermaid | The site loads themeVariables from --diagram-* CSS variables, so rendered diagrams follow the active light or dark site theme. Add mermaid: true to the page front matter. |
| OmniGraffle | Set the canvas, node fill, stroke, text, corner radius, and shadow from the generated export; keep Signal orange for emphasis and active flow only. |
| draw.io | Create one reusable style set from the export, then apply it to nodes and connectors rather than entering per-shape values. |
| XMind | Use the export for the central topic, branch label, boundary, and relationship styles; do not use its automatic rainbow palette. |
External tools cannot consume CSS custom properties directly. Their exported diagrams use the resolved values from the light collection; the source token names remain the durable design decision.