How to Onboard Diagram Design to a Website: The Complete Process

Diagram Design automatically extracts your website's colors and typography, maps them to semantic design tokens, and writes them to style-guide.md to ensure every generated diagram matches your brand identity.

The open-source cathrynlavery/diagram-design repository provides an automated onboarding system that enables the skill to adopt any website's visual style. When you onboard Diagram Design to a website, the process analyzes your site's HTML and CSS, validates accessibility compliance, and persists brand tokens for consistent diagram generation. This eliminates manual theme configuration and ensures WCAG AA contrast standards for diagram text.

The Automated Onboarding Pipeline

The onboarding implementation defined in references/onboarding.md executes a seven-phase pipeline to capture and apply your brand identity.

Step 1: Initiate Site Analysis

Trigger the onboarding flow by providing your website URL to the agent:

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

The agent immediately fetches your homepage HTML and begins parsing the document structure and computed styles.

Step 2: Extract Semantic Design Tokens

During extraction, the skill maps specific DOM elements and CSS properties to semantic tokens documented in the repository's README (lines 94-102). The parser locates:

• <body> background → paper token
• Primary text color → ink token
• Secondary/caption text → muted token
• Card-like containers → paper-2 token
• Brand color (CTAs, links, headings) → accent token
• <h1> font family → title font token
• <body> font family → node-name font token
• <code> or <pre> font → sublabel font token

Step 3: Validate Accessibility Compliance

Before persisting values, the skill performs a WCAG AA contrast check between the extracted ink and paper tokens. If your site's colors fail contrast requirements for diagram-appropriate text sizes (9-12px), the system proposes corrected values with an explanation of the accessibility adjustment.

Step 4: Review and Apply Changes

The agent displays a diff comparing the existing style-guide.md against the new token values. Confirm the changes to write the tokens:

yes, apply it

Upon confirmation, the skill writes the brand-derived tokens to skills/diagram-design/references/style-guide.md according to the specification in references/onboarding.md.

Step 5: Generate Branded Diagrams

After onboarding, every diagram request automatically uses your site's paper color, ink color, accent color, and typefaces. The system emits a "fidelity receipt" listing the exact source URLs, extracted colors, fonts, and any fallback values employed during generation.

Working with Brand Profiles

For multi-client projects, you can save onboarding results as named profiles using the CLI commands defined in commands/profile.md.

Save the current onboarding as a reusable profile:

/diagram-design:profile save acme

Reference the profile in other projects by creating a marker file:

echo "profile: acme" > .diagram-design

This allows you to maintain distinct brand identities across different websites without re-running the full onboarding flow.

Manual Token Configuration

If you prefer direct editing over automated extraction, modify the token table in style-guide.md manually:

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

The file stores semantic tokens that drive all diagram styling decisions, including color values for paper, ink, accent, and font family definitions for title, node-name, and sublabel typography.

Summary

• Automated extraction: The onboarding process fetches your website, parses HTML/CSS, and maps visual properties to semantic tokens like paper, ink, and accent.
• Accessibility validation: WCAG AA contrast checks ensure diagram text readability at small sizes (9-12px), with automatic corrections when necessary.
• Persistent branding: Approved tokens write to references/style-guide.md, ensuring all subsequent diagrams inherit your brand identity.
• Profile management: Save onboarding results as named profiles via /diagram-design:profile save for multi-client workflows.
• Fidelity tracking: Each onboarding generates a receipt documenting exact source URLs, extracted values, and fallback logic.

Frequently Asked Questions

How long does the onboarding process take?

The complete onboarding flow requires approximately 60 seconds from initial command to final token application. This includes fetching the target URL, parsing styles, running contrast checks, and displaying the confirmation diff.

What happens if my website colors fail accessibility contrast checks?

If the extracted ink and paper values fail WCAG AA compliance for diagram-appropriate text sizes, the skill automatically proposes accessibility-corrected values. The diff displays both your original colors and the adjusted values, explaining the specific contrast ratio improvements before you confirm application.

Can I use different brand styles for different projects?

Yes. According to commands/profile.md, you can save any onboarding result as a named profile using /diagram-design:profile save [name]. Reference these profiles across projects using .diagram-design marker files, enabling distinct brand identities without re-onboarding each time.

Where are the brand tokens stored after onboarding?

The system writes all extracted colors and fonts to skills/diagram-design/references/style-guide.md within the repository. This file serves as the single source of truth for diagram styling, containing semantic tokens for background colors (paper, paper-2), text colors (ink, muted), accent colors, and typography definitions.

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