diagram_craft v1.0.0

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.