Understanding Semantic Tokens (Paper, Ink, Muted, Accent) in the Diagram-Design Style Guide

The Diagram-Design system uses semantic tokens to decouple design meaning from raw hex codes, allowing diagrams to adapt to any brand palette by remapping roles like paper, ink, muted, and accent through a JSON configuration.

The cathrynlavery/diagram-design repository implements a semantic-by-role architecture that revolutionizes how diagram colors are managed. Instead of hardcoding color values, this approach references abstract roles that describe the purpose of each color within the visual hierarchy. This methodology ensures that the same diagram structure can instantly adapt to different brand identities, accessibility requirements, or dark-mode themes without structural changes.

What Are Semantic Tokens in Diagram-Design?

Semantic tokens are abstract identifiers that describe design values by their meaning rather than their concrete appearance. In the Diagram-Design style guide, defined in references/style-guide.md, these tokens create a strict separation between semantic intent and visual implementation.

According to the source code at line 15 of style-guide.md, all tokens must be referenced by their semantic role rather than raw color values. When a diagram requires customization, users update a JSON mapping that links each semantic role to a concrete color (for example, paper: "#ffffff"). The rendering engine automatically inherits these values, guaranteeing consistency across all diagram types and themes—including dark-mode variants where each token resolves to its dark-mode counterpart (see line 129).

The Core Semantic Token Roles

The Diagram-Design system defines five primary semantic roles that govern color application across diagrams.

Paper: The Canvas Foundation

The paper token represents the background or canvas color—the surface upon which the diagram is drawn. In references/style-guide.md, the default implementation uses "white-smoke paper" as the standard background value. This token ensures that diagrams maintain consistent background contrast regardless of the specific theme applied.

Ink: Primary Foreground Elements

The ink token serves as the primary foreground color, governing text, lines, and most shape strokes. The style guide specifies "jet-black ink" for default text and stroke rendering. By centralizing all text and line colors through this single token, the system enforces readability standards and ensures that foreground elements maintain sufficient contrast against the paper background.

Muted: Secondary and Neutral Accents

The muted token applies to secondary or neutral elements that require visual presence without demanding attention. The style guide implements "blue-slate muted" for non-focus connectors, borders, and subtle highlights. This role prevents visual clutter while maintaining the structural integrity of diagram connections.

Accent: Highlight and Alert States

The accent token conveys meaning and draws attention to critical elements. "Atomic-tangerine accent" flags important actions, security concerns, or errors within diagrams. Unlike the muted role, accent colors are designed to break the visual hierarchy and immediately direct user attention to specific nodes or connections.

Link: Interactive Elements

An additional link token handles interactive components such as hyperlinks and clickable diagram elements. This separation ensures that interactive states remain distinct from static accent colors, preserving usability across different interaction modes.

How Semantic Tokens Enable Brand Portability and Theming

The semantic token architecture delivers three critical advantages for diagram implementation.

Brand Portability: Swapping a brand’s color palette requires editing only the token mapping JSON file. The diagram’s layout, semantic structure, and visual hierarchy remain untouched, allowing identical diagrams to serve multiple brand identities without code duplication.

Accessibility Compliance: Because semantics are explicit in the markup, the system can programmatically enforce contrast ratios. The scripts/verify-semantic-motion.py script validates that color changes do not break readability requirements, ensuring WCAG compliance across theme variations.

Dynamic Theming: Dark-mode themes are generated by converting each semantic token to its dark-mode counterpart while preserving the visual meaning. The paper token might invert to a dark charcoal while maintaining its role as the canvas background, ensuring visual coherence across lighting conditions.

Implementing Semantic Tokens in Code

When rendering diagrams, the system applies semantic tokens through data attributes and CSS custom properties.

Every SVG element receives a data-semantic-role attribute that identifies its semantic function:

<!-- Rectangle using the accent token for important actions -->
<rect x="10" y="10" width="100" height="40"
      data-semantic-role="accent"
      class="semantic-token"></rect>

<!-- Background using paper token -->
<rect x="0" y="0" width="800" height="600"
      data-semantic-role="paper"
      class="semantic-token"></rect>

