DEV Community

babycat
babycat

Posted on

Design AI Citations for Failure, Not Just the Happy Path

#a11y #frontend #ai #ux

An AI citation is often rendered as a tiny blue [3]. That works only when the source exists, loads quickly, matches the quoted revision, and is usable by keyboard and screen-reader users.

A citation component needs states, not just a link.

type CitationState =
  | { kind: "loading"; label: string }
  | { kind: "available"; label: string; href: string; excerpt: string }
  | { kind: "changed"; label: string; href: string; retrievedAt: string }
  | { kind: "missing"; label: string; reason: "deleted" | "forbidden" | "offline" };
Enter fullscreen mode Exit fullscreen mode

Render each state in text:

<aside aria-labelledby="sources-heading">
  <h2 id="sources-heading">Sources</h2>
  <ol>
    <li>
      <a href="/docs/retention">Audit-log retention policy</a>
      <p>Retrieved 12 July 2026. The source has changed since retrieval.</p>
      <details>
        <summary>Show the excerpt used</summary>
        <blockquote>Audit logs are retained for 30 days…</blockquote>
      </details>
    </li>
  </ol>
</aside>
Enter fullscreen mode Exit fullscreen mode

Do not encode verification as green alone. Use text such as “source available,” “source changed,” or “source unavailable.” Keep inline markers short, but give links descriptive accessible names such as aria-label="Source 3: Audit-log retention policy".

Interaction rules

  • Opening a citation must not discard the generated answer.
  • Keyboard focus moves only after an explicit user action.
  • A failed preview preserves the original link when safe.
  • Excerpts include a source revision or retrieval time.
  • A citation proves where text came from, not that a claim is true.
  • Streaming adds citations without repeatedly announcing the whole list.

For live updates, announce a restrained summary such as “Two sources added” in a polite live region. Let users navigate the durable list normally. Respect prefers-reduced-motion if citations animate into place.

Test keyboard order, 200% zoom, high contrast, source deletion, authorization failure, slow networks, changed documents, long titles, duplicate sources, and citations created before streaming ends.

The public MonkeyCode repository describes project requirements and AI task workflows. Citation states are relevant when a coding interface presents requirement or repository evidence, but this component is a proposed pattern, not a description of MonkeyCode's current UI.

Disclosure: I contribute to the MonkeyCode project. The product connection is based on public documentation; no MonkeyCode accessibility test is claimed.

A useful citation interface helps readers understand what evidence is available, what changed, and what still needs judgment.

Top comments (0)