The kit: built-in parts
The kit is a set of ready-made parts (buttons, rows, fields, switches, empty and error states) that look right in any theme, in light and dark, and are accessible from the start. Import the ones a page uses:
import { Button, ListRow, Section, TextField } from "@duolith/kit";
Then place them like any component:
<Section title="Account">
<ListRow title="Email" value="ada@example.com" icon="mail" chevron href="/email" />
</Section>
<TextField label="Name" bind:value={name} error={nameError} />
<Button label="Save" icon="check" loading={saving} onPress={save} />
The runnable gallery, with every part, variant, size and state, is examples/kit, and for the pickers, filters, tabs and media, examples/inputs-and-media:
duolith dev examples/kit --port 4400
duolith dev examples/inputs-and-media --port 4401
Parts are .duo components (in packages/kit/parts/) built into the duolith command, so there is nothing to install, and a build includes only the parts a project imports. Each part's full specification (props, pieces, states, accessibility, tokens) is in spec/kit/<part>.yaml. Decisions: 0028 (the kit), 0029 (the language features below), 0030 (icons), 0034 to 0036 (overlays and toasts), 0037 (keys and Tab stops), 0038 (the image cache), 0039 (chips and zoom), 0040 and 0041 (the navigation parts), 0042 (the public folder).
The parts
| Family | Part | What it is |
|---|---|---|
| Buttons | Button | label, variant (primary, secondary, ghost, danger), size (sm, md, lg), icon, iconEnd, loading, disabled, full, submit, onPress |
IconButton | icon and label (required: it is the accessible name), variant, size, selected for a button that stays on, disabled, onPress | |
| Lists and cards | ListRow | title, subtitle, value, icon, chevron, destructive, disabled; a button with onPress, a link with href; pieces leading and trailing |
Section | rows on one surface with lines between them; title, footer, action with onAction | |
Card | title, subtitle, flat, onPress (the whole card is one button); piece media | |
Avatar | name (initials and accessible name), src, size (sm, md, lg, xl), status (online, away, offline) | |
Badge | label, tone (neutral, primary, success, danger), solid, icon | |
Divider | a line; label, inset, vertical | |
| Inputs | TextField | label, bind:value, placeholder, hint, error, type, icon, disabled, onChange |
TextArea | label, bind:value, placeholder, hint, error, rows, limit (shows a count), disabled | |
| Selection | ToggleRow | label, hint, icon, bind:checked, disabled, onChange |
Checkbox | label, hint, bind:checked, disabled; pressing the label ticks it | |
RadioGroup | label, options ({ value, label, hint? }[]), bind:value, disabled | |
SegmentedControl | label, options ({ value, label, icon? }[]), bind:value, disabled | |
Slider | label, bind:value (a number), min, max, step, unit, disabled | |
Chip | label, bind:selected, icon, disabled, onPress (decides instead of flipping) | |
ChipGroup | label, options ({ value, label, icon? }[]), bind:value (the chosen value), multiple with bind:values (the chosen list), disabled | |
| Pickers | DatePicker | an inline month: label, bind:value (ISO date such as "2026-11-14"), min, max, disabledDates (a list or a function), locale, disabled |
TimePicker | label, bind:value ("HH:MM", 24-hour), step (minutes), locale (12 or 24 hours and AM/PM words), disabled | |
Stepper | a number with − and +: label, bind:value, min, max, step, unit, disabled | |
| Search and tabs | SearchField | label, bind:value, placeholder, disabled, onSubmit; a clear button, Escape empties it |
Tabs | in-page tabs (not the app's tab bar): label, tabs ({ value, label, icon?, disabled? }[]), bind:selected; children are the panel | |
| Media | Image | src, alt or decorative, ratio (1:1, 4:3, 3:2, 16:9, 3:4, 2:3), fit (cover, contain), placeholder, radius, lazy, zoomable; piece fallback |
ImageViewer | full screen and zoomable: src, alt, bind:open | |
| Feedback | Skeleton | a loading placeholder: shape (line, circle, block), lines, width, size, label |
Spinner | size, label; takes the text colour around it | |
ProgressBar | value from 0 to 1 (none while unknown), label, showValue, tone | |
EmptyState | title, message, icon, action with onAction | |
ErrorState | title, message, icon, retry label, retrying, onRetry | |
| Navigation | TabBar | the bar of tabs at the bottom of a layout; label, rail (a column at the leading edge in a large window) |
TabBarItem | label, icon, href, badge (a count, shown above 0), exact, current (overrides the matching); current while the route is at href or below it | |
NavHeader | the bar at the top of a screen: title, large, showBack, onBack, up and upTitle; a back button when the screen was pushed, an up button when there is nothing to go back to; pieces leading and trailing | |
Toolbar | a row of actions with one Tab stop; label, flat | |
Breadcrumbs | items ({ label, href? }[]), the last the current page; label | |
Link | a text link; href, external, muted; marks http and https links to other sites | |
| Overlays | Sheet | title, bind:open, bind:detent (medium, large); piece trigger; children scroll. Drag the handle between detents or down to dismiss; from the side on a wide window |
Dialog | title, message, bind:open, dismissible; pieces trigger and actions; children are the body | |
AlertDialog | title, message, confirmLabel, cancelLabel, destructive, bind:open, onConfirm, onCancel; piece trigger | |
Menu | label, items ({ label, icon?, destructive?, disabled?, onSelect? } or { divider: true }), bind:open, placement; piece trigger | |
Popover | label, bind:open, placement; piece trigger; children are its content | |
Tooltip | text, placement (top, bottom, left, right); wraps the control it describes | |
Toast | the toast region, placed once: position (bottom, top), label. Show toasts with toast() from @duolith/client | |
Select | label, options ({ value, label }[]), bind:value, placeholder, disabled | |
ActionSheet | title, actions ({ id, label, destructive? }[]), bind:open, cancel, onChoose; piece trigger | |
| More | Accordion | sections ({ id, title, body }[]), bind:open (the open ids), multiple; each heading says expanded or collapsed |
Banner | title, message, tone (info, success, danger: an alert), action with onAction, onDismiss | |
Pager | one page at a time: label, pages ({ title, body?, image? }[]), bind:page; previous, next, a dot per page, and a swipe left or right | |
Pagination | pages, bind:page (from 1), label; the pages near the current one, marked current | |
Rating | label, bind:value, max, readonly; a radio group of stars | |
ProgressRing | value from 0 to 1, label, size (sm, md, lg) | |
Combobox | label, options, bind:value, placeholder, onChoose; suggests what matches as the user types, in a listbox the arrow keys reach | |
ChipInput | label, bind:values, placeholder; Enter adds a chip, each chip has a remove button | |
DataTable | label, columns ({ key, label, sortable?, numeric? }[]), rows, bind:sort, bind:descending; a table whose headers say how it is sorted | |
FileInput | label, bind:files ({ name, size? }[]), icon, onPick (call the media-picker effect there) | |
Fab | the floating action button: label, icon, extended, onPress | |
| Gestures | SwipeRow | label, actions ({ id, label, destructive? }[]), bind:open, onAction; a swipe left shows the actions, and its More button does too |
PullToRefresh | onRefresh (may return a promise), bind:refreshing, label; a pull down from the top, or its Refresh button, refreshes | |
Drawer | title, bind:open; piece trigger; a modal panel from the start edge, closed by Escape, the scrim, Close or a swipe left | |
DateRangePicker | label, bind:start, bind:end, min, max, disabledDates, locale, disabled; DatePicker's grid choosing a start, then an end |
The gesture parts hear on:swipe (decision 0121), which you can put on any <view>: on:swipe={(event) => ...} receives event.direction, one of left, right, up and down. A swipe down counts only from the top of what scrolls around the view. Give every swipe another way to do the same thing, such as a button, because a keyboard and a screen reader cannot swipe.
A misspelt import is caught at build time: import { Buton } from "@duolith/kit" is E0123, "Did you mean Button?". Import parts by name: import kit from "@duolith/kit" and import * as kit from "@duolith/kit" are E0129.
Binding a part to state
Fields, switches and pickers bind both ways, like the elements inside them:
---
import { state } from "@duolith/client";
import { RadioGroup, Slider, TextField, ToggleRow } from "@duolith/kit";
let email = state("");
let notifications = state(true);
let plan = state("monthly");
let volume = state(40);
const plans = [
{ value: "monthly", label: "Monthly", hint: "£4 a month" },
{ value: "yearly", label: "Yearly", hint: "£40 a year" },
];
---
<TextField label="Email" type="email" bind:value={email} />
<ToggleRow label="Notifications" bind:checked={notifications} />
<RadioGroup label="Plan" options={plans} bind:value={plan} />
<Slider label="Volume" unit="%" bind:value={volume} />
Leave the binding out and the part keeps its own value, starting from value="..." if you pass one.
Your own components can do the same: declare the prop with a bindable(...) default, and bind it inside.
components/Search.duo
---
import { bindable, props } from "@duolith/client";
let { query = bindable("") } = props<{ query?: string }>();
---
<input type="search" bind:value={query} />
Only bindable props can be bound (E0108) or assigned by the component (E0114). Passed one way instead (<TextField value={name} />), the part keeps what is typed as its own until name changes, and then shows the new value.
Leading and trailing content: pieces
ListRow shows children at its trailing edge. To put something before the title, or to be explicit, give it in a piece:
<ListRow title="Ada Lovelace" subtitle="Online now" onPress={openChat}>
<piece name="leading"><Avatar name="Ada Lovelace" status="online" /></piece>
<piece name="trailing"><Badge label="New" tone="primary" /></piece>
</ListRow>
Card has a media piece for full-bleed content above its title. A component of your own offers a piece by writing <slot name="leading" />. A piece the component does not show is E0127; the same piece given twice is E0128; <piece> anywhere but directly inside a placed component is E0126.
Overlays: sheets, dialogs, menus, popovers, tooltips, toasts and select
Overlay parts show above the screen. Open one from state with bind:open, or give it the control that opens it in a trigger piece; that control is told whether the overlay is open, and focus goes back to it when the overlay closes.
---
import { state, toast } from "@duolith/client";
import { AlertDialog, Button, Dialog, IconButton, Menu, Select, Sheet, TextField, Toast, Tooltip } from "@duolith/kit";
let editing = state(false);
let confirming = state(false);
let name = state("Ada");
let country = state("gb");
const countries = [{ value: "fr", label: "France" }, { value: "gb", label: "United Kingdom" }];
const actions = [
{ label: "Edit", icon: "edit", onSelect: () => (editing = true) },
{ divider: true },
{ label: "Delete", icon: "trash", destructive: true, onSelect: () => (confirming = true) },
];
---
<Menu label="Post actions" items={actions}>
<piece name="trigger"><IconButton icon="more" label="More" /></piece>
</Menu>
<Dialog title="Edit name" bind:open={editing}>
<TextField label="Name" bind:value={name} />
<piece name="actions"><Button label="Save" onPress={() => { editing = false; toast("Saved"); }} /></piece>
</Dialog>
<AlertDialog title="Delete this post?" confirmLabel="Delete" destructive bind:open={confirming}
onConfirm={() => toast("Deleted", { action: { label: "Undo", onPress: undo } })} />
<Sheet title="Share"><piece name="trigger"><Button label="Share" /></piece>...</Sheet>
<Tooltip text="Add to favourites"><IconButton icon="star" label="Favourite" /></Tooltip>
<Select label="Country" options={countries} bind:value={country} />
<Toast />
toast(message, { tone, action, duration }) comes from @duolith/client and can be called from any script; place <Toast /> once on the page to show them (decision 0036). Tones are neutral, success and danger; a toast goes after 5 seconds (8 with an action), at most three show at once and the rest wait, and they pause while the pointer or focus is on them. Swipe one sideways to dismiss it.
The runnable gallery, every overlay open in each state, light and dark, is examples/overlays.
| Part | What assistive technology hears | Keyboard and focus |
|---|---|---|
| Sheet, Dialog | a modal dialog named by its title | focus moves to its first control; Tab stays inside; the page behind is inert and does not scroll; Escape (and the backdrop) close it; focus returns to the trigger |
| AlertDialog | an alertdialog, described by its message | focus starts on Cancel, the safe choice; Escape cancels; the backdrop does nothing |
| Menu | a menu of menu items; its trigger has aria-haspopup="menu" and aria-expanded | ArrowDown/ArrowUp (wrapping), Home, End, a letter jumps to the next item starting with it; Enter chooses; Escape or Tab closes; ArrowDown on the trigger opens it |
| Popover | a dialog that is not modal | focus moves in; a press outside or Escape closes it |
| Tooltip | the control is described by the tooltip's text | shows 500 ms after hover or focus; Escape hides it |
| Toast | a polite live region; error toasts are alerts | never takes focus; its buttons are reachable with Tab |
| Select | a combobox that opens a listbox; each option selected or not | Enter, Space or ArrowDown opens it on the chosen option; arrows, Home, End and letters move; Enter chooses; Escape closes without choosing |
These parts are built on one element, <overlay kind="...">, which your own components can use too (decision 0034): kind is dialog, sheet, popover, menu, listbox, tooltip or toasts; open={...} shows it; anchor={id} names the element it belongs to (needed by the anchored kinds, E0151) and placement (top, bottom, with -start or -end, or left, right) where it sits, flipping and shifting to stay on screen; on:dismiss runs when the person asks to close it, and the overlay closes when you set open to false; on:detent runs when a sheet is dragged to another detent. An unknown or empty kind is E0150, a missing or empty anchor E0151, a placement E0152, a detent E0153, and an attribute written twice E0154.
Variants and conditional classes
A part's variants are props, and the part turns them into classes with class:name={condition}, which you can use in your own files too:
<button
class="row items-center gap-2 p-3 rounded-md"
class:bg-primary={variant === "primary"}
class:text-on-primary={variant === "primary"}
class:chosen={isChosen}
>
The name is one utility (prefixes allowed, such as class:pressed:opacity-75) or a class from the file's style block. It applies while the condition holds, and wins over the element's class where the two disagree.
Navigation parts
The navigation parts sit on the router (see navigation): tabs are links, and the header's back button calls back(). The runnable example is examples/navigation-kit, a small app with every part, light and dark, with the tab bar as a rail on a wide window.
A tab bar goes in a layout, so it stays while the screens inside it change:
pages/_layout.duo
---
import { state } from "@duolith/client";
import { TabBar, TabBarItem } from "@duolith/kit";
let unread = state([1, 2, 3], { shared: "unread" });
---
<view class="lg:row">
<slot />
<TabBar rail>
<TabBarItem label="Home" icon="home" href="/" />
<TabBarItem label="Inbox" icon="inbox" href="/inbox" badge={unread.length} />
<TabBarItem label="Settings" icon="settings" href="/settings" />
</TabBar>
</view>
Each item is current while the route is at its href (without its query, fragment or trailing slash) or below it (/inbox/7 keeps Inbox current); exact limits that to href itself, and / is always matched exactly. A tab that owns routes elsewhere says so with current={route().path.startsWith("/post/")}. rail turns the bar into a column at the leading edge from 1024px wide; the view around it must then be lg:row, as above. The bar keeps clear of the home indicator (env(safe-area-inset-bottom)).
Each screen starts with its header:
<screen title="Message">
<NavHeader title="Message">
<piece name="trailing"><IconButton icon="trash" label="Delete" onPress={remove} /></piece>
</NavHeader>
...
</screen>
The back button appears by itself when the screen was pushed from another one, showing that screen's title ("‹ Inbox", named "Back to Inbox"). The first screen of a visit, a screen opened from its address and a screen a tab opened have none. Your own markup can ask the same thing with canGoBack() and backTitle() from @duolith/client. A screen opened from its address has nothing to go back to; give it up="/inbox" upTitle="Inbox" and it shows "‹ Inbox" there instead, replacing the screen with its parent. large puts a big title under the bar, which scrolls away under it while the bar's title fades in; showBack={false} never shows the button, and onBack runs instead of back().
<Toolbar label="Message actions">
<IconButton icon="send" label="Reply" onPress={reply} />
<IconButton icon="star" label="Star" selected={starred} onPress={toggleStar} />
</Toolbar>
<view class="hidden lg:flex">
<Breadcrumbs items={[{ label: "Library", href: "/library" }, { label: "Travel" }]} />
</view>
<Link href="/settings">Settings</Link>
<Link href="https://example.com/terms">Terms</Link>
Theming
Parts use only theme tokens: colours such as primary, surface, raised, ink, muted, danger and success, the radius and space scales, and the text styles. Change them in your project's theme.yaml and every part follows, in light and dark (see styling). A part never uses a literal colour; pnpm check enforces it.
Each part also reads tokens of its own, var(--part-<part>-<token>), declared under look: in its spec with a value for each platform look where they differ. A theme changes them under parts:, and look: platform picks the iOS or Material values (see styling). A test checks that every token a part reads is declared, and every declared one is read.
TextField passes autocomplete to its field, so <TextField label="Password" type="password" autocomplete="current-password" /> lets the browser, iOS and Android offer the saved password. Android has no autofill hint for nickname, organization, organization-title, cc-name or url, so a native build refuses them (E0519); the web build takes them.
Accessibility
| Part | What assistive technology hears | Keyboard |
|---|---|---|
| Button, IconButton | a button named by its label; selected makes IconButton a toggle (pressed or not) | Tab to reach, Enter or Space to press; disabled ones are skipped |
| ListRow | a button with onPress, a link with href, otherwise plain text; a disabled row is never a link and is marked disabled | the same; disabled rows are skipped |
| TextField, TextArea | a text field named by its label and described by its error, or else its hint; error marks it invalid and announces the message | Tab |
| ToggleRow, Checkbox | a switch or a checkbox named by its label and described by its hint | Space flips it |
| RadioGroup, SegmentedControl | a radio group named by its label, each option a radio, checked or not | one Tab stop, on the chosen option (or the first); arrow keys move and choose, wrapping at the ends |
| Slider | a slider named by its label | arrow keys, Home, End |
| Spinner, ProgressBar | a status, a progress bar | none |
| ErrorState | an alert, announced when it appears | Tab to the retry button |
| Chip, ChipGroup | toggle buttons (pressed or not) in a group named by its label | each chip a Tab stop; Enter or Space flips it |
| DatePicker, DateRangePicker | a grid named by the label and month; each day a gridcell named by its full date, the chosen one selected (DateRangePicker: the start, the end and the days between, named "…, start", "…, end" or "…, in range", with a status reading the range) | one Tab stop, on the focused day; arrows move a day or a week, Home and End to the week's ends, PageUp and PageDown a month, skipping days that cannot be chosen; Enter or Space chooses |
| TimePicker, Stepper | spinbuttons with their value, minimum, maximum and value text; AM and PM a radio group | arrows step, PageUp and PageDown step further, Home and End to the ends; the − and + buttons are not Tab stops |
| SearchField | a search landmark holding a search box | Enter submits, Escape empties |
| Tabs | a tab list of tabs (selected or not, each controlling the panel) over a tab panel | one Tab stop on the chosen tab; arrows show the next or previous tab, wrapping and skipping disabled ones; Home, End |
| Skeleton | nothing, or with label a status that announces it | none |
| Image, ImageViewer | an image named by alt (decorative ones are skipped); the viewer a dialog | a zoomable Image is a button; the viewer takes focus, keeps Tab inside, closes with Escape and gives focus back |
| TabBar, TabBarItem | a navigation landmark named Tabs; each tab a link, the current one aria-current="page", named "Inbox, 3 new" with a badge | Tab to each tab, Enter follows |
| NavHeader | a banner holding the title as a heading; the back button named Back or "Back to Settings" | Tab to the back button and the actions |
| Toolbar | a toolbar named by its label | one Tab stop (the control used last, or the first); arrow keys move without pressing, wrapping, Home and End go to the ends, disabled controls are skipped; keys with a modifier and caret keys in a text field are left alone |
| Breadcrumbs | a navigation landmark named Breadcrumb; the last item aria-current="page" and not a link; a crumb for the screen before goes back to it | Tab to each link |
| Link | a link; an http or https one to another site adds "opens another site" | Tab, Enter |
| Combobox | a combobox (the field) controlling a listbox of options, aria-expanded while it shows | typing keeps focus in the field; ArrowDown and ArrowUp move into the options, Enter chooses and returns to the field, Escape closes and stays in it |
| DataTable | a table of rows, column headers and cells; each sortable header has aria-sort, its button named "Sort by Name" | Tab to each sort button, Enter or Space sorts, then reverses |
| SwipeRow | a group named by its label; the More button says whether the actions are expanded; each action a button | Tab to More, Enter shows the actions, each then a Tab stop |
| PullToRefresh | a Refresh button, and a status that says Refreshing | Tab to Refresh, Enter refreshes |
| Drawer | a modal dialog named by its title | focus moves in and stays; Escape closes it and gives focus back to the trigger |
Every focusable part shows a 2px outline in the primary colour when reached by keyboard.
These come from three small language features you can use anywhere: role (one of group, radio-group, radio, status, alert, heading, image, separator, navigation, banner, toolbar, alert-dialog, menu-item, option, combobox, table, cell, and the words under "Keys and Tab stops" below; E0124 otherwise), selected={...}, sorted (ascending, descending or none, on a column header), invalid and described-by={id} (with id), plus label and disabled. A view with role="radio-group" gets the one Tab stop and arrow keys by itself, and so does a view with role="toolbar" (moving focus without choosing).
Keys and Tab stops in your own files
The pickers and tabs are built from two small features you can use too (decision 0037). on:key={(event) => ...} hears the navigation keys (arrows, Home, End, PageUp, PageDown, Escape) on an element or inside it, and the key does nothing else. tab-stop={condition} makes an element its group's one Tab stop, or with no value makes a view focusable. After an on:key handler, focus moves to the element's Tab stop, so you move focus by changing state:
<view role="tab-list" label="Sections" on:key={(event) => move(event.key)}>
<list each={tabs} as="tab" key={tab.value}>
<button role="tab" selected={tab.value === chosen} tab-stop={tab.value === chosen}>{tab.label}</button>
</list>
</view>
A spinbutton takes value-now, value-min, value-max and value-text; a tab points at its panel with controls={id}. The role words grew: search, grid, row, gridcell, column-header, tab-list, tab, tab-panel, spinbutton, dialog.
Images
An <image> (and the Image part) needs alt, saying what it shows, or decorative when it adds nothing for a screen reader user (E0160). Every address is fetched and decoded once for the whole app, however many images show it (decision 0038): the first one shows its placeholder colour and fades in from a blur, and later ones, on any screen, appear at once. lazy waits until the image is near the screen; on:load and on:error say how it went, which is how Image shows its fallback piece:
<Image src="/photos/lake.svg" alt="A lake below mountains" ratio="16:9" placeholder="#7fa7bd" zoomable>
<piece name="fallback"><icon name="image" /></piece>
</Image>
zoomable on an image gives it pinch, wheel and double-tap zoom and panning; <Image zoomable> opens it full screen in an ImageViewer (decision 0039). On a plain <image>, decorative={...} and zoomable={...} follow their condition, and zoomable={false} is not zoomable. placeholder is one of the theme's colour names, such as raised, or any CSS colour.
Put an app's own images in public/ (public/photos/lake.jpg is /photos/lake.jpg): any file is copied as it is, PNG and JPEG as well as SVG, leaving out names that start with a dot and symbolic links. A public file cannot take a path the build writes, such as index.html or anything under _duolith/ (E0161, decision 0042). Files in public/ are served from the app's own origin, so an SVG opened directly can run script as the app: only put SVG files there that you trust like your own code.
Icons
<icon name="chevron-right" /> draws an icon from the built-in set in spec/kit/icons.yaml, in the colour of the text around it, 1.25em square unless utilities size it (w-6 h-6). It is hidden from screen readers unless you give it a label. Parts take icon names as props, such as <Button icon="plus" />. A name written as text is checked at build time (E0125, with a suggestion).
alert, arrow-left, arrow-right, arrow-up-right, bell, bookmark, calendar, camera, check, check-circle, chevron-down, chevron-left, chevron-right, chevron-up, clock, close, copy, download, edit, eye, filter, globe, heart, home, image, inbox, info, link, location, lock, mail, menu, minus, moon, more, phone, plus, refresh, search, send, settings, share, star, sun, trash, upload, user, users, wifi, wifi-off.
New elements
The kit is built from the language's own elements, and needed four new ones, which pages can use directly: textarea (several lines, bind:value, rows), checkbox (bind:checked), slider (min, max, step, bind:value gives a number) and progress (value from 0 to 1, or none while unknown). Each is the platform's real control.