# How to Handle the First-Run Style Gate in Diagram-Design

> Learn to manage the first-run style gate in diagram-design. Customize brand colors before generating diagrams to ensure professional results.

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

---

**The first-run style gate in diagram-design is a safety mechanism that pauses diagram generation when the style-guide still contains default colors (paper #f5f5f5, ink #2d3142, accent #eb6c36), ensuring users customize their brand palette before shipping diagrams.**

The **first-run style gate** prevents accidental use of generic styling in the cathrynlavery/diagram-design repository. When you generate your first diagram in a fresh project, the skill checks whether you have customized the color palette in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) or explicitly chosen to use defaults via a marker file. This gate ensures every diagram aligns with your brand identity rather than shipping with the neutral editorial skin.

## How the First-Run Style Gate Works

In [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (lines 17-33), the skill implements a validation check that compares the current [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) against shipped defaults. If the **paper** (`#f5f5f5`), **ink** (`#2d3142`), and **accent** (`#eb6c36`) values remain unchanged, the gate pauses execution and prompts you to customize the palette before continuing.

The gate triggers only when:
- The `.diagram-design` marker file is absent or specifies `profile: default`
- The style-guide tokens match the default exactly
- No valid custom profile is detected

## Bypassing the Gate with Profile Markers

According to [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) (lines 79-82), you can skip the gate by creating a marker file at the repository root. The `.diagram-design` file signals your intent to use either the default profile or a custom one, causing the skill to skip the validation pause.

To bypass using the default profile intentionally:

```bash
echo "profile: default" > .diagram-design

```

To use a named profile and skip the gate:

```bash
echo "profile: acme-corp" > .diagram-design

```

When the marker specifies any valid profile slug, the skill loads that profile directly from `~/.diagram-design/profiles/` and proceeds without prompting.

## Customizing the Style Guide to Remove the Gate

If you modify any token in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) to differ from the shipped defaults, the gate considers the guide **custom-unsaved** and skips the pause. This allows you to proceed with custom colors and optionally save them as a reusable profile.

Complete workflow to customize and persist:

```bash

# 1. Edit the style guide with brand-specific tokens

vi references/style-guide.md

# Change paper, ink, and accent values to your brand colors

# 2. Save the configuration as a reusable profile

diagram-design profile save acme-corp

# Creates ~/.diagram-design/profiles/acme-corp.md

# 3. Create project marker for automatic loading

echo "profile: acme-corp" > .diagram-design

```

Subsequent diagram generations will load the `acme-corp` profile automatically and never trigger the first-run gate.

## Handling Malformed Markers

If the `.diagram-design` marker contains malformed content, the skill falls back to analyzing the style-guide. Profile slugs must match the regular expression `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`. Spaces or invalid characters cause the skill to ignore the marker and proceed with the default check.

Example of an invalid marker:

```text

# .diagram-design

profile: acme corp

```

This produces the error: "Invalid marker content – slug must match `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`. Ignoring marker and falling back to style‑guide check." To resolve, replace spaces with hyphens or remove the marker entirely to let the style-guide gate run.

## Summary

- The first-run style gate pauses diagram generation when [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) contains default colors (paper #f5f5f5, ink #2d3142, accent #eb6c36)
- Create a `.diagram-design` marker with `profile: default` to bypass the gate intentionally without customizing colors
- Use custom profile slugs in the marker to skip the gate and load branded settings automatically from `~/.diagram-design/profiles/`
- Modify any value in the style-guide to trigger custom-unsaved mode, allowing you to save the configuration as a named profile
- Malformed markers fall back to style-guide validation and display clear regex validation errors referencing the slug pattern

## Frequently Asked Questions

### How do I permanently disable the first-run style gate?

Create a `.diagram-design` marker file in your repository root containing `profile: default`. According to the source code in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) (lines 79-82), this signals that the default palette is intentional, causing the skill to bypass the gate permanently for that project.

### What are the exact default colors that trigger the style gate?

The gate specifically checks for **paper** `#f5f5f5`, **ink** `#2d3142`, and **accent** `#eb6c36` in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md). If all three values match these shipped defaults, the gate pauses and prompts for customization as implemented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (lines 17-33).

### Can I recover if I accidentally dismissed the style gate prompt?

If you dismissed the gate by accepting defaults, the gate will not reappear during the current run. To force customization later, manually edit [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) to change any color token, then run `diagram-design profile save [name]` to persist your brand settings for future diagrams.

### What is the required format for profile names in the marker file?

Profile slugs must match the regular expression `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, meaning lowercase alphanumeric characters separated by single hyphens. Spaces and uppercase letters cause the skill to ignore the marker and fall back to the style-guide validation logic with a clear error message.