# What Is the First-Run Style Guide Gate and How Does It Enforce Customization

> Understand the first-run style guide gate in cathrynlavery/diagram-design. Learn how this safeguard ensures custom style profiles before diagram generation, preventing default outputs and promoting unique designs.

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

---

**The first-run style guide gate is a safeguard that blocks diagram generation when the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) has not been customized, forcing users to create a deliberate style profile before any output is produced.**

This mechanism ensures that every diagram generated by `cathrynlavery/diagram-design` reflects intentional design decisions rather than accidental defaults. The gate lives in the project's core definition and acts as a quality checkpoint during the initialization workflow.

## How the First-Run Gate Detects Pristine Style Guides

The gate evaluates two specific conditions to determine whether a style guide has been customized. Both must be true for the gate to trigger:

1. **No active profile header** — the working copy of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) lacks a leading profile header block that identifies a custom configuration.
2. **All semantic-role values and typography tokens match shipped defaults** — the file's content is byte-for-byte identical to the pristine version distributed with the plugin.

When these conditions converge, the generation pipeline executes the **first-time setup gate** documented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md). This interrupts normal processing and launches an onboarding flow that requires profile creation.

## Where the Gate Logic Is Implemented

The gate's behavior is distributed across three critical files in the repository:

| File Path | Purpose |
|-----------|---------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Contains the first-time setup gate implementation invoked on pristine style guides |
| [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) | Defines resolution rules including the "skip the first-run gate" clause for the built-in `default` profile |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | The shipped default style guide used as the comparison baseline |

The logic operates at the intersection of these definitions. The [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file houses the actual gate execution, while [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) establishes when the gate can be legally bypassed.

## Bypassing the Gate with Explicit Profile Selection

Users can skip the first-run style guide gate entirely by creating a project marker file that explicitly selects the built-in `default` profile. According to the resolution rules in [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) (lines 79–82), when `<project-root>/.diagram-design` contains `profile: default`, the gate is **skipped** and generation proceeds with the unmodified default style guide.

```yaml

# Example: .diagram-design marker file that bypasses the gate

profile: default

```

This explicit opt-out preserves the gate's enforcement for typical workflows while providing an escape hatch for scenarios requiring rapid prototyping or strict default adherence.

## Gate Execution in Practice

The enforcement mechanism follows a straightforward decision tree. Pseudocode illustrating the core logic:

```python

# Core first-run gate logic as implemented in the skill definition

if not style_guide_has_header() and style_guide_is_pristine():
    # Trigger onboarding defined in SKILL.md

    run_first_time_setup_gate()
else:
    # Normal generation path

    generate_diagram()

```

When the gate triggers, users must either create a new profile or run a structural check. This ensures that subsequent invocations encounter a customized style guide with a valid header block.

## What a Customized Style Guide Header Looks Like

Adding a profile header transforms the style guide from pristine to customized, permanently satisfying the gate's conditions. A valid header uses HTML comment syntax with structured metadata:

```markdown
<!-- diagram-design-profile
name: Acme Corp
slug: acme
source-url: https://acme.example.com
created: 2026-08-14
updated: 2026-08-14
notes: Custom brand colours
-->

# Style Guide

...

```

Once this header exists, `style_guide_has_header()` returns true and the gate yields to normal generation regardless of content modifications elsewhere in the file.

## Enforcement Guarantees and Design Philosophy

The first-run style guide gate enforces customization through **blocking rather than warning**. Unlike optional linting or post-hoc validation, this gate operates as a hard dependency in the generation pipeline. No diagram output is produced until the user demonstrates intent by creating or selecting a profile.

This design choice reflects the project's philosophy that visual consistency requires deliberate configuration. The default style guide serves as a template and teaching tool, not a production-ready fallback.

## Summary

- The **first-run style guide gate** runs during initial diagram generation to detect untouched [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) files.
- It triggers when no profile header exists **and** all values match the shipped defaults.
- The gate is **defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)** and **documented in [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md)** with bypass rules for explicit `default` profile selection.
- Users bypass enforcement by adding a profile header or creating a `.diagram-design` marker with `profile: default`.
- The mechanism ensures every production diagram derives from intentional style configuration rather than unexamined defaults.

## Frequently Asked Questions

### How do I know if the first-run gate has triggered?

The gate produces an explicit onboarding prompt that interrupts generation. If you see a message requesting profile creation or structural check rather than diagram output, the gate has activated. Successful generation without this interruption indicates either prior customization or explicit default profile selection.

### Can I permanently disable the first-run gate?

Not globally. The gate is intrinsic to the skill's initialization logic. You can only bypass it per-project by either customizing the style guide with a profile header or explicitly selecting `profile: default` in your `.diagram-design` marker file. These bypasses must be reestablished for each new project root.

### What happens if I edit the style guide without adding a profile header?

Partial modifications without a header will satisfy condition 2 (no longer pristine) but fail condition 1 (still no header). In this intermediate state, behavior depends on version-specific implementation details. Best practice is to add the profile header immediately when beginning customization to ensure predictable gate resolution.

### Where is the pristine default style guide located?

The comparison baseline lives at [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) in the repository. This file ships with the plugin and serves as the reference against which your working copy is evaluated. Never modify this reference file directly; create your customized profile instead.