# How the First-Run Style-Guide Gate Works in diagram-design

> Discover how the first-run style-guide gate in diagram-design protects your visual brand by ensuring custom accent colors are set before diagram generation.

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

---

**The first-run style-guide gate is a mandatory safeguard in diagram-design that blocks diagram generation until the project's visual brand is customized, checking whether the `accent` color token in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) still equals the default `#eb6c36`.**

This article explains the complete mechanics of the gate as implemented in the `cathrynlavery/diagram-design` repository. The gate ensures every new project establishes a unique visual identity before any SVG or diagram output is produced, preventing accidental use of generic default styling across generated artifacts.

## Where the Gate Lives in the Codebase

The first-run style-guide gate is defined in **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** at **section 0**, making it the very first step in the skill's execution workflow. This placement guarantees that no downstream processing—philosophy selection, layout algorithms, or render generation—can proceed until the gate is satisfied.

The gate's detection logic is simple but effective. It inspects [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) for three shipped default tokens:

- `paper: #f5f5f5`
- `ink: #2d3142`
- `accent: #eb6c36`

If all three remain unchanged, execution pauses and the user receives the customization prompt.

## The Five Customization Options

When triggered, the gate presents five distinct paths for establishing brand identity. These options are enumerated in **lines 23-34 of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)**:

| Option | Method | Description |
|--------|--------|-------------|
| **(a)** | URL extraction | Pull a complete color palette from a website URL |
| **(b)** | Skill import | Extract tokens from an already-installed skill |
| **(c)** | Folder scan | Ingest a local design-system folder |
| **(d)** | Manual entry | Paste tokens directly via interactive input |
| **(e)** | Default acceptance | Explicitly proceed with generic defaults (requires confirmation) |

Each option routes to a dedicated handler documented in **[`references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/onboarding.md)**. The URL-based flow is defined in [§ URL](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#url), skill-based in [§ Skill](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#skill), and folder-based in [§ Folder](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md#folder).

## How Completion Is Detected

The gate uses a single-token heuristic to detect customization. As noted in **line 35 of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)**, the system considers a repository customized when the `accent` token no longer equals `#eb6c36`.

This approach is intentionally lightweight. The `accent` color is the most visually distinctive brand element, making it the least likely token to remain at default by accident. Once changed, the gate stores a passed-state marker, allowing all subsequent skill invocations to skip directly to the main workflow.

## The Gate's Role in the Pipeline

After passing the first-run style-guide gate, the skill proceeds through its standard phases: philosophy selection, diagram type selection, layout computation, and final render. Every downstream step consumes tokens from [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) as the **single source of truth**.

As documented in **[[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) § "Design System"](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md#5-design-system)**, this centralized token architecture means:

- SVG primitives read color values directly from the style guide
- Typography handlers in `type-*.md` files reference the same font stacks
- Connector geometry and spacing inherit from the design system

## Implementation Reference

The gate's logic is embedded in helper scripts within the `scripts/` directory. The **[`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py)** module executes the gate check before any diagram generation occurs, integrating it into the CLI and agent pipeline.

```python

# Pseudocode mirroring the gate's decision logic

import yaml
import pathlib

STYLE_GUIDE = pathlib.Path('skills/diagram-design/references/style-guide.md')

def load_style_tokens():
    data = yaml.safe_load(STYLE_GUIDE.read_text())
    return data.get('tokens', {})

def is_customized():
    tokens = load_style_tokens()
    # Default accent is #eb6c36; any deviation indicates customization

    return tokens.get('accent', '').lower() != '#eb6c36'

if not is_customized():
    print("⚠️  First-run style-guide gate: defaults detected.")
    # Trigger the five-option onboarding prompt

else:
    print("✅  Style guide customized — proceeding to diagram generation.")

```

The prompt handling dispatches to the appropriate onboarding flow:

```python
options = {
    "a": "pull palette from URL",
    "b": "extract from installed skill", 
    "c": "scan local design-system folder",
    "d": "paste tokens manually",
    "e": "accept defaults"
}
choice = input("Choose an option (a-e): ").strip().lower()
if choice in options:
    run_onboarding_flow(choice)  # Delegates to references/onboarding.md handlers

```

## Key Files in the Gate System

Understanding these four files is essential for working with or extending the gate:

- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** — Master skill definition containing the gate specification and workflow orchestration
- **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)** — Centralized token store (paper, ink, accent, typography) inspected by the gate
- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)** — Concrete procedures for all five customization paths
- **[`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py)** — CLI integration point that executes the gate before diagram generation

## Summary

- The **first-run style-guide gate** in diagram-design blocks all diagram generation until visual branding is established
- It detects uncustomized projects by checking if `accent` still equals `#eb6c36` in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md)
- Users receive **five onboarding options**: URL extraction, skill import, folder scan, manual entry, or explicit default acceptance
- The gate delegates implementation details to [`references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/onboarding.md) and executes via [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py)
- Once passed, [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) becomes the single source of truth for all downstream design decisions

## Frequently Asked Questions

### What happens if I choose option (e) to accept the defaults?

The gate will store your explicit confirmation and never prompt again, but your diagrams will use the generic `#eb6c36` accent color. This is generally discouraged for production projects where brand differentiation matters, though it may be acceptable for personal or experimental work.

### Can I re-trigger the gate after passing it initially?

Yes. Manually setting the `accent` token back to `#eb6c36` in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) will cause [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) to detect an uncustomized state on the next run, presenting the full onboarding menu again. This is useful for rebranding or correcting initial choices.

### Why does the gate only check the `accent` token instead of all three defaults?

The `accent` token is chosen as the canary because it is the most visually distinctive and least likely to remain at default by coincidence. This keeps detection logic minimal while maintaining reliable differentiation between generic and customized branding.

### Does the gate affect existing diagrams in the repository?

No. The gate only controls whether *new* diagram generation can proceed. Existing rendered SVGs or exported assets retain their original styling. To propagate new brand tokens to existing diagrams, you must regenerate them through the normal skill workflow after passing the gate.