How to Customize Design System Tokens (Colors, Fonts, Spacing) in Diagram-Design

The single source of truth for diagram-design tokens is the style-guide.md file located in the skill's references folder, where semantic tables for colors, typography, and spacing define the visual identity of every generated diagram.

The cathrynlavery/diagram-design repository uses a token-based architecture that centralizes visual styling in a single markdown file. By editing these design system tokens, you can completely rebrand generated diagrams—changing palettes, font families, and layout scales—without modifying any diagram-type code or logic.

Locate the Central Token File

All design tokens reside in skills/diagram-design/references/style-guide.md. This file establishes the default skin (white-smoke paper, jet-black ink, atomic-tangerine accent, and blue-slate muted) through semantic mappings that the layout engine consumes during SVG generation. The file contains three primary token tables: Color, Typography, and Spacing.

Customize Color Tokens

The Color table maps semantic names to hex values starting around line 19 of style-guide.md. Key tokens include paper (background), ink (primary text), accent (highlights), and muted (secondary elements).

To rebrand the accent color, locate the accent row and replace the hex value:

| `accent` | Focal highlight colour | `#0066ff` |

This changes the focal highlight from the default atomic-tangerine (#eb6c36) to a corporate blue. The layout engine applies this value to decision nodes, emphasis paths, and interactive highlights in the generated SVG.

Customize Typography Tokens

The Typography section (starting near line 90) defines three font family tokens: title, body, and code. Each entry includes a complete font stack to ensure graceful degradation.

To use a custom typeface for headings, update the title token:

| `title` | Heading font | `"Roboto Slab", serif` |

This replaces the default "Instrument Serif", serif stack. The body token controls paragraph and label text, while code handles monospaced annotations. All three tokens support web-safe fonts, local installed fonts, or Google Fonts loaded via the rendering pipeline.

Customize Spacing Tokens

The Spacing table (beginning around line 130) provides a numeric scale that controls padding, margins, and node gutters. The tokens follow a naming convention of spacing-1, spacing-2, etc., with values defined in pixels.

To tighten the layout density, reduce the small gap value:

| `spacing-2` | Small gap | `4px` |

This changes the default 8px to 4px, compressing the space between related diagram elements. Adjusting spacing-3 and spacing-4 alters medium and large gaps, respectively, affecting overall diagram whitespace without touching layout algorithms.

Validate and Apply Changes

After editing style-guide.md, generate a test diagram to verify the new branding. The first time you customize tokens, the skill may prompt you to run the onboarding flow referenced in skills/diagram-design/references/onboarding.md. You can also execute verification scripts in the scripts/ directory to ensure WCAG contrast ratios and token consistency remain valid.

Complete workflow example:

# 1. Open the style guide in your editor

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

# 2. Edit tokens (colors, fonts, spacing) and save

# 3. Generate a test diagram

diagram-design import-mermaid <<'EOF'
graph LR
  A[Start] --> B[Process]
  B --> C{Decision}
  C -->|Yes| D[Result]
  C -->|No| E[Alternative]
EOF

# 4. Save the branding as a reusable profile

diagram-design profile save my-brand

Summary

• Edit skills/diagram-design/references/style-guide.md to modify the default skin without changing diagram logic
• Update the Color table (line ~19) to change palette values for paper, ink, accent, and muted
• Modify the Typography table (line ~90) to set custom title, body, and code font families
• Adjust the Spacing table (line ~130) to control layout density via spacing-1, spacing-2, and higher scale values
• Use diagram-design profile save to persist branded configurations for reuse across multiple projects
• Run verification scripts in scripts/ to validate contrast and token integrity after changes

Frequently Asked Questions

Where does diagram-design store its default color palette?

The default color palette is defined in the Color token table within skills/diagram-design/references/style-guide.md, starting around line 19. This table maps semantic names like paper, ink, and accent to specific hex values such as #eb6c36 for the atomic-tangerine accent color.

Can I use custom Google Fonts in my diagrams?

Yes. Edit the Typography table in style-guide.md (around line 90) and replace the font-family value for the title, body, or code token with your desired font stack, such as "Roboto Slab", serif. The rendering engine will apply this stack to the generated SVG output.

How do I save my token customizations for reuse across projects?

Use the CLI command diagram-design profile save <profile-name> to store your current style-guide.md configuration as a named profile. This allows you to apply the same color, font, and spacing tokens to other projects without manually re-editing the file each time.

What happens if I make a typo in a token value?

The verification scripts located in the scripts/ directory will detect invalid hex codes, malformed font stacks, and WCAG contrast violations when executed. Additionally, the onboarding flow in skills/diagram-design/references/onboarding.md provides a "taste-gate" check that validates token integrity before finalizing the branding.

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