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

> Discover how the first-run style gate in Diagram Design stops default-skinned diagrams by requiring explicit customization before generation.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: internals
- Published: 2026-08-20

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (lines 17-33). The comparison ensures that a project cannot slip through with an untouched, generic palette.

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (lines 25-28):

```markdown
> 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```yaml

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.