The barrels
The eighteen sub-barrels of the design system, what is in each, and the four rules that keep a vendored copy working.
Every name in the design system reaches you through ~ui, which resolves to packages/ui/src in
this repository and to src/vendor/ui in a scaffolded app — the same import either way, for the
reason vendoring explains.
The eighteen barrels
| Barrel | What is in it | Some of what it exports |
|---|---|---|
primitives | The small pieces every screen is built from. | Button, Input, Avatar, Card, Alert, Badge, Tag, Kbd, Progress, Skeleton, EmptyState, Markdown, CodeBlock |
shell | App chrome: the frame a standalone app draws around a module. | AppShell, Topbar, NavRail, SideNav, UserMenu |
layout | The house layouts a module composes inside that frame. | ModuleRoot, useBand, PageHeader, PageBody, Toolbar, SplitPane, InspectorHost, Island, FloatingDock, AuthLayout |
chat | A thread and the things in it, plus the assistant half — what a model is doing, as opposed to what it said. | MessageList, MessageBubble, Composer, ConversationListItem, ThreadHeader, AttachmentGallery, RunStep, RunGroup, StreamingText, VoiceRecorder, TestChat |
forms | Controls and their labelling. | Field, FormField, Select, Combobox, Checkbox, Switch, RadioGroup, SegmentedControl, Textarea, PasswordInput, DateField, TimeInput, DurationInput, TimezoneSelect, ChipInput, FileDrop, CopyField, FilterRow |
data | Rows, cells and the numbers over them. | DataTable, DataTableColumn, DataTableEdit, DataCards, StatTile, StackedMeter, JsonView, MediaGrid |
feedback | What the app says back. | ToastProvider, useToast, ActionBar, BulkProgress |
overlay | Surfaces that cover the page. | Dialog, Drawer, Overlay, Portal |
nav | Moving inside a module. | Tabs, Breadcrumbs, Pagination, Stepper, Collapsible |
dnd | Pointer-events drag with a keyboard twin and announcements. | useDragSession, useGridDragSession, DragLayer |
lib | The headless layer: pure functions grouped by domain — geometry, time, chat, data, interaction, app, markdown. A lib module absent from the barrel is package-internal on purpose. | bandFor, bandAtLeast, filterItems, nextSortState, parseMarkdown, packLanes, parseHotkey, csvText, screenToWorld |
canvas | A pannable, zoomable scene and the things that float over it. | Canvas, CanvasNode, CanvasHandle, CanvasEdges, CanvasToolbar, CanvasMinimap, CanvasPalette, useCanvas, useCanvasSelection |
calendar | Time as a grid, and the shapes on it. | TimeGrid, MonthGrid, MiniCalendar, AgendaList, EventChip, WeekHoursEditor, ResourceHeader |
floating | Anything anchored to a trigger: the positioning, focus and dismissal engine. | FloatingSurface, Popover, DropdownMenu, MenuButton, ContextMenu, Tooltip, Command |
hooks | Behaviour without markup, so a module can compose its own. | useContainerBand, useAnchoredPosition, useDismiss, useFocusTrap, useHotkeys, useRovingFocus, usePresence, useCopyToClipboard, useStoredList, useGates, useTestChat |
theme | Light, dark, and following the system. | ThemeToggle, useTheme |
icons | One export per glyph, grouped by file: arrows, actions, objects, communication, channels, status. | IconProps, IconSearch, IconChevronDown, IconSparkles, IconWhatsApp, IconCheck |
app | Whole dialogs an app needs once. | ShortcutsDialog, ConfirmDialog |
The vendoring contract
The wizard copies the whole src/ tree onto your disk, so the tree has to survive the move
byte-for-byte. Four rules make that true, and each of them is a rule because breaking it breaks the
copy rather than this repository.
Each directory keeps its own barrel, so the export list for a component lives beside the component,
and the root src/index.ts only stitches the barrels together. Validate pass 11(d) walks that chain
in both directions — every component file is named in its directory's barrel, and every directory
barrel is re-exported from the root — because a component nobody can import type-checks, renders in
the gallery through a deep import, and is invisible to every consumer of ~ui. Anything genuinely
internal opts out by living under internal/.
The gallery is apps/design-system: every exported component in its states, and the tokens rendered
from the live CSS custom properties. It is where you look at a change before a module uses it — and
the tokens it renders are the ones listed here.
Traps
The cross-domain sharp edges of the Chatfuel API — identity and selection, schema and introspection, deprecated fields, pagination, and data semantics — in full.
Tokens
The semantic token vocabulary in tokens.css — colour roles, sizes, shapes and motion — how dark mode is mapped, and what the design-system passes refuse.