# How to Add Custom Brand Colors for Onboarding in diagram-design

> Learn to add custom brand colors for onboarding in diagram-design by fetching from a URL or token file and updating style-guide.md with your brand's palette.

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

---

**You add custom brand colors in diagram-design by running the onboarding flow, which fetches colors from a URL or local token file and rewrites [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with your brand's palette mapped to semantic roles.**

The diagram-design skill from cathrynlavery/diagram-design centralizes all visual tokens in a single file. When you onboard a new brand, the skill automatically extracts color values, maps them to semantic design roles, and validates them against accessibility constraints. This guide covers the exact pipeline, constraints, and commands to customize your brand colors.

## Where Colors Live in diagram-design

All visual tokens are defined in **[`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) (lines 17–27). This file declares four semantic color roles:

| Token | Purpose | Default (light) | Default (dark) |
|-------|---------|----------------|----------------|
| `paper` | Page background / node fill | `#f5f5f5` | `#2d3142` |
| `ink` | Primary text / strokes | `#2d3142` | `#f5f5f5` |
| `muted` | Secondary text / arrow strokes | `#4f5d75` | `#bfc0c0` |
| `accent` | Focal color (1–2 per diagram) | `#eb6c36` | `#f08a59` |

These **semantic tokens** are the single source of truth. All diagram types ([`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md), [`type-journey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-journey.md), etc.) reference these tokens rather than hard-coded hex values. Change [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) once, and every diagram inherits the new palette.

## The Onboarding Pipeline for Custom Brand Colors

The onboarding flow is orchestrated from **[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)** and documented in **[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md)** (lines 15–33 for URL flow, lines 167–232 for token-file mapping). The pipeline executes four steps:

1. **Fetch** – Downloads the target page or reads a local JSON/YAML token file.
2. **Extract** – Parses the source for hex color values (`#xxxxxx`) and font families.
3. **Map** – Assigns extracted colors to semantic roles using heuristics (most-used color becomes `accent`).
4. **Preview & Apply** – Generates a diff of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), prompts for approval, then writes the new tokens.

## Critical Constraints You Must Respect

The skill validates new tokens against hard rules defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) (lines 31–38). Violations block the onboarding:

| Constraint | Rationale |
|------------|-----------|
| **One accent only** – A single `accent` color may be defined. | Preserves visual hierarchy and focal signal. |
| **Contrast compliance** – `ink` must meet WCAG AA against `paper`; `muted` must meet AA for text ≥ 11px. | Guarantees legibility across diagram types. |
| **No rainbow palette** – Maximum three colors mapped to `paper`, `ink`, `accent`. Remaining colors become `muted` variants. | Prevents color overload in diagrams. |
| **Three typefaces retained** – `title`, `node-name`, and `sublabel` families must remain. | Maintains typographic rhythm. |

## How to Run Onboarding for Custom Brand Colors

### URL-Based Onboarding (Fastest)

Invoke the skill with your brand's website:

```bash
Onboard this skill to my site https://example.com

```

The skill executes the full pipeline: fetch, extract, map, preview, and apply. For manual preview before writing, use the **preview** command documented in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

### Token-File Onboarding (For Design Systems)

1. Prepare your JSON or YAML token file (e.g., `~/brand/tokens.json`).
2. Invoke the skill with the file path:

```bash
Onboard Schematic from my design system at ~/brand/tokens.json

```

The skill flattens nested tokens (e.g., `color.brand.primary.value`), applies the same mapping heuristics, and generates the diff.

### Manual Editing (Fallback)

If automatic extraction fails, edit [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) directly:

- Replace hex values in the token tables (lines 19–27).
- **Do not change token names** (`paper`, `ink`, `muted`, `accent`).
- Run the **taste-gate** validation to confirm constraints:

```bash
diagram-design validate

```

## Example: Swapping the Default Brand Palette

Given this brand palette:

| Brand token | Hex |
|-------------|-----|
| `primary` | `#1e90ff` (dodger-blue) |
| `secondary` | `#ff6f61` (coral) |
| `neutral` | `#f5f5f5` (warm-grey) |

Map to semantic roles in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md):

```markdown
| Role    | Purpose                   | Default (light) | New Value |
|---------|---------------------------|-----------------|-----------|
| `paper` | Page background, node fill| `#f5f5f5`       | `#f5f5f5` |
| `ink`   | Primary text / strokes    | `#2d3142`       | `#1e90ff` |
| `muted` | Secondary text / arrows   | `#4f5d75`       | `#ff6f61` |
| `accent`| Focal color               | `#eb6c36`       | `#ff6f61` |

```

Save, then validate:

```bash
diagram-design validate

```

## Key Files for Brand Color Onboarding

| File | Location | Purpose |
|------|----------|---------|
| [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) | [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Central token definition; edit for manual overrides |
| [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) | [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) | Detailed pipeline documentation (URL, Skill, Folder flows) |
| [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) | [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | User-facing command surface; triggers onboarding |
| `type-*.md` | [`skills/diagram-design/references/type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-process.md) (example) | Diagram specs that inherit tokens from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) |

## Summary

- **Custom brand colors** are added via the onboarding flow in diagram-design, which rewrites [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with extracted and mapped color tokens.
- **Three onboarding methods**: URL-based (fastest), token-file (for design systems), or manual editing with validation.
- **Four semantic roles** control the palette: `paper`, `ink`, `muted`, `accent` — all diagram types reference these automatically.
- **Hard constraints** enforce one accent, WCAG AA contrast, and limited palette size to maintain diagram clarity.

## Frequently Asked Questions

### What happens if my brand has more than three colors?

The onboarding heuristics select the three most dominant colors for `paper`, `ink`, and `accent`. Additional colors are mapped to `muted` variants or discarded. You can manually assign roles in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) if the automatic selection misses your preferred focal color.

### Can I use a CSS file instead of JSON/YAML for token-file onboarding?

The skill parses any file containing hex color values (`#xxxxxx`), including CSS, SCSS, or extracted design tokens. Place the file at a reachable path and invoke with `Onboard from ~/brand/styles.css`. The extraction layer is format-agnostic for color detection.

### Why does my new accent color fail the taste-gate validation?

The **taste-gate** enforces the **one accent** rule and **contrast compliance**. Confirm your `accent` doesn't appear in `ink` or `muted` roles, and verify `ink` against `paper` meets WCAG AA. Run `diagram-design validate` with verbose output to see specific failure reasons.

### Do I need to update individual diagram files after onboarding?

No. All diagram types ([`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md), [`type-journey.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-journey.md), etc.) reference semantic tokens from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). Once onboarding updates that file, every diagram automatically uses the new custom brand colors.