# How URL-Based Brand Onboarding Works in Diagram Design

> Learn how diagram design uses URL based brand onboarding to automatically extract color palettes and typography from any website URL for branded diagrams. See the pipeline in action.

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

---

**Diagram Design’s URL-based brand onboarding automatically extracts color palettes and typography from any website URL to generate cohesive, branded diagrams through a deterministic fetch-extract-validate-apply pipeline.**

Diagram Design ships with a neutral “editorial” skin (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines) by default, but users can instantly align generated diagrams with corporate identity using the URL-based brand onboarding feature. This process, defined in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), treats fetched website data as untrusted visual signals and maps them to semantic design tokens stored in the style guide.

## The 8-Step Onboarding Pipeline

The URL-based onboarding flow follows a deterministic sequence from invocation to application, ensuring reproducible brand fidelity across all 39 diagram visual types.

### Step 1: Invocation and URL Parsing

The flow begins when a user invokes the onboarding command via CLI or conversational agent. According to [[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L27), the skill parses commands like `onboard diagram-design to https://example.com` and initializes the brand extraction pipeline.

### Step 2: Fetching Untrusted Page Data

The skill uses the built-in `agent-browser` (or a plain `fetch`) to download the HTML and a screenshot of the target site. As specified in [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 52-61](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L52-L61), this data is explicitly treated as **untrusted** and is used solely for visual signal extraction, never for executable code or configuration.

### Step 3: Extracting Colors and Fonts

From the rendered CSS and screenshot, the skill derives specific design tokens:

- **paper** – Background color of `<body>`
- **ink** – Primary text color
- **muted** – Secondary or caption color
- **accent** – Most-used brand color (CTA, links)
- **rule** – Border or hairline color
- **title**, **node-name**, **sublabel** – Font families for headings, body text, and code elements

This extraction logic is documented in [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 70-86](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L70-L86).

### Step 4: Mapping to Semantic Roles

The extracted raw tokens are matched to the **semantic roles** defined in the design system (`paper`, `ink`, `muted`, `accent`, `rule`, etc.). During this phase, as detailed in [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 103-112](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L103-L112), the system builds a confidence table that allows users to correct low-confidence guesses before proceeding.

### Step 5: Automated Validation

Before writing any changes, the skill performs safety checks defined in [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 217-224](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L217-L224):

- **AA contrast** validation for `ink` on `paper` and `muted` on `paper`
- **Saturation check** ensuring `accent` is the most saturated color
- **Warm neutral fallback** if `paper` is pure white (prevents sterile output)

If any check fails, the system proposes corrected values rather than rejecting the input entirely.

### Step 6: Diff Preview and Brand Fidelity Receipt

The system generates a unified diff showing proposed changes to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), accompanied by a **brand fidelity receipt** listing detected URLs, exact color values, font families, and extraction sources. This transparency step, covered in [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 30-41](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L30-L41), ensures users understand exactly what visual data drives the new palette.

### Step 7: Application and Profile Persistence

After user approval, the diff is written to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), becoming the single source of truth for subsequent diagrams. The skill optionally saves the configuration as a named client profile at `~/.diagram-design/profiles/<slug>.md` for future reuse, as noted in [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 56-62](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L56-L62).

### Step 8: Post-Onboarding Verification

Users can open the gallery at [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html) to verify that all 39 visual types respect the new palette. If adjustments are needed, users can manually tweak specific roles in the style guide and re-run the onboarding process to refine the extraction.

## Command-Line Interface

The URL-based brand onboarding exposes intuitive CLI commands for both initial setup and profile management:

```bash

# Initialize onboarding from a corporate website

diagram-design onboard https://mycompany.com

# Confirm the proposed changes after diff review

yes

# Save the configuration as a reusable profile

diagram-design save-profile acme

# Generate a diagram using the onboarded brand tokens

diagram-design draw flowchart my-flow.mmd

```

The same flow integrates with conversational AI agents (Claude or OpenAI), where natural language prompts like "Onboard diagram-design to https://example.com" trigger the identical pipeline with interactive approval steps.

## Core Source Files and Trust Boundaries

The onboarding architecture relies on specific files that enforce safety guarantees and data integrity:

- **[[`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)**: Complete specification of URL-based and alternative onboarding pipelines.
- **[[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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 receiving validated brand tokens.
- **[[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L165-L172)**: Entry point documentation linking to onboarding spec and gating behavior.
- **[[`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)](https://github.com/cathrynlavery/diagram-design/blob/main/README.md#L188-L242)**: User-facing feature overview and high-level concepts.
- **[`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py)**: Trust-boundary enforcement ensuring [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) fetches remote content safely.

## Summary

- **URL-based brand onboarding** converts any website into a diagram-compatible design system through an automated eight-step pipeline.
- The process extracts **semantic tokens** (paper, ink, accent, muted, rule) from CSS and screenshots, treating all fetched data as untrusted.
- **Automated validation** enforces AA contrast ratios and prevents pure-white backgrounds, proposing corrections when standards are missed.
- Changes are previewed via unified diffs and **brand fidelity receipts** before being committed to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).
- Users can persist brand configurations as named profiles in `~/.diagram-design/profiles/` for consistent reuse across projects.
- The gallery at [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html) provides immediate visual verification across all 39 diagram types.

## Frequently Asked Questions

### What happens if the target website uses custom fonts or a dark-mode-first design?

If the site uses custom-hosted fonts that cannot be resolved, or presents a dark-mode-first palette that conflicts with the default light-mode assumptions, the onboarding flow falls back to sensible defaults from the editorial skin. As documented in the “When URL onboarding fails” section of [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), the system informs the user which manual adjustments are needed to complete the brand mapping.

### How does the system ensure accessibility compliance during brand extraction?

The validation step explicitly checks for **AA contrast ratios** between `ink` and `paper`, and between `muted` and `paper`, as implemented in [[`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 217-224](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L217-L224). If extracted colors fail these checks, the system generates corrected values that meet accessibility standards before presenting the final diff to the user.

### Can I revert to the default editorial skin after onboarding a brand?

Yes. Since the onboarding process writes changes to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), you can revert by restoring the original neutral values (white-smoke paper, jet-black ink, atomic-tangerine accent) or by deleting the active profile in `~/.diagram-design/profiles/`. The system will automatically fall back to the baseline editorial skin when no custom tokens are detected, as gated by the logic in [[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L165-L172).

### Where are the extracted brand artifacts stored locally?

After approval, brand tokens are written 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. Additionally, users may save named profiles to `~/.diagram-design/profiles/<slug>.md`, creating portable, reusable brand configurations that can be applied to future diagram generation sessions without re-fetching the source URL.