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

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. 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 and 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 (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:

# 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 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 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 provides practical guidance on applying these semantic tokens correctly across different diagram types.

Summary

• Centralized definitions in 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 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 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, 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 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.

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