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

> Discover Diagram Design's editorial quality standards. Learn about visual language, color tokens, grid alignment, and typography for polished diagrams.

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

---

**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/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/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/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/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/import-mermaid.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md#L3-L4), [`import-excalidraw.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-excalidraw.md), and [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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:

```yaml

# 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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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/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/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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/example-scatter-full.html).