Molecules

01

Text pairing

An eyebrow, the page's title and the line under it, set tight so the three read as one, in four sizes from a page to a login.

Open source

Claude Narrator

Hear what a Claude Code session is doing, out loud, while you do something else.

When the page belongs to a family: a category word over the title, set uppercase by it: "Open source".
The page's name, one to four words: "Claude Narrator", "Client space".
The title's step; eyebrow, line and gaps grow with it. h1 an app page, h2 a portal page, h3 a login.
One line of plain text: what the page lets you do, said to the person.

02

Labelled field

A dark grey label above its control: an input, a textarea or a select.

When the control cannot sit inside the label, as one a library renders: the control's id, so the label points at it.

03

List entry

A heading with its supporting text under it and a cover beside it: the unit the home and blog article lists are made of.

Component
ListEntry
Import
@/app/components/ui/list-entry
What it is
One entry of an article list, the whole entry one link: an H3 title, a dark grey PXSmall date and a PSmall intro under it, a portrait cover beside them that grows a little on hover. No outer spacing.
Use when
An entry in a column of articles. SectionBlog and AllArticles render it.
Never
A rule or a box around it, since the list spaces its entries (§8); a card with a square thumbnail, which is PinnedPosts.
PropTypeUse it forNever
hrefstring · requiredThe article's route, /article/<slug>.An external URL.
titlestring | null · requiredThe article's h1, as the row holds it.null, which draws an empty heading.
datestring · requiredThe published date already formatted, as each list writes it: "October 21st 2026" on /blog, "4/12/2026" on the home.A raw ISO string.
introstring | null · requiredThe article's intro, as the row holds it. null draws an empty line and its gap.
image{ src: string; alt: string } | nullWhen the article has a cover: src its path, alt the article's title. null draws the text alone, full width.A cover with an empty alt (§9).
dateFirstboolean · default falsePuts the date above the title; for a long list read by date, as AllArticles.
clampIntroboolean · default falseCuts the intro at four lines; when the entries must stay even, as AllArticles.
Example
<ListEntry
  href="/article/open-source-ai-budgeting-app-claude-cod"
  title="I built an AI-first open-source budgeting app. It runs on top of Claude Code. Here’s how it works."
  date="4/12/2026"
  intro="A baby on the way, moving to a different country, a new job, and buying a house, all in the last 12 months. That’s why I wanted to start budgeting properly. So I looked at what was available. YNAB, Copilot, Monarch... all these are subscription-gated and cloud-dependent. None have a good free tier or great AI features."
  image={{ src: "/images/home-bg.jpeg", alt: "I built an AI-first open-source budgeting app. It runs on top of Claude Code. Here’s how it works." }}
/>

04

Nav item

An icon, a label and the orange dot when it is the current page.

Component
NavItem (default)
Import
@/app/components/NavItem in apps/app
What it is
One side nav link: the section's icon and name, dark grey and black on hover, black trailed by the orange dot when current. An external item opens in a new tab.
Use when
Inside SideNavView, which maps the app's sections to it.
Never
Outside the side nav, which SideNavView draws; more than one current at once, since one page is shown; on www, whose header links are plain text, private to Navbar.
PropTypeUse it forNever
itemItem · requiredThe section as navItems lists it: name the label, href its route, icon its name in the set, external for another app.An item that is not in navItems; the nav is the app's sections.
currentboolean · requiredTurns it black with the orange dot after it; when href is the page shown.True on two items at once.
Example
<NavItem item={{ name: "Home", href: "/", icon: "home" }} current={false} />

05

Tab

The links in the page band: dimmed, white on hover, white with the dot when current.

Design system
Component
Tab (default)
Import
@/app/components/Tab in apps/app
What it is
One link in the page band, for its black fill: white at 60% at rest, white on hover, white trailed by the orange dot when current, and a white focus ring.
Use when
Inside PageBandView, which maps a section's sub-pages to it.
Never
On the grey page, where white text does not read; more than one current at once, since one page is shown.
PropTypeUse it forNever
tabPageBandTab · requiredThe sub-page as the band lists it: name the label, href its route under the section.
currentboolean · requiredTurns it white with the orange dot after it; when href is the page shown.True on two tabs at once.
Example
<Tab tab={{ name: "Molecules", href: "/design-system/molecules" }} current />

06

Code block

Highlighted code with its copy button.

bash
Terminal
npm run dev:web
When the code has one: the language's name for the header, lowercased by it: "bash", "json".
The code as it should be copied, line breaks included.
When the code belongs to a file: its name, shown with a file icon: "Terminal", "package.json".

