# How the Style Guide Token System Maps to Semantic Roles in Diagram-Design

> Discover how the style guide token system in DiagramDesign maps semantic roles like paper and ink to color values for automatic light and dark mode switching without altering diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-11

---

**The style guide token system in Diagram-Design maps abstract semantic roles—such as `paper`, `ink`, and `accent`—to concrete color values, enabling automatic light and dark skin switching without modifying individual diagram specifications.**

The cathrynlavery/diagram-design repository employs a centralized **style guide token system** to maintain visual consistency across all diagram types. Rather than scattering hard-coded hex values throughout type specifications, the system defines semantic roles that describe the purpose of each visual element. This architecture allows the rendering engine to resolve actual colors at runtime based on the active skin, ensuring that a single source of truth drives every visual decision.

## The Three-Layer Architecture of the Token System

The mapping between tokens and semantic roles operates through three distinct layers that separate definition from implementation.

### Token Tables: The Source of Truth

All visual tokens originate 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 contains the "Tokens → Semantic roles" table (lines 15-29), which lists each token with its hex or rgba values and a description of the role it fulfills.

Key tokens defined in this table include:

- `paper` – Page background and default node fill
- `ink` – Primary text and stroke color
- `muted` – Secondary text and arrow strokes
- `accent` – Focal color limited to one or two elements per diagram
- `link` – Specific to HTTP/API arrows

Each token specifies default values for both light and dark skins, creating a complete color palette that responds to the rendering context.

### Semantic-Role Usage in Type Specifications

Diagram specifications—such as [`skills/diagram-design/references/type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-process.md) and [`skills/diagram-design/references/type-tree.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md)—reference these semantic roles when describing fills, strokes, and other visual attributes. The role name is used directly in the specification, allowing the renderer to look up the concrete value at runtime.

This design means that type files contain no hard-coded color values. Instead, they declare intent (e.g., "use the accent color for this focal node"), while the actual value remains decoupled in the style guide.

### Runtime Resolution in the Rendering Engine

When a diagram is generated, the rendering engine reads the token definitions from the style guide, resolves the appropriate value for the current skin (light or dark), and applies it to the SVG or HTML output. Because tokens are the only location where color and opacity are defined, changing a palette or swapping skins automatically updates all diagrams without requiring edits to individual type files.

## Core Semantic Roles and Their Values

The semantic roles abstract color purpose from implementation. Below are the primary roles and their default values as defined in the style guide:

| Semantic Role | Purpose | Light Default | Dark Default |
|---------------|---------|---------------|--------------|
| `paper` | Page background / default node fill | `#f5f5f5` (white-smoke) | `#2d3142` (jet-black) |
| `ink` | Primary text and primary stroke | `#2d3142` (jet-black) | `#f5f5f5` (white-smoke) |
| `muted` | Secondary text and default arrow stroke | `#4f5d75` (blue-slate) | `#bfc0c0` (silver) |
| `soft` | Subtle backgrounds and borders | Varies by skin | Varies by skin |
| `accent` | Focal colour (limited to 1-2 per diagram) | `#eb6c36` (atomic-tangerine) | `#f08a59` |
| `link` | HTTP/API arrows | `#2e5aa8` | `#6a95d8` |

These definitions ensure that semantic meaning remains constant while concrete values adapt to the viewing environment.

## Node-Type to Token Mapping in Practice

The "Node type → treatment" section in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) (lines 53-62) maps logical node categories to specific fill and stroke tokens. This mapping illustrates how semantic roles translate to visual treatments:

| Node Type | Fill Token | Stroke Token |
|-----------|-----------|--------------|
| `focal` | `accent-tint` | `accent` |
| `backend` | `#ffffff` (white) | `ink` |
| `store` | `ink @ 0.05` | `muted` |
| `external` | `ink @ 0.03` | `ink @ 0.30` |
| `input` | `muted @ 0.10` | `soft` |
| `optional` | `ink @ 0.02` | `ink @ 0.20` (dashed) |
| `security` | `accent @ 0.05` | `accent @ 0.50` (dashed) |

Note that some entries use opacity modifiers (e.g., `@ 0.05`) to create variations without defining new tokens, maintaining the constraint that all color values derive from the base token set.

## Practical Implementation Examples

Diagram authors reference semantic roles directly in YAML specifications. The rendering layer handles token resolution:

```yaml

# Example diagram spec using semantic roles

nodes:
  - id: api
    type: external          # → fill: ink @ 0.03, stroke: ink @ 0.30

  - id: db
    type: store             # → fill: ink @ 0.05, stroke: muted

edges:
  - from: api
    to: db
    style: accent           # uses the `accent` token for colour & thickness

```

The rendering engine implements resolution logic similar to the following Python pattern:

```python

# Python snippet that resolves a token to its concrete colour

def resolve_token(token, skin="light"):
    tokens = {
        "paper": {"light": "#f5f5f5", "dark": "#2d3142"},
        "ink":   {"light": "#2d3142", "dark": "#f5f5f5"},
        "accent":{"light": "#eb6c36", "dark": "#f08a59"},
        # … other tokens omitted for brevity …

    }
    return tokens[token][skin]

print(resolve_token("accent", "dark"))   # → #f08a59

```

This separation allows designers to update the color palette in one location while all diagram specifications automatically inherit the new values.

## Validation and Quality Assurance

The repository includes [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) to enforce token system compliance. This validation script ensures that generated diagrams contain no stray hex colors or hard-coded values outside the semantic token system.

For implementation patterns and end-user examples, [`docs/cookbook.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/cookbook.md) provides practical guidance on applying these semantic tokens correctly across different diagram types.

## Summary

- **Centralized definitions** in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) serve as the single source of truth for all color values.
- **Three-layer architecture** separates token definition, semantic-role usage in type files, and runtime resolution.
- **Semantic roles** abstract color purpose (e.g., `paper`, `ink`, `accent`) from concrete hex values, enabling automatic skin switching.
- **Node-type mapping** assigns specific fill and stroke tokens to logical categories like `external`, `store`, and `focal`.
- **Validation tools** like [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) prevent drift from the token system by detecting unauthorized color values.

## Frequently Asked Questions

### What is the purpose of semantic roles in Diagram-Design?

Semantic roles abstract the purpose of a color from its specific value. By labeling elements as `paper`, `ink`, or `accent` rather than using hex codes, the system allows global palette changes—such as implementing dark mode—to propagate automatically without editing individual diagram files.

### How does the style guide token system handle dark mode?

Each token definition in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) specifies both a light and dark default value. The rendering engine detects the active skin context and resolves the appropriate value at runtime, ensuring consistent contrast ratios across themes.

### Where are the token definitions stored in the repository?

The canonical token definitions reside in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), specifically within the "Tokens → Semantic roles" table (lines 15-29) and the "Node type → treatment" mappings (lines 53-62).

### How can I validate that my diagram uses only approved tokens?

Run [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) to validate that your diagram specifications contain no hard-coded colors outside the token system. This script checks that all visual attributes reference valid semantic roles as defined in the style guide.