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

> Learn to customize design system tokens like colors, fonts, and spacing in diagram-design. Modify the style-guide.md file to define your visual identity and generate unique diagrams.

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

---

**The single source of truth for diagram-design tokens is the [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

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

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

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) provides a "taste-gate" check that validates token integrity before finalizing the branding.