How the First-Run Style Gate Prevents Default-Skinned Diagrams in Diagram Design

The first-run style gate forces an explicit customization decision before any diagram is generated, ensuring projects cannot silently ship with the generic default colour and typography skin.

Diagram Design ships with a neutral default skin (paper #f5f5f5, accent #eb6c36, and other semantic roles). To prevent projects from unintentionally publishing diagrams that still use this generic look, the skill implements a first-run style-guide gate that checks every new project before any diagram is emitted. According to the cathrynlavery/diagram-design source code, the gate is implemented in skills/diagram-design/SKILL.md and relies on profile markers and token comparison to block silent default usage.

How the First-Run Style Gate Detects Unconfigured Projects

When a diagram request comes in, the skill looks for a project-level marker file at .<project-root>/.diagram-design. The profile resolution rules in skills/diagram-design/references/profiles.md (lines 71-81) define how this file is evaluated.

If the marker specifies a valid profile that exists, or explicitly declares profile: default, the gate is bypassed entirely. In this case, the skill assumes the profile has already been vetted and does not need to interrupt the user.

Default-Skin Detection Logic

If no valid marker is present, the skill proceeds to inspect the installed references/style-guide.md. It reads the semantic-role values — such as paper, ink, and accent — and compares them against the shipped defaults.

When all tokens match the shipped defaults, the gate triggers. This logic is documented in the first-time setup section of skills/diagram-design/SKILL.md (lines 17-33). The comparison ensures that a project cannot slip through with an untouched, generic palette.

# Simplified detection logic used internally

if all(token == shipped_default for token in style_guide.tokens):
    prompt_user_to_customize()

The User Prompt and Onboarding Flow

Once triggered, the gate pauses generation and presents a clear message asking the user to choose a path forward. The exact prompt text lives in skills/diagram-design/SKILL.md (lines 25-28):

> This is your first diagram in this project. The style guide is still at the default...
> (a) pull from your website URL
> (b) extract from an installed skill
> (c) extract from a local folder / design-system directory
> (d) paste tokens manually
> (e) proceed with the default for now
> (f) load a saved client profile

The options cover full customization, loading a saved profile, or explicitly accepting the defaults. No diagram is emitted until the user selects one of these paths.

Disabling the Gate After First Run

If the user chooses any option other than "proceed with default", the onboarding flow defined in references/onboarding.md runs, or the user can save the customised guide as a named profile. After successful customization — or after an explicit acceptance of the defaults — the gate is disabled for subsequent runs.

As noted in skills/diagram-design/SKILL.md (lines 31-33), the presence of a leading profile header in the working copy signals that the gate has been cleared. The project marker ensures the check is only performed on the very first run.

# Example marker that skips the gate on future runs

profile: acme  # points to ~/.diagram-design/profiles/acme.md

Summary

• The first-run style gate blocks diagram generation when no project marker is found.
• It compares references/style-guide.md tokens against shipped defaults to detect unmodified skins.
• The user must explicitly customize, load a profile, or consciously accept defaults via the prompt in SKILL.md.
• After the first decision, a profile header or marker file disables the gate permanently for that project.

Frequently Asked Questions

What happens if I explicitly want to use the default skin?

You can bypass the gate by creating a .<project-root>/.diagram-design marker file with profile: default. This tells the skill you have consciously chosen the default. The explicit declaration satisfies the gate logic in profiles.md and prevents future interruptions in this project.

Where does Diagram Design store saved client profiles?

Saved profiles are stored as individual markdown files under ~/.diagram-design/profiles/. The profile resolution rules in skills/diagram-design/references/profiles.md map the name you provide in the marker to this directory.

Does the gate check every time I generate a diagram?

No. The check only runs once per project. After you make a decision and the profile header is written to the working copy, the gate is disabled for all subsequent diagram requests in that project.

Which file contains the shipped default token values?

The shipped default values for semantic roles like paper, ink, and accent are defined in references/style-guide.md. These defaults include paper #f5f5f5 and accent #eb6c36, and the gate compares your active tokens against them to decide whether to interrupt generation.

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