` and `<desc>` elements - Prefixed IDs to prevent collisions in composite documents These requirements are specified in [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md). ## Motion and Animation Rules Motion is **disabled by default** (`none`). When explicitly enabled, it follows a strict contract defined in [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) with three permitted modes: `reveal`, `step`, and `loop`. The system never injects external scripts or remote assets; only the local [`animation-controller.js`](https://github.com/cathrynlavery/diagram-design/blob/main/animation-controller.js) is permitted. ## Semantic Patterns First When diagrams require specific behaviors (e.g., queue depth, security boundaries), the skill consults [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) before selecting a visual type. These patterns supply behavioral primitives that the layout type then renders, ensuring semantic accuracy over arbitrary aesthetics. ## First-Run Style-Guide Gate On the first diagram in any new project, the system enforces a **first-run gate**. If [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) still contains default tokens, the skill pauses execution and requires explicit onboarding of brand colors or explicit acceptance of defaults, preventing accidental use of placeholder styles. ## Implementation Examples ### Onboarding Brand Colors ```bash # Run the onboarding command to extract brand assets: diagram-design:onboard https://example.com # Tokens are written to: skills/diagram-design/references/style-guide.md ``` This command respects the first-run gate and enforces contrast validation before saving. ### HTML Export with Accessibility Contract ```html <link rel="stylesheet" href="template.css"> <div class="diagram"> <svg width="640" height="480" role="img" aria-labelledby="title desc"> <title id="title">System Architecture

# Diagram Design Core Design System: 10 Key Rules Explained > Explore the 10 key rules of the Diagram Design core design system. Learn about semantic color roles, accent limits, 4px grids, and WCAG AA contrast for consistent, accessible visuals. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: best-practices - Published: 2026-09-08 --- **The Diagram Design core design system enforces an opinionated editorial aesthetic through semantic color roles, strict accent limits, deterministic 4 px grids, and mandatory WCAG AA contrast checks, all validated against [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) by automated CI checks.** The Diagram Design core design system governs every diagram produced by the cathrynlavery/diagram-design repository. Codified primarily in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and validated by [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py), these rules ensure consistent, brandable, and accessible output across all 39 diagram types. ## Semantic Color Roles and Accent Discipline All colors are expressed as named semantic roles rather than hard-coded hex values. The system defines tokens including `paper`, `ink`, `muted`, `accent`, and `link` in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md). The **accent limit rule** restricts the use of accent colors to only **1–2 elements** per diagram. All remaining elements default to `ink` or `muted`, ensuring clear focal points without visual competition. ## Visual Style Constraints The system prohibits shadows entirely and mandates **hair-line borders** using the `rule` or `rule-solid` tokens. Border-radius is capped at **10 px** or omitted entirely, creating a flat, editorial aesthetic that avoids the "AI-generated" appearance. ## Typography Standards Typography is locked to three specific font families defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md): - **Instrument Serif** for titles and headings - **Geist Sans** for node names and primary labels - **Geist Mono** for technical sub-labels and code elements Sizes and weights are baked into the style guide and cannot be overridden arbitrarily. ## Deterministic Spacing and Grid Systems Every coordinate, width, and gap follows a strict **4 px grid system**. This deterministic approach, documented in the layout constraints section of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), ensures diagrams maintain clean proportions and precise alignment across different contexts and diagram types. ## Contrast Safety and Accessibility Before finalizing any diagram, the system performs automated **WCAG AA contrast checks** for `ink` over `paper` combinations. If brand colors fail at diagram text sizes, the skill proposes corrected values during the onboarding flow described in [`references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/onboarding.md). Exported SVGs must include: - `role="img"` attribute - Resolving `aria-labelledby` references - First-child `` and `<desc>` elements - Prefixed IDs to prevent collisions in composite documents These requirements are specified in [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md). ## Motion and Animation Rules Motion is **disabled by default** (`none`). When explicitly enabled, it follows a strict contract defined in [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) with three permitted modes: `reveal`, `step`, and `loop`. The system never injects external scripts or remote assets; only the local [`animation-controller.js`](https://github.com/cathrynlavery/diagram-design/blob/main/animation-controller.js) is permitted. ## Semantic Patterns First When diagrams require specific behaviors (e.g., queue depth, security boundaries), the skill consults [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) before selecting a visual type. These patterns supply behavioral primitives that the layout type then renders, ensuring semantic accuracy over arbitrary aesthetics. ## First-Run Style-Guide Gate On the first diagram in any new project, the system enforces a **first-run gate**. If [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) still contains default tokens, the skill pauses execution and requires explicit onboarding of brand colors or explicit acceptance of defaults, preventing accidental use of placeholder styles. ## Implementation Examples ### Onboarding Brand Colors ```bash # Run the onboarding command to extract brand assets: diagram-design:onboard https://example.com # Tokens are written to: skills/diagram-design/references/style-guide.md ``` This command respects the first-run gate and enforces contrast validation before saving. ### HTML Export with Accessibility Contract ```html <link rel="stylesheet" href="template.css"> <div class="diagram"> <svg width="640" height="480" role="img" aria-labelledby="title desc"> <title id="title">System Architecture Data flow from client to server ``` ### Enabling Optional Motion ```bash # Request motion via natural language: /diagram-design "create sequence diagram with motion" ``` Generated output includes: ```html ``` ## Summary - **Semantic color roles** replace hex values; only 1-2 elements may use the `accent` role - **No shadows** and maximum **10 px border-radius** maintain flat editorial aesthetics - **Typography** is restricted to Instrument Serif, Geist Sans, and Geist Mono - **4 px grid system** governs all spacing and coordinates deterministically - **WCAG AA contrast** is mandatory before token finalization - **Accessible SVGs** require `role="img"`, proper ARIA labeling, and collision-free IDs - **Motion is opt-in only**, restricted to `reveal`, `step`, or `loop` modes without external scripts - **Semantic patterns** drive visual selection before layout rendering - **First-run gate** forces explicit style guide initialization for new projects - **CI validation** via [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py) enforces all rules automatically ## Frequently Asked Questions ### How do I customize colors for my brand in the Diagram Design core design system? Run the `diagram-design:onboard` command with your website URL. The system extracts palette and font data, validates WCAG AA contrast ratios against the extracted values, and writes tokens to [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). You must explicitly confirm or override defaults due to the first-run gate enforced on initial execution. ### Why does the system limit accent colors to only 1-2 elements? The **accent limit rule** prevents visual noise and maintains strict editorial hierarchy. By restricting high-contrast accent colors to primary focal points, the system ensures viewers immediately understand the diagram's structure without cognitive overload, as specified in the design system section of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md). ### What accessibility standards does the Diagram Design core design system enforce? Every exported SVG must pass **WCAG AA contrast** checks for text legibility and include semantic markup: `role="img"`, `aria-labelledby` attributes resolving to first-child `` and `<desc>` elements, and ID prefixes to prevent collisions when multiple diagrams appear on the same page, as defined in [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md). ### Can I add custom animations or JavaScript to diagrams? No. Motion is **disabled by default** and strictly controlled through [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md). When enabled, only the internal [`animation-controller.js`](https://github.com/cathrynlavery/diagram-design/blob/main/animation-controller.js) may be used with the three approved modes (`reveal`, `step`, `loop`). External scripts, CDN links, and remote assets are prohibited to preserve security and performance guarantees.