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

> Understand the first run style guide gate in diagram design. This pre-output validation ensures accessibility and semantic rules are met before rendering.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md), the system automatically loads [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```text
accent fails contrast on paper

```

The user must adjust the skin values—either by editing the token configuration directly or re-running [`onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md)—before the diagram can be produced.

## Source Files Implementing the Gate

| File | Role |
|------|------|
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding.md). According to the cathrynlavery/diagram-design source code, the system loads [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and executes the validation pipeline in [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.