How to Onboard Your Brand to Diagram-Design Using a Website URL: A Complete Guide

You can onboard diagram-design to your brand by providing a website URL, and the tool will automatically extract color palettes and typography, map them to semantic design tokens, verify contrast accessibility, and write a ready-to-use style guide.

This guide walks through the onboarding flow implemented in the cathrynlavery/diagram-design repository. Whether you're working with Claude, Pi, or another compatible agent, the process remains consistent: fetch, extract, verify, and persist your brand's visual identity.

Onboarding Flow Overview

The onboarding system lives in skills/diagram-design/references/onboarding.md and is invoked through skills/diagram-design/SKILL.md when the agent detects an "onboard" intent. The flow consists of five sequential steps.

1. Trigger Onboarding with a URL

Initiate the process by specifying your brand's homepage:

You: onboard diagram-design to https://yoursite.com

The agent fetches the page, parses HTML/CSS, and extracts the dominant color palette and font stack. This extraction logic is described in the README at lines 48-55.

2. Map Extracted Values to Semantic Tokens

Raw colors and fonts are mapped to six semantic roles used across all 27 diagram types:

Token	Typical Source	Usage
paper	Page background	Diagram canvas background
ink	Body text color	Primary labels and lines
muted	Secondary text	Subtle annotations
accent	CTA/button colors	Highlights and key flows
link	Anchor link color	Connection indicators
paper-2	Alternate background	Contrast sections

The mapping logic is documented in README lines 56-64.

3. Verify WCAG AA Contrast

Before writing tokens, the system runs a contrast check on ink over paper at diagram font scales (9-12px). If contrast fails, the skill proposes adjusted colors with an explanation. This accessibility guardrail appears in README lines 78-81.

4. Write the Style Guide

Approved tokens are persisted to:

skills/diagram-design/references/style-guide.md

This file serves as the single source of truth for all diagram renders. Inspect it anytime to see your brand values:

cat skills/diagram-design/references/style-guide.md

5. Save as a Reusable Profile (Optional)

Create a named profile for multi-brand workflows:

/prompt "save profile acme"

Profiles are stored in ~/.diagram-design/profiles/<slug>.md and referenced via project markers:

echo "profile: acme" > .diagram-design

This mechanism is explained in README lines 98-101.

Code Examples by Interface

Claude Code (or Claude-Compatible Agents)

You: onboard diagram-design to https://example.com
Agent: → fetches the homepage
       → extracts palette + fonts
       → shows a proposed diff
       → writes tokens to references/style-guide.md
You: yes, apply it

Pi (CLI-Style Interface)

# Initiate onboarding

/prompt "onboard diagram-design to https://example.com"

# Confirm after reviewing the diff

/prompt "yes, apply it"

# Save for reuse

/prompt "save profile acme"

Using a Saved Profile in a New Project

# Add marker file to project root

echo "profile: acme" > .diagram-design

# Subsequent diagrams automatically use Acme branding

/prompt "Make me an architecture diagram of my SaaS platform"

What Happens After Onboarding

Every new diagram inherits your brand identity automatically:

• Background color → paper token → diagram canvas
• CTA color → accent token → highlights and flows
• Body font stack → node labels and annotations

The skill emits a fidelity receipt documenting sampled URLs, exact color values, font families, and source URLs for full traceability (README lines 61-64).

Key Files and Their Roles

File	Purpose
skills/diagram-design/references/onboarding.md	Detailed specification of URL-to-tokens flow, color extraction, and contrast handling
skills/diagram-design/references/style-guide.md	Semantic color and font tokens driving all 27 diagram types
skills/diagram-design/SKILL.md	Core entry point; loads onboarding reference on intent detection
~/.diagram-design/profiles/*.md	Saved brand profiles for cross-project reuse
README.md (lines 42-64, 78-81, 98-101)	User-facing onboarding documentation

Summary

• Onboard with a single command: Provide any website URL to extract brand colors and fonts
• Semantic mapping: Six tokens (paper, ink, muted, accent, link, paper-2) cover all diagram needs
• Built-in accessibility: WCAG AA contrast verification prevents unreadable combinations
• Centralized style guide: references/style-guide.md controls every diagram render
• Profile persistence: Save and switch brands via ~/.diagram-design/profiles/ and .diagram-design markers

Frequently Asked Questions

What if my website uses multiple color schemes?

The onboarding process samples the homepage only and extracts the dominant palette. For multi-scheme brands, manually edit references/style-guide.md after initial extraction, or create separate profiles for light/dark variants using the save profile <name> workflow.

Can I override individual tokens without re-onboarding?

Yes. Directly modify skills/diagram-design/references/style-guide.md. The file uses plain markdown with token definitions; changes take effect immediately on the next diagram generation without requiring a new onboarding session.

Does the contrast check cover all token combinations?

No. The system specifically verifies ink over paper at small font sizes (9-12px), which is the most critical readability threshold for diagram labels. Other combinations are not automatically validated—review your style guide manually if accessibility is paramount.

What happens if the URL fetch fails or returns no extractable styles?

The skill will report the failure and fall back to default tokens. You can then either retry with a different URL, provide a direct link to a CSS file, or manually configure style-guide.md based on brand guidelines.

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