@jabworks/condux 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/blueprint/references/diagram-check.mjs

@@ -4,18 +4,29 @@
 // diagram-kit.md) and cannot see its own render. It reads one file, finds
 // every inline <svg>…</svg> block, and reports the geometry mistakes a human
 // would catch on sight: an edge that runs through a box it does not connect
-// to, a label sitting on another label or on a node's own title text, an
-// edge nobody labeled, and text that falls outside the canvas.
+// to, a label sitting on another label or on a node's own title text, a
+// title wider than its own box, an edge nobody labeled, and text that falls
+// outside the canvas.
 //
 // This is a regex-level reader, not a DOM. It understands exactly the
 // idioms diagram-kit.md teaches — `<g transform="translate(x,y)">` offsets,
 // `var(--…)` fills/strokes (never resolved — colors play no part in any
 // check), one shared `<marker>` — and two known approximations:
 //
-//   - text width is estimated at 0.6 em per character (no font metrics);
+//   - text width is estimated at 0.6 em per character (no font metrics) —
+//     measured exact for the kit's mono labels, generous for regular sans,
+//     a little narrow for semibold titles on wide fallback fonts;
 //   - Bézier and arc commands (C S Q T A) contribute only their final
 //     endpoint as a straight segment — curvature itself is invisible to it.
 //
+// Font size is resolved the way a browser cascades it, restricted to what a
+// regex can see: a `.class { font-size: Npx }` rule matching the text's
+// `class`, then a bare `text` / `svg text` rule, then the element's own
+// `font-size` attribute, then one inherited from an enclosing `<g>` or the
+// `<svg>` tag, and finally the browser default of 16px — reported on stderr
+// when it has to be assumed, because an unsized diagram is read blind. Any
+// other selector shape, and any unit but px, is invisible to it.
+//
 // No dependencies, no network, no shelling out, no filesystem writes.
 
 import fs from 'node:fs';
@@ -24,9 +35,13 @@ import { pathToFileURL } from 'node:url';
 // ---------------------------------------------------------------------------
 // Small geometry helpers. A "box" is always { x0, y0, x1, y1 } in viewBox
 // units; nodes/boundaries are boxes with a `line` and (once assigned) a
-// `title`; texts are boxes with `text`, `line`, `free`, `ownEdge`.
+// `title`; texts are boxes with `text`, `line`, `ax`/`ay` (the anchor
+// point), `free`, `owner`, `ownEdge`.
 // ---------------------------------------------------------------------------
 
+// What a browser uses when nothing in the document sizes the text.
+const DEFAULT_FONT_SIZE = 16;
+
 const shrinkBox = (box, n) => ({ x0: box.x0 + n, y0: box.y0 + n, x1: box.x1 - n, y1: box.y1 - n });
 
 const expandBox = (box, n) => shrinkBox(box, -n);
@@ -185,6 +200,42 @@ const stripTags = (s) =>
 // idiom.
 // ---------------------------------------------------------------------------
 
