# How Color Tokens Are Defined and Used in diagram-design's Style Guide
> Learn how diagram design centralizes visual colors using semantic tokens in its style guide. Discover reusable color names like paper, ink, and accent that adapt to light or dark mode.
- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-06
---
**Diagram-design centralizes every visual color in semantic tokens defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), replacing raw hex codes with reusable names like `paper`, `ink`, and `accent` that automatically adapt to light or dark mode.**
The diagram-design repository (cathrynlavery/diagram-design) enforces visual consistency across all diagram types through a strict token-based color system. Rather than scattering hex codes throughout type definitions, all colors are defined once in a master style guide and referenced by semantic name. This enables instant global theming while maintaining accessibility and brand alignment.
## Token Definition in style-guide.md
The foundation of the color system lives in **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)**. This file declares the complete token table that serves as the single source of truth for every hue in the system.
### Semantic Token Structure
The **Tokens** table maps each semantic role to two values: a default hex for light mode and an alternative for dark mode. Tokens are organized by functional purpose:
- **Background / surface** — `paper`, `paper-2`
- **Text / strokes** — `ink`, `muted`, `soft`, `rule`, `rule-solid`
- **Highlight / focal** — `accent`, `accent-tint`
- **Links** — `link`
Any change to these values propagates automatically to every diagram type, eliminating the risk of inconsistent colors across the skill.
## Series Palette for Multi-Series Charts
Charts requiring distinct colors for multiple series use a dedicated **series palette** defined in the same style guide file. Currently, this applies primarily to radar charts.
The palette follows a strict hierarchy: `accent` is reserved for the focal series, while supporting series use `series-1` through `series-5`. This guarantees that the most important data point always receives the primary brand color, with secondary data receiving visually subordinate but distinct hues.
## Terminal Skin (Optional Override)
A separate, opt-in palette exists for terminal-window primitives. These tokens—including `terminal-paper` and `terminal-accent`—are declared alongside the main tokens but are **not** applied to the default skin. This allows specialized diagram types to maintain their own aesthetic without polluting the core token namespace.
## Using Tokens in Diagram Specifications
Diagram types reference colors by **semantic name only**, never by raw hex. The SVG generator substitutes token values at render time based on the active skin.
### Per-Node Color Overrides
Individual nodes can supply custom hex codes that bypass the token system entirely:
```yaml
nodes:
- lane: "ADM"
step: 1
title: "Access Control"
sub: "bucket policies · LDAP"
tool: "MinIO · LDAP console"
color: "#b85450" # tinted rust-red – overrides the default token
```
The `color` field is rendered as-is; all other colors on the node still resolve from tokens. This pattern appears in [`skills/diagram-design/references/type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-data-flow.md).
### Lane and Step-Level Overrides
The same override mechanism applies to lanes and steps. When a `color` key is present at these levels, the generated SVG replaces the default token fill with the supplied hex.
### Arrow Styling
Arrow styles map directly to color tokens:
- `muted` → `{muted}`
- `trigger` → `{accent}`
- `accent` → `{accent}`
- `link` → `{link}`
These mappings are defined in [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md) and ensure that connection semantics remain visually consistent across all diagram types.
## SVG Template Resolution
Internally, templates use token placeholders that the generator replaces:
```svg
Page title
```
At render time, `{paper}`, `{ink}`, and `{accent}` resolve to their current values from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), respecting the active light or dark mode.
## Series Palette in Practice
Radar charts demonstrate the series token system:
```yaml
series:
- name: "Metric A"
token: "series-1"
- name: "Metric B"
token: "series-2"
- name: "Metric C"
token: "accent" # the focal series
```
The `token` field explicitly selects from the palette defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), ensuring that series colors remain coordinated even as the underlying skin changes.
## Key Source Files
| File | Purpose |
|------|---------|
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Master token definitions, series palette, terminal skin |
| [`skills/diagram-design/references/type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-data-flow.md) | Token consumption and override patterns |
| [`skills/diagram-design/references/type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-process.md) | Consistent application including `accent`-only rules |
## Summary
- **Single source of truth**: All colors live in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) as semantic tokens with light/dark variants
- **Semantic naming**: `paper`, `ink`, `accent`, and others replace hex codes throughout the system
- **Series hierarchy**: `accent` is reserved for focal data; `series-1` through `series-5` handle multi-series charts
- **Override capability**: Per-node, per-lane, and per-step hex values bypass tokens when exceptional colors are required
- **Runtime resolution**: Templates use placeholders; final values are injected at render time, enabling instant skin switching
## Frequently Asked Questions
### What happens if I use a hex code instead of a token name?
Hex codes are valid only in **override fields** (`color` keys on nodes, lanes, or steps). Using a hex where a token name is expected will cause a rendering failure, as the generator attempts to resolve the string as a token key. Follow the patterns in [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md) to ensure correct usage.
### Can I add new tokens to the style guide?
Yes, but the change must be coordinated across all diagram types that reference it. Because [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is the single source of truth, adding a token requires updating the token table and ensuring downstream templates can consume it. No code changes are needed in individual type definitions if they already use dynamic token resolution.
### How does dark mode switching work?
The generator reads the active skin configuration (typically from [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md)) and selects the appropriate hex value from each token's light/dark pair. This happens at render time, so the same diagram source produces visually distinct outputs without modification.
### Why is `accent` treated differently from other series tokens?
The `accent` token carries **semantic weight** as the primary brand color. Reserving it for the focal series ensures visual hierarchy: viewers immediately recognize which data category deserves primary attention. This rule is enforced by convention in type specifications like [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md).