Diagram legend labels on surface

How this rule is fixed

Pilot deterministic fixer: handbook_after · harness mode standalone · verify expect_rule_clean.

• Harness: apply-harness-fixture-remediation.py copies the After example HTML from this handbook page onto the defect fixture, then invoke-det-ruleset-remediation-verify.sh re-audits and expects zero findings for this rule.
• Production sites: run-website-ux-remediation-loop.sh runs handbook_html_patch (HTML patches in lib/ux-deterministic-fixers/fixers/patches/) before invoking the Cursor agent when the quality gate still fails.

Detection module: docs/design/ux-audit/deterministic-design-rules.md#det-diagram-labels. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink diagrams teach mechanism through visible node names, not only modal legends or alt text. Catalog entries in js/ks-diagram-catalog.js declare items[].node strings (for example Step A on linear, Stage 1 / Gate 1 on gate). Template SVGs under assets/svg/template-*.svg and rendered tiles (ks_diagram_tile_html, forge-diagram, ks-diagram-tile, data-diagram-key) must surface those strings in readable <text> / <tspan> nodes—or, for ASCII figures, in .forge-diagram-ascii-pre lines—so sighted readers and zoomed UI see the same vocabulary as the catalog contract.

This deterministic rule complements DET.DIAGRAM.ALT (informative vs decorative exposure) and DET.DIAGRAM.ASSET_REGISTRY (registered keys and paths). It does not judge arrow direction or gate symbology (AI.DIAGRAM.SEMANTIC_ACCURACY). Coverage thresholds: at least 2 characters per label token; for catalog keys with legend entries, at least 2 matching nodes or 50% of legend nodes (whichever is higher). Placeholder tokens such as [subtitle] and [Title - …] do not count as readable labels.

Plan: Open js/ks-diagram-catalog.js for the tile's data-diagram-key; list items[].node values. Do: Mirror those strings in SVG <text> (or ASCII body) when customizing assets/svg/template-*.svg or page copy. Check: Re-run auditor metrics (diagramLabelsReport, diagramLabelsRepoReport) or compare DevTools text nodes to the catalog modal legend. Act: Fix template SVG, catalog legend, or generator wiring—never rely on alt alone when the on-surface labels are empty or abbreviated.

Passing signals

• Linear template: data-diagram-key="linear" tile shows SVG text Step A, Step B, Step C, Step D matching catalog nodes (see assets/svg/template-linear-flow.svg).
• Gate template: data-diagram-key="gate" tile exposes Stage 1, Gate 1, Stage 2, Gate 2, Stage 3 as readable <text> (not only diamond G glyphs) when the catalog lists full gate names.
• Catalog coverage: For a key with N legend nodes, at least max(2, ceil(N × 0.5)) node strings appear in fetched SVG or inline svg text (substring match allowed).
• ASCII parity: figure.forge-diagram-ascii / .forge-diagram-ascii-pre lines include catalog node tokens when data-diagram-key is set.
• Repo scan clean: scanRepoDiagramLabels reports no repoIssues for registered template-*.svg files mapped in generator/pages/_diagram_gallery.py.
• Decorative skip: Tiles with aria-hidden="true" or role="presentation" are excluded; charts under [data-ks-chart] / .ks-chart-mount are out of scope.
• Readable minimum: Each counted label is at least 2 characters after trim and is not a lone bracketed placeholder ([subtitle], [Footer note - …]).

Failing signals

• diagram-labels-no-readable-text: Visible data-diagram-key tile (for example linear) whose SVG/ASCII surface has only placeholders or empty <text> nodes—no catalog node strings on the rendered surface.
• diagram-labels-legend-gap: Some labels exist but fewer than required matches (for example only Step A on a four-node linear legend; Stage 1–Stage 3 without Gate 1 / Gate 2 on gate).
• Abbreviated gate glyphs: Catalog lists Gate 1 but SVG shows only G inside diamonds—legend keys do not appear on the surface.
• Alt-only naming: Informative alt describes nodes while SVG text stays generic; this rule still fails because it inspects on-diagram text, not alt.
• Catalog drift: Renamed legend nodes in js/ks-diagram-catalog.js without updating assets/svg/template-*.svg (or the reverse).
• Unkeyed tiles: Diagrams without data-diagram-key are not scored for legend alignment (fix registry first under DET.DIAGRAM.ASSET_REGISTRY).

