Task
Diagram
<forma-diagram>
Presentation-only diagram nodes, connectors, metadata and key; the consumer owns geometry, routing, semantics and color mapping.
- Authoring tag
<forma-diagram>- Category
- Workflow and diagrams
- Behavior owner
- Application content
- Canonical source
patterns/diagram.html
Purpose
The diagram family renders a workflow or relationship diagram that has already been laid out by the consumer. A figure.forma-diagram holds a caption, a scrollable canvas, a text list of every relationship and an optional key. Nodes are HTML articles placed with --forma-diagram-x, --forma-diagram-y and --forma-diagram-w; connectors are SVG paths whose geometry is supplied by the consumer. Forma paints boxes, shapes, line styles, arrowheads, labels and authored colors. It never lays out, routes, selects, drags or validates anything, and it never infers meaning from color: each node states its kind and state as text, and the relationship list carries every connection without the drawing.
Use when
- An application or export (for example Forma Studio) has computed node positions and connector paths and needs production-quality, dependency-free HTML and SVG output.
- Nodes need authored colors, for example by owning team, while kind and state stay in text.
- The diagram must remain understandable in forced colors, grayscale print and to screen readers.
Avoid when
- The relationships are a simple sequence: use Steps or Provenance trail, which reflow without a canvas.
- Items move between columns by status: use Lane board.
- Users explore a large spatial surface with an index and orientation: use Spatial canvas.
- Hand-placing a workflow: write a portable
.forma-workflow.jsonand let Forma.Workflow lay it out and render this markup (docs/workflow/RENDERING.md).
Behavior to know
- Geometry is physical, like SVG:
left/topplacement does not mirror in right-to-left documents, so nodes stay attached to their connectors. - Non-color cues: visible kind text,
data-forma-shape,data-forma-lineand the relationship list. - Authored color arrives as resolved custom property values; removing one restores the Forma token default.
- Focus uses Forma's foundation ring and never reads authored color.
Basic example
The smallest correct markup: the canonical pattern from patterns/diagram.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal diagram
Rendered from the canonical pattern file.
Live demo. 1 native action works here and is verified by an outcome test.
Fill colors show the owning team through a consumer-defined mapping (see the key). They say nothing about state: each item states its kind and state in text.
- Draft article leads to Legal review (solid line).
- Legal review leads to Publish when approved (solid line).
- Legal review leads to Rework when changes are requested (dashed line).
- Rework returns to Draft article (dotted line).
- Editorial
- blue fill
- Legal
- amber fill
- Unassigned
- Forma default
<forma-diagram class="forma-component-tag">
<figure class="forma-diagram" aria-labelledby="diagram-title">
<figcaption id="diagram-title">Publication workflow</figcaption>
<p>Fill colors show the owning team through a consumer-defined mapping (see the key). They say nothing about state: each item states its kind and state in text.</p>
<div class="forma-diagram__viewport" tabindex="0" role="group" aria-label="Publication workflow canvas, scroll to see all items">
<div class="forma-diagram__canvas" style="--forma-diagram-canvas-w: 720px; --forma-diagram-canvas-h: 330px;">
<svg class="forma-diagram__wires" viewBox="0 0 720 330" aria-hidden="true" focusable="false">
<defs>
<marker id="diagram-arrow" class="forma-diagram-marker" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z"/></marker>
</defs>
<path class="forma-diagram-connector" d="M216 70 H258" marker-end="url(#diagram-arrow)"/>
<path class="forma-diagram-connector" d="M460 70 H502" marker-end="url(#diagram-arrow)"/>
<path class="forma-diagram-connector" data-forma-line="dashed" d="M360 150 V198" marker-end="url(#diagram-arrow)"/>
<path class="forma-diagram-connector" data-forma-line="dotted" d="M260 260 H116 V152" marker-end="url(#diagram-arrow)"/>
</svg>
<article class="forma-diagram-node" data-forma-shape="rounded" aria-labelledby="node-draft" style="--forma-diagram-x: 16px; --forma-diagram-y: 24px; --forma-diagram-w: 200px; --forma-diagram-fill: #e8f0ff; --forma-diagram-accent: #2f5fb3; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">Task</p>
<h3 class="forma-diagram-node__label" id="node-draft">Draft article</h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Done</dd><dt>Team</dt><dd>Editorial</dd></dl>
</article>
<article class="forma-diagram-node" aria-labelledby="node-review" style="--forma-diagram-x: 260px; --forma-diagram-y: 24px; --forma-diagram-w: 200px; --forma-diagram-fill: #fff1d6; --forma-diagram-accent: #8a5300; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">Decision</p>
<h3 class="forma-diagram-node__label" id="node-review">Legal review</h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Active</dd><dt>Team</dt><dd>Legal</dd></dl>
</article>
<article class="forma-diagram-node" data-forma-shape="pill" aria-labelledby="node-publish" style="--forma-diagram-x: 504px; --forma-diagram-y: 24px; --forma-diagram-w: 200px; --forma-diagram-fill: #e8f0ff; --forma-diagram-accent: #2f5fb3; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">End</p>
<h3 class="forma-diagram-node__label" id="node-publish"><a href="#diagram-title">Publish</a></h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Waiting</dd><dt>Team</dt><dd>Editorial</dd></dl>
</article>
<article class="forma-diagram-node" data-forma-shape="rounded" aria-labelledby="node-rework" style="--forma-diagram-x: 260px; --forma-diagram-y: 200px; --forma-diagram-w: 200px;">
<p class="forma-diagram-node__kind">Task</p>
<h3 class="forma-diagram-node__label" id="node-rework">Rework</h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Not started</dd></dl>
</article>
<span class="forma-diagram-connector__label" style="--forma-diagram-x: 372px; --forma-diagram-y: 164px;">changes requested</span>
</div>
</div>
<ol class="forma-diagram__relations" aria-label="Relationships">
<li>Draft article leads to Legal review (solid line).</li>
<li>Legal review leads to Publish when approved (solid line).</li>
<li>Legal review leads to Rework when changes are requested (dashed line).</li>
<li>Rework returns to Draft article (dotted line).</li>
</ol>
<dl class="forma-diagram-legend" aria-label="Key: fill color by owning team">
<div><dt><span class="forma-diagram-legend__swatch" style="--forma-diagram-fill: #e8f0ff; --forma-diagram-accent: #2f5fb3;"></span> Editorial</dt><dd>blue fill</dd></div>
<div><dt><span class="forma-diagram-legend__swatch" style="--forma-diagram-fill: #fff1d6; --forma-diagram-accent: #8a5300;"></span> Legal</dt><dd>amber fill</dd></div>
<div><dt><span class="forma-diagram-legend__swatch"></span> Unassigned</dt><dd>Forma default</dd></div>
</dl>
</figure>
</forma-diagram>
Click or tap the code once to select all of it, then copy.
Examples
Generated from a portable workflow, with ports and status
This markup is the unedited output of forma-workflow render for examples/workflows/forma/workflows/runtime-ports.forma-workflow.json (diagram contract 2.1.0). Ports are markers placed on a side with data-forma-side and --forma-diagram-port-offset; their shape shows direction. Status is text in the node metadata; data-forma-status adds a secondary outline or border cue. The relationship list names the ports each connector uses.
- Ground supply leads to Propellant tank: “LOX fill”; from port out to port fill.
- Propellant tank leads to Engine chill-down: “Feed”; from port feed to port in.
- Propellant tank leads to Boil-off vent: “Vent”; from port vent; dotted line.
<forma-diagram class="forma-component-tag">
<figure class="forma-diagram" id="diagram-portable-workflow" aria-labelledby="diagram-portable-workflow-title">
<figcaption id="diagram-portable-workflow-title">Propellant loading</figcaption>
<div class="forma-diagram__viewport" tabindex="0" role="group" aria-label="Propellant loading diagram, scroll to see all items">
<div class="forma-diagram__canvas" style="--forma-diagram-canvas-w: 840px; --forma-diagram-canvas-h: 272px;">
<svg class="forma-diagram__wires" viewBox="0 0 840 272" aria-hidden="true" focusable="false">
<defs>
<marker id="diagram-portable-workflow-arrow" class="forma-diagram-marker" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
<path d="M0 0 L10 5 L0 10 z" />
</marker>
</defs>
<path class="forma-diagram-connector" id="diagram-portable-workflow-e-r1" d="M224 72 L320 72" marker-end="url(#diagram-portable-workflow-arrow)" />
<path class="forma-diagram-connector" id="diagram-portable-workflow-e-r2" d="M520 72 L616 72" marker-end="url(#diagram-portable-workflow-arrow)" />
<path class="forma-diagram-connector" id="diagram-portable-workflow-e-r3" data-forma-line="dotted" d="M420 24 L420 12 L604 12 L604 200 L616 200" marker-end="url(#diagram-portable-workflow-arrow)" />
</svg>
<article class="forma-diagram-node" id="diagram-portable-workflow-n-supply" data-forma-status="complete" aria-labelledby="diagram-portable-workflow-n-supply-label" style="--forma-diagram-x: 24px; --forma-diagram-y: 24px; --forma-diagram-w: 200px; --forma-diagram-h: 96px;">
<p class="forma-diagram-node__kind">External</p>
<h3 class="forma-diagram-node__label" id="diagram-portable-workflow-n-supply-label">Ground supply</h3>
<dl class="forma-diagram-node__meta">
<dt>Status</dt>
<dd>Connected</dd>
</dl>
<span class="forma-diagram-port" data-forma-side="right" data-forma-direction="out" style="--forma-diagram-port-offset: 50%;" aria-hidden="true"></span>
</article>
<article class="forma-diagram-node" id="diagram-portable-workflow-n-tank" data-forma-status="active" aria-labelledby="diagram-portable-workflow-n-tank-label" style="--forma-diagram-x: 320px; --forma-diagram-y: 24px; --forma-diagram-w: 200px; --forma-diagram-h: 96px;">
<p class="forma-diagram-node__kind">Data</p>
<h3 class="forma-diagram-node__label" id="diagram-portable-workflow-n-tank-label">Propellant tank</h3>
<dl class="forma-diagram-node__meta">
<dt>Status</dt>
<dd>Filling</dd>
</dl>
<span class="forma-diagram-port" data-forma-side="left" data-forma-direction="in" style="--forma-diagram-port-offset: 50%;" aria-hidden="true"></span>
<span class="forma-diagram-port" data-forma-side="top" data-forma-direction="out" style="--forma-diagram-port-offset: 50%;" aria-hidden="true"></span>
<span class="forma-diagram-port" data-forma-side="right" data-forma-direction="out" style="--forma-diagram-port-offset: 50%;" aria-hidden="true"></span>
</article>
<article class="forma-diagram-node" id="diagram-portable-workflow-n-engine" data-forma-shape="rounded" data-forma-status="blocked" aria-labelledby="diagram-portable-workflow-n-engine-label" style="--forma-diagram-x: 616px; --forma-diagram-y: 24px; --forma-diagram-w: 200px; --forma-diagram-h: 96px;">
<p class="forma-diagram-node__kind">Task</p>
<h3 class="forma-diagram-node__label" id="diagram-portable-workflow-n-engine-label">Engine chill-down</h3>
<dl class="forma-diagram-node__meta">
<dt>Status</dt>
<dd>Waiting for temperature</dd>
</dl>
<span class="forma-diagram-port" data-forma-side="left" data-forma-direction="in" style="--forma-diagram-port-offset: 50%;" aria-hidden="true"></span>
</article>
<article class="forma-diagram-node" id="diagram-portable-workflow-n-vent" data-forma-shape="rounded" aria-labelledby="diagram-portable-workflow-n-vent-label" style="--forma-diagram-x: 616px; --forma-diagram-y: 152px; --forma-diagram-w: 200px; --forma-diagram-h: 96px;">
<p class="forma-diagram-node__kind">Task</p>
<h3 class="forma-diagram-node__label" id="diagram-portable-workflow-n-vent-label">Boil-off vent</h3>
<dl class="forma-diagram-node__meta">
<dt>Status</dt>
<dd>Monitoring</dd>
</dl>
</article>
<span class="forma-diagram-connector__label" aria-hidden="true" style="--forma-diagram-x: 272px; --forma-diagram-y: 72px;">LOX fill</span>
<span class="forma-diagram-connector__label" aria-hidden="true" style="--forma-diagram-x: 568px; --forma-diagram-y: 72px;">Feed</span>
<span class="forma-diagram-connector__label" aria-hidden="true" style="--forma-diagram-x: 604px; --forma-diagram-y: 106px;">Vent</span>
</div>
</div>
<ol class="forma-diagram__relations" aria-label="Relationships">
<li>Ground supply leads to Propellant tank: “LOX fill”; from port out to port fill.</li>
<li>Propellant tank leads to Engine chill-down: “Feed”; from port feed to port in.</li>
<li>Propellant tank leads to Boil-off vent: “Vent”; from port vent; dotted line.</li>
</ol>
</figure>
</forma-diagram>
Click or tap the code once to select all of it, then copy.
Approval chain with default styling
Three nodes with no authored color, so every surface uses Forma tokens. The rejection path is dashed and labelled, the start and end nodes use the pill shape, and the relationship list repeats each connector in reading order.
- Submit claim leads to Manager review (solid line).
- Manager review leads to Reimbursed when approved (solid line).
- Manager review returns to Submit claim when rejected for a missing receipt (dashed line).
<forma-diagram class="forma-component-tag">
<figure class="forma-diagram" aria-labelledby="diagram-default-appearance-title">
<figcaption id="diagram-default-appearance-title">Expense approval</figcaption>
<div class="forma-diagram__viewport" tabindex="0" role="group" aria-label="Expense approval canvas, scroll to see all items">
<div class="forma-diagram__canvas" style="--forma-diagram-canvas-w: 640px; --forma-diagram-canvas-h: 250px;">
<svg class="forma-diagram__wires" viewBox="0 0 640 250" aria-hidden="true" focusable="false">
<defs>
<marker id="diagram-default-appearance-arrow" class="forma-diagram-marker" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z"/></marker>
</defs>
<path class="forma-diagram-connector" d="M196 60 H228" marker-end="url(#diagram-default-appearance-arrow)"/>
<path class="forma-diagram-connector" d="M412 60 H444" marker-end="url(#diagram-default-appearance-arrow)"/>
<path class="forma-diagram-connector" data-forma-line="dashed" d="M320 110 V150 H106 V116" marker-end="url(#diagram-default-appearance-arrow)"/>
</svg>
<article class="forma-diagram-node" data-forma-shape="pill" aria-labelledby="diagram-default-appearance-submit" style="--forma-diagram-x: 16px; --forma-diagram-y: 20px; --forma-diagram-w: 180px;">
<p class="forma-diagram-node__kind">Start</p>
<h3 class="forma-diagram-node__label" id="diagram-default-appearance-submit">Submit claim</h3>
</article>
<article class="forma-diagram-node" aria-labelledby="diagram-default-appearance-review" style="--forma-diagram-x: 230px; --forma-diagram-y: 20px; --forma-diagram-w: 180px;">
<p class="forma-diagram-node__kind">Decision</p>
<h3 class="forma-diagram-node__label" id="diagram-default-appearance-review">Manager review</h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Active</dd></dl>
</article>
<article class="forma-diagram-node" data-forma-shape="pill" aria-labelledby="diagram-default-appearance-paid" style="--forma-diagram-x: 446px; --forma-diagram-y: 20px; --forma-diagram-w: 180px;">
<p class="forma-diagram-node__kind">End</p>
<h3 class="forma-diagram-node__label" id="diagram-default-appearance-paid">Reimbursed</h3>
</article>
<span class="forma-diagram-connector__label" style="--forma-diagram-x: 150px; --forma-diagram-y: 160px;">rejected, needs receipt</span>
</div>
</div>
<ol class="forma-diagram__relations" aria-label="Relationships">
<li>Submit claim leads to Manager review (solid line).</li>
<li>Manager review leads to Reimbursed when approved (solid line).</li>
<li>Manager review returns to Submit claim when rejected for a missing receipt (dashed line).</li>
</ol>
</figure>
</forma-diagram>
Click or tap the code once to select all of it, then copy.
Authored color by owning team
The consumer maps owning team to fill and accent through its own profile and passes resolved values. Two different kinds share one color and the key explains the mapping. One connector has an authored stroke and weight; its meaning is still stated in the relationship list.
Fill color shows the owning team only. Kind and state are written on each item.
- Triage alert leads to Customer impact? (solid line).
- Customer impact? leads to Page on-call engineer when customers are affected (dotted line, handed to another team).
- Support
- blue fill
- Platform
- amber fill, dark border
<forma-diagram class="forma-component-tag">
<figure class="forma-diagram" aria-labelledby="diagram-authored-color-title">
<figcaption id="diagram-authored-color-title">Incident escalation</figcaption>
<p>Fill color shows the owning team only. Kind and state are written on each item.</p>
<div class="forma-diagram__viewport" tabindex="0" role="group" aria-label="Incident escalation canvas, scroll to see all items">
<div class="forma-diagram__canvas" style="--forma-diagram-canvas-w: 640px; --forma-diagram-canvas-h: 170px;">
<svg class="forma-diagram__wires" viewBox="0 0 640 170" aria-hidden="true" focusable="false">
<defs>
<marker id="diagram-authored-color-arrow" class="forma-diagram-marker" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z"/></marker>
</defs>
<path class="forma-diagram-connector" d="M196 70 H228" marker-end="url(#diagram-authored-color-arrow)"/>
<path class="forma-diagram-connector" data-forma-line="dotted" style="--forma-diagram-connector-stroke: #8a5300; --forma-diagram-connector-width: 3;" d="M412 70 H444" marker-end="url(#diagram-authored-color-arrow)"/>
</svg>
<article class="forma-diagram-node" data-forma-shape="rounded" aria-labelledby="diagram-authored-color-triage" style="--forma-diagram-x: 16px; --forma-diagram-y: 20px; --forma-diagram-w: 180px; --forma-diagram-fill: #e8f0ff; --forma-diagram-accent: #2f5fb3; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">Task</p>
<h3 class="forma-diagram-node__label" id="diagram-authored-color-triage">Triage alert</h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Done</dd><dt>Team</dt><dd>Support</dd></dl>
</article>
<article class="forma-diagram-node" aria-labelledby="diagram-authored-color-decide" style="--forma-diagram-x: 230px; --forma-diagram-y: 20px; --forma-diagram-w: 180px; --forma-diagram-fill: #e8f0ff; --forma-diagram-accent: #2f5fb3; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">Decision</p>
<h3 class="forma-diagram-node__label" id="diagram-authored-color-decide">Customer impact?</h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Active</dd><dt>Team</dt><dd>Support</dd></dl>
</article>
<article class="forma-diagram-node" data-forma-shape="rounded" aria-labelledby="diagram-authored-color-page" style="--forma-diagram-x: 446px; --forma-diagram-y: 20px; --forma-diagram-w: 180px; --forma-diagram-fill: #fff1d6; --forma-diagram-stroke: #5c3a00; --forma-diagram-accent: #8a5300; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">Task</p>
<h3 class="forma-diagram-node__label" id="diagram-authored-color-page">Page on-call engineer</h3>
<dl class="forma-diagram-node__meta"><dt>State</dt><dd>Waiting</dd><dt>Team</dt><dd>Platform</dd></dl>
</article>
</div>
</div>
<ol class="forma-diagram__relations" aria-label="Relationships">
<li>Triage alert leads to Customer impact? (solid line).</li>
<li>Customer impact? leads to Page on-call engineer when customers are affected (dotted line, handed to another team).</li>
</ol>
<dl class="forma-diagram-legend" aria-label="Key: fill color by owning team">
<div><dt><span class="forma-diagram-legend__swatch" style="--forma-diagram-fill: #e8f0ff; --forma-diagram-accent: #2f5fb3;"></span> Support</dt><dd>blue fill</dd></div>
<div><dt><span class="forma-diagram-legend__swatch" style="--forma-diagram-fill: #fff1d6; --forma-diagram-stroke: #5c3a00; --forma-diagram-accent: #8a5300;"></span> Platform</dt><dd>amber fill, dark border</dd></div>
</dl>
</figure>
</forma-diagram>
Click or tap the code once to select all of it, then copy.
Budget approval across two lanes
A Workflow profile export with lanes, an ellipse start and end, a diamond decision with labelled outcomes, and two kinds of authored color: an amber fill that the consumer maps from the status field, and a purple fill a person chose by hand. The key keeps the two apart, and every node states its kind, owner and status in text.
Amber fill comes from the status mapping (Needs input). Purple is a highlight the author chose; it carries no status. Owners come from the lane.
- Submit request leads to Prepare budget (solid line).
- Prepare budget leads to Within budget? (solid line, moves from the Requester lane to the Finance lane).
- Within budget? leads to Approve spend when the answer is yes (solid line).
- Within budget? returns to Prepare budget when the answer is no, revise (dashed line).
- Approve spend leads to Closed (solid line).
- Status is Needs input
- amber fill, from the status mapping
- Author highlight
- purple fill, chosen by hand, no status meaning
- No mapping or highlight
- Forma default
<forma-diagram class="forma-component-tag">
<figure class="forma-diagram" aria-labelledby="diagram-lanes-title">
<figcaption id="diagram-lanes-title">Budget approval</figcaption>
<p>Amber fill comes from the status mapping (Needs input). Purple is a highlight the author chose; it carries no status. Owners come from the lane.</p>
<div class="forma-diagram__viewport" tabindex="0" role="group" aria-label="Budget approval canvas, scroll to see all items">
<div class="forma-diagram__canvas" style="--forma-diagram-canvas-w: 780px; --forma-diagram-canvas-h: 430px;">
<div class="forma-diagram-group" data-forma-group="lane" style="--forma-diagram-x: 0px; --forma-diagram-y: 0px; --forma-diagram-w: 780px; --forma-diagram-h: 190px;">
<p class="forma-diagram-group__header"><span class="forma-diagram-group__kind">Lane</span> <span class="forma-diagram-group__label">Requester</span></p>
</div>
<div class="forma-diagram-group" data-forma-group="lane" style="--forma-diagram-x: 0px; --forma-diagram-y: 196px; --forma-diagram-w: 780px; --forma-diagram-h: 234px; --forma-diagram-accent: #6b3fa0;">
<p class="forma-diagram-group__header"><span class="forma-diagram-group__kind">Lane</span> <span class="forma-diagram-group__label">Finance</span></p>
</div>
<svg class="forma-diagram__wires" viewBox="0 0 780 430" aria-hidden="true" focusable="false">
<defs>
<marker id="diagram-lanes-arrow" class="forma-diagram-marker" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z"/></marker>
</defs>
<path class="forma-diagram-connector" d="M184 110 H214" marker-end="url(#diagram-lanes-arrow)"/>
<path class="forma-diagram-connector" d="M320 164 V222" marker-end="url(#diagram-lanes-arrow)"/>
<path class="forma-diagram-connector" d="M412 314 H468" marker-end="url(#diagram-lanes-arrow)"/>
<path class="forma-diagram-connector" data-forma-line="dashed" d="M228 314 H200 V150 H214" marker-end="url(#diagram-lanes-arrow)"/>
<path class="forma-diagram-connector" d="M558 240 V110 H638" marker-end="url(#diagram-lanes-arrow)"/>
</svg>
<article class="forma-diagram-node" data-forma-shape="ellipse" aria-labelledby="diagram-lanes-submit" style="--forma-diagram-x: 24px; --forma-diagram-y: 64px; --forma-diagram-w: 160px; --forma-diagram-h: 92px;">
<p class="forma-diagram-node__kind">Start</p>
<h3 class="forma-diagram-node__label" id="diagram-lanes-submit">Submit request</h3>
</article>
<article class="forma-diagram-node" data-forma-shape="rounded" aria-labelledby="diagram-lanes-prepare" style="--forma-diagram-x: 216px; --forma-diagram-y: 40px; --forma-diagram-w: 210px; --forma-diagram-fill: #fff1d6; --forma-diagram-accent: #8a5300; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">Activity</p>
<h3 class="forma-diagram-node__label" id="diagram-lanes-prepare">Prepare budget</h3>
<dl class="forma-diagram-node__meta"><dt>Status</dt><dd>Needs input</dd><dt>Owner</dt><dd>Requester <span class="forma-diagram-value-state" data-forma-value-state="derived">from lane</span></dd></dl>
</article>
<article class="forma-diagram-node" data-forma-shape="diamond" aria-labelledby="diagram-lanes-decide" style="--forma-diagram-x: 228px; --forma-diagram-y: 222px; --forma-diagram-w: 184px;">
<p class="forma-diagram-node__kind">Decision</p>
<h3 class="forma-diagram-node__label" id="diagram-lanes-decide">Within budget?</h3>
</article>
<article class="forma-diagram-node" aria-labelledby="diagram-lanes-approve" style="--forma-diagram-x: 470px; --forma-diagram-y: 240px; --forma-diagram-w: 180px; --forma-diagram-fill: #efe6fb; --forma-diagram-accent: #6b3fa0; --forma-diagram-foreground: #1d1d1b;">
<p class="forma-diagram-node__kind">Activity</p>
<h3 class="forma-diagram-node__label" id="diagram-lanes-approve">Approve spend</h3>
<dl class="forma-diagram-node__meta"><dt>Status</dt><dd>Waiting</dd><dt>Owner</dt><dd>Finance <span class="forma-diagram-value-state" data-forma-value-state="derived">from lane</span></dd></dl>
</article>
<article class="forma-diagram-node" data-forma-shape="ellipse" aria-labelledby="diagram-lanes-closed" style="--forma-diagram-x: 640px; --forma-diagram-y: 64px; --forma-diagram-w: 124px; --forma-diagram-h: 92px;">
<p class="forma-diagram-node__kind">End</p>
<h3 class="forma-diagram-node__label" id="diagram-lanes-closed">Closed</h3>
</article>
<span class="forma-diagram-connector__label" style="--forma-diagram-x: 422px; --forma-diagram-y: 290px;">yes</span>
<span class="forma-diagram-connector__label" style="--forma-diagram-x: 150px; --forma-diagram-y: 320px;">no, revise</span>
</div>
</div>
<ol class="forma-diagram__relations" aria-label="Relationships">
<li>Submit request leads to Prepare budget (solid line).</li>
<li>Prepare budget leads to Within budget? (solid line, moves from the Requester lane to the Finance lane).</li>
<li>Within budget? leads to Approve spend when the answer is yes (solid line).</li>
<li>Within budget? returns to Prepare budget when the answer is no, revise (dashed line).</li>
<li>Approve spend leads to Closed (solid line).</li>
</ol>
<dl class="forma-diagram-legend" aria-label="Key: what fill color means in this diagram">
<div><dt><span class="forma-diagram-legend__swatch" style="--forma-diagram-fill: #fff1d6; --forma-diagram-accent: #8a5300;"></span> Status is Needs input</dt><dd>amber fill, from the status mapping</dd></div>
<div><dt><span class="forma-diagram-legend__swatch" style="--forma-diagram-fill: #efe6fb; --forma-diagram-accent: #6b3fa0;"></span> Author highlight</dt><dd>purple fill, chosen by hand, no status meaning</dd></div>
<div><dt><span class="forma-diagram-legend__swatch"></span> No mapping or highlight</dt><dd>Forma default</dd></div>
</dl>
</figure>
</forma-diagram>
Click or tap the code once to select all of it, then copy.
Metadata with default, derived and missing values
One node inside a dashed phase boundary shows how the consumer marks values it did not receive from the author. Each tag is text (default, derived, from source, unknown, unavailable, invalid), so the distinction survives grayscale, forced colors and screen readers; explicit values carry no tag.
- Collect vendor details belongs to the Discovery phase; it has no connections yet.
<forma-diagram class="forma-component-tag">
<figure class="forma-diagram" aria-labelledby="diagram-states-title">
<figcaption id="diagram-states-title">Vendor onboarding, discovery phase</figcaption>
<div class="forma-diagram__viewport" tabindex="0" role="group" aria-label="Vendor onboarding canvas, scroll to see all items">
<div class="forma-diagram__canvas" style="--forma-diagram-canvas-w: 460px; --forma-diagram-canvas-h: 330px;">
<div class="forma-diagram-group" data-forma-group="phase" data-forma-line="dashed" style="--forma-diagram-x: 0px; --forma-diagram-y: 0px; --forma-diagram-w: 460px; --forma-diagram-h: 330px;">
<p class="forma-diagram-group__header"><span class="forma-diagram-group__kind">Phase</span> <span class="forma-diagram-group__label">Discovery</span></p>
</div>
<article class="forma-diagram-node" data-forma-shape="rounded" aria-labelledby="diagram-states-vendor" style="--forma-diagram-x: 24px; --forma-diagram-y: 44px; --forma-diagram-w: 410px;">
<p class="forma-diagram-node__kind">Activity</p>
<h3 class="forma-diagram-node__label" id="diagram-states-vendor">Collect vendor details</h3>
<dl class="forma-diagram-node__meta">
<dt>Status</dt><dd>In review</dd>
<dt>Priority</dt><dd>Normal <span class="forma-diagram-value-state" data-forma-value-state="default">default</span></dd>
<dt>Phase</dt><dd>Discovery <span class="forma-diagram-value-state" data-forma-value-state="derived">derived from phase</span></dd>
<dt>Risk tier</dt><dd>Tier 2 <span class="forma-diagram-value-state" data-forma-value-state="source-bound">from vendor registry</span></dd>
<dt>Due</dt><dd><span class="forma-diagram-value-state" data-forma-value-state="unknown">unknown</span></dd>
<dt>Contract</dt><dd><span class="forma-diagram-value-state" data-forma-value-state="unavailable">unavailable, registry offline</span></dd>
<dt>Cost center</dt><dd>12-A <span class="forma-diagram-value-state" data-forma-value-state="invalid">invalid, not a listed cost center</span></dd>
</dl>
</article>
</div>
</div>
<ol class="forma-diagram__relations" aria-label="Relationships">
<li>Collect vendor details belongs to the Discovery phase; it has no connections yet.</li>
</ol>
</figure>
</forma-diagram>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile scrolling canvas
On a phone the fixed-size canvas scrolls inside its own focusable viewport, while the caption and the relationship list reflow to the screen width.
What changes at narrow widths
- The canvas keeps its consumer-supplied size (here 560 by 150 px) and scrolls inside
.forma-diagram__viewport; the page itself does not scroll sideways at 320px. - The viewport is a focusable, named group, so keyboard users can scroll it with the arrow keys and touch users can pan it;
overscroll-behavior: containstops the pan from scrolling the page. - The relationship list and key reflow to full width, so every connection is readable without panning the canvas.
- Node text wraps with
overflow-wrap: anywhereinside the authored node width; Forma does not rescale geometry for orientation changes.
<forma-diagram class="forma-component-tag">
<figure class="forma-diagram" aria-labelledby="diagram-mobile-title">
<figcaption id="diagram-mobile-title">Password reset</figcaption>
<div class="forma-diagram__viewport" tabindex="0" role="group" aria-label="Password reset canvas, scroll to see all items">
<div class="forma-diagram__canvas" style="--forma-diagram-canvas-w: 560px; --forma-diagram-canvas-h: 150px;">
<svg class="forma-diagram__wires" viewBox="0 0 560 150" aria-hidden="true" focusable="false">
<defs>
<marker id="diagram-mobile-arrow" class="forma-diagram-marker" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0 0 L10 5 L0 10 z"/></marker>
</defs>
<path class="forma-diagram-connector" d="M176 60 H198" marker-end="url(#diagram-mobile-arrow)"/>
<path class="forma-diagram-connector" d="M362 60 H384" marker-end="url(#diagram-mobile-arrow)"/>
</svg>
<article class="forma-diagram-node" data-forma-shape="pill" aria-labelledby="diagram-mobile-request" style="--forma-diagram-x: 16px; --forma-diagram-y: 20px; --forma-diagram-w: 160px;">
<p class="forma-diagram-node__kind">Start</p>
<h3 class="forma-diagram-node__label" id="diagram-mobile-request">Request link</h3>
</article>
<article class="forma-diagram-node" aria-labelledby="diagram-mobile-verify" style="--forma-diagram-x: 200px; --forma-diagram-y: 20px; --forma-diagram-w: 160px;">
<p class="forma-diagram-node__kind">Task</p>
<h3 class="forma-diagram-node__label" id="diagram-mobile-verify">Verify email</h3>
</article>
<article class="forma-diagram-node" data-forma-shape="pill" aria-labelledby="diagram-mobile-set" style="--forma-diagram-x: 386px; --forma-diagram-y: 20px; --forma-diagram-w: 160px;">
<p class="forma-diagram-node__kind">End</p>
<h3 class="forma-diagram-node__label" id="diagram-mobile-set">Set new password</h3>
</article>
</div>
</div>
<ol class="forma-diagram__relations" aria-label="Relationships">
<li>Request link leads to Verify email (solid line).</li>
<li>Verify email leads to Set new password (solid line).</li>
</ol>
</figure>
</forma-diagram>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Live demo. 1 native action works here and is verified by an outcome test.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
aria-labelledby | figure, node article | id of the caption or node label | — | Names the diagram by its caption and each node by its label heading. |
tabindex | .forma-diagram__viewport | 0 | — | Makes the scrolling canvas reachable by keyboard so it can be scrolled without a pointer. |
role | .forma-diagram__viewport | group | — | Gives the focusable viewport a role so its name is announced. |
aria-label | viewport, relations list, legend | string | — | Names the canvas (say that it scrolls), the relationship list and the key. |
aria-hidden | svg.forma-diagram__wires | true | — | Hides the drawn connectors; the relationship list is their text equivalent. |
focusable | svg.forma-diagram__wires | false | — | Keeps legacy browsers from putting the SVG in the tab order. |
marker-end | path.forma-diagram-connector | url(#marker-id) | — | Attaches the arrowhead. Marker ids must be unique in the document. |
style | canvas, node, group, connector, label, swatch | custom property declarations | — | Where the consumer writes resolved geometry and authored color values. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-diagram | Block class | — | The figure root: a single-column grid of caption, optional description, viewport, relationship list and key. |
.forma-diagram__canvas | Element class | — | Positioning context sized by --forma-diagram-canvas-w and --forma-diagram-canvas-h. |
.forma-diagram__membership | Element class | — | Description list naming each group, lane or phase and its members in reading order. |
.forma-diagram__relations | Element class | — | Ordered list with one text item per connector, in reading order. |
.forma-diagram__viewport | Element class | — | Bordered region that scrolls the canvas in both directions and contains overscroll. |
.forma-diagram__wires | Element class | — | The SVG layer that fills the canvas and draws connectors. Ignores pointer events. Its viewBox must match the canvas size so path coordinates and node positions share one pixel space. |
--forma-diagram-canvas-h | Custom property | — | Canvas height in px, supplied by the consumer. Default 320px. |
--forma-diagram-canvas-w | Custom property | — | Canvas width in px, supplied by the consumer. Default 720px. |
.forma-diagram-connector | Block class | — | An SVG path connector; stroke comes from authored or token values. |
.forma-diagram-connector__label | Element class | — | A text label placed on the canvas with --forma-diagram-x/-y, on a surface-colored background. |
[data-forma-line] | Attribute hook | "dashed", "dotted" | Connector line style: absent for solid, dashed or dotted. Presentation only; state the meaning in the relationship list. |
--forma-diagram-connector-stroke | Custom property | — | Authored connector color. Falls back to the functional border token. |
--forma-diagram-connector-width | Custom property | — | Authored connector stroke width in SVG units. Default 2. |
.forma-diagram-group | Block class | — | A group, lane or phase boundary placed with --forma-diagram-x, -y, -w and -h. Put it first in the canvas so it paints beneath connectors and nodes. Overlap never implies membership: state membership in text. |
.forma-diagram-group__header | Element class | — | The boundary's visible heading row, holding the kind and label text. |
.forma-diagram-group__kind | Element class | — | Visible kind text (Lane, Phase, Group), small uppercase. |
.forma-diagram-group__label | Element class | — | The group's name, for example the actor that owns a lane. |
[data-forma-group] | Attribute hook | "lane" | Group presentation: absent or group for a boxed region, lane for a band with an inline-start accent, phase for a band with a top accent. Presentation only; the kind is the text in __kind. |
[data-forma-line] | Attribute hook | "dashed", "dotted" | Connector line style: absent for solid, dashed or dotted. Presentation only; state the meaning in the relationship list. |
--forma-diagram-group-accent | Custom property | default var(--forma-diagram-accent, var(--forma-diagram-group-stroke)) | Internal resolved group accent; read-only. Set --forma-diagram-accent instead. |
--forma-diagram-group-fill | Custom property | default var(--forma-diagram-fill, transparent) | Internal resolved group fill; read-only. Set --forma-diagram-fill instead. Transparent by default. |
--forma-diagram-group-foreground | Custom property | default var(--forma-diagram-foreground, var(--forma-color-text-primary, #161616)) | Internal resolved group text color; read-only. Set --forma-diagram-foreground instead. |
--forma-diagram-group-stroke | Custom property | default var(--forma-diagram-stroke, var(--forma-color-border-functional, #555555)) | Internal resolved group border; read-only. Set --forma-diagram-stroke instead. |
.forma-diagram-legend | Block class | — | A dl key that explains any authored color mapping; wraps as a flex row. |
.forma-diagram-legend__swatch | Element class | — | A small sample box that reads the same color properties as a node. |
.forma-diagram-marker | Block class | — | An SVG marker for arrowheads, filled with the functional border color. |
.forma-diagram-node | Block class | — | An absolutely placed node box with a 2px border and a 6px inline-start accent. Long text wraps anywhere. |
.forma-diagram-node__description | Element class | — | Optional description text inside a node. |
.forma-diagram-node__kind | Element class | — | Visible kind text (Task, Decision, End), small uppercase. The primary non-color cue. |
.forma-diagram-node__label | Element class | — | The node's label, normally an h3 that also names the node. |
.forma-diagram-node__meta | Element class | — | A dl of metadata the consumer chose to show, laid out as a two-column grid. |
[data-forma-shape] | Attribute hook | "diamond", "ellipse", "pill", "rounded" | Node shape: absent for a rectangle, rounded for rounded corners, pill for fully rounded ends, ellipse, or diamond (a square box whose content sits inside the diamond; give it enough width for the label). Presentation only: the kind text, not the shape, says what the node is. |
[data-forma-status] | Attribute hook | "active", "blocked", "cancelled", "failed", "pending", "skipped", "waiting" | On a node or group: the core status (pending, waiting, active, blocked, failed, skipped, cancelled) for a secondary outline or border cue. The status itself is text in the node metadata. |
--forma-diagram-node-accent | Custom property | default var(--forma-diagram-accent, var(--forma-diagram-node-stroke)) | Internal resolved accent color; read-only. Set --forma-diagram-accent instead. |
--forma-diagram-node-fill | Custom property | default var(--forma-diagram-fill, var(--forma-color-surface-primary, #fafafa)) | Internal resolved fill on each node; read-only. Set --forma-diagram-fill instead. |
--forma-diagram-node-foreground | Custom property | default var(--forma-diagram-foreground, var(--forma-color-text-primary, #161616)) | Internal resolved text color; read-only. Set --forma-diagram-foreground instead. |
--forma-diagram-node-stroke | Custom property | default var(--forma-diagram-stroke, var(--forma-color-border-functional, #555555)) | Internal resolved border color; read-only. Set --forma-diagram-stroke instead. |
.forma-diagram-port | Block class | — | A connection-point marker inside a node; .forma-diagram-port__label names it. |
.forma-diagram-port__label | Element class | — | Structural element; see the Basic example for placement. |
[data-forma-direction] | Attribute hook | "in", "inout" | On .forma-diagram-port: in (square), out (circle) or inout (diamond). |
[data-forma-side] | Attribute hook | "bottom", "left", "right", "top" | On .forma-diagram-port: the node side the port sits on (top, right, bottom, left). |
--forma-diagram-port-offset | Custom property | — | On .forma-diagram-port: position along its side as a percentage (default 50%). |
.forma-diagram-value-state | Block class | — | A small text tag after a metadata value that says how the consumer obtained it. Explicit values carry no tag. |
[data-forma-value-state] | Attribute hook | "invalid", "source-bound", "unavailable", "unknown" | Secondary border cue on the value-state tag: default or derived (dashed), source-bound (double), unknown or unavailable (dotted), invalid (solid, bold). The tag text carries the meaning. |
--forma-diagram-h | Custom property | — | Minimum node height, or the group height. Nodes grow taller when content needs it. |
--forma-diagram-x | Custom property | — | Horizontal position of a node or connector label from the canvas's left edge (physical, not mirrored in RTL). |
--forma-diagram-y | Custom property | — | Vertical position of a node or connector label from the canvas top. |
--forma-diagram-w | Custom property | — | Node width. Default 12rem. |
--forma-diagram-fill | Custom property | — | Authored node background. Falls back to the primary surface token. |
--forma-diagram-stroke | Custom property | — | Authored node border. Falls back to the functional border token. |
--forma-diagram-accent | Custom property | — | Authored inline-start accent bar. Falls back to the node stroke. |
--forma-diagram-foreground | Custom property | — | Authored node text color. The consumer is responsible for contrast against the fill. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves to the canvas viewport, then to any links inside nodes in source order. |
| Arrow keys, Page Up / Page Down (viewport focused) | Scrolls the canvas. Native scrolling of a focused overflow region. |
| Selection, moving or connecting nodes | Not provided. Editing interactions belong to the consuming editor and must not reuse forma-diagram* classes. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Default appearance | no authored custom properties | Nodes and connectors use Forma surface, border and text tokens. |
| Authored color | --forma-diagram-fill / -stroke / -accent / -foreground, --forma-diagram-connector-stroke / -width | Consumer-resolved colors; removing one restores the token default. |
| Shape | data-forma-shape="rounded" | "pill" | "ellipse" | "diamond" | Rounded corners, pill ends, ellipse or diamond; rectangle when absent. Every shape keeps a real border for backgrounds-off print. |
| Group, lane or phase | div.forma-diagram-group with data-forma-group="lane" | "phase" and optional data-forma-line | A labelled boundary beneath nodes; accepts the same authored color properties as a node. |
| Metadata value state | span.forma-diagram-value-state with data-forma-value-state | Text tag marking default, derived, source-bound, unknown, unavailable or invalid values. |
| Line style | data-forma-line="dashed" | "dotted" | Dash pattern on a connector; solid when absent. |
| Viewport focus | :focus-visible on .forma-diagram__viewport | Foundation focus ring, independent of authored color. |
| Forced colors | @media (forced-colors: active) | Nodes, swatches and labels become Canvas/CanvasText; connectors and markers use CanvasText. Kind text, shape and line style remain. |
| @media print | Viewport stops scrolling and nodes avoid page breaks. Authored strokes and accents print; boundaries without an authored stroke print black, so they stay visible with backgrounds disabled. |
Accessibility
Forma provides
- Provides a structural place for a text relationship list, so every connection is available without the drawing, color or SVG.
- Keeps kind text, shape and line style visible in forced colors, grayscale and backgrounds-off print.
- Makes the canvas scroll inside its own region so the page does not overflow at 320px.
- Never derives focus appearance from authored color.
Your application supplies
- Write one relationship item per connector, in reading order, including the meaning of any dashed or dotted line.
- Give every node a visible kind and, where relevant, a state in text; never let color, shape or line style be the only carrier of meaning.
- Provide a key whenever color carries grouping information, and check contrast between authored fill and foreground.
- Make the viewport focusable with a name that says it scrolls, and keep marker ids unique.
- Keep node source order meaningful; it is the reading order for assistive technology regardless of position.
Responsive behavior
- The figure is a single-column grid that shrinks to the container; the canvas does not reflow because geometry belongs to the consumer.
- When the canvas is wider or taller than the viewport,
.forma-diagram__viewportscrolls in both directions with contained overscroll. - Node text wraps within
--forma-diagram-w; at 200% text size nodes grow taller, so consumer layouts should leave vertical room. - Connector labels do not wrap (
white-space: nowrap); keep them short. - The relationship list and the key reflow to any width.
Motion
- No animation: nodes, connectors and labels are static. Any layout transition, panning or highlighting is editor behavior owned by the consumer.
Usage guidance
Do
- Resolve metadata-to-color mapping in the consumer profile and pass only final values.
- Match the SVG
viewBoxto the canvas size so nodes and connectors line up.
Avoid
- Encoding status in color, for example red for failed, without text.
- Adding selection handles, guides or drag targets inside an exported diagram, or styling them with
forma-diagram*classes. - Positioning nodes with logical properties; SVG coordinates are physical.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.