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

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 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. 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 and detailed in 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, 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 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, 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, 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. SVG elements, CSS custom properties, and the icon pipeline—illustrated in 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:

$ 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 fragment looks like this:

# 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:

<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	High-level description of the onboarding flow and token mapping
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	Central token store (semantic colour roles and font definitions) used by all diagram generators
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	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 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, while custom fonts are rejected by default.
• All validated tokens are persisted in 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 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. 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}