Sources

01Preview

Pick a component and change its options. The favicons here are neutral placeholders made by the docs; apps pass real favicon URLs.

componentSourceCardSourceStackSourceItemfaviconyesnoexcerpt lines2130new tabyesnosources13461clickableyesnoselectedunsettruefalsefile name

openbiology.exampleCellular respiration: how cells release energy (opens in a new tab)Cellular respiration turns glucose and oxygen into usable energy (ATP), water and carbon dioxide. Most of it happens in the mitochondria.

tsx

import { SourceCard } from '@nuton/ui'

<SourceCard
  href="https://openbiology.example/respiration"
  title="Cellular respiration: how cells release energy"
  site="openbiology.example"
  favicon={faviconUrl}
  excerpt="Cellular respiration turns glucose and oxygen into usable energy (ATP), water and carbon dioxide. Most of it happens in the mitochondria."
/>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens

npm install @nuton/ui @nuton/tokens

yarn add @nuton/ui @nuton/tokens

Peer dependencies: react and react-dom 18 or later. No brand images ship with the package: your app supplies favicons (D12).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

SourceItem uses the FileFormatIcon styles, which ship in the same stylesheet.

03Usage

import { SourceCard, SourceItem, SourceStack } from '@nuton/ui'

export function AnswerSources({ sources, onOpen }) {
  return (
    <>
      <SourceStack sources={sources} onClick={onOpen} />
      {sources.map((s) => (
        <SourceCard key={s.url} href={s.url} title={s.title} site={s.domain} favicon={s.faviconUrl} excerpt={s.quote} />
      ))}
      <SourceItem name="Form and Function in Design.pdf" onClick={() => openFile('form-and-function')} />
    </>
  )
}

• A SourceCard links from its title, which covers the whole card. It opens in a new tab by default and says so to screen readers; set newTab={false} for sources inside Nuton.
• SourceStack summarises many sources in one small control. Give it onClick to open the full list, and wire aria-expanded when it shows and hides them.
• SourceItem is a file row. Pass selected when the row picks which file is shown, so it reads as a toggle.
• Pass favicons as URLs from your source data. When one is missing or fails, a neutral globe shows instead.
• Put cards and items in a list (<ul>) so people hear how many there are.

04Variants and sizes

Three components, each with one size.

Source card

PreviewCode

openbiology.exampleCellular respiration: how cells release energy (opens in a new tab)Cellular respiration turns glucose and oxygen into usable energy (ATP), water and carbon dioxide. Most of it happens in the mitochondria.

Source stack

PreviewCode

13 sources, +9 more3 sources13 sources, +9 more

Source item

<SourceItem name="Form and Function in Design.pdf" />
<SourceItem name="Lecture 3 – Colour theory.pptx" />
<SourceItem name="Reading list.docx" />

Sizes

Values from the component CSS, which follows Figma's geometry (References 3852:44840, Links 3850:35433, source file item 3842:32371).

05States and interactions

State tokens

06Composition examples

AI answer with sources

The stack sits under the answer. Pressing it shows the source cards and sets aria-expanded, so screen readers know the list opened.

PreviewCode

Mitochondria release energy from food through cellular respiration. Glucose is broken down in stages (glycolysis, the Krebs cycle and the electron transport chain) to make ATP, the energy the cell uses.

6 sources, +2 more

Lesson source files

A list of the files a lesson was built from. Choosing one shows it; the chosen row is pressed.

<ul aria-label="Lesson sources">
  {files.map((f) => (
    <li key={f.id}>
      <SourceItem name={f.name} selected={f.id === shownId} onClick={() => show(f.id)} />
    </li>
  ))}
</ul>

07API reference

SourceCard props

SourceStack props

SourceItem props

Styling hooks

.nu-source-card (__site, __title, __excerpt[data-lines]), .nu-source-stack ([data-interactive], __more), .nu-source-item([data-selected], __name) and the shared .nu-source-favicon. Override with the --nu-source-* tokens.

Accessibility

You must: pass a real title for every card (not the URL); keep aria-expanded in sync when a stack shows and hides sources; translate labels, including the new-tab hint and the source count.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Putting buttons or other links inside a SourceCard. The title link covers the whole card.
• Giving a stack an onClick but no visible result, or not updating aria-expanded.
• Using selected on rows that open a file in a new view instead of choosing what is shown.
• Shipping brand logos as favicons in the design system. Apps fetch them from the source.

Related components

• File uploadAdd files, and the FileFormatIcon used by SourceItem.
• AvatarPeople, rather than sites, in a stack.
• Link buttonA single text link.
• Audio playerPodcast episodes made from the same sources.