sequence-diagram

name

sequence-diagram

description

Use when the user asks for a sequence diagram, ladder diagram, message-exchange diagram, or any temporal flow showing who talks to whom in order ("draw the OAuth flow", "show the request lifecycle", "diagram the protocol over time", "sequence diagram for X"). Produces dark-themed self-contained SVG with actor lifelines, sync/async/return messages, self-loops, halo text, and a geometry-audit gate that knows about lifelines.

Sequence Diagram Skill

Generate UML-2.x-lite sequence diagrams as self-contained SVG files, sharing the blueprint aesthetic of the sibling architecture-diagram and mindmap skills: dark #020617 background, JetBrains Mono, halo text, semantic palette, deterministic geometry-audit gate.

What triggers this skill

• "Draw a sequence diagram of X"
• "Show the [OAuth | login | checkout | webhook] flow over time"
• "Ladder diagram for protocol Y"
• "Show the message exchange between A and B"
• "Activity diagram of [request]" — users frequently conflate these; default to sequence when there's a clear temporal order of messages between named actors
• Any request whose answer is "X happens, then Y, then Z" with named actors

When to use this skill vs siblings

You want…	Skill
Static topology — what calls what, where it lives, how it's deployed	architecture-diagram
Radial topic tree — one focal point, themes radiating out	mindmap
Temporal sequence — who talks to whom, in what order, over time	sequence-diagram (this one)

Rule of thumb: if every arrow in your diagram needs a number to make sense, you want a sequence diagram.

Output contract

Same as the rest of the plugin:

• Self-contained .svg file (or .html if delivering to a user with the export toolbar — copy from ../architecture-diagram/resources/template.html and swap the SVG body).
• Dark #020617 background, JetBrains Mono via the inline <style> block, halo text via paint-order: stroke fill.
• Geometry-audit (../architecture-diagram/resources/geometry-audit.py) must exit 0 before the diagram is done.

Visual conventions (UML 2.x, blueprint-adapted)

Element	Notation	Implementation
Actor box	rounded rect, semantic color	<rect class="component <color>" rx="2"> with name + optional sub-label
Lifeline	dashed vertical line below actor	<line class="lifeline" stroke-dasharray="4,4"> — the lifeline class makes the audit skip it for edge-edge / edge-crosses-component checks
Synchronous call	solid arrow, filled V chevron	<path d="M src,y L tgt,y" marker-end="url(#ah-<color>)">
Async call	dashed arrow, open V chevron	same path + stroke-dasharray="5,3"
Return	dashed line, open chevron, optional label	stroke-dasharray="4,3", lighter stroke
Self-loop	right-side bump arrow	<path d="M x,y q 32,0 32,16 T x,y+16"> with arrowhead at end
Activation bar (optional)	thin rect on lifeline	<rect width="8" fill="rgba(...)"> overlapping lifeline at activation span
Note	halo-only text in clear space	<text class="note"> — no chip rect
Numbering (optional)	small badge or prefix on label	label = "1. login" — simplest readable form

Semantic colors per actor type (reuse from architecture-diagram)

Actor type	kind	Stroke
Human user	slate	#94a3b8
Frontend / SPA / mobile	cyan	#22d3ee
Backend service	emerald	#34d399
Database / store	violet	#a78bfa
Auth / IDP / KMS	rose	#fb7185
Cloud edge / LB / CDN	amber	#fbbf24
External system	slate	#94a3b8

Workflow

1. Extract actors from the brief. Read the user's prose; identify the distinct named participants (USER, SPA, AUTH SERVER, DB, API, …). Typical count: 3–6. Cap at 7 — beyond that, split the diagram.
2. Extract messages in order. Each message = (src actor, tgt actor, label, kind ∈ {sync, async, return, self}). Keep labels short — verbs preferred ("request token", "fetch user").
3. Compute layout (algorithm below).
4. Emit SVG. Actor row first, then lifelines, then messages top-to-bottom.
5. Run geometry-audit. Must be clean. Lifelines are now exempt from edge-edge crossings (see Audit notes below).

Layout algorithm

The diagram is two zones: an actor row at the top, then a message ladder below.

Step 1 — column widths and positions

N = number of actors
LEFT  = 60                  # left margin
RIGHT = 60                  # right margin
COL_W_i  = max(180, label_w_i + 40)         # per-actor; longest of name and sub-label drives width
x_i      = LEFT + sum(COL_W_j for j < i) + COL_W_i / 2     # actor center

W = LEFT + sum(COL_W) + RIGHT

Step 2 — actor row

ACTOR_TOP    = 80
ACTOR_H      = 56
actor_box_i  = rect(x = x_i - aw_i/2, y = ACTOR_TOP, w = aw_i, h = ACTOR_H, rx = 4)
  where aw_i = max(140, label_w_i + 28)

Title and subtitle live above the actor row (y = 32 and y = 52), same as every other diagram in this plugin.

Step 3 — lifeline geometry

Each lifeline runs from the bottom of its actor box down to LIFELINE_BOTTOM:

