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

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 rather than literal color codes or font names, you can customize diagram colors and fonts using style-guide.md without ever modifying the individual type-*.md specification files.

Understanding the Token Architecture in style-guide.md

In 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. 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, 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.

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:

diagram-design onboarding <brand-website-url>

This script extracts the dominant palette and font families, then writes them directly into style-guide.md and updates the default skin. For implementation details, see skills/diagram-design/references/onboarding.md.

Edit the Token Tables Manually

For precise control, locate the relevant row in style-guide.md and update the value.

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

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

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

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

{
  "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 from design-system exports.

Switch Between Named Profiles

Add a new profile inside 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:

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:

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 defines a profile called branding-blue, invoke it like this:

# 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 by hand, a typical diff changes the accent role while leaving its semantic name intact:

@@ -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 — The master token definition for colors, typography, spacing, and stroke rules.
• skills/diagram-design/references/onboarding.md — Documents the helper that auto-generates a skin from a brand URL and rewrites style-guide.md.
• 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) — Reference the semantic tokens for each specific diagram type.
• commands/export-diagram.md — Defines the CLI command used to invoke the diagram generator with a --profile flag.

Summary

• 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 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. 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?

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. 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. These files reference semantic tokens rather than defining raw colors or fonts, which is why editing style-guide.md alone is sufficient to reskin every diagram type.

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