diagram-create

Diagram Creation

Diagrams are code. A project keeps one diagrams.py that defines its diagrams with the diagram package. One command checks every diagram against the layout rules, writes the HTML pages with inline SVG, checks in Chromium that all text fits, and writes one PNG for each SVG. The package fixes every color, font, and size, so all diagrams share one style.

D is the diagram folder of the project, docs/diagrams/ by default.

1. Decide whether to draw

• Draw only when a reader learns more from the picture than from a paragraph or a table. A list of things is a table. A one-box diagram is a sentence.
• Charts of data (bars, lines, scatter) are out of scope.
• The best move is usually deletion. Each node is a distinct idea: merge two nodes that always travel together. Each arrow carries information: remove an arrow that the layout already shows. A diagram is done when nothing can be removed. Aim for a density of about 4 out of 10.

2. Set up the diagram folder

1. If D already has a diagrams.py and a diagram/ package, use them. Follow the README or AGENTS.md in that folder. Those project rules override this skill.
2. If the project has an older generator in this style (a script with an Svg class and zone, path, label, and node helpers), keep using it. It has none of the build checks. Port it to the package only when the user asks: each path string becomes a list of waypoints, and each label becomes the label of its edge.
3. Otherwise, copy scripts/diagrams.py and the scripts/diagram/ package from this skill's directory into D. diagrams.py holds two example diagrams. Replace them with the real ones. Make sure that the repository ignores __pycache__/.

The package lives in the project, so the project can build its diagrams without this skill. To change the style, edit diagram/style.py. Never pass colors or fonts from a diagram function.

3. Workflow

1. Collect the facts. Take every node, edge, and label from the source of truth: code, configuration, infrastructure as code, manifests, and pipeline definitions. Draw the current state, unless the page that shows the diagram says that it shows a plan. Never invent a component to fill the layout.
2. Choose the type (§4). Read its section in references/diagram-types.md. Read references/drawing-api.md before the first diagram.
3. State the plan in one short message: the type, the nodes, and what the budget (§6) cuts or splits. If the user can answer, let them redirect you. If not, continue and list your assumptions in the report.
4. Write one function for each diagram in diagrams.py, and list the pages in PAGES. First sketch the grid of columns and rows, then compute the coordinates.
5. Download the icons and build (§7). Fix every error that the build reports, then run the taste gate (§8).
6. If D has a README index, update it when you add, rename, or remove a diagram. Delete the HTML and PNG files that the build reports as stale. Commit diagrams.py, the HTML pages, and the PNGs together. Never edit the generated files by hand.