how-to-guide

How URL-Based Brand Onboarding Works in Diagram Design

September 8, 2026 cathrynlavery/diagram-design ↗

Diagram Design’s URL-based brand onboarding automatically extracts color palettes and typography from any website URL to generate cohesive, branded diagrams through a deterministic fetch-extract-validate-apply pipeline.

Diagram Design ships with a neutral “editorial” skin (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines) by default, but users can instantly align generated diagrams with corporate identity using the URL-based brand onboarding feature. This process, defined in skills/diagram-design/references/onboarding.md, treats fetched website data as untrusted visual signals and maps them to semantic design tokens stored in the style guide.

The 8-Step Onboarding Pipeline

The URL-based onboarding flow follows a deterministic sequence from invocation to application, ensuring reproducible brand fidelity across all 39 diagram visual types.

Step 1: Invocation and URL Parsing

The flow begins when a user invokes the onboarding command via CLI or conversational agent. According to [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L27), the skill parses commands like onboard diagram-design to https://example.com and initializes the brand extraction pipeline.

Step 2: Fetching Untrusted Page Data

The skill uses the built-in agent-browser (or a plain fetch) to download the HTML and a screenshot of the target site. As specified in [onboarding.md lines 52-61](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L52-L61), this data is explicitly treated as untrusted and is used solely for visual signal extraction, never for executable code or configuration.

Step 3: Extracting Colors and Fonts

From the rendered CSS and screenshot, the skill derives specific design tokens:

  • paper – Background color of <body>
  • ink – Primary text color
  • muted – Secondary or caption color
  • accent – Most-used brand color (CTA, links)
  • rule – Border or hairline color
  • title, node-name, sublabel – Font families for headings, body text, and code elements

This extraction logic is documented in [onboarding.md lines 70-86](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L70-L86).

Step 4: Mapping to Semantic Roles

The extracted raw tokens are matched to the semantic roles defined in the design system (paper, ink, muted, accent, rule, etc.). During this phase, as detailed in [onboarding.md lines 103-112](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L103-L112), the system builds a confidence table that allows users to correct low-confidence guesses before proceeding.

Step 5: Automated Validation

Before writing any changes, the skill performs safety checks defined in [onboarding.md lines 217-224](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L217-L224):

  • AA contrast validation for ink on paper and muted on paper
  • Saturation check ensuring accent is the most saturated color
  • Warm neutral fallback if paper is pure white (prevents sterile output)

If any check fails, the system proposes corrected values rather than rejecting the input entirely.

Step 6: Diff Preview and Brand Fidelity Receipt

The system generates a unified diff showing proposed changes to style-guide.md, accompanied by a brand fidelity receipt listing detected URLs, exact color values, font families, and extraction sources. This transparency step, covered in [onboarding.md lines 30-41](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L30-L41), ensures users understand exactly what visual data drives the new palette.

Step 7: Application and Profile Persistence

After user approval, the diff is written to skills/diagram-design/references/style-guide.md, becoming the single source of truth for subsequent diagrams. The skill optionally saves the configuration as a named client profile at ~/.diagram-design/profiles/<slug>.md for future reuse, as noted in [onboarding.md lines 56-62](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L56-L62).

Step 8: Post-Onboarding Verification

Users can open the gallery at assets/index.html to verify that all 39 visual types respect the new palette. If adjustments are needed, users can manually tweak specific roles in the style guide and re-run the onboarding process to refine the extraction.

Command-Line Interface

The URL-based brand onboarding exposes intuitive CLI commands for both initial setup and profile management:


# Initialize onboarding from a corporate website

diagram-design onboard https://mycompany.com

# Confirm the proposed changes after diff review

yes

# Save the configuration as a reusable profile

diagram-design save-profile acme

# Generate a diagram using the onboarded brand tokens

diagram-design draw flowchart my-flow.mmd

The same flow integrates with conversational AI agents (Claude or OpenAI), where natural language prompts like "Onboard diagram-design to https://example.com" trigger the identical pipeline with interactive approval steps.

Core Source Files and Trust Boundaries

The onboarding architecture relies on specific files that enforce safety guarantees and data integrity:

Summary

  • URL-based brand onboarding converts any website into a diagram-compatible design system through an automated eight-step pipeline.
  • The process extracts semantic tokens (paper, ink, accent, muted, rule) from CSS and screenshots, treating all fetched data as untrusted.
  • Automated validation enforces AA contrast ratios and prevents pure-white backgrounds, proposing corrections when standards are missed.
  • Changes are previewed via unified diffs and brand fidelity receipts before being committed to style-guide.md.
  • Users can persist brand configurations as named profiles in ~/.diagram-design/profiles/ for consistent reuse across projects.
  • The gallery at assets/index.html provides immediate visual verification across all 39 diagram types.

Frequently Asked Questions

What happens if the target website uses custom fonts or a dark-mode-first design?

If the site uses custom-hosted fonts that cannot be resolved, or presents a dark-mode-first palette that conflicts with the default light-mode assumptions, the onboarding flow falls back to sensible defaults from the editorial skin. As documented in the “When URL onboarding fails” section of [onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), the system informs the user which manual adjustments are needed to complete the brand mapping.

How does the system ensure accessibility compliance during brand extraction?

The validation step explicitly checks for AA contrast ratios between ink and paper, and between muted and paper, as implemented in [onboarding.md lines 217-224](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#L217-L224). If extracted colors fail these checks, the system generates corrected values that meet accessibility standards before presenting the final diff to the user.

Can I revert to the default editorial skin after onboarding a brand?

Yes. Since the onboarding process writes changes to style-guide.md, you can revert by restoring the original neutral values (white-smoke paper, jet-black ink, atomic-tangerine accent) or by deleting the active profile in ~/.diagram-design/profiles/. The system will automatically fall back to the baseline editorial skin when no custom tokens are detected, as gated by the logic in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#L165-L172).

Where are the extracted brand artifacts stored locally?

After approval, brand tokens are written to skills/diagram-design/references/style-guide.md within the repository. Additionally, users may save named profiles to ~/.diagram-design/profiles/<slug>.md, creating portable, reusable brand configurations that can be applied to future diagram generation sessions without re-fetching the source URL.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →