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

> Customize style-guide.md on first run with Diagram Design. Explore manual editing URL extraction profile creation or default options to define your brand's visual identity.

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

---

**When Diagram Design runs for the first time, it offers four methods to customize [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), pauses execution when it detects unmodified default tokens in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```yaml

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), and writes the new tokens only after you approve the changes.

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) containing the extracted values.

### Create a Named Profile

After manually or automatically editing [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), you can persist the configuration as a named profile. As documented in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

```bash

# 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:

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) customization works during the first run:

- **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)** – Documents the profile system for storing and selecting brand-specific [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) before writing any modifications.

### Can I maintain multiple brand profiles simultaneously?

Yes. After customizing [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) that can be applied to any project referencing it via the profile marker system.