How to Manually Customize Brand Tokens in Diagram-Design: A Complete Guide

To manually customize brand tokens in diagram-design, edit the markdown table in skills/diagram-design/references/style-guide.md to update hex values for tokens like paper, ink, and accent, then run scripts/lint-skin.py to validate the changes.

The cathrynlavery/diagram-design repository uses a centralized token system to ensure consistent visual styling across all generated diagrams. When you need to apply custom brand colors without using the automated onboarding wizard, you can manually edit the semantic design tokens that control every visual aspect of the output. This guide walks through the exact file locations and validation steps required to implement your brand palette.

Locate the Central Token File

All semantic design tokens live in a single source-of-truth file: skills/diagram-design/references/style-guide.md. This markdown file contains a table mapping token names to hex color values and font families. Every diagram type, icon set, and generated SVG references this file at runtime to resolve its visual properties.

Open this file in your editor to view the Custom tokens section. The table structure uses three columns: Token for the variable name, Value for the hex code, and Role for the semantic description.

Edit the Token Values

Locate the token definitions you wish to override. The repository uses semantic naming conventions that separate presentation from implementation.

Core Brand Tokens to Customize

The most commonly modified tokens include:

• paper: Background color for diagram canvases
• ink: Primary text color used for labels and content
• accent: Brand primary color for CTAs, links, and highlights
• muted: Secondary UI color for borders and subtle fills
• link: Hyperlink color (falls back to accent if omitted)

Replace the default hex codes in the Value column while keeping the token names unchanged. For example, to implement a corporate blue palette:

| Token   | Value   | Role                                    |
|---------|---------|-----------------------------------------|
| paper   | #ffffff | background (white)                      |
| ink     | #0a1d2b | primary text (deep-navy)                |
| accent  | #1e90ff | brand-primary (link, CTA)               |
| muted   | #c0d6e4 | secondary UI (light-blue)              |
| link    | #1e90ff | hyperlink (same as accent)             |

Validate Your Changes

After editing, run the validation linter to ensure color contrast meets WCAG criteria and all hex values are properly formatted:

python scripts/lint-skin.py

This script checks that every token value is a valid hex color, verifies the file structure remains intact, and validates that contrast ratios meet accessibility standards. The linter outputs a pass/fail status for the style-guide.md file before you generate any diagrams.

Organize Multiple Brands with Profiles

For projects requiring multiple brand skins, create isolated profiles instead of editing the global file directly.

First, create the profiles directory and add a custom profile:

mkdir -p ~/.diagram-design/profiles

cat > ~/.diagram-design/profiles/acme-corp.md <<'EOF'

## Custom tokens

| Token  | Value   | Role                                 |
|--------|---------|--------------------------------------|
| paper  | #ffffff |
| ink    | #0a1d2b |
| accent | #1e90ff |
| muted  | #c0d6e4 |
| link   | #1e90ff |
EOF

Then activate the profile for a specific project by creating a marker file:

echo "profile: acme-corp" > .diagram-design

Place this .diagram-design file in your project root. All diagrams built within that directory will now use the custom profile instead of the global style-guide.md.

Regenerate Example Diagrams

After updating tokens, rebuild the built-in example HTML files in assets/*.html to verify the new palette renders correctly across all diagram types. The rendering scripts import the token table at runtime, so any diagram generated after the edit will automatically pick up the new values without requiring a repository restart.

Summary

• Central token file: All brand values live in skills/diagram-design/references/style-guide.md
• Manual editing: Update the Custom tokens table with your hex values while preserving token names like paper and ink
• Validation: Run scripts/lint-skin.py to check WCAG contrast and syntax
• Profile workflow: Store multiple brands in ~/.diagram-design/profiles/ and activate via .diagram-design markers
• Automatic application: Changes take effect immediately for all subsequently generated diagrams

Frequently Asked Questions

Where are brand tokens stored in diagram-design?

Diagram-design stores all semantic design tokens in skills/diagram-design/references/style-guide.md. This markdown file contains a table mapping token names like paper, ink, and accent to hex color values and typography settings. Every rendering script imports this file at runtime, making it the single source of truth for visual styling across the entire repository.

Can I customize brand colors without running the automated onboarding?

Yes. While the repository provides an automated onboarding flow described in skills/diagram-design/references/onboarding.md, you can bypass it by manually editing the token table in style-guide.md. This manual approach gives you direct control over individual hex values and allows for precise brand alignment without answering interactive prompts or using the wizard interface.

How do I ensure my custom tokens meet accessibility standards?

Run python scripts/lint-skin.py after editing your tokens. This linter validates that all color values are properly formatted hex codes and checks contrast ratios against WCAG guidelines. The script will report any accessibility violations before you generate diagrams, ensuring your brand palette remains readable and compliant with web standards.

Can I maintain multiple brand palettes in the same installation?

Yes, use the profile system documented in skills/diagram-design/references/profiles.md. Create separate markdown files in ~/.diagram-design/profiles/ for each brand, then activate specific profiles by adding profile: <slug> to a .diagram-design marker file in your project root. This allows different projects to use different brand tokens while keeping the global style-guide.md untouched.

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