How Color Tokens Are Defined and Used in diagram-design's Style Guide

Diagram-design centralizes every visual color in semantic tokens defined in 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. 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:

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.

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 and ensure that connection semantics remain visually consistent across all diagram types.

SVG Template Resolution

Internally, templates use token placeholders that the generator replaces:

<rect fill="{paper}" stroke="{rule}" />
<text fill="{ink}">Page title</text>
<path stroke="{accent}" marker-end="url(#arr-accent)" />

At render time, {paper}, {ink}, and {accent} resolve to their current values from style-guide.md, respecting the active light or dark mode.

Series Palette in Practice

Radar charts demonstrate the series token system:

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, ensuring that series colors remain coordinated even as the underlying skin changes.

Key Source Files

File	Purpose
skills/diagram-design/references/style-guide.md	Master token definitions, series palette, terminal skin
skills/diagram-design/references/type-data-flow.md	Token consumption and override patterns
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 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 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 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}