How to Onboard a Brand from a Website URL into Diagram-Design

Diagram-Design automatically extracts visual styles from any website URL to generate diagrams that match the site's branding through a structured five-stage pipeline involving page fetching, design token extraction, semantic mapping, diff preview, and skin application.

The cathrynlavery/diagram-design repository provides a comprehensive brand onboarding system that allows you to adopt the visual identity of any website. By processing a target URL through the onboarding pipeline defined in skills/diagram-design/references/onboarding.md, the tool extracts colors, typography, and design tokens to create a custom skin. This ensures all subsequent diagrams automatically reflect the extracted brand aesthetics without manual configuration.

Understanding the Onboarding Architecture

The URL onboarding process implemented in diagram-design follows a deterministic pipeline that transforms raw website assets into structured design tokens. According to the source specification in skills/diagram-design/references/onboarding.md, the system performs three primary operations: fetching the page and screenshot, extracting CSS-based design tokens, and updating the central style guide.

The extraction logic prioritizes CSS custom properties (such as :root { --accent: … }) when available, falling back to getComputedStyle analysis or histogram-based color sampling from screenshots. This multi-layered approach ensures robust brand fidelity even when websites use complex rendering techniques or custom font hosting.

Step-by-Step URL Onboarding Process

Initiating the Onboarding Flow

To begin onboarding a brand from a website URL, invoke the diagram-design skill with the target URL. The system accepts standard HTTPS URLs and initiates the extraction pipeline immediately.

diagram-design onboarding https://example.com

Alternatively, you can fetch the page manually using the agent-browser tool before invoking the skill, which is the preferred method for complex JavaScript-heavy sites:

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

Fetching and Rendering the Target Page

The skill uses agent-browser as its primary fetching mechanism, with plain fetch as a fallback for static content. This dual approach ensures compatibility with both server-rendered pages and dynamic single-page applications. The command downloads both the HTML source and a rendered screenshot, providing the raw material for token extraction.

The fetched assets are processed according to the trust boundaries defined in scripts/verify-docs-sync.py, which enforces security constraints and ensures the onboarding spec remains synchronized with the implementation.

Extracting Colors and Fonts

The extraction engine analyzes the rendered CSS and screenshot to identify six core semantic colors:

• <body> background maps to paper
• Primary text color maps to ink
• Caption/secondary text maps to muted
• Most-used brand color (from CTAs, links, headings) maps to accent
• Container backgrounds map to paper-2
• Border/hairline colors map to rule (derived from ink with reduced opacity)

For typography, the system extracts font-family values from three specific elements: <h1> for titles, <body> for node names, and <code> or <pre> elements for sublabels. The extraction records the exact family, weight, and source URL. However, only Google Fonts URLs matching the pattern https://fonts.googleapis.com/css2 are permitted to carry into the final skin; custom-hosted fonts are marked as fallback to ensure portability.

Mapping to Semantic Roles

Detected values are placed into a structured table of semantic roles (paper, ink, muted, accent, etc.) accompanied by confidence scores. The validation layer enforces accessibility and design standards:

• AA contrast requirements between ink and paper
• Saturation checks for accent colors to ensure vibrancy
• Non-white paper enforcement, falling back to #fafaf7 if the source uses pure white

This mapping process ensures that extracted brand colors remain functional for diagram readability while preserving the original aesthetic.

Previewing the Brand Diff

Before applying changes, the system generates a git-style diff of style-guide.md showing only the token table changes. This allows visual verification of the brand transformation.

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

A brand fidelity receipt accompanies the diff, listing the sampled URLs, detected hex values, font families, and any page-specific overrides applied during extraction.

Applying the New Skin

Once validated, the system creates a recoverable snapshot of the original style-guide.md before writing the diff. The style-guide.md file serves as the single source of truth for all colors, typography, and tokens within diagram-design, as specified in skills/diagram-design/references/style-guide.md.

After application, regenerate example diagrams to verify the new appearance:

open assets/index.html

Or use the built-in regeneration command:

/regenerate-examples

Managing Multiple Brand Profiles

After successfully onboarding a brand, you can persist the customized style-guide.md as a named client profile. Projects containing a .diagram-design marker file with the property profile: <slug> automatically load that profile, enabling multiple client brands to coexist without overwriting each other's configurations.

diagram-design save-profile my-brand

This profile management system, documented in skills/diagram-design/SKILL.md, allows agencies and multi-brand teams to maintain distinct visual identities across different projects while using a single diagram-design installation.

Summary

• Diagram-Design extracts brand identities from website URLs through an automated five-stage pipeline defined in skills/diagram-design/references/onboarding.md.
• The token extraction process maps CSS properties and computed styles to semantic roles including paper, ink, muted, and accent, with validation for AA contrast and color saturation.
• Font harvesting captures typefaces from <h1>, <body>, and <code> elements, permitting only Google Fonts URLs (https://fonts.googleapis.com/css2) to ensure reliability.
• The git-style diff preview of style-guide.md allows visual verification before committing brand changes, accompanied by a detailed brand fidelity receipt.
• Named profiles enable persistence of multiple brand configurations via the save-profile command and .diagram-design marker files.

Frequently Asked Questions

How does diagram-design handle websites that use pure white backgrounds?

The onboarding pipeline enforces a non-white paper color requirement to ensure diagram readability. If the extraction detects a pure white (#ffffff) background on the source website, the system automatically falls back to #fafaf7 for the paper token. This prevents eye strain while maintaining the warm aesthetic typical of diagram-design outputs.

Can I use custom fonts that are not hosted on Google Fonts?

Custom-hosted fonts are detected during the extraction process but are marked as fallback in the final skin configuration. Only URLs matching the https://fonts.googleapis.com/css2 pattern are permitted to carry into the production style guide. This restriction ensures that generated diagrams remain portable and render correctly across different environments without requiring access to private font servers.

What happens if the contrast ratio between extracted colors fails accessibility standards?

The semantic role validation layer automatically checks for AA contrast compliance between ink (text) and paper (background) tokens. If the extracted values fail to meet the 4.5:1 ratio requirement, the system either adjusts the values slightly or flags the issue in the brand fidelity receipt. This ensures that onboarded brands remain legible in diagram outputs while preserving the intended visual hierarchy.

Where are the brand configuration files stored after onboarding?

The active brand configuration is written to style-guide.md in the project root, which serves as the central token repository according to skills/diagram-design/references/style-guide.md. Before any modifications, the system creates a recoverable snapshot of the original file. Additionally, saved profiles are stored as named copies that can be referenced via the profile property in .diagram-design marker files, allowing rapid switching between client brands.

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