Foundation — Agentic Design Language
Trust & Provenance
Data lineage is not a compliance checkbox — it is the primary interface for calibrated trust. When an agent surfaces a number, recommendation, or synthesis, the user deserves to trace it: the source, its age, the transformation path, and the model's confidence.
Components: ProvenanceChain · CitationCard · ConfidenceMeter · AuditTrail · DataTag
The Four Provenance Questions
Every trust provenance display must answer all four questions. A component that answers only one or two is a partial implementation.
What is the source?
Name, type (document / database / API / agent), and a direct link when available.
How fresh is it?
Inline timestamp — visible at all times, not in a tooltip. Stale data earns a gold border.
What was the transformation path?
The ProvenanceChain shows each step: source → transform → inference → output.
How confident is the model?
ConfidenceMeter shows retrieval confidence and model reasoning confidence as separate axes.
Component Preview
Stale-Source Threshold Reference
The gold border on a CitationCard signals stale data using staleThresholdHours. The threshold must match the update cadence of the data type. A blanket 24-hour threshold is correct for live API feeds but creates constant false alarms on policy documents and static reference data.
Design rule
Always set staleThresholdHours explicitly on CitationCard. The default (24h) is wrong for document and static-reference sources. Consult the table below and configure per data type.
| Source type | Recommended prop | Threshold | Rationale |
|---|---|---|---|
| API (live feed) | staleThresholdHours={1} | 1h | Market rates, FX, live balances — stale within an hour. |
| API (batch/periodic) | staleThresholdHours={4} | 4h | Settlement data, batch reconciliations — 4h typical refresh. |
| Database record | staleThresholdHours={24} | 24h | Entity records, configuration — daily refresh is normal. |
| Agent output | staleThresholdHours={24} | 24h | Agent-generated analysis — valid for one business day. |
| Document (policy/contract) | staleThresholdHours={720} | 30 days | Policy documents change rarely. 24h would false-alarm constantly. Use 720h (30 days) or omit the prop entirely for manual staleness control. |
| Static reference data | stale={false} | Never auto-stale | Country codes, currency symbols, holiday calendars — use explicit stale={false} to permanently suppress the gold border. |
Token Reference
| Token | Value | Meaning | Use in provenance |
|---|---|---|---|
| --ds-color-validation | #C49A1A | Stale data, requires human review, quality threshold | Stale-source border on CitationCard, gold badge on unverified synthesis |
| --ds-color-temporal | #2B44D4 | Data in transit, freshly retrieved | Active retrieval state, transform step indicator in ProvenanceChain |
| --ds-text-muted | 4.83:1 contrast | Secondary metadata | Timestamps, confidence percentages, source type labels |
| --ds-text-secondary | 7:1 contrast | Supporting body content | Source excerpts, chain step labels |
| --ds-surface-raised | — | Card background | CitationCard background, ProvenanceChain output node |
| --ds-border-separator | — | Subtle divider | ProvenanceChain timeline track between steps |
Do / Don't
DO
Show data freshness inline
If data is 3 hours old in a live-market context, that is decision-critical. The timestamp must be visible without a hover interaction.
DON'T
Put the timestamp in a tooltip
Hover-only freshness means most users never see it. In a treasury crisis at 3am, there is no time for precision hovering.
DO
Use gold (--ds-color-validation) for stale data borders
Gold is the semantic token for 'this needs review.' A stale CitationCard earns a gold left-border — the same token used for approval-gate states.
DON'T
Apply a 24h stale threshold to document sources
Policy PDFs and contracts do not change daily. A blanket 24h threshold creates constant false alarms on stable documents. Use staleThresholdHours={720} or stale={false}.
DO
Distinguish retrieval confidence from model confidence
A model may reason very confidently about uncertain data. These are different epistemic claims. ConfidenceMeter axis='dual' renders both axes separately.
DON'T
Use a single confidence score for all uncertainty types
'87% confident' on a synthesis is meaningless without context. 87% confident in what — retrieval match quality or model reasoning?
DO
Link every synthesized output to at least one source
Synthesis without citation is assertion. Every AI-generated number, recommendation, or summary must link to its ProvenanceChain.
DON'T
Write 'Sources: AI-generated' as the only attribution
This is not provenance. It is the absence of provenance, formatted to look like one.
Usage
import { ProvenanceChain } from "@/components/patterns/ProvenanceChain";
import { CitationCard } from "@/components/patterns/CitationCard";
import { ConfidenceMeter } from "@/components/patterns/ConfidenceMeter";
// ProvenanceChain — show the full reasoning path
<ProvenanceChain
title="Recommendation provenance"
steps={[
{ type: "source", label: "ECB FX Rate Feed", time: lastUpdatedAt },
{ type: "transform", label: "Currency normalization", model: "calc-engine" },
{ type: "inference", label: "Exposure synthesis", model: "claude-opus-4.6", confidence: 0.81 },
{ type: "output", label: "EUR/USD rebalancing recommendation" },
]}
/>
// CitationCard — configure staleThresholdHours per data type
<CitationCard
source="Treasury Policy Manual v4.2"
sourceType="document"
lastUpdatedAt={lastUpdatedAt}
staleThresholdHours={720} // 30 days — documents change rarely
chunk="Section 3.4: Rebalancing triggers when exposure exceeds 15% of AUM"
confidence={0.93}
/>
// ConfidenceMeter — dual axis distinguishes retrieval from model confidence
<ConfidenceMeter axis="dual" retrieval={0.94} model={0.68} />Component API
Prop reference for the three components in the Trust Provenance system.
ProvenanceChain
| Prop | Type | Default | Description |
|---|---|---|---|
| steps | ProvenanceStep[] | — | Ordered list of reasoning steps. Each step has: type, label, time (ISO), model (optional), confidence (0–1, optional), status (complete|pending|failed|skipped). |
| title | string | — | Optional heading rendered above the chain. |
| stalenessThresholdMs | number | 3600000 | Steps with lastUpdatedAt older than this value (ms) are flagged as stale with the gold validation color. Default is 1 hour. |
ConfidenceMeter
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | — | Single-axis mode: confidence score 0–1. Mutually exclusive with axis='dual'. |
| axis | "dual" | — | Switches to dual-axis mode (retrieval vs. model confidence). When set, use retrieval and model props instead of value. |
| retrieval | number | — | Dual-axis mode: retrieval confidence 0–1 (how well the source was found/matched). |
| model | number | — | Dual-axis mode: model reasoning confidence 0–1. |
| label | string | — | Single-axis only. Optional label rendered above the bar. |
| thresholds | ConfidenceThresholds | — | Override default low/high thresholds (default: low=0.5, high=0.8). Controls when bars render in outcome-negative vs. validation vs. outcome-positive colors. |
| staleEvidenceAge | string | — | Human-readable age string (e.g. '4h 12m'). Renders a gold stale-evidence warning below the meter. Does not affect the score. |