How to Customize Diagram Colors and Fonts with cathrynlavery/diagram-design: A Complete Guide

Customize diagram colors and fonts by editing the style-guide.md token file or running the automated onboarding flow to extract brand assets from a website, skill, or local design system.

The cathrynlavery/diagram-design repository provides a centralized theming system that treats visual identity as configuration rather than code. Every generated diagram pulls from semantic color roles (paper, ink, muted, accent) and typography tokens defined in a single source-of-truth file. This architecture lets you rebrand entire diagram suites without touching individual templates or SVG generators.

How the Theming System Works

At the core of diagram-design is style-guide.md, located at skills/diagram-design/references/style-guide.md. This file defines:

• Color tokens with light and dark variants
• Typography families, weights, and scales
• Spacing metrics that enforce the 4-pixel grid system

All diagram type definitions (type-*.md files) read from this guide rather than hardcoding values. When the rendering pipeline executes, it:

1. Parses the style guide into CSS variables
2. Maps semantic roles to specific SVG fills, strokes, and text elements
3. Wraps output in HTML templates that load the specified Google Fonts

The pre-output checklist in SKILL.md §9 validates that customizations respect mandatory constraints: WCAG AA contrast ratios, the "1-accent rule" (maximum two accent colors), and connector styling rules.

Method 1: Manually Edit Color and Font Tokens

For direct control, modify style-guide.md in your preferred editor. The file uses a readable table format for color roles:

| Role   | Light (default) | Dark (default) |
|--------|-----------------|----------------|
| paper  | #f5f5f5          | #2d3142        |
| ink    | #2d3142          | #f5f5f5        |
| accent | #eb6c36          | #f08a59        |
| muted  | #6b7280          | #9ca3af        |

Update these hex values to match your brand palette:

| paper  | #fafafa          | #1a1a1a        |
| ink    | #212121          | #e0e0e0        |
| accent | #0066cc          | #3399ff        |
| muted  | #757575          | #bdbdbd        |

The semantic roles have fixed meanings across all diagram types:

• paper — page background, card fills
• ink — primary text, node borders, connector strokes
• accent — focal elements, callouts, highlighted paths
• muted — secondary text, inactive states, decorative lines

Typography tokens follow the same pattern. Locate the font family definitions and replace the Google Fonts URL:

typography:
  families:
    sans: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700"
    mono: "https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500"

Changes take effect on the next diagram generation—no server restart required.

Method 2: Automated Onboarding from a Live Website

The onboarding flow, documented in onboarding.md, extracts a complete brand palette from any accessible URL. This method captures computed CSS, dominant colors from screenshots, and detected font families.

Run the onboarding script from the skill root:

python3 scripts/onboard.py --source url https://example.com

The script performs these operations:

• Fetches the target page using the agent-browser utility
• Parses computed styles and extracts color usage patterns
• Maps discovered colors to semantic roles based on luminance and context
• Generates a preview diff showing proposed style-guide.md changes
• Validates WCAG AA contrast for all light/dark combinations
• Writes the updated file after your confirmation

The URL method works best when your brand site already reflects your design system accurately.

Method 3: Import from Local Design Tokens

For projects with existing token files, point the onboarding flow at a local folder:

python3 scripts/onboard.py --source folder ./brand-design-system

Supported file patterns (per onboarding.md §Folder):

• *.css with CSS custom properties (--color-primary, etc.)
• tokens.json in Style Dictionary or Token Studio format
• *.yaml or *.yml token definition files

The script recursively globs the directory, normalizes naming conventions to the semantic role system, and applies the same validation and approval workflow as the URL method.

Persisting Custom Skins as Named Profiles

After onboarding, you can save the configuration for reuse across projects. The flow prompts:

Save this skin as a named profile? [y/N]: y
Profile name: acme-corp-brand

Profiles are stored at ~/.diagram-design/profiles/ as complete style-guide.md snapshots. To activate a profile in a new project, create a .diagram-design marker file:

profile: acme-corp-brand

The skill automatically loads this profile instead of defaults when generating diagrams in that directory.

Validating Your Customizations

Before finalizing changes, run the built-in self-check against a representative diagram:

python3 skills/diagram-design/scripts/self_check.py examples/example-architecture.html

The validator confirms:

• Connectors use rounded right-angle geometry
• Accent colors appear on maximum two elements per diagram
• Font families match the tokens in style-guide.md
• Contrast ratios meet WCAG AA thresholds for all color pairs

Failures produce actionable error messages referencing the specific rule in SKILL.md.

Template Integration

The HTML templates in skills/diagram-design/assets/ ensure fonts render correctly in output files. Key templates include:

• template.html — standard diagram wrapper
• template-full.html — full-page responsive layout

Both templates dynamically inject the Google Fonts link from your typography tokens, guaranteeing visual consistency between the design system and final deliverables.

Summary

• style-guide.md is the single source of truth for all visual customization in cathrynlavery/diagram-design
• Semantic roles (paper, ink, accent, muted) abstract colors so one change affects every diagram type
• Manual editing gives immediate, precise control over individual tokens
• Onboarding flows automate extraction from websites, installed skills, or local token folders
• Named profiles persist brand configurations for cross-project reuse
• Self-check validation enforces mandatory design constraints before output

Frequently Asked Questions

Where are the color and font definitions stored in diagram-design?

All visual tokens live in skills/diagram-design/references/style-guide.md. This file is loaded by every diagram type and template, making it the only file you need to edit for global theming.

Can I use my existing CSS or JSON design tokens?

Yes. The onboarding flow at scripts/onboard.py accepts a --source folder path and recursively searches for *.css, tokens.json, *.yaml, and *.yml files. It maps your existing tokens to the semantic role system automatically.

How do I ensure my custom colors meet accessibility requirements?

The onboarding script and self-check tool both validate WCAG AA contrast ratios. The self-check specifically tests all color pairs used in your diagrams and fails with specific contrast violation details if thresholds are not met.

What happens if I switch between light and dark modes?

The style-guide.md format requires defining both Light (default) and Dark (default) columns for every color role. The rendering pipeline selects the appropriate column based on the output context, ensuring your diagrams adapt to the viewing environment.

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