How the Diagram‑Design Brand Onboarding Workflow Extracts Design Tokens from a Website URL

The diagram‑design brand onboarding workflow is a declarative pipeline that scrapes a live website’s rendered CSS, computed styles, and screenshot to extract semantic color and typography tokens, validates them for AA contrast compliance, and writes the results into references/style-guide.md to brand‑match all 27 diagram types.

The open‑source cathrynlavery/diagram-design repository provides an AI‑powered skill for generating diagrams that adapt to any visual identity. The workflow defined in references/onboarding.md implements a URL‑driven extraction engine that transforms arbitrary websites into structured design systems. By combining browser automation with CSS analysis, the pipeline maps raw visual properties into semantic roles—paper, ink, accent, and rule—that drive every subsequent visualization.

Step 1 – Invocation and Page Fetching

The extraction process begins when a user issues a natural‑language command such as “Onboard diagram‑design to my site — https://example.com”【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L44-L49】. The skill routes this request to the URL branch of the onboarding flow, triggering an automated capture sequence.

The workflow first retrieves the target page using the built‑in agent-browser tool, which downloads both the raw HTML and a full‑page screenshot【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L52-L58】. If the browser tool is unavailable, the pipeline falls back to a standard fetch operation to obtain markup. This dual‑mode capture ensures the extractor can analyze both DOM structure and rendered pixel data.

# Using the built-in browser tool

agent-browser navigate https://example.com --screenshot out.png --html out.html

Step 2 – Extracting Semantic Color Tokens

Once the page is captured, the pipeline derives six core color tokens from the rendered output. The extractor first scans for CSS custom properties (e.g., :root { --accent: #f7591f }) and, if none are found, falls back to getComputedStyle values or a color‑histogram analysis of the screenshot【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L66-L74】.

The specific semantic mappings are:

• paper – background-color of the <body> element
• ink – Primary text color (highest contrast against paper)
• muted – Caption or meta text color (secondary opacity)
• accent – Most frequently used brand color (CTA buttons, links, headings)
• paper‑2 – Card or elevated surface background
• rule – Border or hairline color (derived from ink tint)【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L66-L74】

The extractor assigns a confidence score to each detection based on usage frequency and CSS specificity, flagging low‑confidence entries for user confirmation【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L101-L110】.

Step 3 – Harvesting Typography Tokens

Parallel to color extraction, the workflow inspects the computed font-family of three semantic HTML elements to build a type hierarchy【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L77-L84】:

1. Title – Derived from the first <h1> tag
2. Node‑name – Derived from the <body> element (primary interface text)
3. Sublabel – Derived from <code> or <pre> blocks (monospace annotations)

The extractor records the exact family name and font weight. A verification step then checks availability against Google Fonts or the local system font stack, substituting a compatible fallback if the detected typeface is not web‑safe【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L90-L95】.

Step 4 – Validation and Constraint Checking

Before persisting any tokens, the pipeline enforces design constraints to ensure accessibility and visual coherence【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L115-L122】:

• Contrast validation – All text colors must meet WCAG AA standards against their respective backgrounds
• Accent saturation guard – The accent color must be the most saturated hue in the palette to maintain brand prominence
• Pure‑white prevention – If paper is detected as #ffffff, the workflow substitutes a warm neutral to reduce eye strain

Low‑confidence detections from the role table are surfaced in the UI for manual override before proceeding.

Step 5 – Previewing and Applying the Token Update

The workflow generates a unified diff of references/style-guide.md showing only the token table changes【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L27-L30】【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L31-L39】. This preview includes a brand fidelity receipt listing sampled URLs, final hex values, and detected font families.

-| `paper`  | `#f5f4ed` | `#1c1a17` |
-| `ink`    | `#0b0d0b` | `#f1efe7` |
-| `accent` | `#f7591f` | `#ff6a30` |
+| `paper`  | `#f8f6f0` | `#1a1815` |
+| `ink`    | `#111111` | `#efeee7` |
+| `accent` | `#c73a2b` | `#e05440` |

Upon user approval, the new tokens are written into references/style-guide.md. The skill optionally creates a recoverable “default” snapshot before overwriting the pristine file【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L54-L58】. Subsequently, all 27 diagram types automatically pull the updated tokens, achieving brand‑matched output across the entire library【/cache/repos/github.com/cathrynlavery/diagram-design/main/README.md#L44-L45】.

Users can verify the integration by opening the visual gallery:

open assets/index.html

Optionally, the workflow can save the customized skin as a named client profile in references/profiles.md, enabling project‑scoped branding without affecting other workspaces【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L304-L307】.

Summary

• The diagram‑design onboarding workflow uses the agent-browser tool to capture both HTML markup and rendered screenshots from a target URL.
• Color tokens are extracted via CSS custom properties, getComputedStyle, or histogram analysis and mapped to semantic roles: paper, ink, muted, accent, paper‑2, and rule.
• Typography tokens are harvested from computed styles of <h1>, <body>, and <code> elements, then validated against Google Fonts or system stacks.
• The pipeline enforces AA contrast ratios, accent saturation dominance, and warm neutrals for pure‑white backgrounds before writing to references/style-guide.md.
• A unified diff preview allows verification of changes before they are applied to all 27 diagram types.

Frequently Asked Questions

What tools does the workflow use to capture website data?

The workflow prefers the built‑in agent-browser tool to navigate the target URL and output both HTML and PNG screenshot assets. If agent-browser is unavailable, the skill falls back to a standard HTTP fetch to retrieve markup【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L52-L58】.

How does the pipeline determine which color becomes the accent token?

The extractor identifies the accent token by analyzing the most frequently occurring saturated color in the rendered screenshot and CSS rules, typically appearing on call‑to‑action buttons, link text, or heading accents. If CSS custom properties define an --accent variable, that value takes precedence over histogram analysis【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L66-L74】.

Can the workflow extract fonts that are not hosted on Google Fonts?

Yes. The extractor records the literal font-family string from computed styles and then checks availability against Google Fonts and the local system font stack. If the detected typeface is unavailable, the pipeline substitutes a compatible fallback while preserving the original name for reference【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L90-L95】.

How can I revert branding changes after onboarding a new site?

Before overwriting references/style-guide.md, the skill can optionally create a recoverable snapshot of the default or previous state. Additionally, you can save the customized skin as a named profile in references/profiles.md, allowing you to switch between brand identities without losing prior configurations【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L54-L58】【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md#L304-L307】.

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