---
name: diagram_craft
description: Design diagrams that people actually understand. Picks the right diagram type, applies layout and clarity discipline, styles hand-drawn whiteboard looks, and enforces accessibility. Use when an agent needs to create a flowchart, chart, architecture diagram, or sketch for a human reader.
---

# Diagram Craft

## Purpose

AI-generated diagrams usually fail on judgment, not tools: wrong chart type, cluttered layout, color-only encoding, legends nobody reads. This skill gives agents the design judgment to make diagrams humans get at a glance. Covers data charts and concept diagrams, both polished and hand-drawn styles.

## Workflow

### 1. The cardinal rule

Before drawing anything, ask: would a numbered list or a table say this better? If yes, do not make a diagram. Draw a diagram only when it shows something a list flattens: branching decisions, flows, relationships, hierarchy, or shape comparisons. A linear sequence with no branches is a list, not a diagram.

### 2. Pick the type by the question

Match the diagram to what the reader needs to answer. For charts of data:

| Question the reader has | Use this | Avoid |
|---|---|---|
| How do these categories compare? | Horizontal bar chart, sorted by value | Pie chart, 3D bars |
| How has this changed over time? | Line chart, time on x-axis | Bars for many time points |
| What is the distribution? | Histogram or box plot | Pie chart |
| What is the relationship between two variables? | Scatter plot | Line chart (implies time) |
| What is the part-to-whole breakdown? | Stacked bar or waffle chart | Pie chart, unless 2-3 slices max |
| What is the geographic pattern? | Choropleth map | Bars by region name |
| What is the ranking? | Horizontal bar chart, sorted | Vertical bars, radar charts |

For concepts and systems:

| What you are showing | Use this |
|---|---|
| Decision path through a process | Flowchart |
| Message flow over time | Sequence diagram |
| Object or service lifecycle | State diagram |
| Component relationships | Flowchart with subgraphs |
| Hierarchical concepts | Mindmap or tree |
| Phases or timeline | Gantt chart |
| Entity relationships | ER diagram |

Pie charts are almost always the wrong choice: people compare angles and areas badly. Two exceptions: exactly 2-3 slices where one dominates, or a convention the audience expects (financial reporting). Never use 3D effects on charts. They distort values and lie about the data.

### 3. Inventory before drawing

Write down every node and label before touching any tool. One diagram shows one concept. Cap sizes: flowcharts around 12 nodes max, sequence diagrams around 8 participants, mindmaps around 15 branches. If you are over the cap, split into two diagrams instead of shrinking text.

### 4. Lay out for the eye

- Flow left to right or top to bottom, never both at once.
- Shapes keep consistent meaning: rectangles are steps, diamonds are decisions, rounded boxes are terminals. Do not invent new meanings mid-diagram.
- Decision diamonds get Yes/No (or Yes/No-style) labels on every outgoing branch. No unlabeled branches.
- Label directly on the thing, not in a legend. If the reader must look at a legend, then the chart, then the legend again, the diagram failed.
- White space is information. Cramped nodes read as unimportant.

### 5. Choose the polish level

Match the style to the message. For working drafts, brainstorming, or inviting feedback, use a hand-drawn whiteboard style (Excalidraw, free and browser-based): the rough look signals "this is open for discussion" and stops pixel-perfect fiddling. For shipped docs and presentations, use clean rendered diagrams (Mermaid in docs, Graphviz for generated output, PlantUML for rich UML). Never ship a polished diagram that is still under debate, and never ship a sketch as a final deliverable.

### 6. Accessibility pass

Run every diagram through this before it ships:

- **Grayscale test.** Convert to grayscale. Can you tell every part apart? Can you match each part to its label? Is every word readable? If any answer is no, redesign.
- **Color is never the sole cue.** Back up every color distinction with a label, a shape, a line style, or a pattern. Readers with color vision deficiency (roughly 8-10% of men) see the diagram through red-green, blue-yellow, or grayscale perception, so hue alone always fails somebody.
- **Contrast.** Text at 4.5:1 against its background (WCAG AA), graphical elements at 3:1. The Okabe-Ito palette in `references/palettes.md` is designed to stay distinguishable under common color vision deficiencies; its yellow needs darkening for white backgrounds.
- **Alt text.** Every published diagram ships with a text description of what it shows and its takeaway, so screen readers get the point, not just "image of chart".
- **Simplify when stuck.** A complex chart that cannot pass the grayscale test gets replaced by something simpler: a bar chart instead of a radar chart, a table instead of a pie with marginal differences.

### 7. Honesty pass

- No truncated axes on bar charts (bars encode value by length; cutting the axis exaggerates differences).
- No decorative gradients inside bars or areas. No 3D. No data encoded in decoration.
- If the diagram carries data, cite the source and the date it is current as of.

## Output Contract

Every diagram delivery includes:

1. **The diagram** in the target format (Mermaid code, SVG/PNG export, or a link to the Excalidraw canvas).
2. **A title** stating what the diagram shows, placed with the diagram.
3. **Alt text** describing the content and the one takeaway.
4. **A note on what was considered and rejected** (one line: "Considered a pie chart, rejected: 7 slices, angles unreadable").
5. For data diagrams: source, date, and any axis notes.

If the diagram will not render in the target environment (Mermaid version, dark mode), say so and pick a different format instead of shipping broken code.

## Operating Rules

- The accuracy rule applies: every number, label, and relationship in a diagram comes from a verified source. Never invent values to make a chart look complete.
- One concept per diagram. Two ideas means two diagrams.
- In Mermaid, quote every label that contains spaces or special characters, and test that the code renders before delivery.
- Do not mix hand-drawn and polished styles in the same document unless the difference is deliberate and labeled.
- If a stakeholder can only name the diagram's topic but not its takeaway after 10 seconds, it needs a redesign, not more decoration.
- Run `bin/lint_diagram.py` on Mermaid sources before shipping. Fix every error, justify every warning.