Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
Choose the phased workflow layout by its readable width
tt-a1i43604e94df7c
diff --git a/archify/explainer/browser-check.mjs b/archify/explainer/browser-check.mjsindex 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.mjsindex 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 = 1const 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.jsindex 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.mdindex 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.