# How a diagram is drawn

> Page: https://docs.plotwork.dev/how-it-works. Index of every page: https://docs.plotwork.dev/llms.txt

What happens to a diagram between the text you write and the picture you see: it is checked, laid out, drawn, described, and placed in your document. It is for anyone who wants to know why a diagram looks the way it does, and what to expect when something goes wrong.

## TL;DR

| Question | Answer |
|---|---|
| What do I write? | Plain text, one statement per line. You choose what a thing is (a database, a gateway), never how it looks. |
| What if I make a mistake? | Every mistake is reported at once, each with a line, a column, and a hint. Nothing is drawn until the source is valid. |
| Who picks the colors? | The theme, in a light and a dark version, so contrast holds in both and diagrams from different authors match. |
| Does the picture depend on a font or a browser? | No. The SVG carries its own colors and measured text, so it looks the same on GitHub, in an editor, or as a file. |
| Can text overflow a box? | No. Boxes grow to fit their text. Text is cut only past a hard limit, and a warning says so. |
| How does it reach my document? | `sync` writes the picture files and a picture block under the fence. |

## 1. The stages

**Diagram source**

```diagram
flow "From text to picture" desc="Source text is checked, laid out, drawn as SVG, described in words, and written into the document." direction=right

node source  step     "Diagram source"   sub="Line-oriented text"
node check   function "Check"            sub="Every mistake, located"
node layout  function "Layout"           sub="Boxes sized to their text"
node paint   function "Draw"             sub="Static SVG"
node svg     storage  "Light and dark SVG"
node outline function "Describe"         sub="Alt text and description"
node sync    function "Place"            sub="Picture block in the document"
node errors  terminal "Mistakes"         icon=status:error

source -> check
check  -> layout  : "valid"
check  --> errors : "invalid"
layout -> paint
paint  -> svg
check  -> outline
svg    -> sync
outline -> sync
```

*Picture: From text to picture: 8 nodes, 8 connections. Source text is checked, laid out, drawn as SVG, described in words, and written into the document.*

**Text description**

**Nodes:**

- Diagram source (Line-oriented text), step
- Check (Every mistake, located), function
- Layout (Boxes sized to their text), function
- Draw (Static SVG), function
- Light and dark SVG, storage
- Describe (Alt text and description), function
- Place (Picture block in the document), function
- Mistakes, terminal

**Connections:**

- Diagram source to Check
- Check to Layout: valid
- Check to Mistakes (dashed): invalid
- Layout to Draw
- Draw to Light and dark SVG
- Check to Describe
- Light and dark SVG to Place
- Describe to Place

## 2. What each stage does

| Stage | What happens | What you see |
|---|---|---|
| Check | The text is read against the language. Unknown words, missing pieces, and unbalanced blocks are found. | Errors with a line, a column, and a hint, and warnings for a diagram that is too dense or too wide. |
| Layout | Each box is sized from the measured width of its text. Flow and schema diagrams route connectors at right angles. Sequence diagrams run on a timeline. | Boxes exactly as large as their text needs, with the same padding on both sides. |
| Draw | The layout is painted as SVG using the theme's colors for the light and the dark version. | Two files: `<id>.svg` and `<id>.dark.svg`. |
| Describe | The diagram is written out in reading order. | The picture's alt text, and the collapsed "Text description" under it. |
| Place | `sync` inserts a picture block under the fence in your Markdown file. | The picture in your document. See [Diagrams in Markdown and on GitHub](https://docs.plotwork.dev/markdown-and-github.md). |

## 3. Why it works this way

| Decision | What it means for you |
|---|---|
| You choose meaning, not color | An agent can write `database` or `gateway` and the look follows. Contrast is the theme's job, in both modes. |
| One statement per line, labels in quotes | A mistake has an exact position, and punctuation in a label never breaks the syntax. |
| Colors are fixed in the SVG | GitHub shows the picture through an image tag, where page styles and variables do not reach. |
| Text is measured, and boxes grow | A long label makes a wider box. A substitute font cannot make text spill out of one. |
| Warnings instead of silent fixes | A diagram that is too dense or too wide is a problem for its author, so you are told, with a hint. |
| The same source gives the same picture | The result does not depend on the machine that drew it. |
| The picture block records a fingerprint | If the diagram or the renderer changes, `sync --check` reports the picture as stale, so a document never shows an old drawing. |

## 4. When something looks wrong

| Symptom | Cause | Fix |
|---|---|---|
| Nothing is drawn and `validate_diagram` lists errors | The source has mistakes | Fix each one using its line, column, and hint. |
| A label ends in an ellipsis (warning `W203`) | The text was longer than the hard limit | Shorten it, or move detail into `sub=` or the prose around the diagram. |
| The diagram looks small (warning `W202`) | It is wider than a Markdown column | Use `direction=down`, shorten labels, or split it. |
| The document shows an old picture | The picture block is stale | Ask your agent to sync the file again, or call `sync_markdown` with it. |

## See also

| Doc | Why |
|---|---|
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The language by example |
| [Diagrams in Markdown and on GitHub](https://docs.plotwork.dev/markdown-and-github.md) | The sync step in use |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every word the language accepts |