How the Onboarding Process in Diagram Design Works: 6-Step Brand Integration

The onboarding process in Diagram Design automatically converts any design source—whether a live URL, installed skill, or local folder—into a branded diagram skin through a six-step pipeline that extracts visual tokens and applies them to style-guide.md.

The onboarding process in Diagram Design (implemented in the cathrynlavery/diagram-design repository) provides a guided flow for transforming external brand assets into consistent, reusable styling. This system ensures that every diagram generated by the skill automatically adheres to your brand's color palette, typography, and design tokens without manual CSS editing.

Overview of the Brand-Onboard Flow

Diagram Design's onboarding is the automatic "brand-onboard" flow that converts a design source into a full-featured skin for every diagram the skill generates. The process unifies three distinct input methods—URL, Skill, and Folder—into a single pipeline defined in [onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md).

Regardless of the source type, the pipeline executes the same six steps, ensuring consistent behavior whether you are scraping a live website or importing from a local design-system repository.

The Six-Step Onboarding Pipeline

The master flow diagram in skills/diagram-design/references/onboarding.md defines the following stages:

Step 1: Read and Fetch the Design Source

The adapter retrieves raw design data based on the input method:

• URL: The agent-browser (or plain fetch) pulls the page content and captures a screenshot for color analysis.
• Skill: The system locates the skill's directory using path resolution tables defined in the onboarding specification.
• Folder: A recursive glob discovers design-token files within the local directory.

This step is implemented in the source-specific sections of [onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#url).

Step 2: Extract Colors and Fonts

Raw visual assets are parsed into structured data:

• Colors are mapped from CSS custom properties, computed styles, or a histogram of the screenshot. The system identifies six semantic color slots: paper, ink, muted, accent, paper-2, and rule.
• Fonts are extracted from the computed font-family of <h1>, <body>, and <code>/<pre> elements. Only Google Fonts URLs are preserved for exact font loading.

See the extraction logic in [onboarding.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#step-2---extract-colors-and-fonts).

Step 3: Map to Semantic Roles

Heuristics translate raw tokens into the semantic-role table. For example, variable names containing "bg" map to paper. The system flags low-confidence guesses—such as ambiguous accent colors—for user confirmation before proceeding.

This mapping ensures that extracted values align with Diagram Design's internal token architecture, maintaining consistency across all diagram types.

Step 4: Preview the Diff

Before modifying any files, the skill generates a unified diff preview showing changes to style-guide.md. The preview includes a brand-fidelity receipt that lists sampled URLs, detected color values, and font sources for verification.

Example diff output:

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

Step 5: Apply the Changes

After user approval (y/N), the new tokens are written to style-guide.md. If the file was still pristine (unused), a recoverable default snapshot is created first, as documented in [profiles.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md). The skill may also regenerate example diagrams to verify the new skin renders correctly.

Step 6: Save a Profile (Optional)

The updated style-guide.md can be stored as a named client profile under ~/.diagram-design/profiles/. Projects containing a .diagram-design marker file automatically load that profile, keeping parallel client workspaces isolated and allowing seamless brand switching across different projects.

CLI Commands for Onboarding

Invoke the pipeline using the skill's CLI wrappers:

# Onboard from a live website

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

# Onboard from an installed skill

onboard diagram-design from acme-design

# Onboard from a local design-system folder

onboard diagram-design from ~/projects/brand/design-tokens/

Each command executes the full six-step pipeline, displaying the diff preview and requiring explicit approval before persisting changes to style-guide.md.

Architectural Safety Mechanisms

The onboarding implementation includes several safeguards to prevent errors:

• Single Source of Truth: All color, typography, and token definitions live exclusively in style-guide.md. Onboarding rewrites only this file, ensuring every diagram type reads identical variables.
• Safety Gates: Before overwriting a pristine style-guide.md, the system creates a snapshot. Contrast checks enforce WCAG AA standards (minimum 4.5:1 ratio), and "accent-most-saturated" rules ensure accessible color selection by default.
• Extensible Adapters: The three source adapters share the same pipeline; each only customizes Step 1 (fetching) and Step 2 (raw extraction). This modular design simplifies adding new source types in future updates.

Key Implementation Files

• skills/diagram-design/references/onboarding.md: Full pipeline specification and source-method details.
• skills/diagram-design/references/style-guide.md: Single source of truth for colors, typography, and semantic tokens.
• skills/diagram-design/references/profiles.md: Profile format definition, storage location (~/.diagram-design/profiles/), and marker file behavior.
• skills/diagram-design/SKILL.md: High-level capability description including the brand onboarding feature.
• README.md: User-facing overview with "60-second onboarding" documentation and quick-start examples.
• skills/diagram-design/assets/index.html: Visual gallery for verifying brand-onboarded palettes across all diagram types.

Summary

• The onboarding process in Diagram Design uses a six-step pipeline to convert URLs, skills, or folders into branded diagram skins.
• All visual tokens are extracted, mapped to semantic roles (paper, ink, accent, etc.), and written to style-guide.md as the single source of truth.
• The system creates recoverable snapshots before modifying pristine files and enforces WCAG AA contrast ratios automatically.
• Named profiles stored in ~/.diagram-design/profiles/ enable persistent brand settings across projects via the .diagram-design marker file.
• Source code and specifications reside in skills/diagram-design/references/onboarding.md and related reference files.

Frequently Asked Questions

What file does the onboarding process modify?

The onboarding process writes all extracted color and font tokens to style-guide.md in the skill directory. This file serves as the single source of truth that every diagram type references for styling variables, ensuring consistent application across your diagrams.

Can I onboard from a local design system instead of a website?

Yes. Use the folder adapter by running onboard diagram-design from /path/to/design-tokens/. The system performs a recursive glob to discover token files and processes them through the same six-step pipeline used for URLs and skills.

What happens if the extracted colors have poor contrast?

The pipeline includes built-in safety gates that enforce AA accessibility standards (minimum 4.5:1 contrast ratio) and "accent-most-saturated" rules. If automatic extraction produces insufficient contrast, the system flags these values during the semantic mapping step for user correction before applying the diff.

How does Diagram Design remember my brand settings between sessions?

After onboarding, you can save the resulting configuration as a named profile using the optional Step 6. Profiles are stored in ~/.diagram-design/profiles/ and automatically loaded when the skill detects a .diagram-design marker file in your project root, ensuring consistent branding without re-running the full pipeline.

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