Chart and data-product contract

Contract version: 0.1.0
Status: proposed public-display requirement

A visualization is a research claim, not decoration. Every chart, table, explorer state, and downloadable slice must make its method and limits inspectable without implying that draft, synthetic, or missing information is an official result.

Required visible frame

Every chart card must show, at the point of use:

• precise metric title and version;
• one-sentence definition, unit, and direction;
• status: synthetic / exploratory / preregistered / reviewed / corrected / retracted;
• population or explicit synthetic fixture label;
• denominator as N included / M eligible, plus missing and invalid counts;
• time period and as-of date;
• uncertainty display or an explicit reason it is unavailable;
• coverage and verification state when capability evidence is displayed;
• material limitation;
• method, accessible table, citation, data-availability, and correction links.

For any v0.1 synthetic numeric projection, show this warning in the chart frame, not only a footer:

Experimental synthetic output — not an official score, credential, ranking, or real-person result. The method and thresholds are unvalidated.

Machine-readable chart manifest

Each rendered chart should be backed by a versioned manifest with at least:

{
  "schema_version": "0.1.0",
  "chart_id": "research.synthetic-evidence-strength.01",
  "chart_version": "0.1.0",
  "status": "synthetic",
  "title": "Synthetic evidence distribution",
  "metric_id": "evidence_state_count",
  "metric_version": "0.1.0",
  "unit": "records",
  "direction": "descriptive",
  "population_label": "Synthetic fixture only",
  "included_n": 24,
  "eligible_m": 24,
  "missing_n": 0,
  "invalid_n": 0,
  "period_start": "2026-08-31",
  "period_end": "2026-08-31",
  "as_of": "2026-08-31T00:00:00Z",
  "method_id": "method.synthetic-display.0.1.0",
  "dataset_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "analysis_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "limitations": ["Synthetic values do not describe any person or population."],
  "correction_policy_ref": "CHANGELOG.md"
}

The example digests are visibly synthetic placeholders. A real publication manifest must contain actual verified digests and must not use this fixture.

Interaction rules

• Changing a filter updates the title/context, denominator, missingness, table, URL state, and screen-reader announcement together.
• A control that does not change data must be styled and named as a label, not an input.
• Default sorting may not create an ordered named-person list.
• Filters must not expose small cells, allow differencing attacks, or reconstruct a person.
• Comparison across benchmark versions is disabled unless a linking study is named.
• Tooltips cannot hold essential information exclusively; keyboard and touch users need the same content.
• Loading, empty, withheld, insufficient-evidence, invalid, corrected, and error states are distinct.
• Export repeats the visible filters, method/version, dates, denominator, suppression, limitations, and digest metadata.

Accessibility rules

• Provide a semantic heading, concise text summary, and table for every data graphic.
• Use native form controls with programmatic labels and 24×24 CSS-pixel minimum targets; prefer 44×44.
• Do not use color alone. Use labels, shape/pattern, and/or direct annotation.
• Normal text must meet WCAG 2.2 AA contrast; meaningful graphics and focus indicators need at least 3:1 contrast.
• Keyboard order follows the visual reading order; focus is visible and unobscured.
• Dense tables use captions, scoped headers, units in headers, and a responsive non-lossy alternative.
• Motion is nonessential and respects prefers-reduced-motion.

Human-capability-specific prohibitions

• no global human-intelligence or personal-worth number;
• no named-person leaderboard or indirectly reconstructable ranking;
• no cost-per-person, compensation efficiency, or “value for money” axis;
• no unsupported percentile or population norm;
• no implication that missing evidence is low capability;
• no official score language for synthetic, experimental, or draft output;
• no protected-attribute filter on public individual data;
• no employer, school, sponsor, fame, payment, or training prestige as a capability feature.

Publication gate

A chart must fail closed if its manifest, method, denominator, source digest, status label, required privacy suppression, or correction link is absent. A broken visualization cannot silently fall back to a number or stale cached result.