+// The two style-rule shapes the checker reads, from every <style> block in
+// the document (comments already blanked): `text { font-size: Npx }` or
+// `svg text { … }` sets the base, `.name { … }` / `text.name { … }` /
+// `svg .name { … }` maps a class. Later rules win, as in a stylesheet.
+// Anything else — element ids, descendant chains, `em`/`rem`/`var()` — is
+// skipped: a size the checker cannot resolve must not become a guess.
+const BASE_SELECTOR = /^(?:svg\s+)?text$/;
+const CLASS_SELECTOR = /^(?:svg\s+)?(?:text)?\.([\w-]+)$/;
+
+const parseStyleFontSizes = (source) => {
+  const styles = { base: null, classes: new Map() };
+  const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  const ruleRe = /([^{}]+)\{([^}]*)\}/g;
+  let sm;
+
+  while ((sm = styleRe.exec(source))) {
+    // A CSS comment is not a rule, and left in place it glues itself onto
+    // the selector that follows it.
+    const css = sm[1].replace(/\/\*[\s\S]*?\*\//g, ' ');
+    let rm;
+    while ((rm = ruleRe.exec(css))) {
+      const size = /(?:^|[\s;{])font-size\s*:\s*(\d+(?:\.\d+)?)px\b/.exec(rm[2]);
+      if (!size) continue;
+
+      for (const selector of rm[1].split(',')) {
+        const s = selector.trim();
+        if (BASE_SELECTOR.test(s)) styles.base = parseFloat(size[1]);
+        const cm = CLASS_SELECTOR.exec(s);
+        if (cm) styles.classes.set(cm[1], parseFloat(size[1]));
+      }
+    }
+  }
+
+  return styles;
+};
+
 const CURVE_ARG_COUNTS = { C: 6, S: 4, Q: 4, T: 2, A: 7 };
 
 const parsePathSegments = (d, warnCurve) => {
@@ -296,14 +347,20 @@ const parsePathSegments = (d, warnCurve) => {
 // ---------------------------------------------------------------------------
 // Per-<svg>-block walk. A single left-to-right tag scan tracks a stack of
 // <g> offsets (and font-size inheritance), skips <defs>/<marker> subtrees
-// entirely, and special-cases <text>…</text> to pull out its raw content
-// (and any positioned <tspan> children) without a general text-node model.
+// entirely — the skip survives any container nested inside them (<g>,
+// <symbol>, …), since only the defs/marker frame itself may end it — and
+// special-cases <text>…</text> to pull out its raw content (and any
+// positioned <tspan> children) without a general text-node model.
 // ---------------------------------------------------------------------------
 
-const walkBlock = (source, blockOffset, blockSource, findLine, notify) => {
+const walkBlock = (source, blockOffset, blockSource, findLine, notify, styles) => {
   const rects = [];
   const texts = [];
   const edges = [];
+  let defaulted = 0;
+  const onDefault = () => {
+    defaulted++;
+  };
 
   const svgOpenMatch = /^<svg\b[^>]*>/.exec(blockSource);
   const svgOpenTag = svgOpenMatch ? svgOpenMatch[0] : '<svg>';
@@ -319,12 +376,16 @@ const walkBlock = (source, blockOffset, blockSource, findLine, notify) => {
 
   let curOffsetX = 0;
   let curOffsetY = 0;
-  let curFontSize = parseFloat(getAttr(svgOpenTag, 'font-size') ?? '') || 13;
+  // null until some enclosing tag carries a font-size — the text element then
+  // decides between its own attribute, the style rules, and the default.
+  let curFontSize = parseFloat(getAttr(svgOpenTag, 'font-size') ?? '') || null;
   let skipDepth = 0;
   const stack = [];
-  // The frame a closing tag restores: offsets, inherited font size, and
-  // whether the subtree was inside <defs>/<marker>.
-  const snapshot = () => ({ prevX: curOffsetX, prevY: curOffsetY, prevFontSize: curFontSize, skip: skipDepth > 0 });
+  // The frame a closing tag restores: offsets and inherited font size.
+  // `skip` means "this frame incremented skipDepth", which only the
+  // defs/marker branch below ever does — a container opened inside a
+  // skipped subtree restores offsets on close, nothing more.
+  const snapshot = () => ({ prevX: curOffsetX, prevY: curOffsetY, prevFontSize: curFontSize, skip: false });
 
   const tagRe = /<\/?[a-zA-Z][^>]*>/g;
   let m;
@@ -364,6 +425,8 @@ const walkBlock = (source, blockOffset, blockSource, findLine, notify) => {
           offX: curOffsetX,
           offY: curOffsetY,
           curFontSize,
+          styles,
+          onDefault,
           texts,
           lineNo,
         });
@@ -430,6 +493,12 @@ const walkBlock = (source, blockOffset, blockSource, findLine, notify) => {
     if (!selfClosing) stack.push(snapshot());
   }
 
+  if (defaulted > 0) {
+    notify(
+      `diagram-check: ${defaulted} text element(s) carry no font-size from an attribute, an enclosing tag, or a text/.class style rule — assumed ${DEFAULT_FONT_SIZE}px; set font-size on the <svg> tag so widths are read as drawn`,
+    );
+  }
+
   return { rects, texts, edges, viewBox };
 };
 
@@ -518,15 +587,39 @@ const pushTextBox = (texts, text, absX, absY, anchor, fontSize, lineNo) => {
     x1 = absX + width;
   }
 
-  texts.push({ x0, y0: top, x1, y1: bottom, text, line: lineNo });
+  texts.push({ x0, y0: top, x1, y1: bottom, ax: absX, ay: absY, text, line: lineNo });
 };
 
-const processTextElement = ({ tag, rawContent, contentOffset, findLine, offX, offY, curFontSize, texts, lineNo }) => {
+// The cascade a browser applies to a <text>, restricted to the shapes the
+// style scan understands: a matching class rule beats a bare `text` rule,
+// which beats the element's own attribute, which beats an inherited one.
+// `inherited` is null when no enclosing tag carried a size; `onDefault` is
+// called when the browser default has to stand in.
+const resolveFontSize = (tag, inherited, styles, onDefault) => {
+  const classAttr = getAttr(tag, 'class');
+  if (classAttr) {
+    for (const cls of classAttr.trim().split(/\s+/)) {
+      if (styles.classes.has(cls)) return styles.classes.get(cls);
+    }
+  }
+
+  if (styles.base !== null) return styles.base;
+
+  const attr = getAttr(tag, 'font-size');
+  if (attr) return parseFloat(attr);
+
+  if (inherited !== null) return inherited;
+
+  onDefault();
+
+  return DEFAULT_FONT_SIZE;
+};
+
+const processTextElement = ({ tag, rawContent, contentOffset, findLine, offX, offY, curFontSize, styles, onDefault, texts, lineNo }) => {
   const x = parseFloat(getAttr(tag, 'x') ?? '0');
   const y = parseFloat(getAttr(tag, 'y') ?? '0');
   const anchor = getAttr(tag, 'text-anchor') ?? 'start';
-  const fontSizeAttr = getAttr(tag, 'font-size');
-  const fontSize = fontSizeAttr ? parseFloat(fontSizeAttr) : curFontSize;
+  const fontSize = resolveFontSize(tag, curFontSize, styles, onDefault);
 
   const tspanRe = /<tspan\b([^>]*)>([\s\S]*?)<\/tspan>/g;
   const tspans = [];
@@ -594,9 +687,12 @@ const findingsForBlock = ({ rects, texts, edges, viewBox }) => {
   const nodes = rects.filter((r) => !r.isBoundary);
 
   // Owned vs. free text, and each node's title (first owned text, in
-  // document order).
+  // document order). A text belongs to the node its box sits in — or, when
+  // the box has outgrown the node, the node its anchor point sits in: a
+  // title too wide for its box is still that box's title, and reporting it
+  // as a free label straddling the node would misname the defect.
   for (const text of texts) {
-    const owner = nodes.find((node) => fullyInside(text, node, 1));
+    const owner = nodes.find((node) => fullyInside(text, node, 1) || pointInBox(text.ax, text.ay, node));
     if (owner) {
       text.free = false;
       text.owner = owner;
@@ -666,11 +762,13 @@ const findingsForBlock = ({ rects, texts, edges, viewBox }) => {
     }
   }
 
-  // 3. label-over-box (free text straddling a node's border)
+  // 3. label-over-box (a text box straddling the border of a node it does
+  // not belong to) and text-overflows-box (a node's own text wider or
+  // taller than the node, past the 1-unit tolerance)
   for (const text of texts) {
-    if (!text.free) continue;
-
     for (const node of nodes) {
+      if (node === text.owner) continue;
+
       if (rectIntersect(shrinkBox(text, 1), node)) {
         findings.push({
           code: 'label-over-box',
@@ -679,6 +777,20 @@ const findingsForBlock = ({ rects, texts, edges, viewBox }) => {
         });
       }
     }
+
+    if (text.owner && !fullyInside(text, text.owner, 1)) {
+      const { owner } = text;
+      const over = Math.max(owner.x0 - text.x0, text.x1 - owner.x1, owner.y0 - text.y0, text.y1 - owner.y1);
+      const where =
+        owner.title === text.text
+          ? `its own ${fmt(owner.x1 - owner.x0)}×${fmt(owner.y1 - owner.y0)} box`
+          : describeNode(owner);
+      findings.push({
+        code: 'text-overflows-box',
+        line: text.line,
+        detail: `"${text.text}" overflows ${where} by ${fmt(over)}`,
+      });
+    }
   }
 
   // 4. edge-through-label (excluding a free text's own edge)
@@ -736,8 +848,9 @@ const findingsForBlock = ({ rects, texts, edges, viewBox }) => {
 // Public API
 // ---------------------------------------------------------------------------
 
-// Finds every <svg>…</svg> block in `source` and runs all six checks against
-// each. Returns Finding[] = { code, line, detail }[], sorted by line then code.
+// Finds every <svg>…</svg> block in `source` and runs all seven checks
+// against each. Returns Finding[] = { code, line, detail }[], sorted by line
+// then code.
 export const checkSvg = (rawSource) => {
   // The kit's own marker block carries `<!-- usage: <line … /> -->`, and the
   // kit says to paste it verbatim — scanned raw, that comment is a phantom
@@ -745,6 +858,7 @@ export const checkSvg = (rawSource) => {
   // comments character-for-character (newlines kept) so line numbers hold.
   const source = rawSource.replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, ' '));
   const findLine = makeLineFinder(source);
+  const styles = parseStyleFontSizes(source);
   let curveWarned = false;
   const notify = (msg) => process.stderr.write(msg + '\n');
   notify.curve = () => {
@@ -758,7 +872,7 @@ export const checkSvg = (rawSource) => {
   let m;
 
   while ((m = blockRe.exec(source))) {
-    const parsed = walkBlock(source, m.index, m[0], findLine, notify);
+    const parsed = walkBlock(source, m.index, m[0], findLine, notify, styles);
     findings.push(...findingsForBlock(parsed));
   }
 

package/skills/blueprint/references/diagram-kit.md

@@ -8,17 +8,36 @@ of the `<style>` block, verbatim.
 
 ## Shared Conventions
 
-- Canvas: `<svg viewBox="0 0 W H" style="max-width:100%">` sized to content;
-  the page wraps it in the wireframe kit's `.frame` shell (either mode's).
+- Canvas: `<svg viewBox="0 0 W H" font-size="13" style="max-width:100%">`
+  sized to content; the page wraps it in the wireframe kit's `.frame` shell
+  (either mode's). The `font-size` is the base every text inherits — see
+  Sizing below.
 - Palette is token roles, referenced with `var(--…)` (CSS variables work in
   inline SVG attributes): fills `var(--card)` / `var(--muted)`, strokes
-  `var(--border)`, edges `var(--subtle)`, text `var(--foreground)`. The one
-  accent is the `--primary` family — for the one thing the diagram is about
-  (the new entity, the changed edge) — never more than one accent use.
+  `var(--border)`, edges `var(--subtle)`, text `var(--foreground)`. Node fills
+  and strokes come from the categorical set instead — see Visual Language.
+- Accent: categorical colour is identity, never emphasis. `--primary` stays
+  the one accent, for the one thing the diagram is about (the new entity, the
+  changed edge): a 2.5px `var(--primary)` stroke and a `var(--primary-text)`
+  title over the node's role tint — never more than one accent use. Semantic
+  tokens (`--success`, `--warning`, `--destructive`, `--info`) are state only,
+  never role — a persistence-green node and a success-green node in one
+  diagram read as the same claim.
 - Text: `--sans` for titles, `--mono` for everything that is data — field
   rows, cardinalities, edge labels (D2). 13–14px labels, 11px annotations
   in `var(--muted-foreground)`. If a label doesn't fit its box, the box
   grows — never shrink the font below 11px.
+- Sizing: the base size goes on the `<svg>` tag (`font-size="13"`), every
+  other size as a `font-size` attribute on the `<text>` itself. Never a
+  `text { font-size }` rule in `<style>` — in the browser it overrides every
+  `font-size` attribute in the diagram, so the sizes you wrote are not the
+  sizes that render. The checker resolves sizes the way the browser does but
+  sees only attributes, a bare `text` rule and `.class` rules; a text it
+  cannot size is read at the browser's 16px and reported on stderr. Budget
+  width at 0.6 em per character (exact for mono, generous for regular sans,
+  a little tight for semibold titles): at 16px a 23-character title needs
+  more than a 210 box, and when it doesn't fit the box grows — the checker
+  reports `text-overflows-box`, never a smaller font.
 - Arrowheads via one shared `<marker>`:
 
 ```html
@@ -36,6 +55,197 @@ of the `<style>` block, verbatim.
 - Every relationship line gets a label. An unlabeled arrow is a guess the
   reader has to make.
 
+## Visual Language
+
+Three channels, one meaning each: **colour is role**, **mark is kind**, **dash
+is protocol**. Two nodes in the same colour make a claim — that they play the
+same part in the system — so colour is never picked for looks.
+
+### Roles
+
+Fixed slots. A role always gets the same categorical token, in every diagram of
+every design, because a per-diagram choice is decoration and a fixed table is a
+language.
+
+| Role | Slot | Applies to |
+|---|---|---|
+| frontend runtime | `--cat-4` | UI services, widget hosts, client-side stores |
+| API / service | `--cat-2` | backend services, gateways, resolvers |
+| persistence | `--cat-3` | databases, caches, object stores |
+| external system | `--cat-7` | third parties, upstream sources, providers |
+| messaging / queue / bus | `--cat-8` | brokers, streams, topics |
+| actor / user | `--cat-6` | people and devices in flow diagrams |
+| batch / scheduler | `--cat-5` | jobs, cron, pipelines |
+| unassigned | `--cat-other` | anything the design has not named yet |
+
+- Tint recipe, verbatim, as attributes on the tag:
+  `fill="var(--cat-N)" fill-opacity="0.10" stroke="var(--cat-N)"`.
+  Never move the stroke into a `.class` rule — the checker reads `stroke` off
+  the tag, and a class-styled node reads as a halo and vanishes from the check.
+- At most five roles per diagram. A sixth means the diagram is answering two
+  questions (same rule as "Choosing the Shape") — split it, or fold the tail
+  roles into `--cat-other`.
+- No new tokens. `--cat-1` … `--cat-8` and `--cat-other` are the whole set;
+  there is no muted variant, and inventing one crosses into the token core
+  every surface inherits.
+- Opaque role fills are banned: body text loses contrast, worst on the dark
+  ground. `fill-opacity="0.10"` is the recipe, not a starting point.
+
+### Kinds
+
+| Kind | Body | Mark | Border |
+|---|---|---|---|
+| service | rounded `<rect>` (`rx="6"`) | none | solid |
+| store | rounded `<rect>` | `mark-store` | solid |
+| external system | rounded `<rect>` | `mark-external` | dashed `6 4` |
+| UI surface | rounded `<rect>` | `mark-ui` | solid |
+| actor / user | pill `<rect>` (`rx` = height / 2) | `mark-actor` | solid |
+| queue / bus | rounded `<rect>` | `mark-queue` | solid |
+| batch / scheduler | rounded `<rect>` | `mark-batch` | solid |
+| boundary | dashed `<rect>` behind its members | title strip | dashed `6 4` |
+
+- **Invariant: a node's body is exactly one stroked `<rect>`.** Everything else
+  on it — halo, title strip, glyph — is a stroke-less `<rect>` or a `<use>`.
+  The checker reads `stroke` from the tag and treats a stroke-less rect as
+  decoration, so the one stroked rect *is* the node's footprint: a second
+  stroked rect inside it reclassifies the node as a boundary, and a body drawn
+  as a cylinder, hexagon or ellipse is invisible to the check — a false
+  `clean`, not a clever shape.
+- No footprint-changing geometry. Kind is carried by the mark and the border,
+  never by a new body shape.
+
+### Marks
+
+Paste this into the `<defs>` beside the arrow marker. `<defs>` content is never
+walked by the checker, so a mark path is a glyph; the same path drawn in the
+body of the svg is read as an unlabeled edge.
+
+```html
+<g id="mark-store"><path d="M1,4 a8,3 0 1,0 16,0 a8,3 0 1,0 -16,0 M1,4 V13 a8,3 0 0,0 16,0 V4" fill="none" stroke="currentColor" stroke-width="1.3"/></g>
+<g id="mark-external"><path d="M3,12 L15,3 M7,3 h8 v8" fill="none" stroke="currentColor" stroke-width="1.3"/></g>
+<g id="mark-ui"><path d="M1,1 h16 v13 h-16 z M1,5 h16" fill="none" stroke="currentColor" stroke-width="1.3"/></g>
+<g id="mark-actor"><path d="M9,2 a3,3 0 1,0 0.01,0 M2,15 a7,5 0 0,1 14,0" fill="none" stroke="currentColor" stroke-width="1.3"/></g>
+<g id="mark-queue"><path d="M1,3 h12 M3,8 h12 M5,13 h12" fill="none" stroke="currentColor" stroke-width="1.3"/></g>
+<g id="mark-batch"><path d="M2,8 a7,7 0 1,0 14,0 a7,7 0 1,0 -14,0 M9,4 V8 h4" fill="none" stroke="currentColor" stroke-width="1.3"/></g>
+```
+
+- Every glyph is drawn on an 18×16 grid. Six marks for eight kinds: a service
+  has no mark (it is the unmarked default) and a boundary uses its title strip.
+- Placement: `<use href="#mark-store" x="…" y="…" width="18" height="16"
+  style="color:var(--cat-N)"/>`, 14px in from the node's top-left — `x` =
+  node `x` + 14, `y` = node `y` + 12, the two extra pixels of headroom keeping
+  the glyph clear of the `rx="6"` corner. `currentColor` picks up the
+  `style="color:…"`, so a mark is always its node's role colour.
+- A `<use>` has no footprint the checker can see, so a mark never collides
+  with anything. It can still collide visually: keep the node's title clear of
+  the glyph's 18px column.
+
+### Edges
+
+| Edge means | Stroke width | Dash |
+|---|---|---|
+| synchronous call (HTTP, gRPC, GraphQL) | 1.5 | solid |
+| in-process hand-off within a boundary | 1 | solid |
+| asynchronous message or event (queue, stream, topic) | 1.5 | `6 4` |
+| file, batch, or adapter protocol transfer | 1.5 | `2 3` |
+
+- Stroke is always `var(--subtle)`. Colour never goes on an edge: colour is
+  role identity, and two channels on one line reads as noise.
+- Everything from Layout and Routing still holds — the shared arrowhead, one
+  haloed `--mono` 11px label per segment, orthogonal paths, distinct ports. A
+  two-way edge adds `marker-start`; flow diagrams keep their hop numbers.
+- Halo fill is `var(--card)`, everywhere (Layout and Routing rule 5).
+  Boundaries in this language are unfilled — only the title strip is tinted —
+  so the ground under every label is the frame's card surface.
+
+### Boundaries
+
+- Body: a dashed `<rect>` in the boundary's role colour,
+  `fill="none" stroke="var(--cat-N)" stroke-dasharray="6 4" rx="4"`, drawn
+  behind its members.
+- Title strip: a stroke-less tinted `<rect>` at the top of the boundary, full
+  width, **48 tall**, `fill="var(--cat-N)" fill-opacity="0.10" rx="4"`. It has
+  no stroke, so the checker reads it as decoration, not a nested node.
+- Title inside the strip: `font-size="14" font-weight="600"
+  letter-spacing="0.04em"` in `var(--cat-N)`, 24px in from the boundary's left
+  edge, baseline at strip top + 30. A title strip makes a region scannable
+  zoomed out; a bare corner label reads at close range only.
+- Members start **≥ 45px below the strip's bottom edge** — boundary top + 93.
+  Labels and their halos need only clear the band: halo top ≥ strip bottom.
+  A halo in the strip punches a `var(--card)` hole through the tint, so a
+  corridor that would put one there moves down, never the strip.
+
+### Legend
+
+An HTML block under the `<svg>`, still inside `.frame` — never inside the svg,
+where the checker scans it and stroked swatches become nodes. At most four
+rows (role, kind, edge, accent), and only entries the diagram actually
+contains: a legend row you cannot point at in the drawing is the five-role cap
+failing out loud. The block below is the legend for the worked fragment at the
+end of this section — three roles, three kinds, two edges, the accent.
+
+```html
+<div class="legend">
+  <div><b>role</b><span><span class="sw" style="background:var(--cat-4);opacity:.35;border:1px solid var(--cat-4)"></span> frontend runtime</span><span><span class="sw" style="background:var(--cat-2);opacity:.35;border:1px solid var(--cat-2)"></span> API / service</span><span><span class="sw" style="background:var(--cat-8);opacity:.35;border:1px solid var(--cat-8)"></span> messaging</span></div>
+  <div><b>kind</b><span><span class="sw" style="border:1px solid var(--border);border-radius:4px"></span> service</span><span><svg width="18" height="16"><use href="#mark-store" width="18" height="16"/></svg> store</span><span><svg width="18" height="16"><use href="#mark-queue" width="18" height="16"/></svg> queue / bus</span></div>
+  <div><b>edge</b><span><i class="ln" style="border-top:1.5px solid var(--subtle)"></i> sync call</span><span><i class="ln" style="border-top:1.5px dashed var(--subtle)"></i> async message</span></div>
+  <div><b>accent</b><span><span class="sw" style="border:2.5px solid var(--primary);border-radius:4px"></span> the one thing this diagram is about</span></div>
+</div>
+<style>
+.legend { display: grid; gap: var(--space-2); font-family: var(--mono); font-size: var(--text-xs); color: var(--muted-foreground); margin-top: var(--space-4); }
+.legend b { color: var(--foreground); margin-right: var(--space-3); display: inline-block; width: 6ch; }
+.legend span { margin-right: var(--space-4); display: inline-flex; align-items: center; gap: 6px; }
+.legend .sw { display: inline-block; width: 14px; height: 14px; }
+.legend .ln { display: inline-block; width: 28px; height: 0; }
+</style>
+```
+
+- The kind swatches `<use>` the same mark ids: one inline `<svg>` per row
+  entry, resolving against the `<defs>` in the diagram above it (same
+  document, so the fragment reference works).
+- A CSS border cannot carry an SVG dash array, so an edge swatch approximates:
+  `6 4` is `dashed`, `2 3` is `dotted`. At 28px they read the same. Add the
+  `2 3` row only when the diagram has a file / batch / adapter edge in it.
+
+### A worked fragment
+
+Two boundaries, four nodes, two protocols. Gutters are 72+, every edge is
+orthogonal and leaves a 50% port, every label is haloed and clear of both strip
+bands, and every node body is one stroked rect.
+
+```html
+<!-- needs the arrow marker and the mark <defs> above. viewBox 0 0 692 352 -->
+<rect x="20" y="20" width="280" height="312" rx="4" fill="none" stroke="var(--cat-4)" stroke-dasharray="6 4"/>
+<rect x="20" y="20" width="280" height="48" rx="4" fill="var(--cat-4)" fill-opacity="0.10"/>
+<text x="44" y="50" font-family="var(--sans)" font-size="14" font-weight="600" letter-spacing="0.04em" fill="var(--cat-4)">FRONTEND RUNTIME</text>
+<rect x="392" y="20" width="280" height="312" rx="4" fill="none" stroke="var(--cat-2)" stroke-dasharray="6 4"/>
+<rect x="392" y="20" width="280" height="48" rx="4" fill="var(--cat-2)" fill-opacity="0.10"/>
+<text x="416" y="50" font-family="var(--sans)" font-size="14" font-weight="600" letter-spacing="0.04em" fill="var(--cat-2)">BACKEND REPORTING API</text>
+<!-- members start at y=116, 48 below the strip that ends at y=68 (45 is the floor) -->
+<rect x="44" y="116" width="232" height="56" rx="6" fill="var(--cat-4)" fill-opacity="0.10" stroke="var(--cat-4)"/>
+<text x="160" y="150" text-anchor="middle" font-family="var(--sans)" font-size="14" font-weight="600" fill="var(--foreground)">Filter + query planner</text>
+<rect x="44" y="252" width="232" height="56" rx="6" fill="var(--cat-4)" fill-opacity="0.10" stroke="var(--cat-4)"/>
+<use href="#mark-store" x="58" y="264" width="18" height="16" style="color:var(--cat-4)"/>
+<text x="160" y="286" text-anchor="middle" font-family="var(--sans)" font-size="14" font-weight="600" fill="var(--foreground)">Frontend catalogs</text>
+<!-- the accent: role tint kept, 2.5px primary stroke, primary-text title -->
+<rect x="416" y="116" width="232" height="56" rx="6" fill="var(--cat-2)" fill-opacity="0.10" stroke="var(--primary)" stroke-width="2.5"/>
+<text x="532" y="150" text-anchor="middle" font-family="var(--sans)" font-size="14" font-weight="600" fill="var(--primary-text)">Reporting query API</text>
+<rect x="416" y="252" width="232" height="56" rx="6" fill="var(--cat-8)" fill-opacity="0.10" stroke="var(--cat-8)"/>
+<use href="#mark-queue" x="430" y="264" width="18" height="16" style="color:var(--cat-8)"/>
+<text x="532" y="286" text-anchor="middle" font-family="var(--sans)" font-size="14" font-weight="600" fill="var(--foreground)">Export queue</text>
+<!-- sync call: 1.5 solid, right 50% port to left 50% port, label 4px above -->
+<path d="M 276 144 H 416" fill="none" stroke="var(--subtle)" stroke-width="1.5" marker-end="url(#arrow)"/>
+<rect x="306" y="129" width="81" height="15" fill="var(--card)"/>
+<text x="346" y="140" text-anchor="middle" font-family="var(--mono)" font-size="11" fill="var(--muted-foreground)">POST /query</text>
+<!-- async message: 1.5 dashed 6 4, bottom 50% port to top 50% port -->
+<path d="M 532 172 V 252" fill="none" stroke="var(--subtle)" stroke-width="1.5" stroke-dasharray="6 4" marker-end="url(#arrow)"/>
+<rect x="465" y="205" width="134" height="15" fill="var(--card)"/>
+<text x="532" y="216" text-anchor="middle" font-family="var(--mono)" font-size="11" fill="var(--muted-foreground)">queue: report.ready</text>
+```
+
+Three roles, two kinds marked, one accent — the `### Legend` block above is
+this fragment's legend, verbatim.
+
 ## Layout and Routing
 
 1. *Grid first.* Assign every node a column and a row before drawing anything.
@@ -59,11 +269,13 @@ of the `<style>` block, verbatim.
    `--mono` 11px: on a horizontal segment it sits 4px above the line, on a
    vertical segment it is centred on the line over its halo.
    Every label gets a halo so a crossing edge stays legible: a stroke-less
-   `<rect>` in the fill the label sits on (`var(--background)` on open
-   canvas, `var(--muted)` inside a filled boundary) drawn behind the text —
+   `<rect>` in `var(--card)` — the frame ground every diagram sits on — drawn
+   behind the text —
    the checker ignores stroke-less rects, so the halo is never mistaken for a
-   node. Two labels never share a corridor position: stagger by 14px or move
-   one to another segment.
+   node. Size the halo from the same budget as the label — characters × 11 ×
+   0.6, plus 4px each side — a halo narrower than its label lets the crossing
+   edge show through the ends. Two labels never share a corridor position:
+   stagger by 14px or move one to another segment.
 6. *Fan-in is a smell.* More than four edges into one box, or more than three
    edges in one gutter, means the diagram is answering two questions — split
    it (same rule as "Choosing the Shape").
@@ -78,7 +290,8 @@ of the `<style>` block, verbatim.
    |---|---|
    | `edge-through-box` | an edge segment crosses a node rect it doesn't attach to |
    | `label-over-label` | two text boxes intersect |
-   | `label-over-box` | a text box straddles a node rect border |
+   | `label-over-box` | a text box straddles the border of a node it doesn't belong to |
+   | `text-overflows-box` | a node's own text is wider or taller than the node |
    | `edge-through-label` | an edge crosses a text box that isn't its own label |
    | `unlabeled-edge` | no text within 24px of the edge |
    | `text-outside-canvas` | text escapes the viewBox |
@@ -136,9 +349,15 @@ labels carry cardinality (`1..*`, `0..1`).
 <text x="290" y="72" text-anchor="middle" font-size="11" fill="var(--muted-foreground)">1..*</text>
 ```
 
-An accented entity (the diagram's one accent) swaps its title-bar fill to
-`var(--primary-muted)`, its strokes to `var(--primary)`, and its title text to
-`var(--primary-text)`.
+Visual Language on this family: the title bar carries the tint of the entity's
+*owning* role (`fill="var(--cat-N)" fill-opacity="0.10"`, and `stroke="var(--cat-N)"`
+on both rects), and the kind mark sits 14px in from the title bar's top-left —
+so a reader sees which service owns which table before reading a field name.
+The bar and the body are siblings, never nested: a bar drawn *inside* the body
+rect makes the checker read the whole entity as a boundary.
+
+An accented entity (the diagram's one accent) keeps its role tint and swaps its
+strokes to 2.5px `var(--primary)` and its title text to `var(--primary-text)`.
 
 ## 2. Request / Data Flow
 
@@ -146,12 +365,18 @@ Actors and stores as boxes on one horizontal band; numbered edges show
 sequence. Number every hop (`1. POST /orders`, `2. validate`, `3. INSERT`) —
 the numbers are what make it a flow rather than a topology.
 
+Visual Language on this family: actors on the band are pill rects
+(`rx` = height / 2) in `--cat-6` with `mark-actor`, stores are rounded rects
+with `mark-store` in their owning role's slot, and the hop numbers stay — kind
+and colour say *what* each box is, the numbers still say *when*.
+
 ## 3. Architecture (boxes-and-arrows)
 
-Services as rounded rects (`rx="6"`), external systems as rects with a dashed
-stroke (`stroke-dasharray="4 3"`), boundaries (network, process, trust) as a
-large dashed `<rect>` behind its members with the boundary name in the top-left
-corner. Edges labeled with protocol or payload (`HTTP`, `queue: order.created`).
+The family the Visual Language section is written for — it uses every channel:
+services, stores, externals, UI surfaces, queues and batch jobs from the kinds
+table; boundaries (network, process, trust) as large dashed rects with a title
+strip; edges dashed by protocol and labeled with the protocol or payload
+(`HTTP`, `queue: order.created`). Take every rule and both fences from there.
 
 ## 4. State Machine
 
@@ -160,6 +385,12 @@ with a filled dot and an arrow, terminal states with a double border (nested
 `<rect>` inset by 3px). Every transition label is the *event* that causes it,
 not a description of the target state.
 
+Visual Language on this family: no role colour and no marks — a state is not a
+component, so a categorical fill would claim a kinship that does not exist.
+Neutral bodies (`var(--card)` / `var(--border)`), `--primary` on the one state
+the diagram is about, and semantic tokens where a state *is* a state
+(`--success` on settled, `--destructive` on failed).
+
 ## Choosing the Shape
 
 | The question being asked | Shape |