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

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 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.

# 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 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 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 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 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 lines 19-22.

Step 6: Generate the style-guide.md Diff

The proposed changes are formatted as a diff against 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 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:

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:

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 – 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 – The canonical token definition file that receives new color and font entries after successful onboarding.
• scripts/verify-doc-sync.py – Validation script that ensures the generated style-guide.md is syntactically correct and that downstream diagrams honor the new tokens.
• 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, 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. The system can also persist the configuration as a named client profile for rapid reuse across future diagram generation tasks.

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