07

Toast

The confirmation after an action, at the bottom right: a black box, an icon in the type's colour (create, info, delete, warning), a title, a line of body, Dismiss and one link.

Client created

Dentiste Le Cézembre was added to the back office.

Changes saved

Dentiste Le Cézembre's admin details were saved.

Client deleted

Maison Orso and its files were deleted.

What happened, in two to four words, the thing first: "Client created", "Changes saved".
One sentence naming the thing and what happened to it: "Dentiste Le Cézembre was added to the back office."

08

Select

A drop-down on an input's hairline: the list hangs under it on a shade, 28px a row, the chosen ticked. Single or multiple, typed to search or not.

Website
Lets several be chosen, each a contained label with a cross in the field; the list stays open.
Lets the field be typed in to narrow the list; when the list is long.
What the empty field says, in dark grey: "Kind of work".
When inside a form: the name of the hidden inputs that carry the values.
Fades the field and stops it opening; when the value cannot change yet.
The id a Field label points at.

09

Table

A grid like a vintage spreadsheet: a hairline around every cell, the header and row numbers on a shade, every row 28px. Enums as labels, booleans as toggles, links in orange, actions as bare icons.

#FileSettled
1F-2026-04124 Oct 2026Draft€640
2F-2026-03420 Oct 2026SentPDF€2,250
3F-2026-02120 Sept 2026PaidPDF€2,250
4F-2026-01220 Aug 2026PaidPDF€1,800
5F-2026-00715 Jul 2026PaidPDF€4,500
5 bills€11,440
Component
Table
Import
ui/table
What it is
A grid like a vintage spreadsheet: a hairline around every cell, no black rule, the header, row numbers and footer on the page shaded darker. Rows 28px tall; headers left, text left, numbers right; an empty cell a grey bar.
Use when
Several things of the same shape, each with the same few facts: bills, entries, clients. Nowhere yet.
Never
A list of entries that are a heading and a text, which is a list (§8); a label and a value, which is a dl; a row that wraps, since a row never grows taller (reference/rules.md).
PropTypeUse it forNever
columnsColumn<T>[] · requiredOne per column: key, label, kind (text, number, date, boolean, tag, link), sortable, render, loud, linkLabel, truncate, narrow.
rowsT[] · requiredThe rows, each with an id; already sorted, since the page owns the order.
sortSortWhen a column is sorted: its key and dir, so the header shows it.
onSort(key: keyof T & string) => voidRuns when a sortable header is pressed; the page flips or changes sort and re-sorts with sortRows.
headerboolean · default trueDraws the header row; false for a two-column sheet whose labels are obvious.
numberedboolean · default falseAdds a # column at the left; when rows are counted or referred to.With selectable.
selectable{ selected: Set<string>; onToggle: (id: string) => void; onToggleAll: () => void }When rows are picked for an action: selected the ids ticked, onToggle flips one, onToggleAll ticks or clears every row.
footerPartial<Record<keyof T & string, ReactNode>>When the table has a total or a count: a last row in black, one entry per column it fills.A second footer.
emptystring · default "Nothing yet."What the table says with no rows: "No bills yet."
classNamestringWidth or space around it: lg:w-[320px].A rule, a fill or a radius (§8).
Example
<Table
  columns={[
    { key: "number", label: "Bill" },
    { key: "dated_on", label: "Date", kind: "date", sortable: true },
    { key: "state", label: "State", kind: "tag", loud: ["Sent"] },
    { key: "amount", label: "Amount", kind: "number" },
  ]}
  rows={bills}
  footer={{ number: "5 bills", amount: "€11,440" }}
/>
Component
CellAction
Import
ui/table
What it is
An action inside a table cell: the bare 14px Icon, dark grey, black on hover, no plate, faded when disabled. Named by its label, which is its aria-label and its tooltip.
Use when
A row's own action in a Table: remove, open. Nowhere yet.
Never
Outside a table cell, which is IconButton or Button; a word beside the icon, since a cell action is an icon alone (reference/rules.md).
Native props
every <button> prop passes through.
PropTypeUse it forNever
iconIconName · requiredThe sign: minus to remove, close, copy.An icon the set lacks, which is an entry in the set (§10).
labelstring · requiredWhat it does, as the accessible name and the tooltip: "Remove".A sentence.
classNamestringWhere it sits.A colour or a size.
disabledboolean · nativeFades the icon and stops it responding; when the action cannot run yet.To hide an action, which is taken out instead.
Example
<CellAction icon="minus" label="Remove" />