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

> Learn to customize diagram colors and fonts using cathrynlavery/diagram-design. Edit the style-guide.md file or use the automated onboarding flow for a seamless design integration.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-18

---

**Customize diagram colors and fonts by editing the [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), located at [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) in your preferred editor. The file uses a readable table format for color roles:

```yaml
| 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:

```yaml
| 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:

```yaml
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

Supported file patterns (per [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) §Folder):

- `*.css` with CSS custom properties (`--color-primary`, etc.)
- [`tokens.json`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) snapshots. To activate a profile in a new project, create a `.diagram-design` marker file:

```yaml
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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

## Template Integration

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

- [`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) — standard diagram wrapper
- [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/onboard.py) accepts a `--source folder` path and recursively searches for `*.css`, [`tokens.json`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.