# How to Onboard a Brand Using a Website URL in Diagram Design

> Automate brand onboarding with Diagram Design. Extract colors and typography from any website URL in a seven-stage flow, mapping to semantic design tokens. Streamline your design process.

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

---

**Diagram Design can automatically extract a brand's colors and typography from any live website URL through a seven-stage onboarding flow that maps detected values to semantic design tokens.**

Brand onboarding in Diagram Design eliminates manual theme configuration by letting the skill ingest a site's visual identity directly from its URL. This process, defined in [[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#url), enables users to generate on-brand diagrams with a single natural-language command.

## The Onboarding URL Method

The **URL method** drives the entire brand extraction pipeline. When invoked, the agent activates `agent-browser` or standard `fetch` to retrieve both the HTML source and a raster screenshot of the target site. This dual capture provides DOM-computed styles for precise parsing and pixel data for color histogram analysis when CSS extraction proves insufficient [onboarding.md § URL lines 52-58].

## Step-by-Step Onboarding Process

### 1. Invocation Trigger

Users initiate onboarding through natural language or explicit slash commands. The skill registers the target URL and begins the extraction sequence [README lines 48-60].

```text

# Natural-language invocation (Claude Code, Codex, or Pi)

onboard diagram-design to https://mybrand.com

# Explicit slash-command (Pi)

/diagram-design:onboard https://mybrand.com

```

### 2. Fetch and Analyze the Page

The agent downloads the complete HTML document and captures a viewport screenshot. This dual-source approach ensures robust extraction even when sites render content dynamically or obfuscate styles behind JavaScript [onboarding.md § URL lines 52-58].

### 3. Extract Colors and Fonts

**Color extraction** proceeds through a fallback hierarchy: CSS custom properties (`:root` variables) first, then computed styles via `getComputedStyle`, finally screenshot histogramming if needed. Detected values map to six semantic roles:

| Role | Source Element | Semantic Token |
|------|---------------|----------------|
| `paper` | `<body>` background | paper |
| `ink` | Primary text color | ink |
| `muted` | Caption/secondary text | muted |
| `accent` | Most-used brand color (CTA, links, headings) | accent |
| `paper-2` | Card/container backgrounds | paper-2 |
| `rule` | Borders and hairlines | rule |

**Font extraction** samples three key selectors: `<h1>` maps to `title`, `<body>` to `node-name`, and `<code>` or `<pre>` to `sublabel`. The agent preserves the exact font source—whether a Google Fonts URL, system stack, or custom `@font-face` declaration—through the "Exact-font gate" that carries forward provenance data for later rendering [onboarding.md § URL lines 68-95].

### 4. Validate Against Accessibility Standards

Extracted values undergo automated quality checks: **WCAG AA contrast verification** between `ink` and `paper`, `muted` and `paper`, plus saturation validation for the `accent` color. Failures trigger proactive adjustments with explanatory reasoning [onboarding.md § URL lines 115-122].

### 5. Preview the Brand Diff

The agent renders a [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) diff showing token replacements (e.g., `paper #f8f6f0 → ink #111111 → accent #c73a2b`) and outputs a **brand-fidelity receipt** documenting sampled URLs, detected roles, font families, weights, and source locations [onboarding.md § URL lines 27-34].

Preview without applying:

```text
/onboard-preview https://mybrand.com

```

### 6. Apply and Persist Changes

Upon confirmation, the skill writes validated tokens to [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md), first creating a recoverable `default` snapshot to enable rollback [onboarding.md § URL lines 56-60]. All subsequent diagrams automatically adopt the onboarded brand skin.

### 7. Save as Named Profile

Users may persist configurations as reusable profiles stored under `~/.diagram-design/profiles/`. Projects containing a `.diagram-design` marker referencing a profile name automatically inherit those brand tokens [onboarding.md § URL lines 30-33].

```text
/save-profile acme

```

## Verifying Onboarding Results

The repository includes [[`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) for post-onboarding validation. Run this utility to confirm generated diagrams honor the new tokens and meet contrast requirements.

## Summary

- **URL-based onboarding** in Diagram Design automatically extracts brand colors and typography from live websites
- The process maps detected values to **six semantic roles** (`paper`, `ink`, `muted`, `accent`, `paper-2`, `rule`) and **three font families** (`title`, `node-name`, `sublabel`)
- **WCAG AA contrast and saturation checks** validate extracted values before application
- **Recoverable snapshots** and **named profiles** enable safe experimentation and reusable brand configurations
- All token changes write to [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md), which diagrams reference at runtime

## Frequently Asked Questions

### What URL formats does Diagram Design support for brand onboarding?

Diagram Design accepts any HTTP or HTTPS URL reachable by the agent, including those requiring standard authentication. The extraction engine handles both server-rendered and client-rendered sites through its dual HTML-plus-screenshot capture strategy [onboarding.md § URL lines 52-58].

### How does the skill handle websites without CSS custom properties?

The fallback chain progresses from `:root` CSS variables to `getComputedStyle` values to screenshot histogramming. This ensures color extraction succeeds even on legacy sites or platforms that inline all styles [onboarding.md § URL lines 68-74].

### Can I revert to the default theme after onboarding?

Yes. The skill automatically creates a `default` snapshot before writing new tokens. Reference this snapshot in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) to restore original styling, or run the onboarding process again with a different URL [onboarding.md § URL lines 56-60].

### Does onboarding work with local development servers?

Yes, provided the agent can resolve the local URL. For localhost or private network addresses, ensure the agent environment has appropriate network access. The URL method does not distinguish between public domains and local servers [README lines 48-60].