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.
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.
h1an app page,h2a portal page,h3a login. - One line of plain text: what the page lets you do, said to the person.
- Component
TextPairing- Import
ui/text-pairing- What it is
- The top of a page or a form: an uppercase dark grey eyebrow, the page's
<h1>in black, and a dark grey line under it, set tight. 60ch wide, no outer spacing. - Use when
- The header of an app page, or of a form standing alone.
/narrator,/snakeand/loginuse it. - Never
- A second one on a page, since it holds the
<h1>; a section heading inside a page, which is anH2orH3.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| eyebrow | string | When the page belongs to a family: a category word over the title, set uppercase by it: "Open source". | More than three words. |
| title | string · required | The page's name, one to four words: "Claude Narrator", "Client space". | A sentence or a question; a page has a name. |
| size | "h1" | "h2" | "h3" | "h4" · default "h1" | The title's step; eyebrow, line and gaps grow with it. h1 an app page, h2 a portal page, h3 a login. | A section heading, which is an H2 or H3. |
| className | string | Space below it: mb-horizontal-padding-heading. | Width or type; the 60ch and the scale are its own. |
- Children
ReactNode. One line of plain text: what the page lets you do, said to the person. Never: a heading, a list or a second paragraph; a page that needs more has a section for it.
- Example
<TextPairing eyebrow="Open source" title="Claude Narrator"> Hear what a Claude Code session is doing, out loud, while you do something else. </TextPairing>
import { TextPairing } from "ui/text-pairing";
<TextPairing eyebrow="Open source" title="Claude Narrator">
Hear what a Claude Code session is doing, out loud, while you do something else.
</TextPairing>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.
- Component
Field- Import
ui/field- What it is
- A control with its label above it in dark grey,
horizontal-padding-labelapart. - Use when
- Every labelled control in a form.
/loginand/unlockuse it. - Never
- A checkbox, whose label sits beside it; a
<fieldset>'s title, which is a<legend>; a label in black, since a label is dark grey (§8).
| Prop | Type | Use it for | Never |
|---|---|---|---|
| label | ReactNode · required | The field's name, one to three words, as a person says it: "Email", "Password". | A sentence or a question; the placeholder carries a sample. |
| id | string | When the control cannot sit inside the label, as one a library renders: the control's id, so the label points at it. | |
| className | string | Space around it, or a width: max-w-[400px]. | A box or a fill (§8). |
- Children
ReactNode· required. The control the label names: anInput, atextareawith thefieldclass, or aselect. One control. Never: a checkbox, whose label sits beside it; a group of fields, which is a<fieldset>.
- Example
<Field label="Email"> <Input type="email" name="email" placeholder="name@example.com" /> </Field>
import { Field } from "ui/field";
<Field label="Email">
<Input type="email" name="email" placeholder="name@example.com" />
</Field>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
H3title, a dark greyPXSmalldate and aPSmallintro 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.
SectionBlogandAllArticlesrender 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.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| href | string · required | The article's route, /article/<slug>. | An external URL. |
| title | string | null · required | The article's h1, as the row holds it. | null, which draws an empty heading. |
| date | string · required | The published date already formatted, as each list writes it: "October 21st 2026" on /blog, "4/12/2026" on the home. | A raw ISO string. |
| intro | string | null · required | The article's intro, as the row holds it. null draws an empty line and its gap. | |
| image | { src: string; alt: string } | null | When 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). |
| dateFirst | boolean · default false | Puts the date above the title; for a long list read by date, as AllArticles. | |
| clampIntro | boolean · default false | Cuts 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." }} />
import { ListEntry } from "@/app/components/ui/list-entry";
<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/NavItemin 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
SideNavViewdraws; more than onecurrentat once, since one page is shown; on www, whose header links are plain text, private toNavbar.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| item | Item · required | The 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. |
| current | boolean · required | Turns 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} />
import NavItem from "@/app/components/NavItem";
<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.
- Component
Tab(default)- Import
@/app/components/Tabin 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
currentat once, since one page is shown.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| tab | PageBandTab · required | The sub-page as the band lists it: name the label, href its route under the section. | |
| current | boolean · required | Turns 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 />
import Tab from "@/app/components/Tab";
<Tab tab={{ name: "Molecules", href: "/design-system/molecules" }} current />06
Code block
Highlighted code with its copy button.
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".
- Component
CodeBlock- Import
ui/code-block- What it is
- The code panel, shaded black at 13% over the grey with a hairline around it: a darker header band with the language, the file name and a copy button, the code under it scrolling sideways. No outer spacing.
- Use when
- Showing code or a command outside an article.
BlockCodeand/narratordraw theirs with it. - Never
- Inside an article's body directly, which is
BlockCode; wrapped text, since a command must stay copyable. - Deviates
- A hairline around the panel and a rule under its header (§8); reuse it, do not copy either.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| language | string | When the code has one: the language's name for the header, lowercased by it: "bash", "json". | |
| code | string · required | The code as it should be copied, line breaks included. | |
| filename | string | When the code belongs to a file: its name, shown with a file icon: "Terminal", "package.json". |
- Example
<CodeBlock code="npm run dev:web" language="bash" filename="Terminal" />
import { CodeBlock } from "ui/code-block";
<CodeBlock code="npm run dev:web" language="bash" filename="Terminal" />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.
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."
- Component
Toast(default)- Import
@/app/components/Toastin apps/app- What it is
- Client. The confirmation after an action: a square black box, no shadow, an icon in the type's colour, a white title, a light line of body, then Dismiss and one link, and a close cross.
- Use when
- Through the toast provider's
showToast({ type, title, body, link })after an action saves, creates or deletes something./backoffice/json-generatoruses it. - Never
- Placed by hand on a page, since the provider places it at the bottom right; for a field's error, which belongs beside the control; a question that waits for an answer, which is the side panel or an in-place confirm.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| type | ToastType · default "info" | info when it only tells, as "Changes saved"; create for a thing created; delete for one deleted; warning when something needs attention. | A colour chosen for looks; the type is what happened (§2). |
| title | string · required | What happened, in two to four words, the thing first: "Client created", "Changes saved". | A sentence with a full stop; the body is the sentence. |
| link | ToastLink | When there is one place to go next: label the words, as "View client"; href the page. | Two links; a link back to the page already open. |
| onDismiss | () => void | Closes it; set by the toast provider. Without it there is no Dismiss and no cross. | Undo, which is an action and not a dismissal. |
- Children
ReactNode. One sentence naming the thing and what happened to it: "Dentiste Le Cézembre was added to the back office." Never: a second sentence; a list; a repeat of the title.
- Example
<Toast type="create" title="Client created">Dentiste Le Cézembre was added to the back office.</Toast>
import Toast from "@/app/components/Toast";
<Toast type="create" title="Client created">
Dentiste Le Cézembre was added to the back office.
</Toast>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.
- 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
Fieldlabel points at.
- Component
Select- Import
ui/select- What it is
- Client. A drop-down: a field with one hairline underneath, the chosen value in black or the placeholder in dark grey, a chevron at the right; the list hangs under it, shaded darker, 28px a row, the chosen rows ticked.
- Use when
- Choosing one or several from a known list: a client's kinds of work, a bill's state, a unit. Nowhere yet.
- Never
- Two or three choices that fit on one line, which are radios; free text, which is an
Input; a list of dozens withoutsearchable; inside aFieldwithout giving both the sameid, since a<label>passes every pick on to the first chip's cross.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| options | SelectOption[] · required | The choices in the order shown, each a value and a label. | |
| value | string[] · required | The chosen values; one at most without multiple. | |
| onChange | (value: string[]) => void · required | Runs on every choice or removal with the new values; the page keeps them. | |
| multiple | boolean · default false | Lets several be chosen, each a contained label with a cross in the field; the list stays open. | |
| searchable | boolean · default false | Lets the field be typed in to narrow the list; when the list is long. | |
| placeholder | string · default "Choose" | What the empty field says, in dark grey: "Kind of work". | A sentence. |
| name | string | When inside a form: the name of the hidden inputs that carry the values. | |
| disabled | boolean · default false | Fades the field and stops it opening; when the value cannot change yet. | To hide a field, which is taken out instead. |
| className | string | Width or space around it: max-w-[400px]. | A border, a fill or a radius (§8). |
| id | string | The id a Field label points at. |
- Example
<Select options={work} value={chosen} onChange={setChosen} multiple placeholder="Kind of work" />
import { Select } from "ui/select";
<Select options={work} value={chosen} onChange={setChosen} multiple placeholder="Kind of work" />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.
- 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).
| Prop | Type | Use it for | Never |
|---|---|---|---|
| columns | Column<T>[] · required | One per column: key, label, kind (text, number, date, boolean, tag, link), sortable, render, loud, linkLabel, truncate, narrow. | |
| rows | T[] · required | The rows, each with an id; already sorted, since the page owns the order. | |
| sort | Sort | When a column is sorted: its key and dir, so the header shows it. | |
| onSort | (key: keyof T & string) => void | Runs when a sortable header is pressed; the page flips or changes sort and re-sorts with sortRows. | |
| header | boolean · default true | Draws the header row; false for a two-column sheet whose labels are obvious. | |
| numbered | boolean · default false | Adds 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. | |
| footer | Partial<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. |
| empty | string · default "Nothing yet." | What the table says with no rows: "No bills yet." | |
| className | string | Width 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" }} />
import { Table } from "ui/table";
<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 itslabel, which is itsaria-labeland its tooltip. - Use when
- A row's own action in a
Table: remove, open. Nowhere yet. - Never
- Outside a table cell, which is
IconButtonorButton; a word beside the icon, since a cell action is an icon alone (reference/rules.md). - Native props
- every
<button>prop passes through.
| Prop | Type | Use it for | Never |
|---|---|---|---|
| icon | IconName · required | The sign: minus to remove, close, copy. | An icon the set lacks, which is an entry in the set (§10). |
| label | string · required | What it does, as the accessible name and the tooltip: "Remove". | A sentence. |
| className | string | Where it sits. | A colour or a size. |
| disabled | boolean · native | Fades 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" />
import { CellAction } from "ui/table";
<CellAction icon="minus" label="Remove" />