# How to Onboard a Brand from a Website URL into Diagram-Design > Effortlessly onboard a brand from a website URL into Diagram-Design. Our tool extracts visual styles automatically, creating branded diagrams in five stages for a seamless workflow. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-09-12 --- **Diagram-Design automatically extracts visual styles from any website URL to generate diagrams that match the site's branding through a structured five-stage pipeline involving page fetching, design token extraction, semantic mapping, diff preview, and skin application.** The cathrynlavery/diagram-design repository provides a comprehensive brand onboarding system that allows you to adopt the visual identity of any website. By processing a target URL through the onboarding pipeline defined in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), the tool extracts colors, typography, and design tokens to create a custom skin. This ensures all subsequent diagrams automatically reflect the extracted brand aesthetics without manual configuration. ## Understanding the Onboarding Architecture The URL onboarding process implemented in diagram-design follows a deterministic pipeline that transforms raw website assets into structured design tokens. According to the source specification in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), the system performs three primary operations: fetching the page and screenshot, extracting CSS-based design tokens, and updating the central style guide. The extraction logic prioritizes **CSS custom properties** (such as `:root { --accent: … }`) when available, falling back to `getComputedStyle` analysis or histogram-based color sampling from screenshots. This multi-layered approach ensures robust brand fidelity even when websites use complex rendering techniques or custom font hosting. ## Step-by-Step URL Onboarding Process ### Initiating the Onboarding Flow To begin onboarding a brand from a website URL, invoke the diagram-design skill with the target URL. The system accepts standard HTTPS URLs and initiates the extraction pipeline immediately. ```bash diagram-design onboarding https://example.com ``` Alternatively, you can fetch the page manually using the `agent-browser` tool before invoking the skill, which is the preferred method for complex JavaScript-heavy sites: ```bash agent-browser navigate https://example.com \ --screenshot site.png \ --html site.html ``` ### Fetching and Rendering the Target Page The skill uses `agent-browser` as its primary fetching mechanism, with plain `fetch` as a fallback for static content. This dual approach ensures compatibility with both server-rendered pages and dynamic single-page applications. The command downloads both the HTML source and a rendered screenshot, providing the raw material for token extraction. The fetched assets are processed according to the trust boundaries defined in [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py), which enforces security constraints and ensures the onboarding spec remains synchronized with the implementation. ### Extracting Colors and Fonts The extraction engine analyzes the rendered CSS and screenshot to identify six core semantic colors: - **`` background** maps to `paper` - **Primary text color** maps to `ink` - **Caption/secondary text** maps to `muted` - **Most-used brand color** (from CTAs, links, headings) maps to `accent` - **Container backgrounds** map to `paper-2` - **Border/hairline colors** map to `rule` (derived from `ink` with reduced opacity) For **typography**, the system extracts `font-family` values from three specific elements: `

` for titles, `` for node names, and `

` or `` elements for sublabels. The extraction records the exact family, weight, and source URL. However, only Google Fonts URLs matching the pattern `https://fonts.googleapis.com/css2` are permitted to carry into the final skin; custom-hosted fonts are marked as `fallback` to ensure portability.

### Mapping to Semantic Roles

Detected values are placed into a structured table of semantic roles (`paper`, `ink`, `muted`, `accent`, etc.) accompanied by confidence scores. The validation layer enforces accessibility and design standards:

- **AA contrast** requirements between `ink` and `paper`
- **Saturation checks** for `accent` colors to ensure vibrancy
- **Non-white paper** enforcement, falling back to `#fafaf7` if the source uses pure white

This mapping process ensures that extracted brand colors remain functional for diagram readability while preserving the original aesthetic.

### Previewing the Brand Diff

Before applying changes, the system generates a `git-style` diff of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) showing only the token table changes. This allows visual verification of the brand transformation.

```diff
- | `paper`  | `#f5f4ed` | `#1c1a17` |
- | `ink`    | `#0b0d0b` | `#f1efe7` |
- | `accent` | `#f7591f` | `#ff6a30` |
+ | `paper`  | `#f8f6f0` | `#1a1815` |
+ | `ink`    | `#111111` | `#efeee7` |
+ | `accent` | `#c73a2b` | `#e05440` |

```

A **brand fidelity receipt** accompanies the diff, listing the sampled URLs, detected hex values, font families, and any page-specific overrides applied during extraction.

### Applying the New Skin

Once validated, the system creates a recoverable snapshot of the original [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) before writing the diff. The [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file serves as the single source of truth for all colors, typography, and tokens within diagram-design, as specified in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md).

After application, regenerate example diagrams to verify the new appearance:

```bash
open assets/index.html

```

Or use the built-in regeneration command:

```bash
/regenerate-examples

```

## Managing Multiple Brand Profiles

After successfully onboarding a brand, you can persist the customized [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) as a named client profile. Projects containing a `.diagram-design` marker file with the property `profile: ` automatically load that profile, enabling multiple client brands to coexist without overwriting each other's configurations.

```bash
diagram-design save-profile my-brand

```

This profile management system, documented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), allows agencies and multi-brand teams to maintain distinct visual identities across different projects while using a single diagram-design installation.

## Summary

- **Diagram-Design** extracts brand identities from website URLs through an automated five-stage pipeline defined in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md).
- The **token extraction** process maps CSS properties and computed styles to semantic roles including `paper`, `ink`, `muted`, and `accent`, with validation for AA contrast and color saturation.
- **Font harvesting** captures typefaces from ``, ``, and `` elements, permitting only Google Fonts URLs (`https://fonts.googleapis.com/css2`) to ensure reliability.
- The **git-style diff preview** of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) allows visual verification before committing brand changes, accompanied by a detailed brand fidelity receipt.
- **Named profiles** enable persistence of multiple brand configurations via the `save-profile` command and `.diagram-design` marker files.

## Frequently Asked Questions

### How does diagram-design handle websites that use pure white backgrounds?

The onboarding pipeline enforces a non-white paper color requirement to ensure diagram readability. If the extraction detects a pure white (`#ffffff`) background on the source website, the system automatically falls back to `#fafaf7` for the `paper` token. This prevents eye strain while maintaining the warm aesthetic typical of diagram-design outputs.

### Can I use custom fonts that are not hosted on Google Fonts?

Custom-hosted fonts are detected during the extraction process but are marked as `fallback` in the final skin configuration. Only URLs matching the `https://fonts.googleapis.com/css2` pattern are permitted to carry into the production style guide. This restriction ensures that generated diagrams remain portable and render correctly across different environments without requiring access to private font servers.

### What happens if the contrast ratio between extracted colors fails accessibility standards?

The semantic role validation layer automatically checks for AA contrast compliance between `ink` (text) and `paper` (background) tokens. If the extracted values fail to meet the 4.5:1 ratio requirement, the system either adjusts the values slightly or flags the issue in the brand fidelity receipt. This ensures that onboarded brands remain legible in diagram outputs while preserving the intended visual hierarchy.

### Where are the brand configuration files stored after onboarding?

The active brand configuration is written to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) in the project root, which serves as the central token repository according to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). Before any modifications, the system creates a recoverable snapshot of the original file. Additionally, saved profiles are stored as named copies that can be referenced via the `profile` property in `.diagram-design` marker files, allowing rapid switching between client brands.