Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Choose the phased workflow layout by its readable width

tt-a1i43604e94df7c
diff --git a/archify/explainer/browser-check.mjs b/archify/explainer/browser-check.mjs
index 49fd259b..72f8f8b0 100644
--- a/archify/explainer/browser-check.mjs
+++ b/archify/explainer/browser-check.mjs
@@ -16,7 +16,7 @@ function measureNativePreviews() {
return Array.from(document.querySelectorAll('.diagram-preview svg')).map(svg=>{
const block=svg.closest('[data-block-type]'),panel=block.closest('.panel'),preview=svg.closest('.diagram-preview');
const prose=panel.querySelector('.block-prose > p')||document.querySelector('.block-prose > p'),body=parseFloat(getComputedStyle(prose||panel.querySelector('.panel-body')||block).fontSize);
- const texts=Array.from(svg.querySelectorAll('text')).filter(e=>e.textContent.trim()&&visible(e)).map(e=>{const m=e.getScreenCTM(),sum=m.a*m.a+m.b*m.b+m.c*m.c+m.d*m.d,det=m.a*m.d-m.b*m.c,scale=Math.sqrt(Math.max(0,(sum-Math.sqrt(Math.max(0,sum*sum-4*det*det)))/2));return {text:e.textContent.trim(),size:parseFloat(getComputedStyle(e).fontSize)*scale/(e.closest('[data-edge-id]')?.8:1)};});
+ const texts=Array.from(svg.querySelectorAll('text')).filter(e=>e.textContent.trim()&&visible(e)).map(e=>{const m=e.getScreenCTM(),sum=m.a*m.a+m.b*m.b+m.c*m.c+m.d*m.d,det=m.a*m.d-m.b*m.c,scale=Math.sqrt(Math.max(0,(sum-Math.sqrt(Math.max(0,sum*sum-4*det*det)))/2));return {text:e.textContent.trim(),size:parseFloat(getComputedStyle(e).fontSize)*scale/(e.closest('[data-edge-id]')?.7:1)};});
const minimum=texts.length?Math.min(...texts.map(t=>t.size)):null,bounds=rect(preview),svgBounds=rect(svg);
const nodes=Array.from(svg.querySelectorAll('[data-node-id]')).filter(visible).map(e=>({id:e.dataset.nodeId,...rect(e)}));
const outside=nodes.filter(n=>n.left<bounds.left-1||n.right>bounds.right+1||n.top<bounds.top-1||n.bottom>bounds.bottom+1);
diff --git a/archify/explainer/diagrams.mjs b/archify/explainer/diagrams.mjs
index a9658684..fc7de7a0 100644
--- a/archify/explainer/diagrams.mjs
+++ b/archify/explainer/diagrams.mjs
@@ -63,6 +63,18 @@ function duplicateCheck(items, context, kind) {
}
}
+// Estimated native workflow canvas width for a column assignment: the widest node per column plus the
+// column gaps, which widen for edge labels. Measured within about 10% of real canvases. The native gate
+// projects 8px edge labels onto a 930px reader, so 1240px is the hard limit; this keeps a margin.
+const READABLE_WORKFLOW_WIDTH = 1100;
+function workflowWidth(nodes, edges) {
+ const columns = Math.max(...nodes.map(node => node.col)) + 1;
+ const widest = Array.from({ length: columns }, (_, col) => Math.max(92, ...nodes.filter(node => node.col === col).map(node => node.width || 0)));
+ const colOf = new Map(nodes.map(node => [node.id, node.col]));
+ const gaps = Array.from({ length: columns - 1 }, (_, col) => Math.max(34, ...edges.filter(edge => colOf.get(edge.from) === col && colOf.get(edge.to) === col + 1).map(edge => (edge.label ? textUnits(edge.label) * 5.4 : 0) + 16)));
+ return widest.reduce((sum, width) => sum + width, 0) + gaps.reduce((sum, gap) => sum + gap, 0) + 80;
+}
+
// Placement supplies native grid/lane hints only. Native renderers own sizing,
// ports, routes, labels, and all quality validation.
function rankedPlacement(nodes, edges) {
@@ -197,26 +209,29 @@ export function compileExplainerDiagram(diagramType, rows, { title, id, line = 1
const first = lanes.keys().next().value;
const order = [...lanes.keys()];
const ranked = [...placed].sort((a, b) => a.col - b.col || a.row - b.row).map(({ row, col, ...node }) => ({ ...node, lane: nodeLanes.get(node.id)?.lane || first }));
- // Up to six nodes read best as one row with phase labels above it; longer processes wrap into lane rows.
- if (ranked.length <= 6 && placed.every(node => node.row === 0)) {
- const row = ranked.sort((a, b) => order.indexOf(a.lane) - order.indexOf(b.lane));
+ // Prefer, in order: one row with phase labels above it; phase rows that step down so each hand-off
+ // edge drops straight; phase rows that each restart at the left. Take the first that stays within
+ // the readable width, since a wider canvas shrinks its edge labels below the native text floor.
+ const row = [...ranked].sort((a, b) => order.indexOf(a.lane) - order.indexOf(b.lane));
+ const used = [...lanes.values()].filter(lane => ranked.some(node => node.lane === lane.id));
+ const sizes = used.map(lane => ranked.filter(node => node.lane === lane.id).length);
+ const wrapped = stair => {
+ const starts = sizes.map((_, i) => stair ? sizes.slice(0, i).reduce((sum, size) => sum + size - 1, 0) : 0);
+ const nextCol = new Map(used.map((lane, i) => [lane.id, starts[i]]));
+ return ranked.map(node => { const col = nextCol.get(node.lane); nextCol.set(node.lane, col + 1); return { ...node, col }; });
+ };
+ const single = row.map(({ lane, ...node }, col) => ({ ...node, lane: 'flow', col }));
+ const candidates = [
+ ...(ranked.length <= 6 && placed.every(node => node.row === 0) ? [{ nodes: single, single: true }] : []),
+ ...(sizes.reduce((sum, size) => sum + size, 0) - (sizes.length - 1) <= 6 ? [{ nodes: wrapped(true) }] : []),
+ { nodes: wrapped(false) },
+ ];
+ const chosen = candidates.find(candidate => workflowWidth(candidate.nodes, edges) <= READABLE_WORKFLOW_WIDTH) || candidates.at(-1);
+ spec.nodes = chosen.nodes;
+ if (chosen.single) {
spec.lanes = [{ id: 'flow', label: spec.meta.title }];
- spec.nodes = row.map(({ lane, ...node }, col) => ({ ...node, lane: 'flow', col }));
spec.phases = order.map(id => ({ id, label: lanes.get(id).label, cols: row.flatMap((node, col) => node.lane === id ? [col] : []) })).filter(phase => phase.cols.length).map(({ cols, ...phase }) => ({ ...phase, fromCol: cols[0], toCol: cols.at(-1) }));
- } else {
- // Each phase row starts under the end of the previous one when the staircase fits six columns,
- // so the hand-off edge drops straight down instead of crossing back over the rows.
- spec.lanes = [...lanes.values()].filter(lane => ranked.some(node => node.lane === lane.id));
- const sizes = spec.lanes.map(lane => ranked.filter(node => node.lane === lane.id).length);
- const stair = sizes.reduce((sum, size) => sum + size, 0) - (sizes.length - 1) <= 6;
- const starts = sizes.map((_, i) => stair ? sizes.slice(0, i).reduce((sum, size) => sum + size - 1, 0) : 0);
- const nextCol = new Map(spec.lanes.map((lane, i) => [lane.id, starts[i]]));
- spec.nodes = ranked.map(node => {
- const laneCol = nextCol.get(node.lane);
- nextCol.set(node.lane, laneCol + 1);
- return { ...node, col: laneCol };
- });
- }
+ } else spec.lanes = used;
if (spec.nodes.some(node => node.col > 5)) fail(context, 'diagram-shorthand-limit', 'A workflow lane holds at most six nodes.', 'Split the process into another lane.');
spec.edges = edges;
} else {
diff --git a/archify/explainer/reader.js b/archify/explainer/reader.js
index cf56b800..cffde2a9 100644
--- a/archify/explainer/reader.js
+++ b/archify/explainer/reader.js
@@ -153,7 +153,7 @@
});
}
// Edge labels are secondary to node text and may sit a little below the reading floor.
- const secondary = text => text.closest('[data-edge-id]') ? .8 : 1;
+ const secondary = text => text.closest('[data-edge-id]') ? .7 : 1;
function textFloor() {
const bodySize = parseFloat(getComputedStyle(document.querySelector('.block-prose>p') || document.body).fontSize);
return window.innerWidth >= 1440 ? Math.max(10,bodySize * .75) : 10;
diff --git a/archify/references/explainer-authoring.md b/archify/references/explainer-authoring.md
index 802b2812..34457abd 100644
--- a/archify/references/explainer-authoring.md
+++ b/archify/references/explainer-authoring.md
@@ -131,7 +131,7 @@ Actor rows: `actor <id> | label | type`. Message rows: `from | to | label | vari
| trace > fix | cause found | emphasis |
```
-Node rows: `id | label | type?`. Edge rows: `from > to | label? | variant?`. Nodes widen to fit their labels. Keep edge labels to one or two words.
+Node rows: `id | label | type?`. Edge rows: `from > to | label? | variant?`. Nodes widen to fit their labels, so a node label names the step in a few words (up to about 10 Chinese characters or 4 English words) and `@steps` carries the detail. Keep edge labels to one or two words.
Group the steps of a process into phases: declare `lane <id> | label` rows, then give each workflow node its phase as a fourth cell. Up to six nodes draw as one row with the phase labels above it; a longer process wraps into one row per phase.