# How URL-Based Brand Onboarding Extracts and Applies Color Tokens

> Learn how URL-based brand onboarding analyzes a website's CSS to extract dominant colors, maps them to semantic tokens, and applies them to your diagrams automatically via style-guide.md.

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

---

**The Diagram-Design skill fetches a live website, analyzes its CSS to extract dominant brand colors, maps them to semantic tokens, and writes the results to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) so every diagram inherits the brand palette automatically.**

Diagram generation tools often struggle with brand consistency. The `cathrynlavery/diagram-design` repository solves this through an automated **URL-based brand onboarding** pipeline that scrapes a website's visual identity and transforms it into reusable design tokens. This article explains exactly how the system extracts raw color data and applies it to diagrams through five core semantic tokens.

---

## The Onboarding Pipeline Overview

The URL-based flow follows four sequential stages defined in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md):

1. **Fetch** the target website and its CSS assets
2. **Extract** color values using frequency analysis and name heuristics
3. **Map** discovered colors to standardized semantic tokens
4. **Persist** the results to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) for template consumption

Each stage includes specific implementation details that ensure reliable brand adoption without manual configuration.

---

## Fetching the Live Website

The onboarding entry point offers multiple input methods, with the **URL option** designed for live site analysis.

In [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), the URL method is documented as:

> "- [§ URL](#url) — fetch a live website"

This triggers an HTTP request to download the target page plus linked stylesheets. The skill parses both inline `<style>` blocks and external CSS files to build a complete color inventory.

---

## Extracting Color Tokens from CSS

Once assets are retrieved, the system applies **two complementary extraction strategies**:

### Frequency-Based Detection

The parser calculates which color appears most frequently on interactive elements. According to the source:

> "- **Most-used brand color** (CTA button, link, heading accent) → `accent`"

This heuristic assumes that brands consistently apply their primary color to high-priority UI elements. The dominant color becomes the canonical `accent` token.

### Name-Based Heuristics

For structured token systems, the parser scans CSS custom properties and JSON design-token files for semantic naming patterns. The mapping table collapses common brand vocabulary into the five core tokens:

| Input names | Output token |
|-------------|--------------|
| `accent`, `brand`, `primary`, `cta`, `highlight` | `accent` |

Additional heuristics apply to **Style Dictionary** formatted JSON:

> "If the JSON follows Style Dictionary format (`{ "color": { "brand": { "value": "#…" } } }`), flatten the path and apply heuristics to the leaf key."

This dual approach handles both ad-hoc CSS and enterprise-grade token systems.

---

## Mapping to Semantic Tokens

Raw extracted colors are normalized to a **fixed five-token palette** used across all diagram types:

- **`paper`** — background fills
- **`ink`** — primary text and strokes
- **`accent`** — brand color from frequency analysis
- **`muted`** — secondary/neutral tones
- **`link`** — hyperlink color

The mapping rules are hardcoded in the onboarding specification to ensure consistency. Once assigned, these values 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), which serves as the single source of truth for all diagram templates.

---

## Applying Tokens to Diagram Output

Diagram templates reference semantic tokens rather than hardcoded hex values. A typical SVG template might include:

```xml
<rect fill="var(--paper)" stroke="var(--ink)"/>
<path fill="var(--accent)"/>
<text fill="var(--link)"/>

```

During rendering, the templating engine substitutes `var(--accent)` with the brand-extracted value from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). Because every diagram pulls from this centralized file, **re-onboarding a new URL instantly updates all visual output** without template modifications.

---

## Practical Usage

Execute the full pipeline from the command line:

```bash

# Trigger URL-based onboarding for a target brand

diagram-design onboard --url https://example.com

# Generate a diagram using the extracted palette

diagram-design drawio architecture.drawio --type system

```

The first command populates [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with the analyzed colors. The second command renders a diagram where `accent`, `ink`, `paper`, and other tokens reflect the live website's visual identity.

---

## Summary

- **URL-based onboarding** downloads a live website and its CSS to analyze brand colors
- **Frequency analysis** identifies the dominant brand color for the `accent` token
- **Name heuristics** map common token vocabularies (`brand`, `primary`, `cta`) to semantic equivalents
- **Five semantic tokens** (`paper`, `ink`, `accent`, `muted`, `link`) standardize all diagram color usage
- **[`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)** persists the extracted palette, enabling instant brand consistency across all diagram templates

---

## Frequently Asked Questions

### What file stores the extracted color tokens after onboarding?

The [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) file receives the mapped color values. This file defines the semantic token structure and serves as the reference for all diagram templates during rendering.

### Does the system work with Style Dictionary JSON files?

Yes. The parser flattens nested Style Dictionary paths like `color.brand.value` and applies the same name-based heuristics to leaf keys. This ensures compatibility with enterprise design-token workflows without manual conversion.

### How does the system handle multiple candidate brand colors?

The frequency-based analyzer prioritizes colors appearing on CTA buttons, links, and heading accents. If multiple colors compete, the most dominant wins the `accent` assignment. Secondary brand colors typically map to `muted` or remain unassigned unless explicitly named in source tokens.

### Can I override extracted colors after onboarding?

Yes. Since [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is a plain markdown file, manual edits persist and immediately affect all subsequent diagram generation. The onboarding command is idempotent—re-running with a new URL replaces previous values, but hand-modified tokens can be preserved by commenting or versioning the file.