How to Customize the Diagram Design System: 4 Configuration Methods Explained

You customize the diagram design system by modifying the centralized style-guide.md file—either manually, through automated brand extraction, or via named profiles that override the default tokens without altering the installed skill.

The cathrynlavery/diagram-design repository treats style-guide.md as the single source of truth for all visual semantics. Every diagram type—architecture diagrams, flowcharts, radar charts—resolves colors, typography, and spacing through semantic tokens (e.g., accent, paper) defined in this file rather than hard-coded values. This architecture ensures that changing one token propagates across every diagram type instantly.

The Central Configuration File: style-guide.md

All customization pathways ultimately modify style-guide.md located at skills/diagram-design/references/style-guide.md. This file defines semantic tokens—logical names like accent, ink, and paper—mapped to specific hex values, font stacks, and spacing scales.

According to the source code in SKILL.md, diagram type specifications (type-*.md files) reference these tokens by role, not by value. This indirection allows the system to remain "skinnable" without touching type-specific logic. The file also contains the inversion rule, which automatically generates dark-mode variants for every light-theme color while preserving opacity and hue relationships.

4 Ways to Customize the Diagram Design System

1. Edit style-guide.md Manually

For immediate, granular control, edit the token tables directly in skills/diagram-design/references/style-guide.md. Locate the semantic role you want to change—such as accent—and replace the hex value. All newly generated diagrams will use the updated color immediately.

# Open the style guide for editing

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

# Example: Change the accent color from #ff5722 to your brand color

# Find the row:

# | `accent` | Focal / 1–2 max per diagram | `#ff5722` | `#ffa07a` |

# Replace with your brand hex code

The system enforces a one-accent rule during validation, ensuring only a single focal accent color exists per diagram to maintain visual hierarchy.

2. Run the Onboarding Flow

The onboarding script automates brand adoption by extracting color palettes and font families from any website URL. Located in skills/diagram-design/references/onboarding.md, this tool rewrites style-guide.md automatically after scraping the target site.

# From the repository root, extract brand assets from a URL

python -m skills.diagram_design.onboarding https://example.com

The script handles missing tokens safely and performs a contrast check (WCAG AA) to verify that the extracted ink color remains readable against the paper background. If the check fails, the skill pauses and prompts for manual adjustment.

3. Create Client Profiles

For managing multiple brands across different projects, save snapshots of style-guide.md as named profiles. These profiles isolate brand configurations from the core installation, enabling different projects to use different visual identities while sharing the same installed skill.

# Save the current style guide configuration as a named profile

diagram-design profile save mybrand

# Stored at: ~/.diagram-design/profiles/mybrand.md

As documented in skills/diagram-design/references/profiles.md, profiles persist full token sets including series palettes for multi-series charts (radar, line, bar), though these remain opt-in and never override the single accent token.

4. Use Project Markers for Profile Binding

Create a .diagram-design marker file in any project root to force the skill to load a specific profile instead of the installed style-guide.md. This keeps the installed skill untouched—ideal for managed marketplace installs where you cannot edit core files.

# In your project root, create a marker binding to the "mybrand" profile

echo "profile: mybrand" > .diagram-design

Subsequent diagram generations in that directory will read from ~/.diagram-design/profiles/mybrand.md rather than the default configuration.

Safety Mechanisms and Validation Rules

When any customization pathway modifies tokens, the system runs automated guards:

• Contrast Validation: Ensures WCAG AA compliance between ink (text) and paper (background) colors.
• One-Accent Enforcement: Prevents multiple competing focal colors that would dilute visual hierarchy.
• Inversion Rule: Automatically derives dark-theme equivalents for every custom color defined in the light theme.

These checks occur before the final write to style-guide.md or a profile file, preventing inaccessible or chaotic color combinations.

How Customizations Propagate to Diagram Types

All diagram type specifications in type-*.md files consume tokens through semantic role references. For example, a flowchart references accent rather than #ff5722. This architecture means:

• Import commands (commands/import-mermaid.md, commands/import-drawio.md) redraw imported content using the current skin, discarding source colors in favor of your active style-guide.md tokens.
• Multi-series charts access opt-in series palettes defined in style-guide.md under the "Series palette" section, but these remain subordinate to the primary accent token.

Step-by-Step Customization Examples

Switching to a Dark Theme:

# The inversion rule auto-generates dark variants, but you can force dark mode

# by editing the paper/ink values or using a pre-configured profile

diagram-design profile save darkmode

# Edit ~/.diagram-design/profiles/darkmode.md to swap paper/ink defaults

echo "profile: darkmode" > .diagram-design

Listing Available Profiles:

diagram-design profile list

# Output shows all saved slugs: mybrand, darkmode, client-a, etc.

Validating Custom Colors Programmatically:

While the skill auto-validates, you can manually trigger a contrast check after editing:

# After manual edits to style-guide.md, run a generation test

diagram-design generate --type flowchart -- validate

# The skill will warn if WCAG AA standards are violated

Summary

• style-guide.md is the single source of truth for all visual tokens in cathrynlavery/diagram-design.
• Four pathways exist: manual editing, URL-based onboarding (onboarding.md), named profiles (profiles.md), and project markers (.diagram-design file).
• Validation rules enforce WCAG AA contrast and a single-accent policy to maintain accessibility and visual coherence.
• Semantic token architecture ensures changes propagate instantly across architecture diagrams, flowcharts, and radar charts without touching type-specific logic.
• Profiles enable multi-brand workflows by storing snapshots in ~/.diagram-design/profiles/ and binding them via project markers.

Frequently Asked Questions

How do I override the default colors for just one project?

Create a .diagram-design marker file in the project root containing profile: <slug>, where <slug> matches a saved profile name. The skill will load ~/.diagram-design/profiles/<slug>.md instead of the installed style-guide.md, leaving the core skill untouched.

What happens if my custom colors fail accessibility standards?

The skill performs a contrast check (WCAG AA) whenever style-guide.md is modified—whether manually or via onboarding. If the ink color lacks sufficient contrast against paper, the skill pauses the operation and prompts you to adjust the hex values before proceeding.

Can I use multiple accent colors in a single diagram?

No. The system enforces a one-accent rule to maintain visual focus. While multi-series charts can access series palettes defined in style-guide.md, these are opt-in and subordinate to the primary accent token; they cannot override the restriction on focal accents.

Where are custom profiles stored on my system?

Saved profiles reside in ~/.diagram-design/profiles/ as individual .md files (e.g., mybrand.md). You can manage these via the CLI (diagram-design profile save, list, or delete) or manually edit the files; the skill loads them based on the profile: key in project markers or CLI arguments.

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