How to Add Custom Brand Colors for Onboarding in diagram-design

You add custom brand colors in diagram-design by running the onboarding flow, which fetches colors from a URL or local token file and rewrites style-guide.md with your brand's palette mapped to semantic roles.

The diagram-design skill from cathrynlavery/diagram-design centralizes all visual tokens in a single file. When you onboard a new brand, the skill automatically extracts color values, maps them to semantic design roles, and validates them against accessibility constraints. This guide covers the exact pipeline, constraints, and commands to customize your brand colors.

Where Colors Live in diagram-design

All visual tokens are defined in style-guide.md located at skills/diagram-design/references/style-guide.md (lines 17–27). This file declares four semantic color roles:

Token	Purpose	Default (light)	Default (dark)
paper	Page background / node fill	#f5f5f5	#2d3142
ink	Primary text / strokes	#2d3142	#f5f5f5
muted	Secondary text / arrow strokes	#4f5d75	#bfc0c0
accent	Focal color (1–2 per diagram)	#eb6c36	#f08a59

These semantic tokens are the single source of truth. All diagram types (type-process.md, type-journey.md, etc.) reference these tokens rather than hard-coded hex values. Change style-guide.md once, and every diagram inherits the new palette.

The Onboarding Pipeline for Custom Brand Colors

The onboarding flow is orchestrated from SKILL.md and documented in onboarding.md (lines 15–33 for URL flow, lines 167–232 for token-file mapping). The pipeline executes four steps:

1. Fetch – Downloads the target page or reads a local JSON/YAML token file.
2. Extract – Parses the source for hex color values (#xxxxxx) and font families.
3. Map – Assigns extracted colors to semantic roles using heuristics (most-used color becomes accent).
4. Preview & Apply – Generates a diff of style-guide.md, prompts for approval, then writes the new tokens.

Critical Constraints You Must Respect

The skill validates new tokens against hard rules defined in style-guide.md (lines 31–38). Violations block the onboarding:

Constraint	Rationale
One accent only – A single accent color may be defined.	Preserves visual hierarchy and focal signal.
Contrast compliance – ink must meet WCAG AA against paper; muted must meet AA for text ≥ 11px.	Guarantees legibility across diagram types.
No rainbow palette – Maximum three colors mapped to paper, ink, accent. Remaining colors become muted variants.	Prevents color overload in diagrams.
Three typefaces retained – title, node-name, and sublabel families must remain.	Maintains typographic rhythm.

How to Run Onboarding for Custom Brand Colors

URL-Based Onboarding (Fastest)

Invoke the skill with your brand's website:

Onboard this skill to my site https://example.com

The skill executes the full pipeline: fetch, extract, map, preview, and apply. For manual preview before writing, use the preview command documented in SKILL.md.

Token-File Onboarding (For Design Systems)

1. Prepare your JSON or YAML token file (e.g., ~/brand/tokens.json).
2. Invoke the skill with the file path:

Onboard Schematic from my design system at ~/brand/tokens.json

The skill flattens nested tokens (e.g., color.brand.primary.value), applies the same mapping heuristics, and generates the diff.

Manual Editing (Fallback)

If automatic extraction fails, edit style-guide.md directly:

• Replace hex values in the token tables (lines 19–27).
• Do not change token names (paper, ink, muted, accent).
• Run the taste-gate validation to confirm constraints:

diagram-design validate

Example: Swapping the Default Brand Palette

Given this brand palette:

Brand token	Hex
primary	#1e90ff (dodger-blue)
secondary	#ff6f61 (coral)
neutral	#f5f5f5 (warm-grey)

Map to semantic roles in style-guide.md:

| Role    | Purpose                   | Default (light) | New Value |
|---------|---------------------------|-----------------|-----------|
| `paper` | Page background, node fill| `#f5f5f5`       | `#f5f5f5` |
| `ink`   | Primary text / strokes    | `#2d3142`       | `#1e90ff` |
| `muted` | Secondary text / arrows   | `#4f5d75`       | `#ff6f61` |
| `accent`| Focal color               | `#eb6c36`       | `#ff6f61` |

Save, then validate:

diagram-design validate

Key Files for Brand Color Onboarding

File	Location	Purpose
style-guide.md	skills/diagram-design/references/style-guide.md	Central token definition; edit for manual overrides
onboarding.md	skills/diagram-design/references/onboarding.md	Detailed pipeline documentation (URL, Skill, Folder flows)
SKILL.md	skills/diagram-design/SKILL.md	User-facing command surface; triggers onboarding
type-*.md	skills/diagram-design/references/type-process.md (example)	Diagram specs that inherit tokens from style-guide.md

Summary

• Custom brand colors are added via the onboarding flow in diagram-design, which rewrites style-guide.md with extracted and mapped color tokens.
• Three onboarding methods: URL-based (fastest), token-file (for design systems), or manual editing with validation.
• Four semantic roles control the palette: paper, ink, muted, accent — all diagram types reference these automatically.
• Hard constraints enforce one accent, WCAG AA contrast, and limited palette size to maintain diagram clarity.

Frequently Asked Questions

What happens if my brand has more than three colors?

The onboarding heuristics select the three most dominant colors for paper, ink, and accent. Additional colors are mapped to muted variants or discarded. You can manually assign roles in style-guide.md if the automatic selection misses your preferred focal color.

Can I use a CSS file instead of JSON/YAML for token-file onboarding?

The skill parses any file containing hex color values (#xxxxxx), including CSS, SCSS, or extracted design tokens. Place the file at a reachable path and invoke with Onboard from ~/brand/styles.css. The extraction layer is format-agnostic for color detection.

Why does my new accent color fail the taste-gate validation?

The taste-gate enforces the one accent rule and contrast compliance. Confirm your accent doesn't appear in ink or muted roles, and verify ink against paper meets WCAG AA. Run diagram-design validate with verbose output to see specific failure reasons.

Do I need to update individual diagram files after onboarding?

No. All diagram types (type-process.md, type-journey.md, etc.) reference semantic tokens from style-guide.md. Once onboarding updates that file, every diagram automatically uses the new custom brand colors.

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