The CSS layer maps these attributes to token variables defined in the style configuration:

.semantic-token[data-semantic-role="accent"] {
  fill: var(--token-accent);
  stroke: var(--token-accent);
}

.semantic-token[data-semantic-role="paper"] {
  fill: var(--token-paper);
}

.semantic-token[data-semantic-role="ink"] {
  fill: var(--token-ink);
  stroke: var(--token-ink);
}

Brand customization occurs through a JSON token map supplied during onboarding:

{
  "paper": "#f8f9fa",
  "ink": "#212529",
  "muted": "#6c757d",
  "accent": "#ff5733",
  "link": "#0d6efd"
}

When this JSON is loaded, the diagram automatically adopts the new palette while preserving all semantic relationships and visual hierarchies.

Technical Implementation and Verification

The Diagram-Design system enforces semantic token compliance through automated verification and architectural patterns.

Data Attributes and CSS Selectors

As implemented in the rendering engine, CSS selectors target data-semantic-role attributes to apply colors from the token map. This approach allows runtime theme switching without JavaScript manipulation of individual element styles.

Semantic Motion Constraints

The system supports semantic motion for animated diagrams, where steps and items inherit colors from corresponding tokens. The scripts/verify-semantic-motion.py script enforces that motion items respect the semantic token contract, ensuring that animation does not introduce ad-hoc colors. Each motion item must carry an ARIA label and use only the defined token palette, maintaining the motion budget within semantic constraints.

Reference Architecture

Key files in the cathrynlavery/diagram-design repository define and manage these tokens:

• references/style-guide.md: Defines all semantic tokens and explains the semantic-by-role principle
• references/semantic-patterns.md: Documents how tokens interact with higher-level patterns like stage frameworks
• SKILL.md: Describes the workflow for loading the style guide and applying tokens during diagram creation
• scripts/verify-semantic-motion.py: Validates that animated elements maintain semantic token compliance

Summary

• Semantic tokens (paper, ink, muted, accent, link) abstract color meaning from hex values in the Diagram-Design system.
• The references/style-guide.md file mandates that all color references use semantic roles rather than raw values, enabling instant brand adaptation.
• Customization occurs through a JSON token map that the rendering engine applies via CSS custom properties and data-semantic-role attributes.
• The architecture supports automatic dark-mode generation, accessibility compliance, and brand portability without structural diagram changes.
• The scripts/verify-semantic-motion.py script ensures that animations remain within the semantic token budget, preventing visual inconsistency.

Frequently Asked Questions

How do I customize the color palette for my brand in Diagram-Design?

Create a JSON token map that assigns hex values to the five semantic roles (paper, ink, muted, accent, link) and supply this configuration during the onboarding workflow described in SKILL.md. The system automatically applies these values through CSS variables, updating all diagram elements that reference those semantic roles without requiring changes to the diagram structure.

What is the difference between the muted and accent tokens?

The muted token applies to secondary elements like non-focus connectors and borders that require minimal visual weight, while the accent token highlights critical elements such as errors or important actions. According to references/style-guide.md, muted uses "blue-slate" for subtlety, whereas accent uses "atomic-tangerine" to break the visual hierarchy and capture attention.

How does Diagram-Design handle dark mode with semantic tokens?

The system generates dark-mode variants by converting each semantic token to its dark-mode counterpart while preserving the semantic meaning. The paper token shifts to a dark background, ink inverts to a light foreground, and accent/muted adjust to maintain contrast ratios. This transformation occurs automatically when the theme context changes, as the CSS variables reference different values from the token map without altering the underlying data-semantic-role attributes.

What happens if an animated diagram uses colors outside the semantic tokens?

The scripts/verify-semantic-motion.py validation script will flag the violation. This enforcement ensures that animated elements—referred to as "semantic motion" items—inherit colors only from the defined token palette. The script checks that each motion item carries an ARIA label and uses only paper, ink, muted, accent, or link tokens, preventing ad-hoc colors from breaking the visual consistency or accessibility compliance of the animation.

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