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

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 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 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 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:

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. The URL-based flow is defined in § URL, skill-based in § Skill, and folder-based in § Folder.

How Completion Is Detected

The gate uses a single-token heuristic to detect customization. As noted in line 35 of 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 as the single source of truth.

As documented in [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 module executes the gate check before any diagram generation occurs, integrating it into the CLI and agent pipeline.

# 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:

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 — Master skill definition containing the gate specification and workflow orchestration
• skills/diagram-design/references/style-guide.md — Centralized token store (paper, ink, accent, typography) inspected by the gate
• skills/diagram-design/references/onboarding.md — Concrete procedures for all five customization paths
• 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
• 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 and executes via scripts/self_check.py
• Once passed, 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 will cause 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.

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