# How to Onboard Diagram Design to a Website: The Complete Process

> Onboard Diagram Design to your website seamlessly. Automate color and typography extraction, map to design tokens, and ensure brand consistency with style-guide.md.

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

---

**Diagram Design automatically extracts your website's colors and typography, maps them to semantic design tokens, and writes them to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) to ensure every generated diagram matches your brand identity.**

The open-source [cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design) repository provides an automated onboarding system that enables the skill to adopt any website's visual style. When you onboard Diagram Design to a website, the process analyzes your site's HTML and CSS, validates accessibility compliance, and persists brand tokens for consistent diagram generation. This eliminates manual theme configuration and ensures WCAG AA contrast standards for diagram text.

## The Automated Onboarding Pipeline

The onboarding implementation defined in [`references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/onboarding.md) executes a seven-phase pipeline to capture and apply your brand identity.

### Step 1: Initiate Site Analysis

Trigger the onboarding flow by providing your website URL to the agent:

```bash
onboard diagram-design to https://example.com

```

The agent immediately fetches your homepage HTML and begins parsing the document structure and computed styles.

### Step 2: Extract Semantic Design Tokens

During extraction, the skill maps specific DOM elements and CSS properties to semantic tokens documented in the repository's README (lines 94-102). The parser locates:

- **`<body>` background** → `paper` token
- **Primary text color** → `ink` token  
- **Secondary/caption text** → `muted` token
- **Card-like containers** → `paper-2` token
- **Brand color (CTAs, links, headings)** → `accent` token
- **`<h1>` font family** → `title` font token
- **`<body>` font family** → `node-name` font token
- **`<code>` or `<pre>` font** → `sublabel` font token

### Step 3: Validate Accessibility Compliance

Before persisting values, the skill performs a WCAG AA contrast check between the extracted `ink` and `paper` tokens. If your site's colors fail contrast requirements for diagram-appropriate text sizes (9-12px), the system proposes corrected values with an explanation of the accessibility adjustment.

### Step 4: Review and Apply Changes

The agent displays a diff comparing the existing [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) against the new token values. Confirm the changes to write the tokens:

```bash
yes, apply it

```

Upon confirmation, the skill writes the brand-derived tokens to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) according to the specification in [`references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/onboarding.md).

### Step 5: Generate Branded Diagrams

After onboarding, every diagram request automatically uses your site's paper color, ink color, accent color, and typefaces. The system emits a "fidelity receipt" listing the exact source URLs, extracted colors, fonts, and any fallback values employed during generation.

## Working with Brand Profiles

For multi-client projects, you can save onboarding results as named profiles using the CLI commands defined in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md).

Save the current onboarding as a reusable profile:

```bash
/diagram-design:profile save acme

```

Reference the profile in other projects by creating a marker file:

```bash
echo "profile: acme" > .diagram-design

```

This allows you to maintain distinct brand identities across different websites without re-running the full onboarding flow.

## Manual Token Configuration

If you prefer direct editing over automated extraction, modify the token table in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) manually:

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

```

The file stores semantic tokens that drive all diagram styling decisions, including color values for `paper`, `ink`, `accent`, and font family definitions for `title`, `node-name`, and `sublabel` typography.

## Summary

- **Automated extraction**: The onboarding process fetches your website, parses HTML/CSS, and maps visual properties to semantic tokens like `paper`, `ink`, and `accent`.
- **Accessibility validation**: WCAG AA contrast checks ensure diagram text readability at small sizes (9-12px), with automatic corrections when necessary.
- **Persistent branding**: Approved tokens write to [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md), ensuring all subsequent diagrams inherit your brand identity.
- **Profile management**: Save onboarding results as named profiles via `/diagram-design:profile save` for multi-client workflows.
- **Fidelity tracking**: Each onboarding generates a receipt documenting exact source URLs, extracted values, and fallback logic.

## Frequently Asked Questions

### How long does the onboarding process take?

The complete onboarding flow requires approximately 60 seconds from initial command to final token application. This includes fetching the target URL, parsing styles, running contrast checks, and displaying the confirmation diff.

### What happens if my website colors fail accessibility contrast checks?

If the extracted `ink` and `paper` values fail WCAG AA compliance for diagram-appropriate text sizes, the skill automatically proposes accessibility-corrected values. The diff displays both your original colors and the adjusted values, explaining the specific contrast ratio improvements before you confirm application.

### Can I use different brand styles for different projects?

Yes. According to [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md), you can save any onboarding result as a named profile using `/diagram-design:profile save [name]`. Reference these profiles across projects using `.diagram-design` marker files, enabling distinct brand identities without re-onboarding each time.

### Where are the brand tokens stored after onboarding?

The system writes all extracted colors and fonts to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) within the repository. This file serves as the single source of truth for diagram styling, containing semantic tokens for background colors (`paper`, `paper-2`), text colors (`ink`, `muted`), accent colors, and typography definitions.