# How to Customize the Diagram Design System: 4 Configuration Methods Explained

> Customize the diagram design system using four methods: manual edits, automated brand extraction, or named profiles. Learn to override default tokens easily.

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

---

**You customize the diagram design system by modifying the centralized [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file—either manually, through automated brand extraction, or via named profiles that override the default tokens without altering the installed skill.**

The `cathrynlavery/diagram-design` repository treats [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) as the single source of truth for all visual semantics. Every diagram type—architecture diagrams, flowcharts, radar charts—resolves colors, typography, and spacing through semantic tokens (e.g., `accent`, `paper`) defined in this file rather than hard-coded values. This architecture ensures that changing one token propagates across every diagram type instantly.

## The Central Configuration File: style-guide.md

All customization pathways ultimately modify **[`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)** located at [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). This file defines **semantic tokens**—logical names like `accent`, `ink`, and `paper`—mapped to specific hex values, font stacks, and spacing scales.

According to the source code in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), diagram type specifications (`type-*.md` files) reference these tokens by role, not by value. This indirection allows the system to remain "skinnable" without touching type-specific logic. The file also contains the **inversion rule**, which automatically generates dark-mode variants for every light-theme color while preserving opacity and hue relationships.

## 4 Ways to Customize the Diagram Design System

### 1. Edit style-guide.md Manually

For immediate, granular control, edit the token tables directly in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). Locate the semantic role you want to change—such as `accent`—and replace the hex value. All newly generated diagrams will use the updated color immediately.

```bash

# Open the style guide for editing

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

# Example: Change the accent color from #ff5722 to your brand color

# Find the row:

# | `accent` | Focal / 1–2 max per diagram | `#ff5722` | `#ffa07a` |

# Replace with your brand hex code

```

The system enforces a **one-accent rule** during validation, ensuring only a single focal accent color exists per diagram to maintain visual hierarchy.

### 2. Run the Onboarding Flow

The onboarding script automates brand adoption by extracting color palettes and font families from any website URL. Located in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), this tool rewrites [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) automatically after scraping the target site.

```bash

# From the repository root, extract brand assets from a URL

python -m skills.diagram_design.onboarding https://example.com

```

The script handles missing tokens safely and performs a **contrast check** (WCAG AA) to verify that the extracted `ink` color remains readable against the `paper` background. If the check fails, the skill pauses and prompts for manual adjustment.

### 3. Create Client Profiles

For managing multiple brands across different projects, save snapshots of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) as **named profiles**. These profiles isolate brand configurations from the core installation, enabling different projects to use different visual identities while sharing the same installed skill.

```bash

# Save the current style guide configuration as a named profile

diagram-design profile save mybrand

# Stored at: ~/.diagram-design/profiles/mybrand.md

```

As documented in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md), profiles persist full token sets including **series palettes** for multi-series charts (radar, line, bar), though these remain opt-in and never override the single `accent` token.

### 4. Use Project Markers for Profile Binding

Create a `.diagram-design` marker file in any project root to force the skill to load a specific profile instead of the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). This keeps the installed skill untouched—ideal for managed marketplace installs where you cannot edit core files.

```bash

# In your project root, create a marker binding to the "mybrand" profile

echo "profile: mybrand" > .diagram-design

```

Subsequent diagram generations in that directory will read from `~/.diagram-design/profiles/mybrand.md` rather than the default configuration.

## Safety Mechanisms and Validation Rules

When any customization pathway modifies tokens, the system runs automated guards:

- **Contrast Validation**: Ensures WCAG AA compliance between `ink` (text) and `paper` (background) colors.
- **One-Accent Enforcement**: Prevents multiple competing focal colors that would dilute visual hierarchy.
- **Inversion Rule**: Automatically derives dark-theme equivalents for every custom color defined in the light theme.

These checks occur before the final write to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) or a profile file, preventing inaccessible or chaotic color combinations.

## How Customizations Propagate to Diagram Types

All diagram type specifications in `type-*.md` files consume tokens through **semantic role references**. For example, a flowchart references `accent` rather than `#ff5722`. This architecture means:

- Import commands ([`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md), [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md)) **redraw** imported content using the current skin, discarding source colors in favor of your active [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) tokens.
- Multi-series charts access opt-in **series palettes** defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) under the "Series palette" section, but these remain subordinate to the primary `accent` token.

## Step-by-Step Customization Examples

**Switching to a Dark Theme:**

```bash

# The inversion rule auto-generates dark variants, but you can force dark mode

# by editing the paper/ink values or using a pre-configured profile

diagram-design profile save darkmode

# Edit ~/.diagram-design/profiles/darkmode.md to swap paper/ink defaults

echo "profile: darkmode" > .diagram-design

```

**Listing Available Profiles:**

```bash
diagram-design profile list

# Output shows all saved slugs: mybrand, darkmode, client-a, etc.

```

**Validating Custom Colors Programmatically:**

While the skill auto-validates, you can manually trigger a contrast check after editing:

```bash

# After manual edits to style-guide.md, run a generation test

diagram-design generate --type flowchart -- validate

# The skill will warn if WCAG AA standards are violated

```

## Summary

- **[`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 `cathrynlavery/diagram-design`.
- **Four pathways** exist: manual editing, URL-based onboarding ([`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md)), named profiles ([`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md)), and project markers (`.diagram-design` file).
- **Validation rules** enforce WCAG AA contrast and a single-accent policy to maintain accessibility and visual coherence.
- **Semantic token architecture** ensures changes propagate instantly across architecture diagrams, flowcharts, and radar charts without touching type-specific logic.
- **Profiles** enable multi-brand workflows by storing snapshots in `~/.diagram-design/profiles/` and binding them via project markers.

## Frequently Asked Questions

### How do I override the default colors for just one project?

Create a `.diagram-design` marker file in the project root containing `profile: <slug>`, where `<slug>` matches a saved profile name. The skill will load `~/.diagram-design/profiles/<slug>.md` instead of the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), leaving the core skill untouched.

### What happens if my custom colors fail accessibility standards?

The skill performs a **contrast check** (WCAG AA) whenever [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is modified—whether manually or via onboarding. If the `ink` color lacks sufficient contrast against `paper`, the skill pauses the operation and prompts you to adjust the hex values before proceeding.

### Can I use multiple accent colors in a single diagram?

No. The system enforces a **one-accent rule** to maintain visual focus. While multi-series charts can access **series palettes** defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), these are opt-in and subordinate to the primary `accent` token; they cannot override the restriction on focal accents.

### Where are custom profiles stored on my system?

Saved profiles reside in **`~/.diagram-design/profiles/`** as individual `.md` files (e.g., [`mybrand.md`](https://github.com/cathrynlavery/diagram-design/blob/main/mybrand.md)). You can manage these via the CLI (`diagram-design profile save`, `list`, or `delete`) or manually edit the files; the skill loads them based on the `profile:` key in project markers or CLI arguments.