Sources, citations & provenance

@ponchia/ui/css/sources.css is an opt-in trust layer for generated reports, AI output, audits, and docs — the grammar that answers "where did this come from?". Generic UI kits have tags and footnotes; this is a small, explicit vocabulary for sources and their trust state.

@import '@ponchia/ui';
@import '@ponchia/ui/css/sources.css';

Bronto owns the visual grammar and the trust states. The host owns fetching, citation numbering, permission checks, and whether a source is actually trustworthy. The state is carried by a rationed tone and an author-written label, so it never relies on colour alone (WCAG 1.4.1). Not in the core bundle.

Trust states

A cross-cutting trust-state class — ui-src--verified, ui-src--stale, and the rest in the table below — sets the tone on a citation chip, source card, or provenance item. Always pair it with a word: the colour is a second channel, not the only one.

A trust-state class needs a host element — on its own a tone class (ui-src--verified and the rest) only sets a --src-tone, it does not draw anything. The host is one of the elements below, or the standalone .ui-src pill.

Standalone trust pill — .ui-src

When you just need a bare labelled chip (a row of provenance tags, an inline "verified" badge) with no surrounding card or citation, use .ui-src as the host and add a tone. It draws a small pill with a leading trust dot:

<span class="ui-src ui-src--verified">Verified</span>
<span class="ui-src ui-src--generated">Machine-generated</span>
<span class="ui-src ui-src--stale">Stale · 14d</span>

The base .ui-src is required — <span class="ui-src--verified"> alone validates against classes.json but renders nothing, because the tone class only carries the colour for a host to consume. The word inside is the channel (WCAG 1.4.1); the dot and tint are reinforcement. Reach for .ui-citation--chip instead when the pill is a real link/button to the source.

Inline citation — .ui-citation

A reference marker on a real <a> or <button> (the visual index is never the only label — give it an accessible name).

<p>
  Latency fell 38%<a class="ui-citation" href="#s1" aria-label="Source 1">[1]</a>.
</p>

<!-- Named-source pill, with a leading trust dot: -->
<a class="ui-citation ui-citation--chip ui-src--verified" href="#s1">
  Q3 incident review
</a>

Source card — .ui-source-card

A single source preview: title, origin, time, excerpt, actions. The border-inline-start carries the trust tone.

<article class="ui-source-card ui-src--generated">
  <h3 class="ui-source-card__title">Model output — pricing summary</h3>
  <p class="ui-source-card__origin">gpt-x · internal</p>
  <p class="ui-source-card__time">2026-06-01 09:42</p>
  <p class="ui-source-card__excerpt">The migration cut p95 latency by 38%…</p>
  <div class="ui-source-card__actions">
    <button class="ui-button ui-button--subtle ui-button--sm" type="button">Open</button>
  </div>
</article>

The parts are __title, __origin, __time, __excerpt (the body text — not __detail/__body), and __actions. A card nests inside a ui-source-list__item when it sits in a references section (below).

Source list — .ui-source-list

A references section: a reset list of source cards (or rows).

<ol class="ui-source-list">
  <li class="ui-source-list__item"><article class="ui-source-card ui-src--verified">…</article></li>
  <li class="ui-source-list__item"><article class="ui-source-card ui-src--stale">…</article></li>
</ol>

Optional behavior — initSources

When you want citations to jump back to their source cards with a visible focus cue, wrap the report or article in data-bronto-sources and initialize the behavior:

<main data-bronto-sources>
  <p>Latency fell 38%<a class="ui-citation" href="#s1" aria-label="Source 1">[1]</a>.</p>
  <article id="s1" class="ui-source-card ui-src--verified">…</article>
</main>

<script type="module">
  import { initSources } from '@ponchia/ui/behaviors';
  const stop = initSources();
</script>

initSources() is progressive enhancement over authored IDs. It resolves .ui-citation[href^="#"] and [data-bronto-source-ref] controls inside each [data-bronto-sources] island, adds preview metadata (title and aria-describedby) when the author did not already provide it, and activation focuses the matching source card with a temporary .is-source-active highlight. It emits bronto:source:focus with { id, citation, source }.

The host still owns fetching, numbering, permission checks, trust decisions, and any rich preview popover. Generated/static reports can stay behavior-free: hash-link navigation and .ui-source-card:target still provide a CSS-only cue.

Provenance — .ui-provenance

A compact metadata row beside generated content — each __item carries a trust dot and a label.

<p class="ui-provenance">
  <span class="ui-provenance__item ui-src--generated">Generated</span>
  <span class="ui-provenance__item ui-src--verified">3 sources</span>
  <span class="ui-provenance__item ui-src--reviewed">Human-reviewed</span>
</p>

Recipes

import { ui } from '@ponchia/ui/classes';

ui.citation({ chip: true, state: 'verified' });
// "ui-citation ui-citation--chip ui-src--verified"
ui.source({ state: 'generated' }); // "ui-source-card ui-src--generated"
ui.provenance({ state: 'reviewed' }); // "ui-provenance ui-src--reviewed"

Accessibility & print

• A citation must be a real link or button with a stable accessible name; the bracketed index alone is not enough.
• initSources() is optional. Initialize it only on trusted markup; the delegated data-bronto-source-ref / href="#…" relationships focus elements inside the source island.
• The trust state must be readable as text — the tone dot/border is decorative reinforcement. Under forced-colors, dots and borders fall back to CanvasText, so the label remains the channel.
• Tone dots and the card's tone border carry print-color-adjust: exact, so they survive printing; expand citation URLs in print where it helps the reader.

Related

• Usage shows where citations fit in reports.
• Reference lists the generated source and citation classes.