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

The 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, 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 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 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 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. This skin declares its own token set (terminal-paper, terminal-accent, etc.) that bypasses the default palette when active.

Per primitive-terminal.md lines 5–6, these terminal-specific tokens shadow the base style-guide.md values, enabling retro terminal aesthetics without breaking the semantic role abstraction.

Practical Usage Examples

Python Token Lookup

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

%% 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

# 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	Master token table defining all semantic roles and series tokens with light/dark values
skills/diagram-design/references/primitive-terminal.md	Terminal skin override tokens that shadow base values when active
commands/profile.md	CLI interface for reading and writing custom token profiles that persist user overrides
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 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. 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 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 with additional series definitions. The accent role remains reserved for 1–2 focal elements maximum per diagram.

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