Before example

Before (failing example)

Diagram label coverage

Catalog keys without on-surface names

Modal legend lists Step A–D, but the SVG surface only shows [subtitle] placeholders.

Catalog legend requires Gate 1 and Gate 2; diamonds only show G.

After example

After (passing example)

Diagram label coverage

Legend keys visible on the tile

Step A, Step B, Step C, Step D (matches catalog nodes)

Surface text includes Stage 1, Gate 1, Stage 2, Gate 2, Stage 3 per catalog.

<figure
  class="forge-diagram forge-diagram-ascii breathe-static mb-0"
  data-diagram-key="gate"
  role="figure"
  hash="Asc"
  data-ks-hash="Asc"
>
  <div class="forge-diagram-ascii-canvas">
    <pre class="forge-code forge-diagram-ascii-pre"><code class="language-text">[ Stage 1 ] --&gt; [ Gate 1 ] --&gt; [ Stage 2 ] --&gt; [ Gate 2 ] --&gt; [ Stage 3 ]</code></pre>
  </div>
  <figcaption class="forge-diagram-ascii-caption forge-support small mt-2 mb-0">
    ASCII gate chain uses the same node names as js/ks-diagram-catalog.js.
  </figcaption>
</figure>

Evidence and remediation

Evidence: Auditor metrics diagramLabelsReport (DOM) and diagramLabelsRepoReport (repo template scan). Violations include kind (diagram-labels-no-readable-text, diagram-labels-legend-gap), key, selectorHint (for example motion.div.forge-diagram[key=linear]), matched / required / legendCount, and svg=assets/svg/template-….svg for template issues. Findings default to warn under visualCatalogGovernance. Capture outer HTML for the diagram root plus fetched SVG source or inline svg subtree.

Remediate (in order):

1. diagram-labels-no-readable-text: Add <text> / <tspan> labels (at least 2 characters) for catalog items[].node strings in assets/svg/template-*.svg, or embed matching tokens in .forge-diagram-ascii-pre. Remove reliance on [subtitle]-only surfaces for informative diagrams.
2. diagram-labels-legend-gap: Align abbreviated glyphs (for example G) with full legend names (Gate 1), or update js/ks-diagram-catalog.js when the shorter form is intentional—then re-run repo scan.
3. Gallery wiring: Ensure generator/pages/_diagram_gallery.py maps the key to the SVG you edited; run DET.DIAGRAM.ASSET_REGISTRY if the key or path is new.
4. Generator path: Prefer render_ks_diagram_block(key="linear") / ks_diagram_tile_html over hand-rolled tiles so data-diagram-key and asset paths stay registered.
5. Follow-on: After labels pass, verify DET.DIAGRAM.ALT and DET.HASH.MARKERS; use AI.DIAGRAM.SEMANTIC_ACCURACY when labels exist but topology disagrees with prose.

Related rules

• DET.DIAGRAM.ALT — decorative vs informative alt / aria-hidden policy for the same diagram roots.
• DET.DIAGRAM.ASSET_REGISTRY — data-diagram-key and assets/svg/ paths must be catalog-registered before label alignment matters.
• DET.HASH.MARKERS — visual roots should emit hash / data-ks-hash on diagram tiles.
• AI.DIAGRAM.SEMANTIC_ACCURACY — arrows, gates, and roles match the story even when labels are present.
• AI.VISUAL.PRODUCT_EXPLANATORY_VALUE — labels should teach product structure, not only satisfy coverage minima.