Usage

Start with these tokens when customizing diagrams:

--diagram-base-color and --diagram-base-color-dark to shift the entire palette

--diagram-background and --diagram-text-color for overall contrast

--diagram-node-background and --diagram-node-border-color for shapes

--diagram-edge-color and --diagram-edge-width for connections

Most diagram colors derive from --diagram-base-color (defaults to --color-accent), so changing it re-tints nodes, edges, and text together. Set tokens on :root in your theme CSS so JS renderers can read them.

Tokens

Base Color Token

The foundation token from which all diagram colors are calculated.

Token	Description	Default Value
`--diagram-base-color`	Base color for all diagram color calculations	`var(--color-accent)`
`--diagram-base-color-dark`	Base color for dark mode	`var(--color-accent-dark)`

Core Diagram Tokens

Base styling tokens that apply to all diagram types.

Token	Description	Default Value
`--diagram-background`	Background color for diagrams	`var(--surface-elevated)`
`--diagram-background-dark`	Background color in dark mode	`var(--surface-elevated-dark)`
`--diagram-font-family`	Font family for diagram text	`var(--font-family-sans)`
`--diagram-font-size`	Font size for diagram text	`calc(var(--text-font-size) * 0.9)`
`--diagram-text-color`	Primary text color	`color-mix(in srgb, var(--diagram-base-color) 95%, var(--diagram-background))`
`--diagram-text-color-dark`	Primary text color in dark mode	`color-mix(in srgb, var(--diagram-base-color-dark) 95%, var(--diagram-background-dark))`

Node and Shape Tokens

Colors and styling for diagram nodes, shapes, and containers. All colors calculated from --diagram-base-color mixed with --diagram-background.

Token	Description	Calculation
`--diagram-node-background`	Primary node/shape fill color	`color-mix(in srgb, var(--diagram-base-color) 15%, var(--diagram-background))`
`--diagram-node-background-secondary`	Secondary node background	`color-mix(in srgb, var(--diagram-base-color) 25%, var(--diagram-background))`
`--diagram-node-background-tertiary`	Tertiary node background (3+ states)	`color-mix(in srgb, var(--diagram-base-color) 35%, var(--diagram-background))`
`--diagram-node-border-color`	Node border color	`color-mix(in srgb, var(--diagram-base-color) 35%, var(--diagram-background))`
`--diagram-node-border-width`	Node border width	`var(--border-width-thick)`
`--diagram-node-text-color`	Text color inside nodes	`var(--diagram-text-color)`

Edge and Connection Tokens

Styling for lines, arrows, and connections between diagram nodes.

Token	Description	Calculation
`--diagram-edge-color`	Line/edge color	`color-mix(in srgb, var(--diagram-base-color) 60%, var(--diagram-background))`
`--diagram-edge-width`	Line/edge width	`var(--border-width-default)`
`--diagram-edge-text-color`	Edge label text color	`var(--diagram-text-color)`

State Tokens

Generic state tokens applicable across diagram types (Gantt tasks, state diagrams, etc.).

Token	Description	Default Value
`--diagram-active-background`	Background for active states	`var(--diagram-node-background-tertiary)`
`--diagram-active-border-color`	Border for active states	`var(--diagram-node-border-color)`
`--diagram-inactive-background`	Background for inactive/default states	`var(--diagram-node-background)`
`--diagram-inactive-border-color`	Border for inactive/default states	`var(--diagram-node-border-color)`
`--diagram-complete-background`	Background for completed states	`var(--diagram-node-background-secondary)`
`--diagram-complete-border-color`	Border for completed states	`var(--diagram-node-border-color)`

Structure Tokens

Tokens for structural diagram elements like grids, sections, and groupings.

Token	Description	Calculation
`--diagram-grid-color`	Grid line color	`var(--diagram-base-color)`

Examples

These examples demonstrate how the theming system applies across different Mermaid diagram types. Each example tests different aspects of the token system.

Default Diagrams

Standard diagram styling with default theme tokens:

:root {
  /* No design token overrides */
}

Tests node backgrounds, decision diamonds, edge colors, and edge labels.

Sequence Diagram

Tests actor backgrounds/borders, signal colors, and activation boxes (uses secondary background).

State Diagram

Tests state node backgrounds, transition colors, and special state indicators. Uses --diagram-node-background variants for different states.

Class Diagram

Tests node hierarchy with different visibility levels using primary/secondary/tertiary backgrounds.

Entity Relationship Diagram

Tests entity boxes, relationship lines, and cardinality labels.

Gantt Chart

Tests timeline bars using --diagram-node-background variants for different task states (done/active/future).

Cytoscape Network Graph

Tests node styling, edge styling, and state selectors (selected nodes use active colors).

Tips

Hierarchy: Use --diagram-node-background, --diagram-node-background-secondary, and --diagram-node-background-tertiary to differentiate node states or groups.

Edges: Adjust --diagram-edge-color and --diagram-edge-width together so connectors stay legible against node fills.

Text overrides: Leave --diagram-text-color as the base and override --diagram-node-text-color only when you need extra contrast.

Renderer parity: Mermaid and Cytoscape both read the same tokens, so keep customizations in token space instead of tool-specific CSS.