Diagram

A diagram a person can put in front of their team: one idea, drawn so nothing clashes, clips or crosses, in the company's look. The rules are diagram-design's (github.com/cathrynlavery/diagram-design, MIT, Copyright (c) 2025 Cathryn Lavery, version 2.6.74), ported as data, a builder and a check. You write the content; the builder owns every coordinate.

SKILL below is this file's folder. Run every script with python3.

First: should it be a diagram?

The best move is usually deletion (diagram-design, Philosophy). Draw only when a reader learns more from the picture than from a paragraph or a three-column table. Every box is one idea: two that always travel together are one box. Every arrow carries something: when the layout already says it, leave the arrow out. A list of things is a list, not a diagram.

Pick the type

A zone or room flow (lobby to lifts to corridor to rooms) is a flowchart of zones, never a drawn plan. Over more than one floor, give each zone its floor as group, and the stair or lift that joins two floors one box in a group of its own between them (plan 10, stair, plan 11), linked from the floor below and to the floor above: the floors stand side by side and the drawing fits a slide. Zones with no route between them stand down their floor's column in the order you list them. Plans print rooms, not routes: when they show no route, draw none and let only the stair or lift join the floors, under the name each plan prints for it.

The loop

1. Read the person's own files for the facts: names, roles, dates, steps. Every word on the diagram comes from them or from the ask. A fact the files do not give stays off the drawing and is named in the reply.
2. Write <name>.diagram.json in the person's folder. Start from the matching file in SKILL/templates/ (flowchart, swimlane, org-chart, timeline, gantt, quadrant, layers); keep its shape, replace every word. Write in the language of the ask.
3. Build: python3 SKILL/scripts/diagram.py <name>.diagram.json. It writes <name>.html (the page), and beside it <name>.pdf, <name>.svg and <name>.png. If it stops with a message, change the data as it says and build again; never edit the HTML or the SVG by hand.
4. Check: python3 SKILL/../_checks/packcheck.py diagram <name>.pdf. Fix what a FAIL line names in the data, build, check again; three rounds at most, then say plainly what still fails.
5. Look at the PNG once. Then hand back the PDF first, and name the SVG and PNG for placing it elsewhere. The data, the page, the SVG and the PNG always stay beside the PDF, also when the person asked only for a PDF: the check reads them, a deck or a web page places the PNG, and the data builds it again. Never delete or move them.

To put the diagram on a business-deck page, use that deck's figure page with image set to the PNG (SKILL/../business-deck/SKILL.md), and check that page with packcheck.py business-deck: it is a deck page, not a diagram, so it has no SVG or PNG of its own.

The data

Every type: type, title (the subject's short name, 60 characters at most), description (one sentence on what the diagram shows, for a reader who cannot see it), and if useful eyebrow (a small label above the title), source (where the facts come from, printed under the drawing), language (en, sv, nb, da, de, fi: month names on a time axis), legend ([{"kind": "focal", "label": "..."}], one entry for each box style used).

A box's kind is its role: step (the default), external (outside the company), optional (only sometimes, drawn dashed), approval (a gate, dashed accent), store (a register or archive), input. focal: true is the accent.

The rules (diagram-design, restated)

• Accent on one or two things at most (one in an org chart): the decision, handoff, task or layer the diagram is about. Accent on five erases the signal.
• Budget: 9 boxes and 12 arrows; a swimlane 5 lanes; an org chart 12 people, 4 tiers, 5 under one person; a gantt 12 tasks; a quadrant 12 items; a layer stack 4 to 6 layers. Over it, make two diagrams: an overview and a detail.
• Short words. A box name fits two lines and its note two lines; an arrow label is 14 characters at most (the builder sets it in capitals); detail belongs in the box, not on the arrow.
• Honest time. Dates sit where they fall; never space events evenly when they are not.
• One owner a step. A step drawn in a lane belongs to that lane's person; a step two people do is two steps.
• Flow reads one way. Swimlanes left to right, flowcharts top to bottom; reorder steps rather than send an arrow back and forth.
• The builder holds the rest: orthogonal arrows with rounded elbows, arrows behind boxes, attach points fanned 12 px apart, labels on an opaque plate clear of their arrow and of every box, a legend as a strip under the drawing, a 4 px grid, the accessible SVG contract, no web font and no outside link.

The look

The library's one look file, skills/business-deck/look.json: its face, its inks and its highlight. A company pack replaces that file and every diagram, deck and page follows; nothing here sets a colour of its own. Pass --look <file> to use another.

What the check holds

DIAG-CONTRACT (the accessible SVG contract and single-file safety, diagram-design's self_check.py), DIAG-OFFLINE (no web address), DIAG-GEOMETRY (its verify-geometry.py: label masks, orthogonal connectors, ports, stacking), DIAG-BOUNDS (nothing past the edge), DIAG-FIT (every text inside its box), DIAG-OVERLAP (nothing on top of anything), DIAG-CONTRAST (4.5:1 text, 3:1 lines), DIAG-BUDGET, DIAG-LABEL (14 characters), DIAG-EXPORT (PDF, SVG and PNG made from this page), DIAG-PNG (the PNG is the whole drawing at twice its size, nothing cut at an edge).

Source and licence

Ported from diagram-design 2.6.74 at commit 7a2e22170ee838e859d8142ba825d83f8b6375e6 (MIT, Copyright (c) 2025 Cathryn Lavery; LICENSE in this folder): the philosophy, the type guide, the node treatments, the connector rules, the complexity budget, the presentation type ramp, the accessible SVG contract and the type references for flowchart, swimlane, org chart, timeline, gantt, quadrant and layer stack, restated; its self_check.py and verify-geometry.py ported unchanged as skills/_checks/diagram_contract.py and diagram_geometry.py. Its other 37 types, dark and motion variants, imports and onboarding are not ported.