Options for Customizing style-guide.md on First Run in Diagram Design

When Diagram Design runs for the first time, it offers four methods to customize style-guide.md: manual file editing, URL-based brand extraction, named profile creation, or accepting the default editorial palette.

The cathrynlavery/diagram-design repository centralizes visual branding in a single style-guide.md file that controls colors, typography, and tokens for all 39 diagram types. Understanding your options for customizing style-guide.md on first run ensures your diagrams inherit the correct brand identity from the start instead of using the built-in defaults.

Four Customization Methods Available on First Run

The onboarding workflow, defined in skills/diagram-design/references/onboarding.md, pauses execution when it detects unmodified default tokens in style-guide.md. At this point, you can choose from four distinct approaches to apply your brand's visual language.

Edit style-guide.md Directly

The fastest method for ad-hoc branding is manually replacing the default token table in skills/diagram-design/references/style-guide.md. The file ships with an editorial palette using paper #f5f5f5, ink #2d3142, and accent #eb6c36, which you can overwrite with your own hex values.

# Example: Manual edit of style-guide.md

paper:   "#ffffff"   # white background

ink:     "#111111"   # dark text

accent:  "#ff6600"   # brand orange

muted:   "#888888"   # secondary text

This approach requires no additional commands—simply save the file and the next diagram generation will use your custom tokens.

Run the URL-Based Onboarding Flow

For automatic extraction of existing brand colors, provide a URL to the onboarding command. According to the source code in skills/diagram-design/references/onboarding.md, the skill extracts the site's palette, runs contrast checks, displays a diff against the current style-guide.md, and writes the new tokens only after you approve the changes.

# Example: Run the URL-based onboarding flow

$ diagram-design onboarding url https://example.com

# → the skill extracts the site’s palette, updates style-guide.md,

#   shows a diff, and asks for confirmation before writing.

This method creates a new "Custom tokens" section in style-guide.md containing the extracted values.

Create a Named Profile

After manually or automatically editing style-guide.md, you can persist the configuration as a named profile. As documented in skills/diagram-design/references/profiles.md, profiles are stored as individual markdown files in ~/.diagram-design/profiles/<slug>.md, allowing one Diagram Design installation to serve multiple clients without repeatedly editing the shared style-guide.md.

# Example: Save the edited file as a profile

$ diagram-design profile save my-brand

# → creates ~/.diagram-design/profiles/my-brand.md

To use a specific profile in a project, create a .diagram-design marker file at the project root:

# Example: Use a profile in a project

echo "profile: my-brand" > .diagram-design

The skill reads this marker and applies the corresponding profile's tokens instead of the default style-guide.md.

Accept the Default Editorial Palette

If you skip customization, the skill continues using the built-in editorial palette. This option suits quick prototyping scenarios where you plan to customize later, though all 39 diagram types will render with the default paper, ink, and accent colors until you modify the configuration.

Key Files in the Customization System

Several files govern how style-guide.md customization works during the first run:

• skills/diagram-design/references/style-guide.md – The central token table that serves as the single source of truth for colors and typography across all diagram types.

• skills/diagram-design/references/onboarding.md – Defines the onboarding workflow, including the manual token acceptance process and URL-based extraction with diff viewing.

• skills/diagram-design/references/profiles.md – Documents the profile system for storing and selecting brand-specific style-guide.md snapshots via named profiles.

• ~/.diagram-design/profiles/<slug>.md – The storage location for saved profiles on your local system.

• .diagram-design – A project-level marker file that specifies which profile to use via the profile: <slug> directive.

Summary

• Manual editing of skills/diagram-design/references/style-guide.md provides immediate control over tokens like paper, ink, accent, and muted colors.
• URL-based extraction automatically pulls brand colors from a website and writes them to a new "Custom tokens" section after your approval.
• Named profiles let you save customized style-guide.md versions to ~/.diagram-design/profiles/ and switch between them using .diagram-design markers.
• Default acceptance allows rapid prototyping using the built-in editorial palette (paper #f5f5f5, ink #2d3142, accent #eb6c36).

Frequently Asked Questions

What happens if I skip customization during the first run?

If you choose not to customize style-guide.md, Diagram Design proceeds with the default editorial palette defined in the source code. Your diagrams will use paper #f5f5f5, ink #2d3142, and accent #eb6c36 until you later modify the configuration file manually or run the onboarding flow.

How do I extract brand colors from an existing website?

Run the URL-based onboarding command with your brand's website URL: diagram-design onboarding url https://example.com. The skill analyzes the site's CSS, extracts the dominant palette, runs contrast accessibility checks, and presents a diff of the proposed changes to style-guide.md before writing any modifications.

Can I maintain multiple brand profiles simultaneously?

Yes. After customizing style-guide.md, save the configuration as a named profile using diagram-design profile save <slug>. Store multiple profiles in ~/.diagram-design/profiles/, then activate specific ones per project by creating a .diagram-design file containing profile: <slug> in the project root.

Where does Diagram Design store saved profiles?

Saved profiles reside in the ~/.diagram-design/profiles/ directory as individual markdown files named <slug>.md. Each file represents a complete snapshot of a customized style-guide.md that can be applied to any project referencing it via the profile marker system.

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