Sources & citations

Inline citations are numbered chips after a claim; hover or focus shows a preview card. Sources lists the same numbers under the answer, with the passage each source contributed.

Body text needs a contrast of at least 4.5:1 1. Every field needs a visible label; a placeholder is not one 2. After an error, move focus to the message, not to the top of the page 3.

Understanding SC 1.4.3: Contrast (Minimum)w3.orgThe visual presentation of text and images of text has a contrast ratio of at least 4.5:1. (source 1, opens in a new tab)
Understanding SC 3.3.2: Labels or Instructionsw3.orgLabels or instructions are provided when content requires user input. A placeholder is not a label. (source 2, opens in a new tab)
Understanding SC 2.4.3: Focus Orderw3.orgFocusable components receive focus in an order that preserves meaning and operability. (source 3, opens in a new tab)

InlineCitation in text · Sources (collapsible, open)Live · light and dark follow the theme switch

Add the source to a shadcn project

npx shadcn@latest add https://docs.atomus.io/r/ai-sources.jsonOpen in v0

Installs the component source, its CSS and the Atomus tokens into components/atomus/. How the registry works

List style

variant="list" — for side panelsLive · light and dark follow the theme switch

In Figma

From guidelines/components/ai-sources.md

Properties, variants and anatomy of the Figma components. React props use the same names.

Sources

The numbered list of sources behind an AI answer: a “3 sources” disclosure with stacked site icons, opening to cards with the number, title, site and the passage the answer used. Numbers match the Inline citations in the text. Part of the Agent kit.

Figma: component set Sources on the 🤖 Agent kit page of Atomus 4.0 (node 25547:925), connected to React with Code Connect. Rows: Source item (node 25547:794); citation chip: Inline citation (node 25547:946). React props use the same names as the Figma properties below.

Property	Type / options
Sources	list (title, url, domain, snippet, icon)
Label	text (“N sources”)
Style	Collapsible · List
Expanded	boolean

Use for

Under every answer that relies on retrieved documents, web pages or files.
A side panel listing everything a research agent read (variant="list").

Not for

Links the person should act on: put them in the answer as normal links.

Accessibility

The disclosure is a button with aria-expanded; the list is an ordered list, so numbers are announced.
Each link says “(source 2, opens in a new tab)” to screen readers.

Inline citation

A small numbered chip right after a claim. Hover or focus shows a preview card (site, title, passage); the chip links to the source. The chip tints with bg-ai-subtle and border-ai on hover and focus.

Property	Type / options
Number	number
Source	Source item

Accessibility

The chip is a link named “Source 2: Title (opens in a new tab)”, described by the preview card (role="tooltip").
The preview opens on focus as well as hover; Esc hides it.

Usage

import { Sources, InlineCitation } from '@stanvision/atomus-react';

<p>Body text needs a contrast of at least 4.5:1 <InlineCitation index={1} source={sources[0]} />.</p>
<Sources sources={sources} />

Props at a glance

Full types and defaults are in React API at the end of the page.

SourceItem — id, title, url, domain (derived from url), snippet, icon.
Sources — variant collapsible (default) or list; label overrides “N sources”.
InlineCitation — index matches the position in sources.

Design guidance

From the Figma guidelines.

Sources

Keep the order of first citation: source 1 is [1] in the text.
Show the passage the answer used, not the page’s meta description.

Forbidden

Never list sources the answer didn’t use.
Never invent or guess a URL — leave url empty when there is no link.

Inline citation

Place the chip right after the sentence or clause it supports, before the full stop of the next one.
Use one chip per source; repeat the number when a source supports several claims.

Forbidden

Never put interactive content in the preview card.
Never cite with colour or superscript alone — always show the number.

React API

Generated from react/src/components by scripts/gen-react-api.mjs — the same tables agents read in guidelines/components/ai-sources.md.

Use only these props; anything else is not part of the API.

`Sources`

Figma: Sources — the numbered list of sources behind an AI answer. Numbers match InlineCitation.

import { Sources } from '@stanvision/atomus-react'; — source: react/src/components/ai/Sources.tsx

Prop	Type	Default	Description
`sources`	`SourceItem[]`	required	Figma: Sources — in citation order; item 1 is citation [1].
`label`	`string`	—	Figma: Label — the disclosure text; defaults to “N sources”.
`variant`	`'collapsible' \| 'list'`	`'collapsible'`	Figma: Style. `collapsible` (default) — a “N sources” disclosure under the answer. `list` — always expanded, for side panels.
`open`	`boolean`	—	Expanded (controlled, `collapsible` only)
`defaultOpen`	`boolean`	`false`	Initial expanded state when uncontrolled
`onOpenChange`	`(open: boolean) => void`	—	Called when the person expands or collapses it
`className`	`string`	—	Extra class on the root element (layout only — never restyle colours or sizes).

Accepts only the props above.

SourceItem:

Field	Type	Description
`id`	`string`	Stable key
`title`	`string`	Page or document title
`url?`	`string`	Link to the source
`domain?`	`string`	Site shown under the title; derived from `url` when omitted
`snippet?`	`string`	The passage the answer relied on
`icon?`	`ReactNode`	Site icon or file-type icon (16px)

`InlineCitation`

Figma: Inline citation — a numbered chip after a claim. Hover or focus shows a preview card; the chip links to the source. Esc hides the preview.

import { InlineCitation } from '@stanvision/atomus-react'; — source: react/src/components/ai/Sources.tsx

Prop	Type	Default	Description
`index`	`number`	required	Figma: Number — the citation number, matching the source’s position in Sources
`source`	`SourceItem`	required	The cited source; its title, site and snippet fill the preview card
`className`	`string`	—	Extra class on the root element (layout only — never restyle colours or sizes).

Accepts only the props above.

SourceItem:

Field	Type	Description
`id`	`string`	Stable key
`title`	`string`	Page or document title
`url?`	`string`	Link to the source
`domain?`	`string`	Site shown under the title; derived from `url` when omitted
`snippet?`	`string`	The passage the answer relied on
`icon?`	`ReactNode`	Site icon or file-type icon (16px)