# How Diagram Design Extracts Tokens from a Website URL for Brand Onboarding

> Diagram Design extracts website color and typography tokens for brand onboarding. It renders pages, maps CSS to roles, validates against WCAG AA, and generates style guide diffs.

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

---

**Diagram Design extracts color and typography tokens from any live website by rendering the page, mapping computed CSS values to semantic roles like paper, ink, and accent, and validating the results against WCAG AA constraints before generating a diff for the style guide.**

Diagram Design automates brand matching by pulling design tokens directly from live URLs. According to the `cathrynlavery/diagram-design` source code, 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) executes a deterministic six-step process to transform a website's visual identity into reusable diagram themes. This entire workflow completes in roughly 60 seconds and automatically colors all 39 diagram types shipped with the tool.

## The 6-Step Token Extraction Pipeline

### Step 1: Fetch the Page with agent-browser

The pipeline begins by obtaining the HTML and a visual screenshot of the target site. The preferred tool is **`agent-browser`**, which renders the full DOM including JavaScript-generated content. If this tool is unavailable, the system falls back to a plain HTTP fetch.

```bash

# Obtain the rendered HTML and a screenshot of the target site

agent-browser navigate https://example.com \
  --screenshot out.png \
  --html out.html

```

*Source reference:* [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) lines 48-53.

### Step 2: Extract Color Tokens from Computed CSS

Once the page is rendered, Diagram Design inspects the computed CSS—including custom properties—and analyzes the screenshot histogram to identify the most salient colors. These raw values are mapped to semantic tokens according to the following deterministic rules:

- **`<body>` background** → `paper`
- **Primary body text color** → `ink`
- **Secondary text/metadata color** → `muted`
- **Dominant brand accent** (e.g., CTA or link color) → `accent`
- **Card-background or slightly darker panel** → `paper-2`
- **Border/hairline color** → `rule` (converted to a low-opacity ink)

*Source reference:* Colour mapping table in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 68-73.

### Step 3: Capture Typography from Key Elements

The system reads the rendered `font-family` stacks from three critical element types to establish the type scale:

- **`<h1>` elements** → **`title`** family
- **`<body>` text** → **`node-name`** family
- **`<code>` or `<pre>` elements** (monospaced text) → **`sublabel`** family

If a specific role cannot be detected, the pipeline retains schematic defaults: *Instrument Serif* for titles and *Geist Mono* for monospaced text.

*Source reference:* Font extraction description in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 78-84.

### Step 4: Map Raw Values to Semantic Roles

Detected colors and fonts are inserted into a provisional token table (including `paper`, `ink`, `muted`, `accent`, etc.) with confidence flags attached to each entry. This table is presented to the user for review before any changes are committed.

*Source reference:* "Propose a diff" table in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 101-108.

### Step 5: Validate Accessibility and Constraints

Before finalizing the new skin, the pipeline enforces strict design constraints:

1. **WCAG AA contrast** must pass for the `ink`/`paper` pairing.
2. The **accent color** must be the most saturated token in the set.
3. If the site uses pure white (`#FFFFFF`), the system suggests a fallback warm-neutral white to reduce eye strain.

*Source reference:* Constraint checks in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 19-22.

### Step 6: Generate the style-guide.md Diff

The proposed changes are formatted as a diff against [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). Upon user approval, the new tokens are written to the canonical style guide and optionally saved as a named client profile for future reuse.

*Source reference:* Diff preview and apply steps in [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md) lines 27-33.

## Implementation Examples

The following examples demonstrate how to replicate the extraction logic in your own scripts.

### Fetching and Parsing Custom Properties

This Python snippet mimics the color extraction step using `requests` and `beautifulsoup4` to scrape CSS custom properties:

```python
import requests
from bs4 import BeautifulSoup
import re

def get_root_styles(url):
    resp = requests.get(url, timeout=10)
    soup = BeautifulSoup(resp.text, "html.parser")
    # Look for CSS custom properties in :root

    style_tags = soup.select("style")
    props = {}
    for tag in style_tags:
        for line in tag.string.splitlines():
            m = re.search(r'--([^:]+):\s*([^;]+);', line)
            if m:
                props[m.group(1).strip()] = m.group(2).strip()
    return props

# Example usage

props = get_root_styles("https://example.com")
print("Found custom properties:", props)

```

### Mapping Colors to Semantic Tokens

This pseudo-code illustrates the logic used internally to map extracted palette values to the Diagram Design token schema:

```python
def map_colors(palette):
    tokens = {}
    tokens["paper"]   = palette["background"]
    tokens["ink"]     = palette["body_text"]
    tokens["muted"]   = palette["caption_text"]
    tokens["accent"]  = palette["brand_accent"]
    tokens["paper-2"] = palette.get("card_background", darken(palette["background"]))
    tokens["rule"]    = rgba(palette["ink"], 0.12)
    return tokens

```

## Key Files in the Onboarding System

The extraction process is coordinated across several critical files in the repository:

- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)** – Contains the full specification for URL-based onboarding, including the six-step pipeline, color/font extraction rules, and validation logic.
- **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)** – The canonical token definition file that receives new color and font entries after successful onboarding.
- **[`scripts/verify-doc-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-doc-sync.py)** – Validation script that ensures the generated [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is syntactically correct and that downstream diagrams honor the new tokens.
- **[`commands/onboard.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/onboard.md)** – User-facing command documentation that invokes the URL onboarding process.

## Summary

- **Diagram Design** uses `agent-browser` to fetch live HTML and screenshots from target URLs.
- Colors are extracted from computed CSS and mapped to semantic roles: `paper`, `ink`, `muted`, `accent`, `paper-2`, and `rule`.
- Typography is captured from `<h1>`, `<body>`, and `<code>` elements to define `title`, `node-name`, and `sublabel` families.
- All extracted tokens are validated for WCAG AA contrast and saturation requirements before deployment.
- The final output is a diff applied to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), which skins all 39 diagram types in approximately 60 seconds.

## Frequently Asked Questions

### What tool does Diagram Design use to fetch website HTML during onboarding?

Diagram Design prefers the **`agent-browser`** command-line tool to navigate the target URL, capture a screenshot, and save the rendered HTML. If `agent-browser` is unavailable, the pipeline automatically falls back to a standard HTTP fetch request.

### Which CSS properties map to the "paper" and "ink" tokens?

The **`paper`** token is derived from the computed background color of the `<body>` element, while the **`ink`** token is sourced from the primary text color applied to body text. These represent the base canvas and primary content color for all generated diagrams.

### How does Diagram Design validate extracted color tokens?

The pipeline runs three constraint checks: it verifies **WCAG AA contrast** ratios between `ink` and `paper`, ensures the `accent` color is the most saturated token in the set, and suggests a warm-neutral fallback if the site uses pure white (`#FFFFFF`).

### Where are the extracted tokens stored after onboarding?

Once validated and approved by the user, 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)**. The system can also persist the configuration as a named client profile for rapid reuse across future diagram generation tasks.