# How to Onboard Your Brand to Diagram-Design Using a Website URL: A Complete Guide

> Onboard your brand to Diagram-Design by providing a URL. The tool extracts palettes, typography, maps to tokens, verifies contrast, and generates a style guide.

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

---

**You can onboard diagram-design to your brand by providing a website URL, and the tool will automatically extract color palettes and typography, map them to semantic design tokens, verify contrast accessibility, and write a ready-to-use style guide.**

This guide walks through the **onboarding flow** implemented in the [cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design) repository. Whether you're working with Claude, Pi, or another compatible agent, the process remains consistent: fetch, extract, verify, and persist your brand's visual identity.

## Onboarding Flow Overview

The onboarding system lives in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) and is invoked through [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) when the agent detects an "onboard" intent. The flow consists of five sequential steps.

### 1. Trigger Onboarding with a URL

Initiate the process by specifying your brand's homepage:

```text
You: onboard diagram-design to https://yoursite.com

```

The agent fetches the page, parses HTML/CSS, and extracts the **dominant color palette** and **font stack**. This extraction logic is described in the README at lines 48-55.

### 2. Map Extracted Values to Semantic Tokens

Raw colors and fonts are mapped to six **semantic roles** used across all 27 diagram types:

| Token | Typical Source | Usage |
|-------|--------------|-------|
| `paper` | Page background | Diagram canvas background |
| `ink` | Body text color | Primary labels and lines |
| `muted` | Secondary text | Subtle annotations |
| `accent` | CTA/button colors | Highlights and key flows |
| `link` | Anchor link color | Connection indicators |
| `paper-2` | Alternate background | Contrast sections |

The mapping logic is documented in README lines 56-64.

### 3. Verify WCAG AA Contrast

Before writing tokens, the system runs a **contrast check** on `ink` over `paper` at diagram font scales (9-12px). If contrast fails, the skill proposes adjusted colors with an explanation. This accessibility guardrail appears in README lines 78-81.

### 4. Write the Style Guide

Approved tokens are persisted to:

```

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

```

This file serves as the **single source of truth** for all diagram renders. Inspect it anytime to see your brand values:

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

```

### 5. Save as a Reusable Profile (Optional)

Create a named profile for multi-brand workflows:

```bash
/prompt "save profile acme"

```

Profiles are stored in `~/.diagram-design/profiles/<slug>.md` and referenced via project markers:

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

```

This mechanism is explained in README lines 98-101.

## Code Examples by Interface

### Claude Code (or Claude-Compatible Agents)

```text
You: onboard diagram-design to https://example.com
Agent: → fetches the homepage
       → extracts palette + fonts
       → shows a proposed diff
       → writes tokens to references/style-guide.md
You: yes, apply it

```

### Pi (CLI-Style Interface)

```bash

# Initiate onboarding

/prompt "onboard diagram-design to https://example.com"

# Confirm after reviewing the diff

/prompt "yes, apply it"

# Save for reuse

/prompt "save profile acme"

```

### Using a Saved Profile in a New Project

```bash

# Add marker file to project root

echo "profile: acme" > .diagram-design

# Subsequent diagrams automatically use Acme branding

/prompt "Make me an architecture diagram of my SaaS platform"

```

## What Happens After Onboarding

Every new diagram inherits your brand identity automatically:

- **Background color** → `paper` token → diagram canvas
- **CTA color** → `accent` token → highlights and flows
- **Body font stack** → node labels and annotations

The skill emits a **fidelity receipt** documenting sampled URLs, exact color values, font families, and source URLs for full traceability (README lines 61-64).

## Key Files and Their Roles

| File | Purpose |
|------|---------|
| [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) | Detailed specification of URL-to-tokens flow, color extraction, and contrast handling |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Semantic color and font tokens driving all 27 diagram types |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Core entry point; loads onboarding reference on intent detection |
| `~/.diagram-design/profiles/*.md` | Saved brand profiles for cross-project reuse |
| [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) (lines 42-64, 78-81, 98-101) | User-facing onboarding documentation |

## Summary

- **Onboard with a single command**: Provide any website URL to extract brand colors and fonts
- **Semantic mapping**: Six tokens (`paper`, `ink`, `muted`, `accent`, `link`, `paper-2`) cover all diagram needs
- **Built-in accessibility**: WCAG AA contrast verification prevents unreadable combinations
- **Centralized style guide**: [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) controls every diagram render
- **Profile persistence**: Save and switch brands via `~/.diagram-design/profiles/` and `.diagram-design` markers

## Frequently Asked Questions

### What if my website uses multiple color schemes?

The onboarding process samples the **homepage only** and extracts the dominant palette. For multi-scheme brands, manually edit [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) after initial extraction, or create separate profiles for light/dark variants using the `save profile <name>` workflow.

### Can I override individual tokens without re-onboarding?

Yes. Directly modify [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). The file uses plain markdown with token definitions; changes take effect immediately on the next diagram generation without requiring a new onboarding session.

### Does the contrast check cover all token combinations?

No. The system specifically verifies `ink` over `paper` at small font sizes (9-12px), which is the most critical readability threshold for diagram labels. Other combinations are not automatically validated—review your style guide manually if accessibility is paramount.

### What happens if the URL fetch fails or returns no extractable styles?

The skill will report the failure and fall back to default tokens. You can then either retry with a different URL, provide a direct link to a CSS file, or manually configure [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) based on brand guidelines.