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

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 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 and executed through the skill’s entry point in 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. 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):

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

Programmatic onboarding via slash command (Pi example):

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

Manual override (for custom tweaks or preserving defaults):

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

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 rather than hardcoded fallbacks.

Key Files in the Onboarding Flow

• skills/diagram-design/references/onboarding.md — Complete specification of the URL-to-tokens extraction logic
• skills/diagram-design/references/style-guide.md — Single source of truth for color and font tokens; mutated during onboarding
• skills/diagram-design/SKILL.md — Skill entry point that routes onboarding requests to the reference implementation
• 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 along with a fidelity receipt, requiring user confirmation before activation.
• Use 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, 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. 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 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.

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