How the First-Run Style Gate Prevents Default-Skinned Diagrams in Branded Projects

The first-run style gate in Diagram Design forces new projects to customize the default color palette (white-smoke paper, jet-black ink, atomic-tangerine accent) before generating any diagram, ensuring branded projects never ship with unintentional default styling.

The cathrynlavery/diagram-design repository implements a mandatory gate to eliminate the risk of shipping diagrams that use the built-in default skin. This mechanism intercepts generation commands until the user explicitly customizes the style guide or selects a valid profile, preventing accidental deployment of the neutral white-smoke and atomic-tangerine palette in branded contexts.

How the First-Run Style Gate Works

The gate operates through three coordinated mechanisms defined in SKILL.md: project-marker detection, token-value validation, and interactive onboarding.

Gate Entry Point and Project Markers

According to the source code in skills/diagram-design/SKILL.md (lines 17–33), the gate triggers whenever a diagram generation command is invoked. The system first checks for a .diagram-design marker file that points to an existing profile. If the repository contains a valid marker referencing any profile—including the built-in default profile—the gate is skipped entirely (SKILL.md#L23–24, references/profiles.md#L79–82).

Default-Skin Detection Logic

If no marker exists or the profile cannot be resolved, the skill reads references/style-guide.md and compares the color tokens (paper, ink, accent) against the shipped defaults: paper #f5f5f5, ink #2d3142, and accent #eb6c36 (atomic-tangerine). When these values remain unchanged from the defaults, the gate pauses execution and blocks diagram rendering until customization occurs (SKILL.md#L25–32).

Interactive Customization Prompt

When the gate detects unchanged defaults, it presents an interactive prompt offering multiple onboarding paths: extracting colors from a website, importing from an installed skill, manually pasting token values, or loading a saved client profile. Selecting any path updates the style-guide.md file, immediately satisfying the gate requirement for the current and all future runs (SKILL.md#L27–31).

Persistence and Profile Resolution

Once customized, the project persists its decision either by writing a leading profile header to the working copy or by creating a valid .diagram-design marker. This action marks the project as having passed the gate, causing subsequent diagram generations to bypass the check entirely (SKILL.md#L31–33).

Configuring the Gate: Practical Examples

The following commands demonstrate how the gate behaves during initial setup, explicit profile selection, and manual customization.

New project triggering the gate:

# 1. Create a new project – the gate will fire because no marker exists yet

$ diagram-design generate diagram.mmd

# → Prompt appears: “This is your first diagram … default (neutral white‑smoke + atomic‑tangerine). Customize?”

Skipping with a branded profile:

# 2. Add a marker that selects a saved profile (e.g., a corporate brand)

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

# Subsequent generation skips the gate

$ diagram-design generate diagram.mmd

# → Diagram is rendered without the first‑run prompt

Explicit default selection:

# 3. Use the built‑in default profile – the gate is also skipped

$ echo "profile: default" > .diagram-design
$ diagram-design generate diagram.mmd

# → No prompt; default‑skin is allowed only when explicitly chosen

Manual customization workflow:

# 4. Manually customize the style guide and save it as a profile

$ diagram-design edit style-guide.md   # change paper, ink, accent values

$ diagram-design save acme‑brand       # creates ~/.diagram-design/profiles/acme‑brand.md

$ echo "profile: acme‑brand" > .diagram-design
$ diagram-design generate diagram.mmd

# → Gate is bypassed because a custom profile is now active

Core Files Controlling Style Enforcement

The gate relies on four key components within the repository:

• SKILL.md – Defines the first-run gate logic and its interactive behavior at lines 17–33.
• references/style-guide.md – Stores the color tokens (paper, ink, accent) that the gate validates against default values.
• references/profiles.md – Documents profile resolution rules, including the exception that profile: default skips the gate.
• .diagram-design – The project marker file that persists the selected profile and signals gate completion.

Summary

• The first-run style gate blocks diagram generation until the default color palette is customized or explicitly acknowledged.
• It detects unmodified default tokens at paper #f5f5f5, ink #2d3142, and accent #eb6c36 in references/style-guide.md.
• Creating a .diagram-design marker with any valid profile value immediately bypasses the gate.
• The gate requires user interaction only once; subsequent runs persist the decision via profile headers or marker files.
• This mechanism ensures branded projects cannot accidentally ship default-skinned diagrams without conscious opt-in.

Frequently Asked Questions

What triggers the first-run style gate in Diagram Design?

The gate triggers when executing a diagram generation command in a project that lacks a .diagram-design marker file and contains unmodified default color tokens in references/style-guide.md. Specifically, when the paper, ink, and accent values match the shipped defaults (#f5f5f5, #2d3142, #eb6c36), the system pauses and prompts for customization before rendering any output.

How do I skip the style gate for a project using the default skin?

To bypass the gate while retaining the default white-smoke and atomic-tangerine palette, create a .diagram-design marker file containing profile: default. According to references/profiles.md (lines 79–82), explicitly selecting the built-in default profile satisfies the gate requirement without requiring color customization, confirming intentional use of the default skin.

Where are custom profiles stored after passing the gate?

When you save a customized style guide as a named profile using diagram-design save <profile-name>, the system creates a Markdown file at ~/.diagram-design/profiles/<profile-name>.md. You then reference this profile by writing profile: <profile-name> to the .diagram-design marker in your project root, which the gate checks before allowing diagram generation.

Can the style gate be disabled globally for all projects?

No, the gate cannot be disabled globally. It is designed to run at least once per project to prevent accidental default-skinned outputs. However, you can automate the bypass by committing a .diagram-design marker with your preferred profile to version control, ensuring team members and CI/CD pipelines never encounter the interactive prompt while maintaining brand consistency.

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