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

> Learn 3 ways to override or update design tokens in Diagram Design manually. Edit style-guide.md, use manual onboarding, or update a saved profile for custom diagram styles.

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

---

**Users can manually override or update design tokens in Diagram Design by editing [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) in place.

1. Open [`./skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/./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

```bash

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

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)
- Optionally prompts you to save the configuration as a named profile

This method is defined in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with an added metadata header, as specified in [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.