Diagram semantic accuracy

How this rule is fixed

This is an AI-enabled rule. Pass/fail requires model judgment; there is no deterministic fixer in the pilot registry.

• Harness: invoke-ai-ruleset-harness.sh runs design-rules/ai/run-design-ai-rule.sh on the Before fixture and expects findings with matching principleId.
• Remediation: Cursor agent plans from forge-ux-remediation.plan.md after sitewide audit — not handbook After copy.

Detection module: docs/design/ux-audit/ai-enabled-design-principles.md#ai-diagram-semantic-accuracy. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink ships diagrams as static SVG tiles (render_ks_diagram_block, ks_diagram_tile_html), ASCII figures (forge-diagram-ascii), and optional expand modals (ks-diagram-trigger, data-diagram-key). Deterministic gates (DET.DIAGRAM.LABELS, DET.DIAGRAM.ALT, DET.DIAGRAM.ASSET_REGISTRY) prove labels exist, alt policy is coherent, and assets are registered; they do not judge whether arrows, gates, and node roles match the story the page tells.

This AI rule asks: do shapes and flow match the described mechanism? A loop template under a "linear gate chain" caption, an agent→human arrow when copy says "human approves before agent work," or diamond gates drawn as plain rectangles all fail—even when contrast and hash markers pass.

Plan: For each informative diagram, read caption, surrounding prose, and catalog legend_map / contract semantics together with the SVG topology (or modal legend). Do: Swap template keys, relabel nodes, or redraw edges so direction, cardinality, and gate symbology align. Check: A reader can trace the claimed sequence on the figure without mental correction. Adjust: When the same mismatch repeats (for example caption always says "sequential" while template-loop-cycle ships), propose a DET.* candidate or tighten diagram contract semantics fields.

Passing signals

• Caption ↔ topology: Prose says "sequential review gates" and the figure is a left-to-right gate chain (template-gate-chain) or linear flow—not a cycle, fork, or reversed arrow unless the text explicitly allows it.
• Arrow direction matches agency: "Human approves, then agent executes" shows approval before the agent box; release follows evidence, not a shortcut from intent to ship.
• Shape vocabulary is consistent: Diamonds (or catalog gate glyphs) mean checkpoints; rectangles mean work stages; dashed vs solid edges match optional vs required paths in the contract legend.
• Labels tie to legend keys: SVG data-node / text labels use the same terms as the figcaption and DET.DIAGRAM.LABELS contract keys (no orphan "Step B" when the story names "Review gate").
• Alt and caption agree: alt and surrounding copy describe the same path the eye can follow (informative diagrams are not decorative while claiming a mechanism).
• Expand modal legend matches tile: When forge-diagram-trigger + data-diagram-key open ks-diagram-catalog.js detail, modal narrative does not contradict the static tile.
• Template choice is intentional: render_ks_diagram_block(key=…) or assets/svg/template-*.svg selection matches the mechanism class (linear, gated, decision branch, network)—not "whatever thumbnail looked good."

Failing signals

• Caption promises a one-way gate chain but the tile shows a loop, bidirectional edge, or agent path that skips the human review node.
• Arrow reversal: edges run opposite to numbered steps in body copy or section heading.
• Wrong template family: linear-flow copy paired with loop-cycle, org-chart, or network mesh topology.
• Gate symbology drift: diamonds labeled "optional" in text drawn as required hard gates (or absent gates where copy says "hard stop").
• Decorative misclassification: role="presentation" / empty alt while the surrounding section argues a product mechanism (DET.DIAGRAM.ALT may pass classification while semantics still fail).
• Legend modal contradicts tile: expanded catalog text describes a different sequence than the inline SVG.
• Unlabeled decision points: fork or join with no label while prose refers to "if review fails, return to intent"—topology hides the branch.

Before example

Before (failing example)

How it works

Human review before agent execution

Work moves in one direction: shape intent, pass a human review gate, then let the agent execute inside bounded scope, then release with evidence.

After example

After (passing example)

How it works

Human review before agent execution

Work moves in one direction: shape intent, pass a human review gate, then let the agent execute inside bounded scope, then release with evidence.

Linear gate chain: Intent → Human review → Agent execution → Release (matches left-to-right arrows and diamond gates in the SVG).

Evidence and remediation

Capture: screenshot of the diagram tile and (if expandable) modal legend; copy the figcaption or support line and one paragraph of mechanism prose; export SVG or note data-diagram-key / src path; link the catalog diagram contract legend_map and semantics when present.

Remediate (in order):

1. Restate the mechanism in one sentence (actors, order, gates, branches). List required nodes and edge directions.
2. Pick the matching template family (template-linear-flow, template-gate-chain, template-decision-flow, etc.) or update custom SVG labels/data-node attributes to match.
3. Align alt, caption or support copy, and body text to the same sequence; fix DET.DIAGRAM.ALT classification if the diagram is informative.
4. Run DET.DIAGRAM.LABELS and registry checks; ensure DET.DIAGRAM.ASSET_REGISTRY and DET.HASH.MARKERS still pass after edits.
5. Re-run AI review on the page batch; if the same topology mismatch repeats across sites, propose a deterministic DET.DIAGRAM.* semantic proxy or tighten catalog semantics / forbidden_patterns.

Related rules

• DET.DIAGRAM.LABELS — SVG text and legend keys are present and readable.
• DET.DIAGRAM.ALT — decorative vs informative classification matches role / aria-hidden usage.
• DET.DIAGRAM.ASSET_REGISTRY — diagram families are registered when shipped to consumers.
• DET.HASH.MARKERS — visual roots emit matching hash and data-ks-hash markers.
• AI.VISUAL.PRODUCT_EXPLANATORY_VALUE — diagrams should explain product structure or user benefit, not generic decoration.
• AI.DATA.INSIGHT_LEGIBILITY — charts must communicate the intended insight; adjacent judgment for data visuals, not SVG flows.