Diagrams in docs
When a diagram helps a reader, which kind to draw for which idea, and what to leave out. How diagrams look is the design system’s job.
When a diagram helps
Draw one when the reader needs to hold several things and their relations in mind at once: parts and their connections, or steps and their order. If the content is a list, a table or one sentence, write the list, the table or the sentence. A diagram that repeats the text next to it costs the reader time and teaches nothing.
Which kind for which idea
| Kind | Answers | Draw it as |
|---|---|---|
| Architecture | What exists and what may talk to what | Boxes and arrows, grouped by where they live |
| Flow | What happens, in order | Numbered steps from a start to an end |
| Decision | Which way something goes | A yes/no shape with one arrow per answer |
| Comparison | How two or more options differ | A table, not a diagram |
| Sequence of screens | What the user sees, step by step | Real screenshots or the real component |
| Business rules | States and what moves between them | The rule charts drawn from the machines |
What goes in it
- One point. Say it in the title. Everything in the diagram should serve that point; the accent goes on the one or two things it is about.
- Nine boxes or fewer. More than that, split it: an overview, then a detail of the part that matters.
- Real names. “Commit gate” and
src/platform, not “Service A”. Every box should be something the reader can find. - Labelled arrows. An arrow says what happens: “copies”, “prints”, “may use”. An arrow nobody can name should go.
- Flows run one way. End a flow at its last step; an arrow back to the start turns the layout round.
- Readable without it. The text still explains everything; the diagram makes it faster to grasp. People with screen readers get the title and description.
- Pick the level for the reader. Everyone gets the big picture; developers get a second diagram with files and commands.
How they look
Shapes, colours, type and lines are set once, in Design system › Foundations › Diagrams. A diagram describes its content; placement and style are automatic, so every diagram on the site looks like part of one family.