Where Is the Single Source of Truth for Colors and Typography in Diagram Design?

Diagram Design stores its authoritative color palette and typographic definitions in a single markdown file located at skills/diagram-design/references/style-guide.md, which acts as the central reference for all diagram types.

The cathrynlavery/diagram-design repository maintains visual consistency across multiple diagram formats—including process flows, Sankey charts, radar diagrams, and high-level overviews—by centralizing every color and font decision in one location. Understanding where this single source of truth resides is essential for maintaining brand coherence when extending or customizing the diagram system.

Central Style Guide Location

All visual styling definitions live in skills/diagram-design/references/style-guide.md. This file serves as the definitive registry for both color tokens and typography tokens used throughout the repository.

When the rendering engine processes any diagram schema, it resolves token references such as {ink}, {muted}, or {sublabel} against the values defined in this specific file. No other location in the repository duplicates these definitions; every diagram type imports from this single source.

Color Token Definitions

The style guide establishes the base palette and semantic color mappings that drive every visual element.

Base Palette Tokens

The file defines foundational tokens including:

• ink – Primary text and line colors
• muted – Secondary or de-emphasized content
• accent – Highlight and focus indicators

Semantic Color Values

Beyond base tokens, the guide maps specific hex values to named semantic colors. For example, the repository defines #b85450 as "rust-red" and #5a7d9a as "slate-blue". These values are not hardcoded in individual diagram files; instead, diagram specifications reference the tokens, and the renderer substitutes the exact hex codes at runtime.

Typography Token Standards

Font consistency is enforced through a comprehensive set of typographic tokens stored in the same style guide.

Font Family and Scaling

The style guide prescribes font families using token references such as {sublabel}, {node-name}, and other semantic identifiers. It also standardizes line-height (e.g., 1.25) and letter-spacing to ensure readable text across different diagram densities.

Application in Components

Every diagram component—from axis titles to legend labels—invokes these tokens. A typical style declaration reads: font-family: {sublabel}; color: {muted}; line-height: 1.25. Because the actual font stack and color hex reside exclusively in style-guide.md, modifying the guide instantly propagates changes across all diagram types.

Token Consumption Across Diagram Types

Individual diagram specifications do not duplicate color or font information. Instead, they import the central style guide through a shared token system.

Referencing the Style Guide

Files such as skills/diagram-design/references/type-process.md and skills/diagram-design/references/type-sankey.md rely on the style guide tokens to enforce consistent styling. When a process diagram specifies a color for a step or a Sankey diagram defines a node label, it uses the token names defined in the central guide.

Rendering Pipeline Integration

The rendering scripts located in paths like scripts/verify-…*.py consume these tokens when generating SVG or HTML outputs. The pipeline reads the style guide once and applies the resolved values to every diagram instance, eliminating the risk of visual drift between different diagram formats.

Practical Code Examples

Diagram definitions reference style tokens through YAML frontmatter and inline style declarations. The following examples demonstrate how the single source of truth is accessed in practice.

# Process diagram definition referencing semantic colors

steps:
  - name: "Data Quality"
    chips: {in: "FL", out: "FL"}
    color: "#5a7d9a"      # Resolved from slate-blue token in style-guide.md

  - name: "Governance"
    chips: {in: "TB", out: "TB"}
    color: "#b85450"      # Resolved from rust-red token in style-guide.md

# High-level diagram typography using token references

title:
  text: "Project Overview"
  style: "font-family: {sublabel}; color: {muted}; line-height: 1.25"

In both cases, the actual values are not stored in the diagram type files but are instead resolved against skills/diagram-design/references/style-guide.md at render time.

Summary

• skills/diagram-design/references/style-guide.md serves as the sole repository for color and typography definitions in the Diagram Design system.
• Color tokens like {ink}, {muted}, and {accent} combine with semantic hex values (e.g., #b85450, #5a7d9a) to standardize the visual palette across all diagram types.
• Typography tokens such as {sublabel} and {node-name} centralize font families, line heights, and spacing to ensure consistent text rendering.
• All diagram specifications—including process, Sankey, and radar types—reference these tokens rather than defining values locally, creating a maintainable single source of truth.

Frequently Asked Questions

What file contains the canonical color definitions in Diagram Design?

The authoritative color definitions reside in skills/diagram-design/references/style-guide.md. This markdown file defines every base token (such as ink and accent) and semantic color value used across the repository.

How do diagram types reference the central style guide?

Diagram type specifications like type-process.md and type-sankey.md use a token substitution system. They reference tokens such as {sublabel} or {muted} in their YAML definitions, and the rendering engine resolves these against the values in style-guide.md during SVG or HTML generation.

Can I modify the typography for all diagrams by editing a single file?

Yes. Because style-guide.md defines all typographic tokens including font families, line heights, and colors, updating this file automatically propagates changes to every diagram type that references those tokens, eliminating the need to edit individual diagram specifications.

Are color hex codes duplicated in individual diagram files?

No. While diagram definitions may specify semantic color names or token references, the actual hex values (such as #5a7d9a for slate-blue) are stored exclusively in the central style guide. This prevents duplication and ensures visual consistency across the cathrynlavery/diagram-design repository.

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