LIFELINE_TOP    = ACTOR_TOP + ACTOR_H + 8           # 8 px gap below actor
LIFELINE_BOTTOM = MSG_TOP + M * ROW_H + 16          # 16 px below last message

Emit each lifeline as:

<line class="lifeline" x1="x_i" y1="LIFELINE_TOP" x2="x_i" y2="LIFELINE_BOTTOM"
      stroke="#475569" stroke-width="1" stroke-dasharray="4,4"/>

The class="lifeline" is required — the geometry-audit uses this class to skip lifelines in edge-edge and edge-crosses-component checks (otherwise every horizontal message would flag).

Step 4 — message ladder

MSG_TOP = LIFELINE_TOP + 24                          # first message y
ROW_H   = 36                                         # vertical gap per message
y_k     = MSG_TOP + k * ROW_H                        # k = 0..M-1

For each message at row k:

• Standard message (src ≠ tgt): straight horizontal segment from src lifeline to just-before tgt lifeline (leave 8 px on the marker side so the chevron sits inside the column, not crossing into the next).

  <path d="M src_x,y_k L tgt_x-sign(tgt-src)*8,y_k"
        stroke="<color>" stroke-width="1.4" marker-end="url(#ah-<color>)"/>
  

• Self-loop (src = tgt): bump 32 px to the right, down 16 px, back. Total vertical footprint = 16 px, fits inside one row.

  <path d="M src_x,y_k h 32 v 16 h -32"
        stroke="<color>" stroke-width="1.4" marker-end="url(#ah-<color>)"/>
  

  Label sits to the right of the bump: <text x="src_x + 40" y="y_k + 4">label</text>.
• Sync vs async vs return — pick from the Visual conventions table for line style. Different arrowhead is not required, but you can use a smaller arrowhead for returns.

Step 5 — labels

Centered above the arrow line, with halo:

label.x = (src_x + tgt_x) / 2
label.y = y_k - 6

If |src_x − tgt_x| < label_w + 16, widen the source/target columns so the label fits. Don't shrink the label — verbosity here costs nothing visually.

Step 6 — canvas height

H = LIFELINE_BOTTOM + 40                             # 40 px footer margin
viewBox = "0 0 W H"

Audit notes

The geometry-audit has been extended (in this repo) to recognize class="lifeline" on <line> and <path> elements. Lifelines are:

• Skipped in edge-crosses-edge (every message crosses every lifeline — by design)
• Skipped in edge-crosses-component (lifelines shouldn't cross actor boxes anyway; if they do, the actor box layout itself is wrong)
• Still parsed so the audit can read them — just exempt from those two checks

Other audit classes apply normally:

• component-overlap — actor boxes must not overlap
• label-overlaps-component — message labels must not sit on an actor box
• edge-crosses-label — different messages' labels must not collide

If you see edge-crosses-edge findings in a sequence diagram, those are between messages (not lifelines) — typically a sign that two messages share a y-coordinate by mistake, or that a self-loop bump overlaps the next row. Fix by spacing or by re-ordering.

Worked example

"Show the OAuth 2.0 authorization code flow with PKCE: user clicks login on the SPA, SPA redirects to the IDP, IDP authenticates the user and stores a code in its DB, IDP redirects back with the code, SPA exchanges the code (with verifier) for a token at the IDP, IDP returns the token, SPA calls the API with the token, API verifies and returns the resource."

Extracted:

• Actors (5): USER (slate), SPA (cyan), IDP (rose), DB (violet), API (emerald)
• Messages (9): each line of the prose maps to one message in order
• One self-loop on IDP for "authenticate user" (its internal step)

See ../../examples/14-sequence-oauth-code-flow.svg for the rendered output.

What you must not do

• ❌ Don't draw lifelines without class="lifeline" — the audit will flag every message as crossing a lifeline.
• ❌ Don't use curved Bezier paths for inter-actor messages. Sequence diagrams expect straight horizontal arrows. Bezier curves are reserved for self-loops.
• ❌ Don't crowd multiple messages on the same y. Spacing is what makes sequence diagrams readable.
• ❌ Don't number messages just because UML allows it. Add a number prefix only when there are skipped beats or back-references ("see 3.").
• ❌ Don't try to encode alt/loop/par fragments in v1. If the brief genuinely needs branching, draw two sequence diagrams (one per branch) and reference them in prose.
• ❌ Don't load external images / icons / fonts beyond the Google Fonts JetBrains Mono — same constraint as the rest of the plugin.

Limits and when to refactor

• 6 actors → split into two diagrams (e.g., "auth phase" + "API phase").

• 14 messages → consider folding consecutive same-pair calls into one message with a list label.

• Many parallel branches (par fragment territory) → sequence diagrams aren't the right tool; use an architecture diagram with annotated edges instead.

Attribution

Original work. Follows UML 2.x sequence-diagram semantics where applicable, blueprint-adapted to match the architecture-diagram and mindmap aesthetic in this plugin.