How to Onboard a Custom Brand Palette to Diagram‑Design: A Complete Step‑by‑Step Guide

Onboard a custom brand palette to Diagram‑Design by feeding a URL to the built‑in onboarding flow, which extracts colors and fonts, maps them to semantic tokens, and writes the result to skills/diagram-design/references/style-guide.md.

Diagram‑Design stores every visual decision—colors, typography, contrast ratios—in a single source‑of‑truth file. The onboarding system automates the process of aligning those tokens with your corporate brand, whether that brand lives on a public website, in another installed skill, or in a local design folder. This guide walks through the canonical URL‑based workflow and shows how to save the result for reuse across projects.

What Happens During Onboarding

The onboarding flow in skills/diagram-design/references/onboarding.md executes a five‑step pipeline that transforms raw design inputs into semantic tokens.

Step 1: Fetch the Target URL

The skill retrieves the page using either agent-browser or a plain fetch. No authentication is required for public marketing sites; authenticated flows are supported via environment variables passed to the browser agent.

Step 2: Extract Colors and Fonts

The system parses the rendered CSS and a full‑page screenshot to detect:

• Dominant background and text colors (sampling algorithm described in onboarding.md § Step 2)
• Font families from <h1>, <body>, and <code>/<pre> elements

Extraction runs against the live DOM, so dynamic CSS—CSS‑in‑JS, injected stylesheets, or variable‑driven themes—is captured accurately.

Step 3: Map to Semantic Roles

Detected values are assigned to the nine semantic roles defined in style-guide.md:

Token	Typical Use
paper	Canvas background
ink	Primary text
muted	Secondary labels
accent	Highlights, connections
paper-2	Alternate surface (cards, panels)
rule	Borders, dividers
title	Diagram titles
node-name	Entity labels
sublabel	Metadata, captions

The mapping logic prefers high‑contrast pairings and falls back to WCAG‑AA‑safe defaults when the extracted palette fails automated contrast checks.

Step 4: Preview the Diff

Before any write occurs, the skill renders a diff of the proposed changes to style-guide.md alongside a brand‑fidelity receipt. The receipt lists:

• Sampled URLs and page regions
• Extracted hex values (light and dark variants)
• Font family declarations
• Contrast adjustments applied automatically

Review this in your terminal or IDE; the flow pauses for explicit user consent.

Step 5: Apply to Style Guide

Once confirmed, the diff is committed to skills/diagram-design/references/style-guide.md. The system preserves the previous token set as a default snapshot, enabling one‑command rollback:

diagram-design restore-default-skin

Step 6: Save as a Named Profile (Optional)

To reuse this brand configuration elsewhere, persist it to the profile library:

You: "save onboarding result as profile acme"

The profile writes to ~/.diagram-design/profiles/acme.md. Future projects activate it by adding a .diagram-design marker file containing:

profile: acme

Running the Onboarding Flow

Quick Start: Natural Language Invocation

# Single command from any Diagram‑Design host

You: "onboard diagram-design to https://mycompany.com"

The skill handles fetch, extract, map, preview, and apply automatically. Total runtime is typically 15–30 seconds for a standard marketing site.

Manual Path: Direct Style‑Guide Editing

For precise control or air‑gapped environments, edit style-guide.md directly:

# Clone the repository

git clone https://github.com/cathrynlavery/diagram-design.git
cd diagram-design

# Open the token table for editing

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

The file contains a markdown table with columns for token name, light‑mode value, and dark‑mode value. Modify rows in place; no rebuild step is required.

Example Diff Output

Below is an excerpt from a brand‑onboarding preview, showing the transformation applied to style-guide.md:

- | `paper` | `#f5f4ed` | `#1c1a17` |
- | `ink`   | `#0b0d0b` | `#f1efe7` |
- | `accent`| `#0056b3` | `#4aa3f5` |
+ | `paper` | `#f8f6f0` | `#1a1815` |
+ | `ink`   | `#111111` | `#efeee7` |
+ | `accent`| `#c73a2b` | `#e05440` |

The accent shift from blue to red reflects the extracted primary brand color from https://mycompany.com. Dark‑mode values are derived automatically using perceptual lightness scaling.

Verifying the Result

Confirm the new palette across all 39 diagram types by opening the built‑in gallery:

# macOS

open skills/diagram-design/assets/index.html

# Linux

xdg-open skills/diagram-design/assets/index.html

The gallery renders every diagram variant with live tokens from style-guide.md. Scroll to check contrast on complex flows (sequence diagrams, architecture maps) where accent and paper-2 interact frequently.

Alternative Source Types

While URL onboarding is most common, the system supports two additional entry points defined in onboarding.md:

• Installed skill: Reference another Diagram‑Design skill that exports a BrandSpec interface
• Local folder: Point to a directory containing tokens.json, variables.css, or Figma‑exported JSON

Both follow the same extract‑map‑preview‑apply pipeline, differing only in the initial input parser.

Key Implementation Files

File	Responsibility
skills/diagram-design/references/onboarding.md	Complete specification of fetch, extract, map, preview, and apply stages; covers URL, Skill, and Folder source types
skills/diagram-design/references/style-guide.md	Single source‑of‑truth for semantic tokens (paper, ink, accent, etc.); rewritten in Step 5
skills/diagram-design/references/profiles.md	Profile storage format, loading semantics, and .diagram-design marker syntax
skills/diagram-design/SKILL.md	Entry point declaring the onboard command and wiring it to the execution gate
skills/diagram-design/assets/index.html	Visual regression suite for all 39 diagram types; hot‑reloads style-guide.md on refresh

Summary

• Onboard a custom brand palette to Diagram‑Design by invoking the natural‑language command or running the five‑step pipeline manually.
• The flow targets skills/diagram-design/references/style-guide.md, the sole file controlling every diagram's appearance.
• Extraction runs against live CSS and screenshots, capturing dynamic themes accurately.
• WCAG‑AA contrast checks block low‑confidence writes; a brand‑fidelity receipt documents every decision.
• Save successful onboardings as named profiles in ~/.diagram-design/profiles/ for cross‑project reuse.
• Verify changes instantly in skills/diagram-design/assets/index.html, which renders all 39 diagram types with live tokens.

Frequently Asked Questions

Can I onboard from a private site behind authentication?

Yes. Pass credentials via environment variables consumed by agent-browser, or download the site locally and use the Folder source type. The extraction engine does not store credentials; they exist only in the ephemeral browser session.

What happens if the extracted colors fail contrast checks?

The pipeline flags failing pairs in the brand‑fidelity receipt and applies automatic adjustments—usually lightness shifts of ±10%—to reach WCAG‑AA compliance. You may override these suggestions before the final apply step.

How do I restore the original default skin?

Run diagram-design restore-default-skin. This command swaps style-guide.md with the default snapshot preserved during the most recent onboarding. Profiles remain intact; restoring defaults does not delete saved profiles.

Can multiple profiles coexist in one project?

No. A project references exactly one profile via its .diagram-design marker. To composite brands, manually merge token tables in style-guide.md and save the result as a new named profile.

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