Diagram Design Core Design System: 10 Key Rules Explained

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 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 and validated by 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.

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:

• 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, 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.

Exported SVGs must include:

• role="img" attribute
• Resolving aria-labelledby references
• First-child <title> and <desc> elements
• Prefixed IDs to prevent collisions in composite documents

These requirements are specified in 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 with three permitted modes: reveal, step, and loop. The system never injects external scripts or remote assets; only the local 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 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 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

# 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

<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</title>
    <desc id="desc">Data flow from client to server</desc>
    <!-- Uses semantic color roles; accent limited to 1-2 elements -->
    <rect x="50" y="50" width="120" height="60"
          fill="var(--paper)" stroke="var(--ink)"/>
    <rect x="250" y="50" width="120" height="60"
          fill="var(--accent-tint)" stroke="var(--accent)"/>
  </svg>
</div>

Enabling Optional Motion

# Request motion via natural language:

/diagram-design "create sequence diagram with motion"

Generated output includes:

<script type="module">
  import { play } from "./animation-controller.js";
  play({ mode: "step", steps: 5 });
</script>

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

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 <title> and <desc> elements, and ID prefixes to prevent collisions when multiple diagrams appear on the same page, as defined in 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. When enabled, only the internal 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.

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