# How the Style-Guide.md Token System Maps Semantic Roles to Colors

> Discover how the style-guide.md token system maps semantic roles like paper and ink to specific colors. Learn about hex and RGBA values for light and dark UI modes.

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

---

**The [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) token system maps semantic roles like `paper`, `ink`, and `accent` to concrete color values through a two-column table that defines separate hex and RGBA values for light and dark UI modes.**

The Diagram-Design repository uses a **token-based design system** where every color in every diagram derives from a single source of truth. Located at [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), this file eliminates hard-coded hex values and enables global theme consistency with a single edit.

## How Semantic Roles Work

**Semantic roles** are high-level design concepts that describe *what* a color does, not *what* color it is. The [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file defines these roles in a structured table, then binds each to concrete values for both **light** and **dark** modes.

| Role | Purpose | Light Mode | Dark Mode |
|------|---------|-----------|-----------|
| `paper` | Page background, default node fill | `#f5f5f5` | `#2d3142` |
| `ink` | Primary text and strokes | `#2d3142` | `#f5f5f5` |
| `muted` | Secondary text, arrow strokes | `#4f5d75` | `#bfc0c0` |
| `soft` | Sublabels, boundary labels | `#7a8399` | `#8e98ac` |
| `rule` | Hairline borders | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
| `rule-solid` | Stronger borders, baselines | `#bfc0c0` | `rgba(191,192,192,0.25)` |
| `accent` | Focal color (1–2 per diagram max) | `#eb6c36` | `#f08a59` |
| `accent-tint` | Fill for accent-bordered boxes | `rgba(235,108,54,0.08)` | `rgba(240,138,89,0.10)` |
| `link` | HTTP/API calls, external arrows | `#2e5aa8` | `#6a95d8` |

See the complete role definitions in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) lines 17–27 and 42–48.

## Series Tokens for Multi-Color Diagrams

When a diagram needs **non-focal series colors**—for distinguishing multiple data lines, categories, or sequential elements—the token system provides five reserved slots. These avoid color collision with the focal `accent` role.

| Token | Purpose | Light | Dark |
|-------|---------|-------|------|
| `series-1` | First non-focal series | `#7c8f6f` (sage) | `#9caf8f` |
| `series-2` | Second non-focal series | `#5e7a9b` (dusty-blue) | `#82a0c0` |
| `series-3` | Third non-focal series | `#b8915a` (mustard) | `#d3ad7a` |
| `series-4` | Fourth non-focal series | `#9c6b50` (rust-brown) | `#b88670` |
| `series-5` | Fifth non-focal series | `#6e6479` (slate) | `#8d8298` |

This guarantees that any diagram with up to six series (one focal `accent` plus five non-focal) maintains visual harmony without custom palette decisions.

## The Token Resolution Process

The mapping from semantic role to rendered color follows a three-step resolution chain:

1. **Component requests a role** — A node, label, arrow, or border asks for `accent`, `muted`, or `series-3`
2. **Mode selector activates** — The renderer checks current UI mode (light/dark) and pulls the corresponding hex or RGBA value
3. **Value injection** — The concrete color applies to the SVG, Canvas, or terminal output

Because every component goes through this indirection layer, changing `accent` from `#eb6c36` to `#ff4500` in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) recolors every diagram in the repository instantly.

## Terminal Skin Override System

The Diagram-Design repository supports an alternative **terminal skin** defined in [`skills/diagram-design/references/primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-terminal.md). This skin declares its own token set (`terminal-paper`, `terminal-accent`, etc.) that bypasses the default palette when active.

Per [`primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md) lines 5–6, these terminal-specific tokens shadow the base [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) values, enabling retro terminal aesthetics without breaking the semantic role abstraction.

## Practical Usage Examples

### Python Token Lookup

```python
def get_color(role, mode='light'):
    """
    Retrieve a color token from style-guide.md.
    Called by diagram generators before SVG export.
    """
    tokens = load_style_guide()  # Parsed from skills/diagram-design/references/style-guide.md

    return tokens[role][mode]

# Constructing a focal node with accent treatment

focal_node = {
    "fill": get_color('accent-tint', mode='dark'),   # rgba fill

    "stroke": get_color('accent', mode='dark'),      # border color

    "label_color": get_color('ink', mode='dark')     # text color

}

```

### Mermaid Diagram with Token Values

```mermaid
%% When rendered via Diagram-Design, these hex values
%% are validated against style-guide.md tokens
graph LR
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Result]
    
    %% paper / ink
    style A fill:#f5f5f5,stroke:#2d3142
    
    %% series-1 / accent  
    style B fill:#7c8f6f,stroke:#eb6c36
    
    %% accent-tint / accent
    style D fill:rgba(235,108,54,0.08),stroke:#eb6c36

```

### CLI Profile Override

```bash

# Override accent token for current project profile

diagram-design profile set --token accent=#ff4500

# Verify change propagated to style-guide.md

grep -A2 "^| \`accent\`" skills/diagram-design/references/style-guide.md

```

## Key Files in the Token Architecture

| File | Function |
|------|----------|
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Master token table defining all semantic roles and series tokens with light/dark values |
| [`skills/diagram-design/references/primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-terminal.md) | Terminal skin override tokens that shadow base values when active |
| [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) | CLI interface for reading and writing custom token profiles that persist user overrides |
| [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) | Documentation of the single-source-of-truth architecture (lines 188–190) |

## Summary

- **Semantic roles** (`paper`, `ink`, `accent`, `muted`) abstract *purpose* from *value*
- **Dual-mode tokens** provide automatic light/dark theme switching via parallel hex/RGBA columns
- **Series tokens** (`series-1` through `series-5`) reserve non-focal palette slots for multi-series diagrams
- **Terminal skin** demonstrates extensibility through token shadowing without role changes
- **Global propagation** ensures one edit to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) recolors the entire diagram set

## Frequently Asked Questions

### Where is the color token table defined in the repository?

The complete token table 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 contains all semantic roles, series tokens, and their corresponding light and dark mode values. The repository README explicitly identifies it as the single source of truth for color design.

### How do I switch between light and dark mode in a diagram?

Diagram generators automatically select the appropriate column from the token table based on the current UI mode setting. No manual hex changes are required—simply specify the semantic role (e.g., `accent` or `paper`) and the renderer injects the correct value for the active mode.

### Can I add custom colors without modifying style-guide.md?

Yes. Use the profile system documented in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) to create overrides that persist your custom hex values. The `profile set` command writes these into a local configuration that takes precedence over shipped defaults while preserving the semantic role structure.

### What happens if I use more than five series in one diagram?

The token system only reserves five non-focal series slots (`series-1` through `series-5`). Beyond this, you must either reuse tokens (risking visual ambiguity) or extend [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with additional series definitions. The `accent` role remains reserved for 1–2 focal elements maximum per diagram.