Drawing step flows

A .drawio step flow in the same visual language as the architecture diagrams and the flowcharts: light page, white cards with hairline borders, Google's palette on the connectors, and a numbered blue disc on every step.

Build it with step_drawio.py (this directory). Check it with check_routing.py. Look at it with preview.py.

Where the files go

Everything this skill produces lives in one folder, never loose in the project root:

docs/diagrams/
  upload-flow.py             # the script that builds it
  upload-flow.drawio         # the diagram
  upload-flow.preview.svg    # what you looked at

Use the folder the user names. Otherwise put it under docs/diagrams/ when the project has a docs/ directory, and diagrams/ at the project root when it does not — the build script, the .drawio, and any preview or PNG together. write() creates the folder if it is missing, so f.write("docs/diagrams/upload-flow.drawio") is all it takes, and preview.py writes the SVG beside its input.

Never leave a build script, a .drawio or a preview in the project root, and never write outside the project you were pointed at. One folder, named files — a diagram whose script sits next to it can be regenerated; one scattered across a repository root cannot be found again.

What this draws, and what it does not

The test is whether the numbers mean anything. If the arrows have no order — if it is a picture of a system rather than of a sequence — draw it with the architecture skill. If the path forks on a question, that is a flowchart.

The output contract

1. Every connector routed. direct=, bend=, corridor= or points=. There is no default.
2. check_routing.py reporting 0 FAIL.
3. The numbers read 1..n with no gaps. step() numbers for you, in call order, so write the calls in the order the thing happens.
4. Anything that is not a step is a link() — dashed, grey, unnumbered.

The pieces

from step_drawio import Steps, L, R, T, B

s = Steps("Power BI reads BigQuery", "workforce identity federation")

bi    = s.node("Power BI", "report author",
               icon="onprem/analytics/powerbi.png", col=0, row=0)
entra = s.node("Azure AD / Entra ID", "identity + groups + token issuer",
               icon="azure/identity/azure-active-directory.png", col=1, row=0)
wif   = s.node("GCP Workforce Identity Federation", "Workforce pool + provider",
               icon="gcp/security/iam.png", col=0.5, row=1)

s.step(bi, entra, exit=R(), entry=L(), direct=True)
s.step(entra, wif, "OIDC token + groups", exit=B(), entry=R(), bend="VH")
s.write("docs/diagrams/flow.drawio")

node() is a card: a bold title, a grey subtitle saying what it is here for, and an optional icon. note() is commentary — not a step, never numbered.

A column may be fractional. col=0.5 puts a node between the two above it, which is usually where the thing that sits between two systems belongs.

Routes

Most steps in a step flow are direct or a bend. Reach for a corridor when the step has to travel past something, and for points= only when neither fits.

Which lane you want follows from the faces: out of a side and into a side is a corridor, out of the top or bottom and into one is a band. Ask for the other one and it is refused, because that route turns two corners more than it needs and the picture shows it.

Every connector leaves and arrives straight — 26px along the normal of the face it uses, before it turns. That is what keeps an arrowhead pointing into the card rather than skidding along its edge, which reads as a bend right at the tip. A direct step between two faces that are not quite level puts its step halfway along, not next to the arrowhead.

exit= and entry= are always required — L() R() T() B(), optionally with a fraction, R(0.3). Two connectors leaving the same face are spread apart automatically, so they do not lie on top of each other on the way out.

The number is the point

step() takes the next number. link() takes none: a feed, a fallback, a side effect that happens whenever, not at step 4. Keeping those unnumbered is what makes the numbers worth reading.

The disc rides its connector. Where exactly is worked out at write time, with every route known: clear of other lines, of crossings, of cards, and of the other discs, as near the middle as those allow. The label gets its own spot on the same terms. Pass at= (-1 at the source, 1 at the target) to overrule the choice for one disc; it is then left alone.

Both positions are written into the file, so draw.io and the preview show the same picture — a preview that quietly moves what the file pins is worse than one that draws it badly.

Icons

The diagrams package's icons, by path or by name:

python3 ~/.claude/skills/drawing-step-flows/step_drawio.py bigquery

Pass what it prints: icon="gcp/analytics/bigquery.png". A card with no icon is fine — the label simply starts at the left edge.

Geometry

The page measures itself from what is on it. width=/height= are a floor.

Before handing it over

S=~/.claude/skills/drawing-step-flows
python3 "$S/check_routing.py" docs/diagrams/flow.drawio        # must report 0 FAIL
python3 "$S/preview.py" docs/diagrams/flow.drawio              # writes docs/diagrams/flow.preview.svg
rsvg-convert -w 1400 -o docs/diagrams/flow.png docs/diagrams/flow.preview.svg

Then read the picture for what a checker cannot see: a step whose label repeats its target's title, two steps that are really one, a number sequence that no longer matches the prose it illustrates.

Common mistakes

preview.py writes a plain SVG — open it in any browser if you have no rsvg-convert. The PNG step is for pasting into a document, not for looking at it.