# How Design Tokens Are Extracted from a Website URL for Brand Onboarding in Diagram Design

> Learn how Diagram Design extracts design tokens like colors and fonts from a website URL. We map them to semantic tokens and verify WCAG AA contrast for efficient brand onboarding.

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

---

**The Diagram Design skill fetches a homepage, extracts CSS colors and fonts, maps them to semantic tokens like `paper` and `ink`, verifies WCAG AA contrast, and writes them to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) after user confirmation.**

When you onboard a brand with the `cathrynlavery/diagram-design` skill, the system automatically translates your live website’s visual style into a structured design-token system. This process ensures that every diagram generated afterward inherits your brand’s specific colors, typography, and accessibility standards without manual configuration.

## The Six-Step Onboarding Pipeline

The extraction logic is implemented in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) and executed through the skill’s entry point in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md). The pipeline follows six distinct phases:

### 1. Fetch the Homepage

The skill issues an **HTTP GET** request to the URL you provide (e.g., `https://yoursite.com`). This retrieves the raw HTML and CSS needed for downstream analysis.

### 2. Extract Visual Primitives

Once the page loads, the parser inspects the DOM and computed styles to capture:

- The `<body>` background color
- Primary text color
- Secondary or caption color
- The most-used brand color (detected from CTAs, links, or headings)
- Background colors of cards or containers
- Font families for `<h1>`, `<body>`, and `<code>` or `<pre>` elements

### 3. Map to Semantic Design Tokens

Detected values are assigned to **semantic roles** that the diagram system understands. The mapping follows this convention:

| Detected from Site | Becomes Token |
|--------------------|---------------|
| `<body>` background | `paper` |
| Primary text | `ink` |
| Secondary / caption text | `muted` |
| Cards or containers | `paper-2` |
| Most-used brand color (CTA, link, heading) | `accent` |
| `<h1>` font family | `title` font |
| `<body>` font family | `node-name` font |
| `<code>` / `<pre>` font | `sublabel` font |

### 4. Contrast Verification (WCAG AA)

Before persisting tokens, the skill checks **WCAG AA contrast** for `ink` (text) over `paper` (background). If the contrast fails at typical diagram font sizes (9–12 px), the system proposes a corrected color value and explains the adjustment to maintain accessibility compliance.

### 5. Write the Tokens to style-guide.md

Upon passing validation, the skill updates [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). This write operation produces a **fidelity receipt** that records:

- Sampled source URLs
- Exact color role assignments
- Font families and weights
- Font source URLs
- Fallback specifications

### 6. User Confirmation and Application

The skill renders a diff of proposed changes against the current token set. It waits for explicit confirmation (e.g., “yes, apply it”) before committing updates. Once accepted, all subsequent diagram renders use the onboarded brand system automatically.

## Running the Onboarding Process

You can trigger the pipeline through natural language or programmatic commands, depending on your host environment.

**Natural-language onboarding** (compatible with Claude Code, Codex, Factory Droid, Pi, or any skill host):

```text
onboard diagram-design to https://example.com

```

**Programmatic onboarding via slash command** (Pi example):

```bash
/diagram-design:onboard https://example.com

```

**Manual override** (for custom tweaks or preserving defaults):

```bash

# Open the style guide directly

open skills/diagram-design/references/style-guide.md

# Edit token values for paper, ink, accent, etc.

```

## Validating Applied Tokens

After onboarding, verify that generated diagrams respect the new token values using the self-check utility:

```bash
python3 skills/diagram-design/scripts/self_check.py path/to/diagram.html

# Expected output: OK

```

This script confirms that the rendered output references the semantic tokens defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) rather than hardcoded fallbacks.

## Key Files in the Onboarding Flow

- [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) — Complete specification of the URL-to-tokens extraction logic
- [`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 for color and font tokens; mutated during onboarding
- [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) — Skill entry point that routes onboarding requests to the reference implementation
- [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) — Validation utility to assert token compliance in generated output

## Summary

- The Diagram Design skill extracts **design tokens from a website URL** by fetching the homepage and parsing its CSS for colors and fonts.
- Extracted primitives map to semantic tokens: `paper`, `ink`, `muted`, `accent`, `paper-2`, plus font roles for `title`, `node-name`, and `sublabel`.
- The pipeline enforces **WCAG AA contrast** verification before writing tokens to prevent accessibility failures in small diagram text.
- Changes 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) along with a fidelity receipt, requiring user confirmation before activation.
- Use [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) to verify that diagrams respect the onboarded brand tokens.

## Frequently Asked Questions

### What design tokens does the Diagram Design skill extract from a website?

The skill extracts six core visual primitives: the `<body>` background maps to `paper`, primary text to `ink`, secondary text to `muted`, card backgrounds to `paper-2`, the dominant brand color to `accent`, and font families from `<h1>`, `<body>`, and `<code>` elements map to `title`, `node-name`, and `sublabel` respectively.

### How does the skill ensure accessible color contrast during onboarding?

Before writing to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), the system runs a WCAG AA contrast check between `ink` (text) and `paper` (background) specifically at 9–12 px font sizes common in diagrams. If the ratio fails, it suggests a corrected color and documents the adjustment to ensure readable output.

### Can I manually override the extracted design tokens?

Yes. After extraction, you can decline the proposed diff and manually edit [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). Alternatively, you can skip URL-based onboarding entirely and define tokens directly in that file, which serves as the single source of truth for the diagram system.

### Where are the onboarded brand tokens stored?

All token values persist in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) within your project. This file acts as a fidelity receipt, recording the sampled URLs, exact hex values, font families, weights, and any fallback definitions for future reference or auditing.