How the First-Run Style-Guide Gate Works in Diagram Design

The first-run style-guide gate is a mandatory pre-output validation that checks every new diagram against accessibility constraints, semantic token rules, and single-accent requirements defined in style-guide.md before allowing rendering to complete.

The Diagram Design skill in the cathrynlavery/diagram-design repository enforces visual consistency through automated validation. Whenever you generate your first diagram or change the skin via onboarding.md, the first-run style-guide gate intercepts the output to verify that your color tokens meet WCAG AA standards and adhere to the semantic design system.

Validation Rules Enforced by the Gate

According to the source code in skills/diagram-design/references/style-guide.md, the gate executes six specific checks against the token tables before permitting diagram generation.

Contrast Requirements (Lines 76-77)

The gate verifies that ink meets WCAG AA contrast ratios on paper, and that muted meets AA standards on paper for text sized at least 11 pixels. This ensures legibility across both light and dark themes and prevents accessibility failures on the initial render.

Single Accent Rule (Line 77)

Only one accent token may be used per diagram. This constraint preserves focal signal integrity and prevents "rainbow" palette fragmentation that would dilute visual hierarchy.

Series Palette Enforcement (Lines 38-48)

Non-focal series colors must be selected exclusively from the series-* token family. The gate blocks any additional hues outside this defined palette, ensuring multi-series charts do not introduce unauthorized accent colors.

Automatic Inversion Validation (Lines 34-36)

Light-mode rgba values are automatically flipped for dark mode rendering. The gate verifies that opacity-based colors render correctly against dark paper tokens, maintaining visual consistency across theme switches.

Token-Only Design Contract (Line 15)

All diagram colors must reference semantic roles (paper, ink, accent) rather than raw hexadecimal values. This centralizes styling so a single token change propagates across all diagram types without manual code updates.

Pre-Output Taste Gate (Lines 70-71)

After any skin change, the gate performs a final sanity check confirming that the chosen accent token still reads as "focal" against the current paper token. This prevents subtle contrast degradation when switching between brand palettes.

Execution Flow of the Gate

The validation process follows a strict three-phase pipeline implemented in skills/diagram-design/scripts/self_check.py.

First-Run Detection

When a diagram is generated for the first time, or when the user invokes the skill after running onboarding.md, the system automatically loads style-guide.md from the references directory. This triggers the validation sequence before any SVG or HTML emission begins.

Validation Processing

The engine reads the token tables and applies contrast formulas, the one-accent rule, and the inversion rule. It then executes the pre-output taste gate to confirm the visual contract between semantic tokens meets the design system requirements.

Error Handling and Recovery

If any constraint fails, the skill aborts rendering immediately and returns a specific error message identifying the offending token. For example:

accent fails contrast on paper

The user must adjust the skin values—either by editing the token configuration directly or re-running onboarding.md—before the diagram can be produced.

Source Files Implementing the Gate

File	Role
skills/diagram-design/references/style-guide.md	Defines all tokens, constraints, and the pre-output taste gate logic (lines 15, 34-36, 38-48, 70-77).
skills/diagram-design/scripts/self_check.py	Reads the style-guide and invokes the gate before emitting SVG/HTML output.
skills/diagram-design/references/onboarding.md	Guides users through skin changes and automatically triggers the gate after new palette values are written.

Summary

• The first-run style-guide gate validates every new diagram against style-guide.md before rendering occurs, preventing broken first renders.
• It enforces WCAG AA contrast requirements between ink/muted and paper tokens to guarantee text legibility.
• Only one accent token is permitted per diagram to maintain clear focal hierarchy and prevent visual noise.
• The gate ensures token-only design using semantic roles rather than raw hex values, centralizing all visual decisions.
• Automatic inversion of rgba values is verified for dark mode compatibility, ensuring opacity-based colors look correct on dark paper.
• Validation failures produce specific error messages pointing to the exact offending token, requiring skin adjustment before output generation resumes.

Frequently Asked Questions

What triggers the first-run style-guide gate?

The gate activates when generating your first diagram after skill installation, or immediately after changing the skin via onboarding.md. According to the cathrynlavery/diagram-design source code, the system loads style-guide.md and executes the validation pipeline in self_check.py before allowing any output to proceed.

What happens if my colors fail the style-guide gate?

If validation fails—such as when the accent token lacks sufficient contrast against paper (violating lines 76-77)—the skill aborts rendering and returns a descriptive error message. You must correct the token values in your skin configuration or re-run onboarding.md to resolve the violation before the diagram can be generated.

How does the gate handle dark mode colors?

The gate implements an inversion rule (lines 34-36 in style-guide.md) that automatically flips light-mode rgba values for dark mode rendering. During validation, the gate verifies these inverted values maintain proper contrast relationships against dark paper tokens, ensuring visual consistency across theme variations.

Can I bypass the style-guide validation?

No. The gate is a mandatory pre-output check integrated into the Diagram Design skill's rendering pipeline. By enforcing token-only design (line 15) and blocking raw hex values, the gate maintains accessibility standards and brand consistency across all diagram outputs in the cathrynlavery/diagram-design repository.

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