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
feat: layout guidance in SKILL and actionable validator hints (#7)
tt-a1ia925f719a0ba
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1111e864..798d95c1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,10 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo## [Unreleased]+### Added+- **Layout principles in SKILL.md** — main-path-first guidance, side-branch rules, and pointers to `archify-repo` / `maka-architecture` examples.+- **Validator fix suggestions (#7)** — label overlap and component proximity errors now include rects plus concrete `labelAt` / `labelDy` or `pos` nudges.+## [2.9.0] — 2026-07-05### Addeddiff --git a/archify.zip b/archify.zipindex fdce06fc..ed52c150 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 96ca872f..e823a340 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -50,6 +50,20 @@ When the user pastes Mermaid code, do NOT try to render or parse it mechanicallyDrop Mermaid styling; keep only the topology and meaning. You choose grouping, lane order, and what deserves emphasis — that judgment is the product.+## Layout principles (read before placing)++Archify's readability comes from **spatial narrative**, not from drawing every dependency as an arrow. Before you write coordinates or edge lists, plan one clear story:++1. **One main path** — left → right (architecture) or lane → column (workflow). The reader should trace the happy path without crossing lines.+2. **Few labeled edges** — label only cross-boundary or non-obvious transitions on the main path. Adjacent steps stay unlabeled.+3. **Short side branches** — permissions, storage, bots, CI: connect **up or down** from the nearest node on the main path. Never route a secondary edge diagonally across unrelated components.+4. **Cards for detail** — policies, tech stack notes, and "also connects to X" belong in summary cards, not as extra arrows.+5. **Mode fit** — process / approval / tool-call stories → `workflow` or `sequence`. Component maps with ≤12 nodes → `architecture`. If the diagram needs 20+ edges, remove edges until the main path is obvious.++Worked examples on this pattern: `examples/archify-repo.architecture.json` (this repo) and `examples/maka-architecture.architecture.json` (third-party desktop app).++When validation fails on label overlap, read the **Suggested fix** lines (coordinates / `labelAt` / `labelDy`) and apply them directly — do not guess offsets blindly.+## Renderer Modes (architecture / workflow / sequence / dataflow / lifecycle)All five modes follow the same loop:diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjsindex b25765d4..bf1b7eda 100644--- a/archify/renderers/architecture/render-architecture.mjs+++ b/archify/renderers/architecture/render-architecture.mjs@@ -6,6 +6,8 @@ import {asArray,isFinitePoint,rectsOverlap,+ suggestLabelObstacleFix,+ suggestComponentSeparation,anchor,defaultFromSide,defaultToSide,@@ -131,7 +133,7 @@ function validateArchitecture() {for (let i = 0; i < list.length; i += 1) {for (let j = i + 1; j < list.length; j += 1) {if (rectsOverlap(list[i], list[j], 8)) {- problems.push(`Components "${list[i].id}" and "${list[j].id}" are less than 8px apart — move one or shrink its size.`);+ problems.push(`Components "${list[i].id}" and "${list[j].id}" are less than 8px apart — move one or shrink its size.\n${suggestComponentSeparation(list[i], list[j], 8)}`);}}}@@ -165,12 +167,12 @@ function validateArchitecture() {if (!conn.label || !components.has(conn.from) || !components.has(conn.to)) continue;const [lx, ly] = labelPoint(conn, pathFor(conn).points);const w = Math.max(30, textUnits(conn.label) * 4.8 + 10);- labelRects.push({ label: conn.label, x: lx - w / 2, y: ly - 10, width: w, height: 14 });+ labelRects.push({ label: conn.label, x: lx - w / 2, y: ly - 10, width: w, height: 14, lx, ly });}for (const rect of labelRects) {for (const c of components.values()) {if (rectsOverlap(rect, c, -2)) {- problems.push(`Label "${rect.label}" overlaps component "${c.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.`);+ problems.push(`Label "${rect.label}" overlaps component "${c.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.\n${suggestLabelObstacleFix(rect, rect.lx, rect.ly, c)}`);}}}diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjsindex f0921361..9882894f 100644--- a/archify/renderers/dataflow/render-dataflow.mjs+++ b/archify/renderers/dataflow/render-dataflow.mjs@@ -6,6 +6,8 @@ import {asArray,isFinitePoint,rectsOverlap,+ suggestLabelObstacleFix,+ suggestLabelPairFix,anchor,defaultFromSide,defaultToSide,@@ -138,19 +140,19 @@ function validateDataflow() {const longestLine = Math.max(textUnits(flow.label), textUnits(flow.classification || ''));const width = Math.max(34, longestLine * 4.9 + 12);const height = flow.classification ? 27 : layout.labelH;- labelRects.push({ label: flow.label, x: lx - width / 2, y: ly - 11, width, height });+ labelRects.push({ label: flow.label, x: lx - width / 2, y: ly - 11, width, height, lx, ly });}for (const rect of labelRects) {for (const node of nodes.values()) {if (rectsOverlap(rect, node, -2)) {- problems.push(`Label "${rect.label}" overlaps node "${node.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.`);+ problems.push(`Label "${rect.label}" overlaps node "${node.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.\n${suggestLabelObstacleFix(rect, rect.lx, rect.ly, node, 'node')}`);}}}for (let i = 0; i < labelRects.length; i += 1) {for (let j = i + 1; j < labelRects.length; j += 1) {if (rectsOverlap(labelRects[i], labelRects[j], -2)) {- problems.push(`Labels "${labelRects[i].label}" and "${labelRects[j].label}" overlap — adjust labelDx/labelDy.`);+ problems.push(`Labels "${labelRects[i].label}" and "${labelRects[j].label}" overlap — adjust labelDx/labelDy.\n${suggestLabelPairFix(labelRects[i], labelRects[j])}`);}}}diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjsindex 43e14ded..910a98e2 100644--- a/archify/renderers/lifecycle/render-lifecycle.mjs+++ b/archify/renderers/lifecycle/render-lifecycle.mjs@@ -6,6 +6,8 @@ import {asArray,isFinitePoint,rectsOverlap,+ suggestLabelObstacleFix,+ suggestLabelPairFix,anchor,defaultFromSide,defaultToSide,@@ -190,19 +192,19 @@ function validateLifecycle() {const longestLine = Math.max(textUnits(transition.label), textUnits(transition.note || ''));const width = Math.max(32, longestLine * 4.9 + 12);const height = transition.note ? 27 : 16;- labelRects.push({ label: transition.label, x: lx - width / 2, y: ly - 11, width, height });+ labelRects.push({ label: transition.label, x: lx - width / 2, y: ly - 11, width, height, lx, ly });}for (const rect of labelRects) {for (const state of states.values()) {if (rectsOverlap(rect, state, -2)) {- problems.push(`Label "${rect.label}" overlaps state "${state.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.`);+ problems.push(`Label "${rect.label}" overlaps state "${state.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.\n${suggestLabelObstacleFix(rect, rect.lx, rect.ly, state, 'state')}`);}}}for (let i = 0; i < labelRects.length; i += 1) {for (let j = i + 1; j < labelRects.length; j += 1) {if (rectsOverlap(labelRects[i], labelRects[j], -2)) {- problems.push(`Labels "${labelRects[i].label}" and "${labelRects[j].label}" overlap — adjust labelDx/labelDy.`);+ problems.push(`Labels "${labelRects[i].label}" and "${labelRects[j].label}" overlap — adjust labelDx/labelDy.\n${suggestLabelPairFix(labelRects[i], labelRects[j])}`);}}}diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjsindex 3fee0e49..d69aeb98 100644--- a/archify/renderers/shared/geometry.mjs+++ b/archify/renderers/shared/geometry.mjs@@ -188,3 +188,43 @@ export function variantAccent(variant, { dashed = 't-messagebus' } = {}) {? dashed: 't-muted';}++export function formatRect(r) {+ return `[${Math.round(r.x)}, ${Math.round(r.y)}, ${Math.round(r.width)}, ${Math.round(r.height)}]`;+}++function formatDelta(n) {+ const v = Math.round(n);+ return v >= 0 ? `+${v}` : String(v);+}++/** Actionable hint when an edge label rect hits a node/component box (#7). */+export function suggestLabelObstacleFix(labelRect, lx, ly, obstacle, obstacleKind = 'component') {+ const lxR = Math.round(lx);+ const lyR = Math.round(ly);+ const belowY = Math.round(obstacle.y + obstacle.height + 14);+ const aboveY = Math.round(obstacle.y - 4);+ return [+ ` label rect: ${formatRect(labelRect)}`,+ ` ${obstacleKind} "${obstacle.id}" rect: ${formatRect(obstacle)}`,+ ` Suggested fix: labelAt [${lxR}, ${belowY}] or labelDy ${formatDelta(belowY - lyR)} (below); or labelAt [${lxR}, ${aboveY}] or labelDy ${formatDelta(aboveY - lyR)} (above)`,+ ].join('\n');+}++/** Hint when two edge labels collide. */+export function suggestLabelPairFix(a, b) {+ return [+ ` "${a.label}" ${formatRect(a)}; "${b.label}" ${formatRect(b)}`,+ ' Suggested fix: add labelDy +24 on one edge, adjust labelDx, or remove one label',+ ].join('\n');+}++/** Hint when two components/nodes are too close. */+export function suggestComponentSeparation(a, b, minGap = 8) {+ const rightX = Math.round(a.x + a.width + minGap);+ const belowY = Math.round(a.y + a.height + minGap);+ return [+ ` "${a.id}" ${formatRect(a)}; "${b.id}" ${formatRect(b)}`,+ ` Suggested fix: move "${b.id}" pos to [${rightX}, ${Math.round(b.y)}] (right of "${a.id}") or [${Math.round(b.x)}, ${belowY}] (below)`,+ ].join('\n');+}diff --git a/archify/renderers/workflow/render-workflow.mjs b/archify/renderers/workflow/render-workflow.mjsindex 3c3398af..2c31d3d6 100644--- a/archify/renderers/workflow/render-workflow.mjs+++ b/archify/renderers/workflow/render-workflow.mjs@@ -7,6 +7,8 @@ import {isFinitePoint,rectsOverlap,segmentIntersectsRect,+ suggestLabelObstacleFix,+ suggestLabelPairFix,anchor,defaultFromSide,defaultToSide,@@ -270,19 +272,19 @@ function validateWorkflow() {if (!edge.label || !nodes.has(edge.from) || !nodes.has(edge.to)) continue;const [lx, ly] = labelPoint(edge, pathFor(edge).points);const width = Math.max(30, textUnits(edge.label) * 4.8 + 10);- labelRects.push({ label: edge.label, x: lx - width / 2, y: ly - 10, width, height: 14 });+ labelRects.push({ label: edge.label, x: lx - width / 2, y: ly - 10, width, height: 14, lx, ly });}for (const rect of labelRects) {for (const node of nodes.values()) {if (rectsOverlap(rect, node, -2)) {- problems.push(`Label "${rect.label}" overlaps node "${node.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.`);+ problems.push(`Label "${rect.label}" overlaps node "${node.id}" — adjust labelDx/labelDy/labelSegment or set labelAt.\n${suggestLabelObstacleFix(rect, rect.lx, rect.ly, node, 'node')}`);}}}for (let i = 0; i < labelRects.length; i += 1) {for (let j = i + 1; j < labelRects.length; j += 1) {if (rectsOverlap(labelRects[i], labelRects[j], -2)) {- problems.push(`Labels "${labelRects[i].label}" and "${labelRects[j].label}" overlap — adjust labelDx/labelDy or remove one label.`);+ problems.push(`Labels "${labelRects[i].label}" and "${labelRects[j].label}" overlap — adjust labelDx/labelDy or remove one label.\n${suggestLabelPairFix(labelRects[i], labelRects[j])}`);}}}diff --git a/archify/test/geometry.test.mjs b/archify/test/geometry.test.mjsindex 69ebffb5..63759ef5 100644--- a/archify/test/geometry.test.mjs+++ b/archify/test/geometry.test.mjs@@ -19,8 +19,10 @@ import {polylinePath,roundedPath,labelPoint,+ suggestLabelObstacleFix,+ suggestComponentSeparation,} from '../renderers/shared/geometry.mjs';-import { textUnits } from '../renderers/shared/utils.mjs';+import { textUnits, applyTemplate } from '../renderers/shared/utils.mjs';const rect = (x, y, w, h) => ({ x, y, width: w, height: h, cx: x + w / 2, cy: y + h / 2 });@@ -148,3 +150,37 @@ test('textUnits: ASCII=1, CJK=2, mixed sums, fullwidth supplementary=2', () => {assert.equal(textUnits('𠀀'), 2); // CJK Ext-B (supplementary plane)assert.equal(textUnits('🚀'), 2); // emoji});++test('suggestLabelObstacleFix includes rects and labelAt/labelDy hints', () => {+ const labelRect = { x: 100, y: 180, width: 48, height: 14, label: '写入' };+ const obstacle = { id: 'memtool', x: 30, y: 130, width: 230, height: 58 };+ const hint = suggestLabelObstacleFix(labelRect, 124, 188, obstacle);+ assert.match(hint, /label rect: \[100, 180, 48, 14\]/);+ assert.match(hint, /component "memtool"/);+ assert.match(hint, /Suggested fix: labelAt/);+ assert.match(hint, /labelDy \+\d+/);+});++test('suggestComponentSeparation proposes nudged pos', () => {+ const a = { id: 'api', x: 100, y: 200, width: 120, height: 60 };+ const b = { id: 'db', x: 150, y: 200, width: 120, height: 60 };+ const hint = suggestComponentSeparation(a, b, 8);+ assert.match(hint, /move "db" pos to \[228, 200\]/);+});++test('applyTemplate preserves dollar sequences in titles', () => {+ const template = `<title>[PROJECT NAME] Architecture Diagram</title>+<h1>[PROJECT NAME] Architecture</h1>+<p class="subtitle">[Subtitle description]</p>+ <!-- ARCHIFY:SVG_SLOT_START --><svg></svg> <!-- ARCHIFY:SVG_SLOT_END -->+ <!-- ARCHIFY:CARDS_SLOT_START --><div></div> <!-- ARCHIFY:CARDS_SLOT_END -->+[Project Name] • [Additional metadata]`;+ const html = applyTemplate(template, {+ title: 'Plan $$50 tier',+ subtitle: 'test',+ footer: 'f',+ svg: '<svg/>',+ cards: '',+ });+ assert.match(html, /Plan \$\$50 tier/);+});diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjsindex 812629e4..cead38c9 100644--- a/archify/test/layout-rules.test.mjs+++ b/archify/test/layout-rules.test.mjs@@ -114,6 +114,8 @@ const CASES = [(d) => { d.boundaries[0].wraps.push('ghost'); }, ['wraps unknown component "ghost"']],['architecture: label wider than component', 'architecture',(d) => { d.components[0].label = 'An Extremely Long Component Label Overflow'; }, ['wider than component', 'shorten the label']],+ ['architecture: component overlap suggests fix', 'architecture',+ (d) => { d.components[1].pos = [...d.components[0].pos]; }, ['Suggested fix', 'move "']],];for (const [name, mode, mutate, expected] of CASES) {