unstable_toDataPitfallsChain() packages a Semiotic chart into the experimental chain input expected bydatapitfalls. Semiotic contributes the chart config, JSX, reader grounding, config diagnostics, accessibility audit, and optional render evidence. Data Pitfalls remains the model-backed detector that reviews that chain against its pitfall taxonomy. The return-path helpers map a report back into chart-level notifications or Semiotic v3 annotation objects, mirroring the dependency-free bridge added in DataPitfalls PR #35.
Live payload builder
This demo does not call the Claude API. It shows the exact chain payload you would pass todetectPitfalls(), plus an illustrative response showing how Data Pitfalls can turn Semiotic evidence into decision support. The chart intentionally shows only the late-year window, so the Semiotic diagnostics stage has something substantive to hand off without making the visual example fragile.
Monthly revenue rises in the visible September to December window.
Stages9
Diagnostics3E / 1W
A11y auditok
Selected stage: Analysis context
JSON
Question: did monthly revenue improve enough to justify adding sales capacity?
Simulated Data Pitfalls response
This demo does not call a model. It shows the kind of evidence-backed support the bridge lets Data Pitfalls provide once the chain is sent to detectPitfalls().
Verdict:Review before using this chart to justify sales capacity.A Data Pitfalls review can connect the chart to the capacity question, then separate what the chart supports from what the decision still needs. Here it can say revenue rose in the visible window, but the view alone does not prove the increase is enough to add headcount.
Semiotic configJSX reconstructionreader grounding1 config warningsa11y audit: okrender evidencebusiness questionauthor claimsource data withheld
The claim is stronger than the visible evidence
highThe narrative says revenue is accelerating sharply, but the rendered chart only shows Sep-Dec and hides the first eight months from the visible x-domain.
- Config evidence: xExtent is [9, 12].
- Render evidence: one line and four points are visible over xDomain [9, 12].
- Source data is withheld, which is privacy-friendly but limits independent trend checks.
Next step:Show the full year, or label this view as Sep-Dec only and add the capacity threshold the decision depends on.
The decision threshold is missing
mediumThe question asks whether revenue improved enough, but neither the chart nor context defines enough: quota coverage, CAC payback, sales cycle, hiring cost, or target revenue lift.
- Question: did monthly revenue improve enough to justify adding sales capacity?
- The axes show revenue over month number, but no target band or required lift annotation is present.
Next step:Add a target line or annotation for the capacity threshold, then ask whether the observed lift clears it.
The useful output is coaching, not just a warning
infoThe report can give a safer framing the author can reuse with stakeholders instead of only saying the chart is risky.
- Reader grounding supplies what the chart says without relying only on pixels.
- Diagnostics and accessibility audit explain which issues are deterministic Semiotic checks.
Next step:Use the revised wording below as the start of a decision memo or PR review comment.
Safer stakeholder wordingRevenue rose from 9000 to 10100 in the visible Sep-Dec window. Before adding sales capacity, show the full-year trend and compare the lift against the required hiring threshold.
Server workflow
In production, build the bridge in a server job or CI step. UserenderChartWithEvidence() when the chart is SSR-renderable, then pass the resulting chain into Data Pitfalls.
TS
import { unstable_toDataPitfallsChain } from "semiotic/experimental" import { renderChartWithEvidence } from "semiotic/server" import { detectPitfalls, formatReport, hasBlockingFindings } from "datapitfalls" const { svg, evidence } = renderChartWithEvidence("LineChart", props) const input = unstable_toDataPitfallsChain("LineChart", props, { context: "Question: did monthly revenue improve enough to justify adding capacity?", narrative: "Monthly revenue is accelerating sharply.", rendered: { svg, evidence }, config: { includeData: false }, // omits raw rows from config/JSX stages }) const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY, }) console.log(formatReport(report)) if (hasBlockingFindings(report)) process.exit(1)
Return path
DataPitfalls PR #35 adds toSemioticAnnotations() in the DataPitfalls package. Semiotic also exposes structural helpers for apps that already have a report object and want to keep rendering code dependency-free. Whole-chart findings fit theChartContainer notification stack; mark-level findings can become annotations once the host app supplies coordinates or semantic anchors.
TSX
import { ChartContainer } from "semiotic" import { LineChart } from "semiotic/xy" import { unstable_toDataPitfallsAnnotations, unstable_toDataPitfallsNotifications, } from "semiotic/experimental" const notifications = unstable_toDataPitfallsNotifications(report, { max: 3 }) const annotations = unstable_toDataPitfallsAnnotations(report, { anchorFor: (finding) => finding.ruleId === "truncated-axis" ? { x: 9, y: 9000, anchor: "semantic" } : null, }) <ChartContainer notifications={notifications}> <LineChart {...props} annotations={annotations} /> </ChartContainer>
The annotation helper deliberately does not invent x or y. An unanchored Semiotic v3 annotation is dropped until the host places it, while unanchored report-level findings remain visible as notifications.
What Semiotic adds
- Config and JSX give Data Pitfalls source-level evidence for accessors, scales, extents, color choices, annotations, and omitted data.
- Reader grounding gives the detector a non-visual account of what the chart says, including the L1-L4 description used by the agent-reader path.
- Diagnostics surface Semiotic's deterministic checks, including misleading design smells such as non-zero baselines, inverted axes, over-sliced pies, and low contrast.
- Accessibility audit packages Chartability findings so Data Pitfalls can reason over accessibility and design dangers without relying only on pixels.
- Render evidence adds scene-graph facts such as mark counts, domains, emptiness, annotations, and accessible names when a server render is available.
Bridge options
TS
unstable_toDataPitfallsChain(component, props, { includeConfig: true, includeJSX: true, includeGrounding: true, includeDiagnostics: true, includeAccessibility: true, context: "Analytical question, upstream assumptions, or intended audience.", narrative: "Caption or claim that should be checked against the chart.", rendered: { svg, // optional rendered SVG evidence, // optional renderChartWithEvidence() payload image, // optional base64 PNG/JPEG/GIF/WebP for Vision review }, config: { includeData: false }, // other stages may still summarize data-derived facts grounding: { includeStructure: false }, accessibility: { inChartContainer: true, describe: true, navigable: true }, additionalStages: [ { role: "Upstream SQL", artifact: { kind: "code", language: "sql", content: "..." }, }, ], })