How URL-Based Brand Onboarding Extracts and Applies Color Tokens

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

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 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, the URL method is documented as:

"- § 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, 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:

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

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

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