How to Configure Brand Onboarding to Extract Colors from a Website URL in Diagram-Design

Configure brand onboarding by running the agent-browser navigate command against your target URL, then approve the generated token diff to automatically map extracted colors to the style-guide.md semantic roles.

The cathrynlavery/diagram-design repository provides a complete brand onboarding pipeline that scrapes live websites to extract color palettes and typography. This process analyzes CSS custom properties, computed styles, and screenshot histograms to populate the style-guide.md token table with brand-accurate values.

The Five-Step Onboarding Pipeline

The URL-based onboarding flow is defined in skills/diagram-design/references/onboarding.md and executes atomically across five stages:

1. Fetch the Page with Agent-Browser

The pipeline begins by treating the target URL as untrusted input. The system executes:

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

This command captures both the rendered page screenshot and raw HTML without executing remote directives. The trust-boundary validation in scripts/verify-docs-sync.py ensures no remote code execution occurs during this step.

2. Extract Colors and Fonts

The system analyzes the fetched assets through three hierarchical methods:

• Primary: CSS custom properties from :root { --accent: #hex; }
• Secondary: getComputedStyle samples from semantic elements (body, h1, <code>)
• Tertiary: Color histogram analysis of the screenshot PNG

Font detection follows the same priority order, scanning for font-family declarations in computed styles.

3. Map to Semantic Roles

Extracted values are assigned to the diagram-design token architecture:

• paper (backgrounds)
• ink (primary text)
• muted (secondary text)
• accent (interactive elements)
• paper-2 (elevated surfaces)
• rule (borders and dividers)

Low-confidence mappings are flagged for manual confirmation before proceeding to the diff stage.

4. Preview the Diff

A git-style diff of references/style-guide.md displays proposed token changes. This view includes a brand fidelity receipt summarizing the extracted hex codes and font stacks. Users must explicitly approve this diff before the system writes any changes.

5. Apply and Save Profiles

Upon approval, the new tokens commit to style-guide.md. Optionally, persist the configuration as a reusable client profile:

diagram-design profile save mybrand

This creates ~/.diagram-design/profiles/mybrand.md and writes a .diagram-design marker file in the project root.

Security and Trust Boundaries

The onboarding flow implements strict isolation between untrusted web content and the execution environment. The validation logic in scripts/verify-docs-sync.py enforces that fetched HTML is parsed for token extraction only—no scripts execute, no external resources load, and no network requests originate from the analysis phase.

CLI Commands and Automation

Invoke Full Onboarding from Chat

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

The skill parses this command, launches the URL flow, and guides you through interactive diff approval.

Debug with Manual Extraction

For troubleshooting brand detection:

agent-browser navigate https://mybrand.com --screenshot /tmp/out.png --html /tmp/out.html
python -m diagram_design.onboard --preview /tmp/tokens.json

The preview command prints the proposed changes to paper, ink, and accent values without writing to disk.

Regenerate Examples

After applying new brand tokens, refresh all diagram examples:

/regenerate-examples

Key Configuration Files

Understanding these source files ensures accurate customization:

• skills/diagram-design/references/onboarding.md: Canonical specification of URL, Skill, and Folder onboarding flows
• references/style-guide.md: Single source of truth for the token table (modified during Step 5)
• references/profiles.md: Mechanics for persisting customized skins as named client profiles
• scripts/verify-docs-sync.py: Enforces trust boundaries and documentation synchronization

Summary

• Brand onboarding scrapes live URLs to extract visual tokens automatically
• The five-step pipeline fetches, extracts, maps, previews, and commits color/font data to style-guide.md
• Semantic roles (paper, ink, accent, muted) structure the extracted values consistently
• Trust boundaries in verify-docs-sync.py prevent remote code execution during fetching
• Named profiles persist brand configurations for reuse across projects via diagram-design profile save

Frequently Asked Questions

How does diagram-design handle websites without CSS custom properties?

When :root CSS variables are absent, the system falls back to getComputedStyle sampling from semantic HTML elements. If computed styles prove insufficient, it derives a histogram from the screenshot PNG to infer dominant and accent colors.

Can I preview brand changes before they overwrite my style guide?

Yes. Step 4 generates a git-style diff showing exact changes to style-guide.md token values. The system waits for explicit user approval before writing the new skin, preventing accidental overwrites.

What is the brand fidelity receipt?

The brand fidelity receipt is a summary document generated during the preview stage. It lists every extracted hex code, font family, and confidence score, providing transparency into how the algorithm mapped raw website data to semantic roles like paper and accent.

Where are saved brand profiles stored?

Saved profiles reside in ~/.diagram-design/profiles/[profilename].md. The system creates a .diagram-design marker in your project root pointing to the active profile, allowing instant brand context switching between client projects.

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