# How to Onboard Diagram-Design to Match a Website's Brand: The Complete Guide

> Learn how to onboard diagram-design to match your website's brand. This guide details the five-step pipeline for extracting colors, fonts, and ensuring accessibility for custom diagram skins.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-14

---

**TL;DR:** Diagram-Design (also called "Schematic") uses a centralized [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file and a five-step deterministic pipeline to extract a website's colors and fonts, validate accessibility, and generate a brand-matched diagram skin.

To onboard Diagram-Design to match a specific website's brand, the skill follows a deterministic pipeline defined in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md). The process extracts a target site's visual identity and maps it to semantic design tokens, ensuring WCAG compliance and visual coherence across all diagram outputs.

## Three Source Methods for Brand Extraction

Diagram-Design supports three input methods for capturing a website's visual identity. All methods converge on the same core pipeline.

### URL Fetching (Preferred)

The skill uses `agent-browser` to fetch a live site, analyze rendered CSS, and optionally capture screenshots.

```bash
agent-browser navigate https://example.com \
    --screenshot out.png \
    --html out.html

```

This method can sample multiple pages—landing, blog, product—to build a robust, representative palette.

### Skill-Based Import

Read from an already-installed Agent Skill that contains design-token assets. This method bypasses network fetching when tokens are already curated.

### Folder Scanning

Scan a local design-system directory containing CSS/SCSS, JSON tokens, or Markdown files for color and font definitions.

## The Five-Step Onboarding Pipeline

According to the source specification in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), every onboarding workflow executes these steps:

| Step | Action |
|------|--------|
| **1. Read/Fetch** | Retrieve source via network, file read, or skill lookup |
| **2. Extract** | Parse dominant colors (paper, ink, muted, accent, paper-2, rule) and font families (title, node-name, sublabel) from CSS custom properties, color histograms, or token files |
| **3. Map** | Assign extracted values to Schematic's semantic roles using name-heuristics (e.g., `--accent` → `accent`) |
| **4. Validate & Propose** | Run WCAG AA contrast checks, enforce the "one-accent" rule, generate a diff preview of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) |
| **5. Apply** | Write tokens to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) after user approval; optionally regenerate example diagrams |

## Running the Onboarding Flow

Invoke the onboarding flow directly:

```bash
opencode run "Onboard Schematic to my site — https://example.com"

```

The skill auto-generates a diff preview showing proposed changes to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md):

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

```

Approve to apply, or the skill prompts for clarification if extraction fails.

## Architectural Constraints in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)

Four hard rules—enforced during validation—ensure brand-matched skins remain legible:

- **Contrast requirements:** `ink` must satisfy WCAG AA against `paper`; `muted` must satisfy AA against `paper` for text ≥11px.
- **One-accent rule:** Only a single color may occupy the `accent` role to preserve visual hierarchy.
- **Warm-neutral paper:** Pure white (`#ffffff`) is discouraged; cream or grey with warmth is preferred.
- **Three-font limit:** Serif for titles, sans-serif for node names, mono for technical labels. Custom fonts persist only when publicly hostable (e.g., Google Fonts); otherwise, defaults apply.

## Key Files for Onboarding Reference

| File | Purpose |
|------|---------|
| [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) | Complete workflow specification, source methods, and validation rules |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Central token definition consumed by all diagrams |
| [`skills/diagram-design/assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template.html) | Minimal scaffold for previewing diagrams post-onboarding |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | High-level skill description and available commands |
| [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html) | Example gallery; rebuild after onboarding to confirm rendering |

## Handling Edge Cases

When extraction fails—due to custom-hosted fonts, overly complex color schemes, or dark-mode-first sites—the skill falls back to sensible defaults and explicitly prompts the user for clarification. For robust palette extraction, configure URL-based onboarding to sample multiple page types.

## Summary

- **Single source of truth:** All brand tokens live in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) per the `diagram-design` architecture.
- **Three input methods:** URL fetching (via `agent-browser`), skill import, or folder scan.
- **Five deterministic steps:** Read, extract, map, validate, apply.
- **Hard constraints:** WCAG AA contrast, one-accent rule, warm-neutral paper, three-font typography.
- **Validation before write:** Every onboarding generates a diff preview requiring explicit user approval.

## Frequently Asked Questions

### What happens if the target website uses a dark-mode-first design?

The skill detects dominant background values and may flag the extraction for user clarification. If dark mode is confirmed as primary, the mapping logic inverts semantic roles—dark values assign to `paper` (background) and light values to `ink` (foreground)—but WCAG AA validation still applies.

### Can I use custom fonts that aren't on Google Fonts?

No. The onboarding pipeline retains custom fonts only when publicly hostable. Non-hostable fonts trigger a fallback to default families (system serif, sans-serif, or mono) to ensure diagrams render correctly in any environment.

### How do I verify the new skin renders correctly after onboarding?

Rebuild the example gallery by regenerating [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html). The skill suggests this step automatically after writing to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). Open [`skills/diagram-design/assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template.html) for quick manual preview of individual diagrams.

### What permissions does `agent-browser` need for URL onboarding?

The browser agent requires network access to the target domain and screenshot capability. No authentication is required for public sites; authenticated or gated content requires pre-exporting assets and using the **Folder** source method instead.