How to Manually Override or Update Design Tokens in Diagram Design: 3 Methods

Users can manually override or update design tokens in Diagram Design by editing style-guide.md directly, using the manual onboarding option, or updating a saved profile—each method modifies semantic color, typography, and UI values that control diagram appearance.

Diagram Design uses a single source-of-truth architecture where all visual styling lives in style-guide.md. This central file defines semantic tokens—colors like paper, ink, accent, and muted, plus typography families and stroke widths—that automatically propagate to every generated diagram. According to the cathrynlavery/diagram-design source code, users have three distinct pathways to customize these tokens without touching the core engine.

---

Method 1: Directly Edit the Style Guide

The most straightforward approach modifies references/style-guide.md in place.

1. Open ./skills/diagram-design/references/style-guide.md
2. Locate the Semantic roles table (lines 17–29)
3. Replace hex values in the "Default (light)" column with your brand colors
4. Save the file and run any diagram-design command

# Example: change accent color from atomic tangerine to deep orange

vim ./skills/diagram-design/references/style-guide.md

# Before:

# | `accent` | `#eb6c36` (atomic-tangerine) | ...

# After:

# | `accent` | `#ff5722` (deep orange) | ...

diagram-design draw --type flowchart my-diagram.mmd

The file also contains Series palette, Terminal skin, and Typography tables. All modifications must respect the Constraints section documented at lines 31–38, which enforces contrast ratios, the one-accent rule, and typographic family limits.

---

Method 2: Use Manual Onboarding (Option D)

The onboarding flow provides a guided interface for token entry without manual file editing.

When you run diagram-design onboard, the gate presents multiple choices. Selecting (d) Manual triggers a structured input sequence:

diagram-design onboard

# Choose (d) Manual when prompted

# Input format: comma-separated token:value pairs

paper:#fafafa, ink:#222222, muted:#777777, accent:#ff5722, link:#1e90ff

The skill then:

• Writes these values under a new Custom tokens section in style-guide.md
• Optionally prompts you to save the configuration as a named profile

This method is defined in onboarding.md at lines 35–38 and is ideal for one-off customizations or when you want validation before persisting changes.

---

Method 3: Update a Client Profile

For reusable brand configurations, Diagram Design supports named profiles that encapsulate complete token sets.

# Step 1: Save current tokens as a profile

diagram-design profile save mybrand

# Step 2: Edit the profile directly (~/.diagram-design/profiles/mybrand.md)

vim ~/.diagram-design/profiles/mybrand.md

# Step 3: Reload to activate

diagram-design profile load mybrand

Profile files are full copies of style-guide.md with an added metadata header, as specified in profiles.md lines 27–44. You can maintain multiple profiles—client-a, client-b, dark-mode—and switch between them per project. The profile switch command also triggers reload.

---

Design Token Constraints You Must Respect

All override methods enforce the same architectural rules documented in style-guide.md lines 31–38:

• Contrast: ink must achieve WCAG AA contrast on paper; muted must meet AA for text ≥11px
• One-accent rule: Only one color may serve as accent; additional accents dilute visual hierarchy
• Three-color maximum: Limit brand palette to paper, ink, and accent; derive muted from these
• Typography lock: Preserve three families—Instrument Serif (titles), Geist Sans (node names), Geist Mono (technical)

Violating these constraints produces warnings during generation and may degrade diagram readability.

---

Summary

• Direct editing: Fastest for quick iterations; modify references/style-guide.md semantic tables directly
• Manual onboarding: Guided input with optional profile persistence; accessed via diagram-design onboard option (d)
• Profile management: Best for multi-brand workflows; edit ~/.diagram-design/profiles/*.md and reload with profile load

All three pathways converge on style-guide.md as the runtime source of truth, ensuring consistent token application across the Diagram Design skill.

---

Frequently Asked Questions

Where are design tokens physically stored in Diagram Design?

All tokens reside in references/style-guide.md within the skill directory. This file contains semantic color roles, typography specifications, terminal skin values, and series palette definitions. Runtime commands read this file to apply styling to generated diagrams.

Can I override tokens without editing files manually?

Yes. Running diagram-design onboard and selecting (d) Manual allows interactive token entry. The skill writes your input to style-guide.md automatically and offers to save the result as a reusable profile, eliminating direct file manipulation.

What happens if I violate the contrast or one-accent constraints?

The Constraints section in style-guide.md documents these as design guidelines rather than hard blocks. However, generated diagrams may fail accessibility checks or exhibit poor visual hierarchy. The system does not prevent override—you assume responsibility for readable output.

How do I share custom tokens across multiple machines or team members?

Save your configuration as a named profile using diagram-design profile save <name>. The resulting file in ~/.diagram-design/profiles/ can be version-controlled, copied to other systems, or distributed as a team standard. Load with diagram-design profile load <name> to activate.

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