Skip to content

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

feat: layout guidance in SKILL and actionable validator hints (#7)

tt-a1ia925f719a0ba
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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
### Added
diff --git a/archify.zip b/archify.zip
index fdce06fc..ed52c150 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 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 mechanically
Drop 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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] &bull; [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.mjs
index 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) {