Interface Lab
Login
Back to knowledge
Frontend Implementation

AI Response Citation and Evidence Surface Contract

Citations in AI/RAG answers are not footer decoration. They are an evidence surface joining claims, sources, snippets, permissions, streaming state, copy/share behavior, and auditability.

ai-uicitationsragsourcesstreaming

Design Principle

Trustworthy AI interfaces let users see which claims have sources, whether sources are accessible, when evidence was generated, how to open or copy it, and how missing, stale, or low-confidence evidence is handled.

Large Theory

Trust in an AI answer cannot come only from model tone or a Sources heading. Users need to trace concrete claims to concrete sources, know whether a source is a web page, file, database row, or tool result, and understand citation state while the answer streams. A healthy AI evidence surface handles reading flow, citation granularity, evidence cards, permission boundaries, copy/share, error recovery, and mobile usability together.

Small Points

  1. Define accountability first: casual exploration, internal assist, customer-facing answer, high-risk domain, or compliance audit. Higher risk needs timestamps, no-answer behavior, human review, and evidence export.
  2. Choose granularity by task: claim-level uses inline citations, answer-level uses a source list, and complex evidence uses source cards or drawers. Do not number every sentence and create reading noise.
  3. Citation data needs at least stable id, source type, title, href/locator, provider, snippet/quote, cited claim ids, retrievedAt, access/status, and optional score.
  4. Layer answer, evidence, and reasoning: the final answer is for reading; sources are verifiable evidence; tool logs, retrieval traces, and reasoning summaries belong in separate collapsible areas. Do not expose hidden chain-of-thought as trust UI.
  5. Citation state during streaming must be honest: sources pending, partial sources, complete, and error. Do not show clickable final citation markers before source data exists.
  6. Source cards need missing, stale, inaccessible, restricted, and low-confidence states. Internal docs must not leak file names, paths, or URLs that the user cannot access.
  7. Copy, share, and export must decide whether citations are preserved. If they are omitted, say so clearly. Otherwise the copied answer loses evidence context.
  8. Hover-only citations are not enough. Mobile and keyboard users need focusable triggers, closeable popovers/drawers, clear aria labels, and long URLs/snippets that do not overflow the whole page.

Design Judgment

The contract works when users can locate the cited claim, open or inspect the source, see snippet/quote evidence, know whether evidence is complete, and keep sources when copying or sharing. If sources are only a footer link list, or citation markers cannot be mapped to source cards, the interface does not support trustworthy AI.

Implementation Notes

Create an AiResponseCitationContract: answerId, status, riskLevel, answerParts, citations, and actions. In React, store source parts and text parts separately and connect them with stable ids; source cards and inline markers render from the same citations array. AI SDK/AI Elements projects can combine Sources, Inline Citation, Message, and Reasoning. assistant-ui fits production chat runtimes and multi-backend integration. tool-ui Citation fits schema-validated source cards from tool payloads. Test no sources, one source, many sources, sources pending, missing source, permission denied, copy with citations, and mobile drawer behavior.

Counterexamples/Risks

An answer ends with Sources: 3 but does not map claims to sources; citation pills appear during streaming while source data is empty; retrieval score is shown as confidence without explanation; hover cards fail on phones; copied answers drop citations; private file paths leak to external users; reasoning, tool logs, and evidence are mixed in one trust drawer.

Case Study

AI Elements Sources says it lets users view the sources or citations used to generate a response and supports a collapsible source list, custom sources, and responsive controls; its example passes source-url message parts through sendSources: true. Inline Citation separates citation pills, source cards, carousel navigation, source metadata, and quotes, and notes that inline citations are not currently supported out of the box by ordinary markdown/Response flows, recommending structured citation data. Reasoning places reasoning content in a separate collapsible area and distinguishes reasoning from Chain of Thought. tool-ui Citation emphasizes a clickable reference card with title, domain, favicon, and snippet so readers can trace claims. The reusable lesson is that trustworthy AI UI is not one link list; it is a contract among answer parts, source data, streaming status, and evidence actions.

Source Links

AI Elements: https://elements.ai-sdk.dev/ AI Elements Sources: https://elements.ai-sdk.dev/components/sources AI Elements Inline Citation: https://elements.ai-sdk.dev/components/inline-citation AI Elements Message: https://elements.ai-sdk.dev/components/message AI Elements Reasoning: https://elements.ai-sdk.dev/components/reasoning AI SDK streamText: https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text assistant-ui: https://www.assistant-ui.com/ assistant-ui GitHub: https://github.com/assistant-ui/assistant-ui tool-ui Citation: https://www.tool-ui.com/docs/citation tool-ui GitHub: https://github.com/assistant-ui/tool-ui

Agent Directive

Before generating AI answer UI, output the citation data contract, streaming source states, source card/drawer behavior, permission boundaries, and copy/export rules; do not only place unmapped links at the answer footer.