Where to Find the Single Source of Truth for Diagram Design Tokens

The single source of truth for Diagram Design tokens is the style-guide.md file located at skills/diagram-design/references/style-guide.md, which defines all colors, typography, and semantic tokens used across every diagram generation.

Maintaining visual consistency across complex diagram generations requires a centralized authority that eliminates hard-coded values. In the cathrynlavery/diagram-design repository, the single source of truth for Diagram Design tokens lives in a dedicated markdown reference that both documentation and runtime scripts consume directly.

The Centralized Token Repository

The definitive list of all design tokens resides in skills/diagram-design/references/style-guide.md. According to the file's opening documentation, this path explicitly serves as the single source of truth for colors, typography, and semantic tokens. No diagram type, primitive, or export routine within the repository defines hard-coded hex values; instead, every component references the tables defined in this file.

The repository structure enforces this hierarchy strictly. While type-specific reference files (such as type-*.md) and the main skill documentation (SKILL.md) describe tokens by their semantic role—like accent, paper, or ink—they explicitly instruct readers to look up actual hex values in style-guide.md. This ensures that updating a single value in the style guide propagates instantly across all diagram generations.

Structure of the Style Guide

The file organizes visual properties into distinct sections that cover every aspect of diagram styling.

Semantic Color Tokens

The Tokens table maps semantic roles to their default light and dark hex values. Core roles include:

• paper – Page background and default node fill
• ink – Primary text and line colors
• accent – Highlight elements and interactive indicators

Each row defines the purpose, light mode value, and dark mode value for the role, ensuring theme-aware rendering.

Extended Palettes and Typography

Beyond core tokens, the style guide includes:

• Series palette – Optional distinct colors for multi-series charts that extend beyond the base semantic roles
• Terminal skin – An alternate, opt-in palette specifically for terminal-window primitives
• Typography table – Maps semantic roles to font families, sizes, and weights, ensuring consistent text rendering across all diagram types

Runtime Enforcement and Validation

The repository treats style-guide.md as a configuration file, not merely documentation. The skill reads this file at runtime to validate and apply styles.

The scripts/lint-skin.py utility validates diagram examples against the token definitions in the style guide, ensuring no unauthorized hex codes appear in generated output. As implemented in the source, this linter specifically targets the path skills/diagram-design/references/style-guide.md to perform its checks.

Additionally, skills/diagram-design/scripts/self_check.py provides runtime access to token values. When invoked with the --show-token flag, this script reads the style guide directly to return current hex values for debugging purposes.

Accessing Tokens Programmatically

You can interact with the style guide both through Python parsing and CLI utilities.

Parsing Tokens in Python

The following script extracts the semantic token mappings from the markdown table:

import pathlib

# Path to the style guide (relative to the repo root)

STYLE_GUIDE = pathlib.Path(
    "skills/diagram-design/references/style-guide.md"
)

def parse_style_guide():
    # Grab the markdown table lines that start with '|'

    rows = [
        line.strip()
        for line in STYLE_GUIDE.read_text().splitlines()
        if line.startswith("|") and "Role" not in line
    ]

    # Convert markdown table rows to a dict keyed by token name

    tokens = {}
    for row in rows:
        cols = [c.strip() for c in row.split("|")[1:-1]]
        role, purpose, light, dark = cols[:4]
        tokens[role] = {"purpose": purpose, "light": light, "dark": dark}
    return tokens

if __name__ == "__main__":
    token_map = parse_style_guide()
    # Print the hex for the accent token (light mode)

    print("Accent (light):", token_map["accent"]["light"])
    # Example: list all token names

    print("All tokens:", ", ".join(token_map.keys()))

Querying via CLI

Use the built-in self-check script to query specific token values without parsing the file manually:

# From the repo root, ask the skill to show the current value of a token

python -m skills.diagram_design.scripts.self_check --show-token accent

# → Output: accent = #eb6c36 (light), #f08a59 (dark)

Updating a Token Manually

To modify a token across the entire skill, edit the source file directly:

# Open the file in your editor

code skills/diagram-design/references/style-guide.md

Locate the Tokens table and update the desired hex value. For example, changing the paper color from white-smoke to cream:

| `paper` | Page background, default node fill | `#faf3e0` (cream) | `#2d3142` (jet-black) |

After saving, any subsequent diagram generation immediately uses the new value without requiring code changes elsewhere.

Summary

• The file skills/diagram-design/references/style-guide.md serves as the single source of truth for all Diagram Design tokens
• It defines semantic color roles, series palettes, terminal skins, and typography settings in structured markdown tables
• All diagram types and primitives reference these definitions rather than hard-coded values, ensuring visual consistency
• The system reads this file at runtime, meaning changes propagate automatically to all diagram generations
• Use lint-skin.py for validation and self_check.py with --show-token for programmatic debugging

Frequently Asked Questions

What file contains the single source of truth for Diagram Design tokens?

The file skills/diagram-design/references/style-guide.md contains all color, typography, and semantic token definitions. This markdown file is explicitly designated as the single source of truth in its opening documentation and is referenced by all diagram generation logic, including type-specific reference files and the main skill documentation.

How do I update a color token across all diagrams?

Edit the value in skills/diagram-design/references/style-guide.md within the Tokens table. Update the hex code for the relevant semantic role—such as accent or paper—in either the light or dark column. Because the skill reads this file at runtime via utilities like self_check.py, changes apply immediately to all subsequent diagram generations without requiring modifications to individual diagram scripts.

Can I query token values programmatically?

Yes. You can parse the markdown table using Python to extract token mappings as demonstrated above, or use the CLI utility self_check.py with the --show-token flag. For example, running python -m skills.diagram_design.scripts.self_check --show-token accent returns the current hex values for the accent token in both light and dark modes.

What semantic roles are defined in the style guide?

The style guide defines core semantic roles including paper (page background), ink (text and lines), and accent (highlight elements). It also includes extended definitions for multi-series chart palettes and terminal-specific skins, all documented in the Tokens table and Typography sections of style-guide.md.

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