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

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 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 (lines 17-33), the skill implements a validation check that compares the current 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 (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:

echo "profile: default" > .diagram-design

To use a named profile and skip the gate:

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

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

# .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 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 (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. If all three values match these shipped defaults, the gate pauses and prompts for customization as implemented in 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 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.

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