How to Onboard a Brand Using a Website URL in Diagram Design

Diagram Design can automatically extract a brand's colors and typography from any live website URL through a seven-stage onboarding flow that maps detected values to semantic design tokens.

Brand onboarding in Diagram Design eliminates manual theme configuration by letting the skill ingest a site's visual identity directly from its URL. This process, defined in [skills/diagram-design/references/onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#url), enables users to generate on-brand diagrams with a single natural-language command.

The Onboarding URL Method

The URL method drives the entire brand extraction pipeline. When invoked, the agent activates agent-browser or standard fetch to retrieve both the HTML source and a raster screenshot of the target site. This dual capture provides DOM-computed styles for precise parsing and pixel data for color histogram analysis when CSS extraction proves insufficient [onboarding.md § URL lines 52-58].

Step-by-Step Onboarding Process

1. Invocation Trigger

Users initiate onboarding through natural language or explicit slash commands. The skill registers the target URL and begins the extraction sequence [README lines 48-60].

# Natural-language invocation (Claude Code, Codex, or Pi)

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

# Explicit slash-command (Pi)

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

2. Fetch and Analyze the Page

The agent downloads the complete HTML document and captures a viewport screenshot. This dual-source approach ensures robust extraction even when sites render content dynamically or obfuscate styles behind JavaScript [onboarding.md § URL lines 52-58].

3. Extract Colors and Fonts

Color extraction proceeds through a fallback hierarchy: CSS custom properties (:root variables) first, then computed styles via getComputedStyle, finally screenshot histogramming if needed. Detected values map to six semantic roles:

Role	Source Element	Semantic Token
paper	<body> background	paper
ink	Primary text color	ink
muted	Caption/secondary text	muted
accent	Most-used brand color (CTA, links, headings)	accent
paper-2	Card/container backgrounds	paper-2
rule	Borders and hairlines	rule

Font extraction samples three key selectors: <h1> maps to title, <body> to node-name, and <code> or <pre> to sublabel. The agent preserves the exact font source—whether a Google Fonts URL, system stack, or custom @font-face declaration—through the "Exact-font gate" that carries forward provenance data for later rendering [onboarding.md § URL lines 68-95].

4. Validate Against Accessibility Standards

Extracted values undergo automated quality checks: WCAG AA contrast verification between ink and paper, muted and paper, plus saturation validation for the accent color. Failures trigger proactive adjustments with explanatory reasoning [onboarding.md § URL lines 115-122].

5. Preview the Brand Diff

The agent renders a style-guide.md diff showing token replacements (e.g., paper #f8f6f0 → ink #111111 → accent #c73a2b) and outputs a brand-fidelity receipt documenting sampled URLs, detected roles, font families, weights, and source locations [onboarding.md § URL lines 27-34].

Preview without applying:

/onboard-preview https://mybrand.com

6. Apply and Persist Changes

Upon confirmation, the skill writes validated tokens to references/style-guide.md, first creating a recoverable default snapshot to enable rollback [onboarding.md § URL lines 56-60]. All subsequent diagrams automatically adopt the onboarded brand skin.

7. Save as Named Profile

Users may persist configurations as reusable profiles stored under ~/.diagram-design/profiles/. Projects containing a .diagram-design marker referencing a profile name automatically inherit those brand tokens [onboarding.md § URL lines 30-33].

/save-profile acme

Verifying Onboarding Results

The repository includes [skills/diagram-design/scripts/self_check.py](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) for post-onboarding validation. Run this utility to confirm generated diagrams honor the new tokens and meet contrast requirements.

Summary

• URL-based onboarding in Diagram Design automatically extracts brand colors and typography from live websites
• The process maps detected values to six semantic roles (paper, ink, muted, accent, paper-2, rule) and three font families (title, node-name, sublabel)
• WCAG AA contrast and saturation checks validate extracted values before application
• Recoverable snapshots and named profiles enable safe experimentation and reusable brand configurations
• All token changes write to references/style-guide.md, which diagrams reference at runtime

Frequently Asked Questions

What URL formats does Diagram Design support for brand onboarding?

Diagram Design accepts any HTTP or HTTPS URL reachable by the agent, including those requiring standard authentication. The extraction engine handles both server-rendered and client-rendered sites through its dual HTML-plus-screenshot capture strategy [onboarding.md § URL lines 52-58].

How does the skill handle websites without CSS custom properties?

The fallback chain progresses from :root CSS variables to getComputedStyle values to screenshot histogramming. This ensures color extraction succeeds even on legacy sites or platforms that inline all styles [onboarding.md § URL lines 68-74].

Can I revert to the default theme after onboarding?

Yes. The skill automatically creates a default snapshot before writing new tokens. Reference this snapshot in references/style-guide.md to restore original styling, or run the onboarding process again with a different URL [onboarding.md § URL lines 56-60].

Does onboarding work with local development servers?

Yes, provided the agent can resolve the local URL. For localhost or private network addresses, ensure the agent environment has appropriate network access. The URL method does not distinguish between public domains and local servers [README lines 48-60].

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