# How to Customize Diagram Colors and Fonts Using `style-guide.md`

> Learn to customize diagram colors and fonts by editing style-guide.md. Discover methods like semantic role tables, scripts, and named profiles for effortless visual token management.

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

---

**[`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is the single source of truth for all visual tokens in Diagram Design, so you can customize diagram colors and fonts by editing its semantic role tables, running the onboarding script, injecting a JSON token block, or switching named profiles.**

The `cathrynlavery/diagram-design` repository separates diagram logic from visual presentation through a strict semantic token system. Because every diagram component references abstract roles defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) rather than literal color codes or font names, you can customize diagram colors and fonts using [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) without ever modifying the individual `type-*.md` specification files.

## Understanding the Token Architecture in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)

In [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), visual design is expressed as a set of **semantic tokens**. This indirection means a single edit to a token value ripples across every diagram type that consumes it.

### Semantic Color Roles

The **"Tokens → Semantic roles"** table maps abstract names to concrete values. Roles such as `paper`, `ink`, and `accent` are defined near lines 19–22 and 26–27 of [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). Diagram type specs never store raw hex values; instead they declare something like `fill: accent-tint`, and the rendering engine resolves that role to the actual color defined in the table.

### Typography Tokens

The **"Typography"** section assigns font families, sizes, and weights to semantic roles like `title`, `node-name`, and `sublabel` (see lines 76–77). When a diagram primitive needs to render a node label, it pulls the `node-name` token. As long as that token exists in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), updating its family or weight automatically changes every diagram that uses it.

### Stroke, Radius, and Spacing Tokens

Line 98 and surrounding rows define values such as `stroke-default` inside the **"Stroke, radius, spacing"** table. All shapes consume these globals, so changing the token updates line thickness, corner radius, or padding across the entire system.

### Customization Entry Points

The **"Customizing the skin"** section (lines 23–31) documents four supported ways to apply a new visual skin:

1. Run the onboarding script to auto-extract a palette from a brand URL.
2. Edit the semantic tables manually.
3. Paste a brand-token JSON block directly into the file.
4. Switch between named profiles defined in [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md).

## Four Methods to Customize Diagram Colors and Fonts

### Auto-Extract a Palette With the Onboarding Script

The fastest way to customize diagram colors and fonts is to let the CLI parse an existing website's CSS. Run:

```bash
diagram-design onboarding <brand-website-url>

```

This script extracts the dominant palette and font families, then writes them directly into [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and updates the default skin. For implementation details, see [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md).

### Edit the Token Tables Manually

For precise control, locate the relevant row in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and update the value.

To change a color, edit the hex or `rgba` entry in the semantic roles table:

```markdown
| `accent` | Focal / 1–2 max per diagram | `#ff4500` (orange-red) |

```

To adjust typography, modify the family, size, or weight for the target role:

```markdown
| `node-name` | Geist (sans) | 14px | 700 |

```

After manual edits, run the **taste gate**—the post-process validation step—to verify that contrast requirements still hold.

### Inject a Brand Token JSON Block

Append a structured JSON object such as:

```json
{
  "paper": "#fafafa",
  "ink": "#212121",
  "accent": "#c2185b",
  "fontTitle": "Merriweather",
  "fontBody": "Inter"
}

```

Then map each JSON key to the existing semantic roles in the **"Semantic roles"** table. This approach is especially useful in CI pipelines that generate [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) from design-system exports.

### Switch Between Named Profiles

Add a new profile inside [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) that points to an alternate set of token values. When generating a diagram, select that profile with the `--profile` flag:

```bash
diagram-design export-diagram \
  --type type-architecture \
  --profile branding-blue \
  --output my-diagram.svg

```

This method lets you maintain multiple brand skins in parallel without duplicating type specifications.

## Practical Code Examples

### Apply a Custom Skin Programmatically in Node.js

You can load a JSON version of your tokens and apply them globally before rendering:

```javascript
const { Diagram } = require('diagram-design');

// Load a custom style-guide (JSON version)
const customTokens = require('./my-style-tokens.json');

// Apply it globally
Diagram.setTokens(customTokens);

// Generate a diagram – all colors & fonts follow the new tokens
Diagram.render({
  type: 'type-uml-class',
  content: '...'
});

```

### Render a Diagram via CLI With a Profile

If [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) defines a profile called `branding-blue`, invoke it like this:

```bash

# Assuming profiles.md defines a profile called "branding-blue"

diagram-design export-diagram \
  --type type-architecture \
  --profile branding-blue \
  --output my-diagram.svg

```

### Manually Patch the Accent Color

When editing [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) by hand, a typical diff changes the `accent` role while leaving its semantic name intact:

```diff
@@ -24,7 +24,7 @@
 | `accent` | Focal / 1–2 max per diagram | `#eb6c36` (atomic-tangerine) |
| `accent-tint` | Fill for accent-bordered boxes | `rgba(235,108,54,0.08)` |
| `link` | HTTP/API calls, external arrows | `#2e5aa8` |
+| `accent` | Focal / 1–2 max per diagram | `#ff6600` (bright orange) |

```

Because diagrams reference the `accent` role, every shape that relies on it updates instantly.

## Essential Files for Diagram Customization

Several files in the `cathrynlavery/diagram-design` repository work together to define and apply visual skins:

- **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)** — The master token definition for colors, typography, spacing, and stroke rules.
- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)** — Documents the helper that auto-generates a skin from a brand URL and rewrites [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).
- **[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)** — Defines named skin collections and the rules for switching between them.
- **`skills/diagram-design/references/type-*.md`** (for example, [`type-uml-class.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-uml-class.md)) — Reference the semantic tokens for each specific diagram type.
- **[`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md)** — Defines the CLI command used to invoke the diagram generator with a `--profile` flag.

## Summary

- **[`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)** is the central source of truth for every visual token in the `cathrynlavery/diagram-design` repository.
- Diagram components consume **semantic roles**—such as `accent`, `ink`, and `node-name`—rather than raw colors or font names.
- You can customize diagram colors and fonts using [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) by running the onboarding script, editing token tables manually, injecting a JSON token block, or switching named profiles.
- After manual edits, run the **taste gate** validation to ensure accessible contrast ratios.
- Programmatic changes are supported through `Diagram.setTokens()` in Node.js or the `--profile` flag on the CLI.

## Frequently Asked Questions

### What is the difference between a semantic role and a raw hex value?

A **semantic role** is an abstract name like `accent` or `ink` that describes the purpose of a color inside a diagram. The rendering engine resolves this role to an actual hex or `rgba` value stored in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). Because diagram specs reference the role instead of the literal color code, changing one table row updates every diagram automatically.

### How do I validate contrast after editing [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)?

Run the built-in **taste gate**—the post-process validation step that checks contrast requirements after any manual edit to the token tables. This ensures that new color combinations remain accessible before diagrams are generated.

### Can I automate style-guide updates in a CI pipeline?

Yes. Inject a brand-token JSON block containing keys like `paper`, `ink`, `accent`, `fontTitle`, and `fontBody`, then map those keys to the semantic roles in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). This pattern lets design-system exports drive diagram skin updates automatically during continuous integration.

### Where are diagram type specifications defined?

Each diagram type has its own reference file under `skills/diagram-design/references/type-*.md`—for example, [`type-uml-class.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-uml-class.md). These files reference semantic tokens rather than defining raw colors or fonts, which is why editing [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) alone is sufficient to reskin every diagram type.