# How Brand Onboarding from a URL Extracts Design Tokens in diagram-design

> Learn how diagram-design brand onboarding extracts design tokens from a URL. It scans websites for colors and fonts, mapping them to semantic tokens for automatic brand inheritance in diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-19

---

**The `diagram-design` skill fetches a live website, scans its HTML and CSS for colors and fonts, maps the most-used values to semantic tokens like `accent` and `title`, and persists them into [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) so every generated diagram inherits the brand automatically.**

The `cathrynlavery/diagram-design` repository provides a skill that automates brand consistency by using **brand onboarding from a URL to extract design tokens**. When triggered, the system crawls the target page, extracts visual assets, and translates them into a semantic palette and typographic system stored in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). This eliminates manual style configuration and ensures that subsequent diagrams match the target brand without extra edits.

## The URL Onboarding Pipeline

### Fetching the Live Site

The process begins when the user supplies a URL to the onboarding command. According to the high-level flow described in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and detailed in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md), the skill issues an HTTP GET request to fetch the page content. The fetch logic is handled by utilities such as [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py), which is responsible for retrieving external resources before diagram generation.

### Parsing Colors from HTML and CSS

Once the page is retrieved, the skill examines the response for color definitions. It scans `<meta>` tags, inline `style` attributes, and linked stylesheets to identify hex and RGB values. The heuristic logic defined in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) prioritizes the most frequently used brand color—typically the call-to-action button or link color—and maps it directly to the semantic `accent` token. Secondary colors are matched to `brand`, `primary`, `cta`, or `highlight` based on their CSS variable names or usage context.

### Extracting Typography and Google Fonts

For typography, the parser looks for `<link rel="stylesheet">` elements pointing to `fonts.googleapis.com`. The exact family name, available weights, and stylesheet URL are copied into the style guide as the `title` or `body` token. As noted in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md), custom-hosted fonts are rejected unless explicitly approved, keeping the font pipeline predictable and license-safe.

### Mapping Values to Semantic Tokens

The extracted raw values are not stored as-is. Instead, they are translated into the repository’s semantic token system. The central token store, [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), defines roles such as `paper`, `ink`, `muted`, `accent`, and `link`. During onboarding, the skill runs a contrast check against the mapped colors, writes only the changed tokens, and pauses for user approval before committing updates.

### Generating the Fidelity Receipt

After a successful import, the skill emits a short fidelity receipt that lists the exact colors and fonts adopted. For example, it records that the most-used brand color `#eb6c36` was mapped to the `accent` token. This receipt is displayed in the preview panel so the user can verify brand capture accuracy before the tokens go live.

### Applying Tokens to Diagram Renders

All subsequent diagram generators read from the updated [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). SVG elements, CSS custom properties, and the icon pipeline—illustrated in [`scripts/build-icons.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/build-icons.py) through its use of `currentColor`—automatically inherit the onboarded palette and fonts. This means every new diagram render uses the brand colors without requiring manual CSS edits.

## Code Examples

The skill’s help output demonstrates the CLI flow:

```text
$ diagram-design onboard --source-url https://example.com
Fetching https://example.com …
Extracting colour palette …
  → most used colour #eb6c36 → token `accent`
  → secondary colour #2d3142 → token `brand`
Extracting fonts …
  → Google Font “Instrument Serif” (weights 400,600) → token `title`
Writing updated style-guide.md …
✅ Brand onboarding complete. See receipt:
  • accent: #eb6c36
  • brand:  #2d3142
  • title-font: Instrument Serif

```

After onboarding, the generated [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) fragment looks like this:

```markdown

# Style guide – brand-onboarded

## Colours

| Token   | Value   |
|---------|---------|
| accent | #eb6c36 |
| brand  | #2d3142 |
| paper  | #f5f5f5 |
| ink    | #2d3142 |
| muted  | #bfc0c0 |

## Fonts

| Role   | Family          | Weights |
|--------|-----------------|---------|
| title  | Instrument Serif| 400,600 |
| body   | Geist           | 400,500 |
| mono   | Geist Mono      | 400,500 |

```

Diagram templates consume the new tokens through CSS variables:

```html
<style>
  :root {
    --accent: #eb6c36;
    --brand:  #2d3142;
    --font-title: 'Instrument Serif', serif;
  }
</style>
<svg>
  <text style="fill: var(--accent); font-family: var(--font-title);">
    Branded Diagram Title
  </text>
</svg>

```

## Key Source Files

The following files define the complete URL-to-token pipeline in `cathrynlavery/diagram-design`:

| File | Role |
|------|------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | High-level description of the onboarding flow and token mapping |
| [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) | Detailed step-by-step guide for the URL method, including token extraction rules |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Central token store (semantic colour roles and font definitions) used by all diagram generators |
| [`scripts/build-icons.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/build-icons.py) | Icon pipeline that adopts `currentColor`, ensuring icons follow the brand palette once tokens are set |
| [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) | Handles fetching external resources (including URLs) before diagram generation |

## Summary

- The `diagram-design` skill fetches a target URL via HTTP and parses the returned HTML and CSS for visual assets.
- Color heuristics defined in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) map the most-used brand color to the `accent` token and secondary colors to semantic roles.
- Google Fonts are extracted from `<link>` tags and written into [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), while custom fonts are rejected by default.
- All validated tokens are persisted in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), which serves as the single source of truth for every diagram render.
- The icon pipeline in [`scripts/build-icons.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/build-icons.py) and SVG templates consume these tokens through `currentColor` and CSS variables, ensuring brand consistency automatically.

## Frequently Asked Questions

### What file stores the extracted design tokens after URL onboarding?

The 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). This file acts as the central style contract for the entire repository, defining semantic color roles and font families that all diagram generators read at render time.

### How does the skill determine which color becomes the `accent` token?

The onboarding logic in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) applies a frequency heuristic: the most-used brand color on the page—typically appearing on primary buttons or anchor links—is automatically mapped to `accent`. Secondary colors are assigned to `brand`, `primary`, `cta`, or `highlight` based on their CSS variable names or contextual usage.

### Can the skill use custom-hosted web fonts instead of Google Fonts?

No. The URL onboarding flow specifically looks for `<link>` tags pointing to `fonts.googleapis.com` and extracts those families and weights. Custom-hosted fonts are rejected unless explicitly approved by the user, keeping the typography pipeline consistent and license-safe.

### Which script handles the initial HTTP fetch for the onboarding URL?

The fetch operation is performed by utilities in [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py), which is designed to retrieve external resources before diagram generation. This same fetching infrastructure is reused when the onboarding command is invoked with a `--source-url` parameter.