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

TL;DR: Diagram-Design (also called "Schematic") uses a centralized 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. 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.

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, 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
5. Apply	Write tokens to style-guide.md after user approval; optionally regenerate example diagrams

Running the Onboarding Flow

Invoke the onboarding flow directly:

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

The skill auto-generates a diff preview showing proposed changes to style-guide.md:

-| `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

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	Complete workflow specification, source methods, and validation rules
skills/diagram-design/references/style-guide.md	Central token definition consumed by all diagrams
skills/diagram-design/assets/template.html	Minimal scaffold for previewing diagrams post-onboarding
skills/diagram-design/SKILL.md	High-level skill description and available commands
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 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. The skill suggests this step automatically after writing to style-guide.md. Open 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.

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