---
title: "Diagram Design (Cathryn Lavery)"
section: "raw"
type: "source"
created: "2026-08-23"
updated: "2026-08-23"
canonical: "https://pyweb.dev/wiki/raw/articles/cathryn-lavery-diagram-design-2026"
---
# Diagram Design (Cathryn Lavery)

> Editorial diagrams your designer won't hate. 39 visual types and semantic system patterns for AI coding agents (Claude Code, Codex, Factory Droid, Pi). Self-contained HTML + SVG. No shadows, no Mermaid slop.

## Overview & Core Philosophy

Diagram Design is an opinionated visual diagram generation skill and design system authored by Cathryn Lavery. It allows autonomous coding agents to produce publication-grade, self-contained HTML/SVG diagrams instead of generic rounded-box diagrams or unformatted Mermaid charts.

### The Philosophy: Deletion & Signal
- **The highest-quality move is usually deletion:** Every node must represent a distinct idea. Two nodes that always travel together are merged into one node.
- **Connections carry information:** If a relationship is obvious from spatial layout, remove the connecting line.
- **Focal Accent Rule:** Accent color is strictly editorial, reserved for the 1–2 things the reader should inspect first. Using accent color across multiple nodes destroys the signal.
- **Target Density:** 4/10. Complete enough to be technically sound without becoming a dense, overwhelming wall. Above 9 nodes, content should usually be split into two diagrams or an overview/detail pair.
- **Grid Discipline:** Coordinates, widths, padding, and gaps are strictly divisible by 4px, avoiding the floaty, unanchored feel of generic AI visual generation.

## Visual Types and Semantic Routing

The system separates behavioral meaning from spatial layout:
1. **Semantic Patterns (Behavior):** First identifies dynamic characteristics such as fan-in queues/bottlenecks, multi-stage frameworks with semantic slots, unstructured input to structured artifact pipelines, paired policy-evaluation traces, secure paved roads, governance catalogs, or compensating security layers.
2. **Visual Types (Layout):** Maps the semantic requirement to one of 39 standard layout grammars (Architecture, Flowchart, Sequence, State Machine, ER/Data Model, Timeline, Swimlane, Quadrant, Radar/Spider, Polar Chart, Loop/Flywheel, Nested, Tree, Org Chart, Layer Stack, Venn, Pyramid/Funnel, Treemap, Bar/Line/Scatter/Gantt, High-Level, Process, Medallion, Data Flow, DP Integration, DP Security Matrix, Sankey, Fishbone, Wardley Map, Kanban, User Journey, Deployment, Dependency Graph, UML Class, Story Map, Database Schema).

## Technical Artifact Structure & Accessibility

- **Self-Contained Deliverables:** Single `.html` files containing inline SVG, embedded CSS, semantic typography (Instrument Serif, Geist sans, Geist Mono), and zero external image/script dependencies (except optional Google Fonts).
- **Accessible Figures:** Inline SVGs carry `role="img"`, namespaced `aria-labelledby`, first-child `<title>` and `<desc>` elements providing structural descriptions rather than geometric narration.
- **Motion & Reduced Motion:** Static output is the default. When animation is explicitly chosen for step-through explanations, it includes a complete static first frame and strictly respects `prefers-reduced-motion: reduce`.
- **Import Redrawing & Fidelity Ledgers:** Rather than mechanical format conversion from draw.io or Mermaid, the skill ingests topological components and redraws them against the design system's grid and token ramp, emitting an explicit fidelity ledger detailing merged, collapsed, and dropped elements.

---

## Agent Navigation

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt