# How to Onboard a Custom Brand Palette to Diagram‑Design: A Complete Step‑by‑Step Guide

> Easily onboard a custom brand palette to Diagram-Design. This guide shows how to use the built-in flow to extract colors and fonts, map them to tokens, and update your style guide.

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

---

**Onboard a custom brand palette to Diagram‑Design by feeding a URL to the built‑in onboarding flow, which extracts colors and fonts, maps them to semantic tokens, and writes the result to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md).**

Diagram‑Design stores every visual decision—colors, typography, contrast ratios—in a single source‑of‑truth file. The onboarding system automates the process of aligning those tokens with your corporate brand, whether that brand lives on a public website, in another installed skill, or in a local design folder. This guide walks through the canonical URL‑based workflow and shows how to save the result for reuse across projects.

## What Happens During Onboarding

The onboarding flow in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) executes a five‑step pipeline that transforms raw design inputs into semantic tokens.

### Step 1: Fetch the Target URL

The skill retrieves the page using either `agent-browser` or a plain `fetch`. No authentication is required for public marketing sites; authenticated flows are supported via environment variables passed to the browser agent.

### Step 2: Extract Colors and Fonts

The system parses the rendered CSS and a full‑page screenshot to detect:

- **Dominant background and text colors** (sampling algorithm described in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) § Step 2)
- **Font families** from `<h1>`, `<body>`, and `<code>`/`<pre>` elements

Extraction runs against the live DOM, so dynamic CSS—CSS‑in‑JS, injected stylesheets, or variable‑driven themes—is captured accurately.

### Step 3: Map to Semantic Roles

Detected values are assigned to the nine semantic roles defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md):

| Token | Typical Use |
|-------|-------------|
| `paper` | Canvas background |
| `ink` | Primary text |
| `muted` | Secondary labels |
| `accent` | Highlights, connections |
| `paper-2` | Alternate surface (cards, panels) |
| `rule` | Borders, dividers |
| `title` | Diagram titles |
| `node-name` | Entity labels |
| `sublabel` | Metadata, captions |

The mapping logic prefers high‑contrast pairings and falls back to WCAG‑AA‑safe defaults when the extracted palette fails automated contrast checks.

### Step 4: Preview the Diff

Before any write occurs, the skill renders a diff of the proposed changes to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) alongside a **brand‑fidelity receipt**. The receipt lists:

- Sampled URLs and page regions
- Extracted hex values (light and dark variants)
- Font family declarations
- Contrast adjustments applied automatically

Review this in your terminal or IDE; the flow pauses for explicit user consent.

### Step 5: Apply to Style Guide

Once confirmed, the diff is committed to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). The system preserves the previous token set as a default snapshot, enabling one‑command rollback:

```bash
diagram-design restore-default-skin

```

### Step 6: Save as a Named Profile (Optional)

To reuse this brand configuration elsewhere, persist it to the profile library:

```text
You: "save onboarding result as profile acme"

```

The profile writes to `~/.diagram-design/profiles/acme.md`. Future projects activate it by adding a `.diagram-design` marker file containing:

```yaml
profile: acme

```

## Running the Onboarding Flow

### Quick Start: Natural Language Invocation

```text

# Single command from any Diagram‑Design host

You: "onboard diagram-design to https://mycompany.com"

```

The skill handles fetch, extract, map, preview, and apply automatically. Total runtime is typically 15–30 seconds for a standard marketing site.

### Manual Path: Direct Style‑Guide Editing

For precise control or air‑gapped environments, edit [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) directly:

```bash

# Clone the repository

git clone https://github.com/cathrynlavery/diagram-design.git
cd diagram-design

# Open the token table for editing

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

```

The file contains a markdown table with columns for token name, light‑mode value, and dark‑mode value. Modify rows in place; no rebuild step is required.

## Example Diff Output

Below is an excerpt from a brand‑onboarding preview, showing the transformation applied to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md):

```diff
- | `paper` | `#f5f4ed` | `#1c1a17` |
- | `ink`   | `#0b0d0b` | `#f1efe7` |
- | `accent`| `#0056b3` | `#4aa3f5` |
+ | `paper` | `#f8f6f0` | `#1a1815` |
+ | `ink`   | `#111111` | `#efeee7` |
+ | `accent`| `#c73a2b` | `#e05440` |

```

The `accent` shift from blue to red reflects the extracted primary brand color from `https://mycompany.com`. Dark‑mode values are derived automatically using perceptual lightness scaling.

## Verifying the Result

Confirm the new palette across all 39 diagram types by opening the built‑in gallery:

```bash

# macOS

open skills/diagram-design/assets/index.html

# Linux

xdg-open skills/diagram-design/assets/index.html

```

The gallery renders every diagram variant with live tokens from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). Scroll to check contrast on complex flows (sequence diagrams, architecture maps) where `accent` and `paper-2` interact frequently.

## Alternative Source Types

While URL onboarding is most common, the system supports two additional entry points defined in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md):

- **Installed skill**: Reference another Diagram‑Design skill that exports a `BrandSpec` interface
- **Local folder**: Point to a directory containing [`tokens.json`](https://github.com/cathrynlavery/diagram-design/blob/main/tokens.json), [`variables.css`](https://github.com/cathrynlavery/diagram-design/blob/main/variables.css), or Figma‑exported JSON

Both follow the same extract‑map‑preview‑apply pipeline, differing only in the initial input parser.

## Key Implementation Files

| File | Responsibility |
|------|---------------|
| [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) | Complete specification of fetch, extract, map, preview, and apply stages; covers URL, Skill, and Folder source types |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Single source‑of‑truth for semantic tokens (`paper`, `ink`, `accent`, etc.); rewritten in Step 5 |
| [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) | Profile storage format, loading semantics, and `.diagram-design` marker syntax |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Entry point declaring the `onboard` command and wiring it to the execution gate |
| [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html) | Visual regression suite for all 39 diagram types; hot‑reloads [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) on refresh |

## Summary

- **Onboard a custom brand palette to Diagram‑Design** by invoking the natural‑language command or running the five‑step pipeline manually.
- The flow targets [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), the sole file controlling every diagram's appearance.
- Extraction runs against live CSS and screenshots, capturing dynamic themes accurately.
- WCAG‑AA contrast checks block low‑confidence writes; a brand‑fidelity receipt documents every decision.
- Save successful onboardings as named profiles in `~/.diagram-design/profiles/` for cross‑project reuse.
- Verify changes instantly in [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html), which renders all 39 diagram types with live tokens.

## Frequently Asked Questions

### Can I onboard from a private site behind authentication?

Yes. Pass credentials via environment variables consumed by `agent-browser`, or download the site locally and use the Folder source type. The extraction engine does not store credentials; they exist only in the ephemeral browser session.

### What happens if the extracted colors fail contrast checks?

The pipeline flags failing pairs in the brand‑fidelity receipt and applies automatic adjustments—usually lightness shifts of ±10%—to reach WCAG‑AA compliance. You may override these suggestions before the final apply step.

### How do I restore the original default skin?

Run `diagram-design restore-default-skin`. This command swaps [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with the default snapshot preserved during the most recent onboarding. Profiles remain intact; restoring defaults does not delete saved profiles.

### Can multiple profiles coexist in one project?

No. A project references exactly one profile via its `.diagram-design` marker. To composite brands, manually merge token tables in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and save the result as a new named profile.