Data insight legibility

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-data-insight-legibility. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink data charts (render_ks_chart_mount, data-ks-chart, forge-data-charts.js) and adjacent tables ship on showcase pages (Dcs, Dca) and consumer dashboards. Deterministic checks confirm summaries exist (DET.CHART.ALT_SUMMARY), tables have headers (DET.DATA.TABLE_HEADERS), and meaning is not color-only (DET.DATA.COLOR_ONLY). This AI rule judges whether a visitor can answer “so what?” from the block—not merely decode bars or slices.

Plan: Read the chart in context (section title, surrounding copy, operator task). Note whether emphasis, annotation, and takeaway copy align with the story the page claims. Do: Add an outcome-first heading, a one-sentence insight, and in-chart or adjacent labels for the comparison you want remembered. Check: A skimmer gets the main claim without hovering every bar or inferring from palette alone. Adjust: If missing summaries or unlabeled series repeat, tighten DET.CHART.ALT_SUMMARY or propose annotation helpers in forge-data-charts.js.

Passing signals

• Takeaway title states the insight (h2 / h3 in ks-section, or card-label inside forge-card)—not only the chart kind (commit_weekly) or raw metric name.
• Plain-language summary beside or below the mount (forge-support, figcaption, or aria-describedby) names direction, magnitude, and comparison window (e.g. “Commits doubled in W10 after the release freeze lifted”).
• Emphasis matches the story: annotated peak/trough, highlighted series, or callout on the bar/week that supports the takeaway—not decorative accent alone.
• Redundant encoding: series use labels, values on bars, lenses-overview-donut-swatch + text, or table columns—not hue alone (DET.DATA.COLOR_ONLY ally).
• Accessible summary satisfies DET.CHART.ALT_SUMMARY (non-trivial text, aria-describedby, or nearby caption) and stays consistent with visible emphasis.
• Chart mount keeps KS attributes (ks-chart-mount, data-ks-chart-kind, data-ks-chart-state) inside a bounded region with loading/error states readable.

Failing signals

• Only the auto caption from render_ks_chart_mount (<strong>Weekly commits</strong> · <code>commit_weekly</code>) with no “so what” sentence.
• Accurate SVG geometry but no annotation on the week, repo, or score the prose discusses.
• Competing charts at equal visual weight with identical forge-support stubs—visitor cannot tell which block answers the section question.
• Insight buried in tooltip-only <title> elements with no visible takeaway for keyboard or skimming readers.
• Color highlights the tallest bar while copy claims a different trend (emphasis contradicts narrative).
• Dense multi-chart grids (data-charts-static style) with no per-chart summary or section-level synthesis.

Before example

After example

Evidence and remediation

Capture: screenshot of the chart block at desktop and narrow widths; copy the DOM around ks-chart-mount including headings, aria-describedby targets, and any forge-card wrapper. For API-driven charts (data-ks-chart-url), capture loading and error states too.

Remediate (in order):

1. Replace kind-only headings with an outcome title (h2/h3 or card-label + insight headline).
2. Add a one-sentence takeaway (forge-support or figcaption) that states direction, delta, and window; wire aria-describedby on the mount (DET.CHART.ALT_SUMMARY).
3. Emphasize the series or period the copy names (amber peak bar, callout text, table row bold)—keep redundant text labels (DET.DATA.COLOR_ONLY).
4. If multiple charts share a section, add a section synthesis paragraph or reorder so one chart is primary.
5. Re-run deterministic chart/table checks; if tooltip-only insight repeats, propose a DET.* annotation contract for forge-data-charts.js.

Related rules

• DET.CHART.ALT_SUMMARY — chart or graph has a non-trivial text summary, aria-describedby, or nearby caption.
• DET.DATA.COLOR_ONLY — meaning not conveyed by color alone where detectable.
• DET.DATA.TABLE_HEADERS — tables expose <th> scope or explicit header associations.
• AI.VISUAL.PRODUCT_EXPLANATORY_VALUE — product visuals teach mechanism and outcome, not decoration alone.
• AI.DIAGRAM.SEMANTIC_ACCURACY — diagram topology matches captioned mechanism (adjacent judgment for SVG flows).