Editorial Quality Standards for Diagrams Generated by Diagram Design: The Complete Style Guide

Diagram Design enforces a tightly-controlled visual language defined in a centralized Style Guide, requiring semantic color tokens, a strict one-accent maximum per diagram, 4px grid alignment, and a three-family typography stack to ensure every output resembles a polished editorial illustration.

The cathrynlavery/diagram-design repository provides a systematic approach to transforming raw diagrams from Mermaid, Excalidraw, or Draw.io sources into publication-ready visuals. These editorial quality standards guarantee that every generated diagram maintains consistent visual hierarchy, accessibility compliance, and professional polish suitable for high-end editorial layouts.

Semantic Color System and Tokens

All colors in Diagram Design are referenced by semantic roles rather than raw hex values, creating a single source of truth defined in [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L11-L27).

Core color tokens include:

• paper – background canvas
• ink – primary content and lines
• muted – secondary labels and annotations
• accent – the sole focal highlight color

Changing a token value updates every diagram automatically across all diagram types. For multi-series charts that legitimately require multiple colors—currently limited to radar charts only—the system provides a curated series-1 through series-5 palette, while reserving accent specifically for the focal series.

The 1-Accent Rule and Focal Node Treatment

Diagram Design mandates the "1-accent" rule: at most one accent (or accent-tint) may appear per diagram. This accent marks the editorial focal point, such as the most important node, line, or flow. Adding a second accent dilutes the visual signal and constitutes a standards violation.

According to [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L53-L56), nodes marked as focal receive an accent-tint fill and an accent stroke. The standard permits a maximum of two focal nodes per diagram to maintain visual clarity and prevent competing focal points.

Grid, Spacing, and Typography Standards

4px Grid System

All coordinates, sizes, and gaps must be multiples of 4 px (grid = 4). This constraint, defined at lines 45–46 of [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L45-L46), produces a clean, rhythmical layout and simplifies automated verification tooling.

Three-Family Typography Stack

The system enforces a strict typographic hierarchy using three specific typefaces:

• title – Instrument Serif at 1.75 rem for page headings
• node-name – Geist at 12 px, weight 600 for primary labels
• sublabel – Geist Mono at 9 px for ports, protocols, and URLs

Additional roles such as eyebrow, arrow-label, and callout are defined in the same file to ensure consistent information density across all diagram types.

Accessibility and Contrast Requirements

Diagram Design enforces WCAG AA contrast standards for legibility across both light and dark skins. As documented at lines 174–177 of [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L174-L177):

• ink must meet WCAG AA contrast on paper
• muted must meet AA contrast on paper for text sized 11 px or larger

These guarantees ensure diagrams remain readable in various display contexts, from documentation to presentation slides.

From Import to Editorial: The Transformation Pipeline

The import references ([import-mermaid.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md#L3-L4), import-excalidraw.md, and import-drawio.md) explicitly state that a one-to-one node mapping is not an editorial diagram. Instead, the skill must re-layout, re-style, and apply the full standards suite to raw source files.

Each diagram type ships with a full-editorial HTML example (e.g., [assets/example-scatter-full.html](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-scatter-full.html)) that demonstrates the complete container framing, summary cards, and optional footer. These files illustrate the final editorial layout that the skill aims to produce, distinguishing raw technical diagrams from publication-ready illustrations.

An optional 22 × 22 px dot pattern is available for "hero-style" long-form editorial diagrams, though the default background remains a clean paper fill.

Practical Implementation: Code Examples

The following YAML demonstrates how to apply editorial standards to a scatter plot source:

# diagram-design.yaml – Mermaid source converted to editorial diagram

type: scatter
title: Service Latency Risks
data:
  - name: api-gateway
    x: 120
    y: 0.02
    focal: true        # ← accent applied (1-accent rule)

  - name: auth-service
    x: 95
    y: 0.01
  - name: cache
    x: 60
    y: 0.005
style:
  paper: paper          # semantic tokens

  ink: ink
  accent: accent
  muted: muted

Execute the transformation via the CLI:

diagram-design import-mermaid my-diagram.mmd --type scatter --output diagram.svg

The generated SVG will:

• Use token colors (paper, ink, accent) from the style guide
• Apply accent-tint fill and accent stroke to the api-gateway focal node
• Respect the 4 px grid for all coordinates and spacing
• Apply the three-family typography stack automatically
• Wrap the chart in the full editorial container when using the --full flag

Summary

• Centralized Style Guide: All visual standards live in style-guide.md, creating a single source of truth for colors, typography, and spacing.
• Semantic Tokens: Colors reference roles (paper, ink, accent) rather than hex values, enabling global updates.
• 1-Accent Maximum: Only one accent color per diagram maintains clear visual hierarchy; focal nodes receive special treatment.
• 4px Grid: All measurements use multiples of 4px for rhythmic, verifiable layouts.
• Accessibility First: WCAG AA contrast requirements ensure legibility across contexts.
• Editorial Pipeline: Raw imports require complete re-layout and styling; full-editorial examples demonstrate target output quality.

Frequently Asked Questions

What is the 1-accent rule in Diagram Design?

The 1-accent rule restricts each diagram to a maximum of one accent color (or accent-tint) to mark the editorial focal point. According to [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L74-L82), adding multiple accents dilutes the visual signal and violates the standard. Nodes marked as focal may use the accent color, with a hard limit of two focal nodes per diagram.

How does Diagram Design ensure accessibility in generated diagrams?

Diagram Design enforces WCAG AA contrast ratios as defined in [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md#L174-L177). The ink token must meet AA contrast on paper backgrounds, while muted must meet AA standards for text sized 11 px or larger. These requirements guarantee legibility across different display contexts and skin variations.

What typography fonts does Diagram Design require?

The system mandates a three-family typography stack: Instrument Serif (1.75 rem) for titles, Geist (12 px, weight 600) for primary node labels, and Geist Mono (9 px) for technical sublabels like ports and URLs. This hierarchy is defined in the style guide and applied automatically to all generated diagrams to maintain editorial consistency.

How are raw Mermaid or Excalidraw files converted to editorial quality?

According to [import-mermaid.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md#L3-L4), a direct one-to-one node mapping is insufficient for editorial quality. The skill must re-layout elements on the 4px grid, re-style using semantic tokens, apply the 1-accent rule, and optionally wrap the output in a full-editorial container. Reference implementations are available in files like assets/example-scatter-full.html.

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