# Halftone Design System

> One brand on phone and web: Expo and Next.js kits your coding agent builds from.

Two prototype kits on one set of design tokens: a native kit (Expo, React Native, NativeWind,
react-native-reusables) and a web kit (Next.js, Tailwind 4, shadcn/ui). Each kit lists the only components a
prototype may use. Start with the install guide.

## This site

- [Install guide for agents](https://halftonedesignsystem.com/install.md): pick a kit and a path, then the rules
- [Everything in one file](https://halftonedesignsystem.com/llms-full.txt)
- [shadcn registry for Expo + react-native-reusables (@halftone-native)](https://halftonedesignsystem.com/r/native/registry.json)
- [shadcn registry for Next.js + shadcn/ui (@halftone-web)](https://halftonedesignsystem.com/r/web/registry.json)
- [Studio](https://halftonedesignsystem.com/studio/): people make and keep design systems here (saved in their browser). They hand you an `ht-` theme code or a `.halftone.json`; apply either with `npx halftone-tokens theme apply <code|file>` (the kits' apply-theme skill)

## Native kit

> A brand-agnostic Expo + React Native prototype kit (Expo Router, NativeWind, react-native-reusables).
> Screens are composed ONLY from the components listed below; nothing else exists.

Generated by `npm run registry:build` from registry/components.ts — do not edit by hand.

### Read first

- [AGENTS.md](https://github.com/itsHendri/halftone/blob/main/apps/mobile/AGENTS.md): stack, commands, how to build a prototype, gotchas
- [DESIGN_SYSTEM.md](https://github.com/itsHendri/halftone/blob/main/apps/mobile/DESIGN_SYSTEM.md): tokens, the component registry, patterns, anti-patterns, the hallucination guard
- [DESIGN.md](https://github.com/itsHendri/halftone/blob/main/apps/mobile/DESIGN.md): the design tokens in the DESIGN.md format

### Rules

- Use only the components below, by their exact names. Missing something: stop and say so (the `add-component` skill adds it properly).
- Style with semantic Tailwind classes only. No hex, no Tailwind palette colours, no StyleSheet colours.
- `npm run lint` enforces these rules (`halftone/*`): fix every error before calling a screen done.
- Text through `<Text variant>` from components/ui/text; icons through `<Icon as={…} />` (lucide).
- Check every screen in light and dark.

### Components

#### Actions

- [Button](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/button.tsx): `variant` default/secondary/outline/ghost/link/destructive · `size` sm/default/lg/icon · children are `<Text>`/`<Icon>` — `<Button variant? size? disabled?><Text>…</Text></Button>`
- [Toggle](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/toggle.tsx): pressed two-state button — `<Toggle pressed onPressedChange><ToggleIcon as={…} /></Toggle>`
- [ToggleGroup](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/toggle-group.tsx): `type` single/multiple — `<ToggleGroup type="single|multiple" value onValueChange><ToggleGroupItem value … /></ToggleGroup>`
- [FloatingButton](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/floating-button.tsx): floats OVER the scroll (a Button flows with it) · Material calls it a FAB · `icon label? variant position` · one per screen — `<FloatingButton icon label? variant="primary|secondary" position="inline|bottom-right|bottom-center" />`
- [IconBadge](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/icon-badge.tsx): icon button with unread count/dot · always labelled — `<IconBadge icon count? dot? accessibilityLabel />`
- [SwipeToConfirm](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/swipe-to-confirm.tsx): drag past 85% commits · `tone` primary/destructive · reset via `key` — `<SwipeToConfirm label onConfirm confirmLabel? tone="primary|destructive" />`
- [ActionGrid](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/action-grid.tsx): the row of shortcuts under a screen hero · 3–4 `items`, one row only, last tile is "More" — `<ActionGrid items={[{icon,label,onPress,badge?}]} />`

#### Inputs & selection

- [Input](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/input.tsx): always with `Label` — `<Label htmlFor /> + <Input id placeholder keyboardType … />`
- [Label](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/label.tsx): `htmlFor` · own `onPress` on native
- [Textarea](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/textarea.tsx): `<Textarea placeholder numberOfLines? />`
- [Checkbox](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/checkbox.tsx): `checked onCheckedChange` — `<Checkbox checked onCheckedChange disabled? />`
- [RadioGroup](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/radio-group.tsx): `RadioGroupItem value id` · a `Label htmlFor` the same id names it — `<RadioGroup value onValueChange><RadioGroupItem value id /></RadioGroup>`
- [Switch](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/switch.tsx): settings on/off — `<Switch checked onCheckedChange />`
- [Select](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/select.tsx): pass safe-area `insets` to `SelectContent` — `<Select><SelectTrigger><SelectValue /></SelectTrigger><SelectContent><SelectItem label value /></SelectContent></Select>`
- [FilterChip / FilterChipRow](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/filter-chip.tsx): filter chips · selected is the theme's Chip colour (inverted by default) — `<FilterChipRow><FilterChip label selected onPress icon? /></FilterChipRow>`
- [SegmentedControl](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/segmented-control.tsx): 2–4 options, animated thumb — `<SegmentedControl segments={[{value,label}]} value onChange />`
- [SearchField](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/search-field.tsx): Input + search icon + clear — `<SearchField value onChangeText placeholder />`
- [QuantityStepper](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/quantity-stepper.tsx): `min max step` — `<QuantityStepper value onChange min max step />`
- [Rating](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/rating.tsx): stars · display (half stars, `showValue`, `count`) or input with `onChange` (44pt radio stars) — `<Rating value onChange? showValue? count? size? accessibilityLabel? />`
- [AmountInput](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/amount-input.tsx): hero money field · `editable={false}` with keypad — `<AmountInput value onChangeText symbol helper? onMax? onToggleCurrency? error? editable? />`
- [NumericKeypad](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/numeric-keypad.tsx): 3×4 in-app keypad, keys on `bg-muted` — `<NumericKeypad value onChange maxLength? allowDecimal? />`
- [OtpInput](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/otp-input.tsx): N-digit code, paste-aware — `<OtpInput length value onChange onComplete error? />`
- [PasswordInput](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/password-input.tsx): Input + show/hide — `<PasswordInput value onChangeText />`
- [SelectableCard](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/selectable-card.tsx): card as a radio/checkbox choice — `<SelectableCard title description? icon? detail? selected onPress mode="radio|checkbox" />`
- [Slider](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/slider.tsx): continuous/stepped · `tone` · `accessibilityLabel` names it — `<Slider value onChange min max step? tone? onChangeComplete? accessibilityLabel />`
- [DatePicker](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/date-picker.tsx): field trigger → Calendar in a Sheet — `<DatePicker value onChange placeholder? />`
- [Calendar](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/calendar.tsx): month grid — `<Calendar value onChange />`
- [RangeSelector](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/range-selector.tsx): trackless chart range (1D·1W·1M·1Y·ALL), active is a filled disc — `<RangeSelector options value onChange />`

#### Navigation

- [Tabs](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/tabs.tsx): in-page content switching — `<Tabs value onValueChange><TabsList><TabsTrigger value /></TabsList><TabsContent value /></Tabs>`
- [Menubar](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/menubar.tsx): web/desktop pattern — `<Menubar value onValueChange><MenubarMenu value><MenubarTrigger /><MenubarContent /></MenubarMenu></Menubar>`
- [TabBar / TabBarItem / `tabIcon`](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/tab-bar.tsx): custom bottom tab bar: opaque tints, label, active dot under the label — `<Tabs tabBar={(p) => <TabBar {...p} />}><Tabs.Screen options={{ title, tabBarIcon: tabIcon(HouseIcon) }} /></Tabs>`
- [KitChip](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/kit-chip.tsx): scaffolding, not a product component: the way back to the kit from a sample. Not on the Components page; delete it with the kit shell
- [Stepper](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/stepper.tsx): `numbered` / `compact` flow progress — `<Stepper current total labels? variant="numbered|compact" />`
- [SectionHeader](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/section-header.tsx): title + action, outside the card — `<SectionHeader title action? onAction? />`
- [ScreenHeader](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/screen-header.tsx): the in-body page title + intro · one per screen, first child of the ScrollView — `<ScreenHeader title subtitle? action? size="default|large" />`
- [PagerDots](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/pager-dots.tsx): Full-width slides: HorizontalPager with itemWidth = screen width. — `<PagerDots count activeIndex /> — HorizontalPager renders them for you`
- [HorizontalPager](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/horizontal-pager.tsx): snap pager + dots — `<HorizontalPager itemWidth gap? showDots? onIndexChange?>{cards}</HorizontalPager>`

#### Data display

- [Text](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/text.tsx): the only Text · the scale is previewed in **Foundations › Typography**, not Components
- [Avatar](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/avatar.tsx): image + fallback initials — `<Avatar alt><AvatarImage source /><AvatarFallback><Text /></AvatarFallback></Avatar>`
- [AvatarGroup](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/avatar-group.tsx): overlapping avatars + "+N" — `<AvatarGroup items={[{id,initials,uri?}]} max? size? />`
- [Badge](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/badge.tsx): tag/pill/count · tint with semantic classes — `<Badge variant="default|secondary|destructive|outline"><Text /></Badge>`
- [Separator](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/separator.tsx): `<Separator orientation="horizontal|vertical" />`
- [ListRow](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/list-row.tsx): ONE row · the canonical row · `last` on the final row · `select={{mode,selected}}` makes it a radio/checkbox row — `<ListRow leading title subtitle? value? sublabel? trailing? chevron? onPress? last? />`
- [ListGroup](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/list-group.tsx): the CONTAINER around rows: owns the title, dividers, footnote and card/plain surface · wraps ListRows and sets `last` for you · `variant` card/plain (plain = settings look) — `<ListGroup title? footnote? variant="card|plain">{rows}</ListGroup>`
- [IconCircle](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/icon-circle.tsx): leading icon well, row scale (≤44px) · `shape` circle/square · `tone` — `<IconCircle as size? shape="circle|square" tone? />`
- [KeyValueList / SummaryCard](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/key-value-list.tsx): label/value rows, optionally in a Card — `<SummaryCard title? rows={[{label,value}]} /> · <KeyValueList rows />`
- [StatTile](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/stat-tile.tsx): KPI tile with delta — `<StatTile label value delta? icon? />`
- [PercentChange](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/percent-change.tsx): signed % with trend icon — `<PercentChange value decimals? showIcon? />`
- [ProgressRing](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/progress-ring.tsx): circular determinate progress — `<ProgressRing value size? tone? accessibilityLabel?>{centre}</ProgressRing>`
- [StatusDot](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/status-dot.tsx): `<StatusDot tone size />`
- [Timeline](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/timeline.tsx): vertical status steps joined by a line · each `done` / `current` / `upcoming` with time and note — `<Timeline items={[{ title, time?, description?, state }]} tone? />`
- [LineChart](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/line-chart.tsx): interactive/sparkline · `area` · `onPointerChange` — `<LineChart data variant="interactive|sparkline" height tone area? onPointerChange? />`
- [BarChart](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/bar-chart.tsx): plain Views — `<BarChart data={[{label,value,className?}]} height showValues? />`
- [DonutChart / ChartLegend](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/donut-chart.tsx): ring + legend — `<DonutChart data size>{centre}</DonutChart> + <ChartLegend data />`
- [ValueHeader](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/value-header.tsx): hero figure + caption · `maskable` adds the eye toggle — `<ValueHeader value label? caption? captionTone? maskable? align? />`

#### Feedback & status

- [Alert](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/alert.tsx): inline, persistent · `variant` default/info/success/warning/destructive · `icon` · `onDismiss`/`action` make it a nudge — `<Alert icon variant="default|info|success|warning|destructive" onDismiss? action?><AlertTitle /><AlertDescription /></Alert>`
- [Progress](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/progress.tsx): 0–100 — `<Progress value={0–100} />`
- [Skeleton](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/skeleton.tsx): Match the shape of the content it stands in for. — `<Skeleton className="h-4 w-40" />`
- [Tooltip](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/tooltip.tsx): `<Tooltip><TooltipTrigger asChild /><TooltipContent><Text /></TooltipContent></Tooltip>`
- [`useToast` / ToastProvider](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/toast.tsx): transient · `ToastProvider` is in the root layout — `const toast = useToast(); toast.success("Saved") · .error · .warning · .info`
- [Spinner](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/spinner.tsx): themed ActivityIndicator · announced as "Loading" — `<Spinner size="small|large" tone="primary|foreground|muted" accessibilityLabel? />`
- [EmptyState](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/empty-state.tsx): `default` / `compact` — `<EmptyState icon title subtitle? action? variant="default|compact" />`
- [SuccessScreen](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/success-screen.tsx): the one success template — `<SuccessScreen title body? amount? amountSubtitle? loading?>{extra}</SuccessScreen>`

#### Containers & layout

- [Card](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/card.tsx): never nest cards; titles sit outside · **flat — a shadow means pressable or floating** — `<Card><CardHeader><CardTitle /><CardDescription /></CardHeader><CardContent /><CardFooter /></Card>`
- [Accordion](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/accordion.tsx): `<Accordion type="single|multiple" collapsible><AccordionItem value><AccordionTrigger /><AccordionContent /></AccordionItem></Accordion>`
- [Collapsible](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/collapsible.tsx): `<Collapsible><CollapsibleTrigger asChild /><CollapsibleContent /></Collapsible>`
- [StickyBottomBar](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/sticky-bottom-bar.tsx): safe-area action bar under a ScrollView (`pb-32`) — `<StickyBottomBar transparent?>{buttons}</StickyBottomBar>`
- [PromoCard](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/promo-card.tsx): tinted offer/nudge card · circular arrow CTA, dismiss X, generated art · one per screen — `<PromoCard title body? action? onDismiss? tone? seed? icon? />`
- [Footnote](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/footnote.tsx): small print / disclosure, last in the scroll — `<Footnote action?>{copy}</Footnote>`
- [Prose](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/prose.tsx): long-form text (articles, help, onboarding copy) at the theme's typeset: flow, measure, leading — `<Prose><Text variant="h3" /><Text variant="p" />…</Prose>`

#### Overlays

- [Dialog](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/dialog.tsx): edits with a form — `<Dialog><DialogTrigger asChild /><DialogContent><DialogHeader /><DialogFooter /></DialogContent></Dialog>`
- [AlertDialog](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/alert-dialog.tsx): confirmations — `<AlertDialog>…<AlertDialogCancel /><AlertDialogAction /></AlertDialog>`
- [Popover](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/popover.tsx): A small anchored panel for a quick edit or extra detail next to its trigger. — `<Popover><PopoverTrigger asChild /><PopoverContent side /></Popover>`
- [DropdownMenu](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/dropdown-menu.tsx): pass `insets` — `<DropdownMenu><DropdownMenuTrigger asChild /><DropdownMenuContent insets><DropdownMenuItem /></DropdownMenuContent></DropdownMenu>`
- [ContextMenu](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/context-menu.tsx): long-press — `<ContextMenu><ContextMenuTrigger /><ContextMenuContent insets><ContextMenuItem /></ContextMenuContent></ContextMenu>`
- [HoverCard](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/hover-card.tsx): Opens on press on native. — `<HoverCard><HoverCardTrigger asChild /><HoverCardContent insets /></HoverCard>`
- [Sheet](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/sheet.tsx): bottom sheet shell — `<Sheet open onClose title? description?>{children}</Sheet>`
- [OptionSheet](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/sheet.tsx): pick one of N — `<OptionSheet open onClose title options={[{value,label,description?,icon?}]} value onChange />`
- [ActionSheet](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/sheet.tsx): list of actions + Cancel — `<ActionSheet open onClose title? items={[{label,icon?,destructive?,onPress}]} />`

#### Media & icons

- [Icon](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/icon.tsx): lucide wrapper — `<Icon as={LucideIcon} size? className="text-…" />`
- [Logo](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/logo.tsx): the brand from lib/brand.ts (Studio › Use system › Brand assets) · one-colour logos follow the theme · placeholder + name without one — `<Logo variant?="full|mark" size? name? tone? />`
- [ImageTile](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/image-tile.tsx): rounded image · `seed` draws generated art when there is no `source` — `<ImageTile source? ratio? caption? fallbackIcon? />`
- [AspectRatio](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/ui/aspect-ratio.tsx): `<AspectRatio ratio={16 / 9}>…</AspectRatio>`
- [Placeholder](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/placeholder.tsx): deterministic abstract SVG art from a `seed` · the kit ships no raster imagery — `<Placeholder seed ratio? palette="chart|mono|primary" icon? />`
- [Spot](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/spot.tsx): an icon at illustration scale (≥64px) · EmptyState, SuccessScreen and PermissionPrimer all use it — `<Spot icon size="md|lg|xl" tone? shape="circle|square" ring? />`

#### Marketing

- [PricingCard](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/pricing-card.tsx): one plan · stack 2–3 on a paywall · `highlighted` on one — `<PricingCard name price period? description? features action highlighted? />`

#### AI product

- [ChatMessage](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/chat-message.tsx): one turn · user = bubble on the right, assistant = plain text on the left — `<ChatMessage role="user|assistant" initials?>{content}</ChatMessage>`
- [ChatComposer](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/chat-composer.tsx): the arrow sends · `busy` turns Send into Stop · `onAttach` turns on attachments (paperclip, chips) — `<ChatComposer onSend={(text, files) => …} busy? onStop? placeholder? onAttach? maxFiles? />`
- [AttachmentChip / `formatBytes`](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/attachment-chip.tsx): a file in a conversation: icon by type, name, size · `onRemove` while composing — `<AttachmentChip file={{ name, size, type? }} onRemove? />`
- [ChatThreadList](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/chat-thread-list.tsx): past conversations, grouped by when · `threads activeId onSelect onNew?` — `<ChatThreadList threads={[{id,title,preview?,group?}]} activeId onSelect onNew? />`
- [SourceList / CitedText / `stripCitations`](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/sources.tsx): what an answer is based on · numbered chips · `[n]` in text → inline citations · previews in a Sheet — `<CitedText text="… [1]" sources={[{ title, meta?, snippet?, href? }]} /><SourceList sources />`
- [FollowUpSuggestions](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/follow-up-suggestions.tsx): next questions under the latest answer · tapping one sends it — `<FollowUpSuggestions suggestions={["…"]} onSelect />`
- [StreamingText / `useStreamingText`](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/streaming-text.tsx): an answer arriving · all at once under reduced motion · screen readers get it once — `<StreamingText text onDone? />`
- [ThinkingIndicator](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/thinking-indicator.tsx): the model is working · say what it is doing when you can · still dots under reduced motion — `<ThinkingIndicator label? />`
- [ToolCallCard](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/tool-call-card.tsx): an action the assistant took · `status` running/done/error/stopped · details collapsed — `<ToolCallCard title status input? output? />`
- [ApprovalCard](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/approval-card.tsx): consent before consequence · says what changes and whether it can be undone — `<ApprovalCard title description? details? onApprove onDeny />`

#### Device capabilities

- [PhotoCapture](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/photo-capture.tsx): camera + library · falls back to a seeded `Placeholder` — `<PhotoCapture value? onChange? sources? shape="tile|avatar|wide" label? seed? simulate? />`
- [CodeScanner](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/code-scanner.tsx): QR/barcode viewfinder · simulated emits a sample payload — `<CodeScanner onScan types? hint? ratio? continuous? simulatedValues? simulate? />`
- [BiometricGate / `useBiometricAuth`](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/biometric-gate.tsx): Face ID gate, or the hook for a single action · real only in a dev build — `<BiometricGate title? subtitle? prompt? locked? onUnlock? simulate?>…</BiometricGate> · useBiometricAuth()`
- [PermissionPrimer](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/permission-primer.tsx): shown BEFORE the OS dialog · the skip is not optional — `<PermissionPrimer capability variant="inline|sheet" onAllow onSkip skipLabel? />`
- [`useShare`](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/share.ts): OS share sheet · copies to the clipboard on web — `const { share } = useShare(); share({ message?, url?, title? })`
- [`useNotify` / NotifyProvider](https://github.com/itsHendri/halftone/blob/main/apps/mobile/components/kit/notify.tsx): in-app banner now (`delay: 0`), real OS notification when scheduled — `const { notify } = useNotify(); notify({ title, body?, delay?, icon? })`

### Tokens

Colours are semantic names only, used as Tailwind classes (`bg-primary`, `text-muted-foreground`,
`border-border`, `bg-success/15`). Never hex, never Tailwind palette colours. Both themes are
required; every fill/foreground pairing clears WCAG AA (4.5:1); `npm run tokens:build` names any that falls short (`--strict` fails on it).
A tone's own text on its own tint (`text-success` on `bg-success/15`) clears AA only for these
tints; on a stronger one, put `text-foreground` on the tint:
primary up to /5, success up to /5, warning up to /5, info up to /15, destructive up to /5.

| Name | Light | Dark |
|---|---|---|
| `background` | #ffffff | #09090b |
| `foreground` | #09090b | #fafafa |
| `card` | #ffffff | #18181b |
| `card-foreground` | #09090b | #fafafa |
| `popover` | #ffffff | #18181b |
| `popover-foreground` | #09090b | #fafafa |
| `primary` | #2563eb | #448bff |
| `primary-foreground` | #ffffff | #09090b |
| `secondary` | #f4f4f5 | #27272a |
| `secondary-foreground` | #18181b | #fafafa |
| `muted` | #f4f4f5 | #27272a |
| `muted-foreground` | #52525b | #a1a1aa |
| `accent` | #f4f4f5 | #27272a |
| `accent-foreground` | #18181b | #fafafa |
| `destructive` | #d92223 | #fb504e |
| `destructive-foreground` | #ffffff | #09090b |
| `success` | #15803d | #22c55e |
| `success-foreground` | #ffffff | #09090b |
| `warning` | #b45309 | #fbbf24 |
| `warning-foreground` | #ffffff | #09090b |
| `info` | #0369a1 | #0ea5e9 |
| `info-foreground` | #ffffff | #09090b |
| `border` | #e4e4e7 | #27272a |
| `input` | #e4e4e7 | #27272a |
| `ring` | #2563eb | #448bff |
| `sidebar` | #fafafa | #18181b |
| `sidebar-foreground` | #09090b | #fafafa |
| `sidebar-primary` | #2563eb | #448bff |
| `sidebar-primary-foreground` | #ffffff | #09090b |
| `sidebar-accent` | #f4f4f5 | #27272a |
| `sidebar-accent-foreground` | #18181b | #fafafa |
| `sidebar-border` | #e4e4e7 | #27272a |
| `sidebar-ring` | #2563eb | #448bff |
| `chart-1` | #3b82f6 | #60a5fa |
| `chart-2` | #22c55e | #4ade80 |
| `chart-3` | #f59e0b | #fbbf24 |
| `chart-4` | #ef4444 | #f87171 |
| `chart-5` | #0ea5e9 | #38bdf8 |
| `button` | #2563eb | #448bff |
| `button-foreground` | #ffffff | #09090b |
| `button-edge` | #2563eb | #448bff |
| `field` | #e4e4e7 | #27272a |
| `field-edge` | #e4e4e7 | #27272a |

- Spacing (4-pt grid, Tailwind numeric scale): 0 0px · 1 4px · 2 8px · 3 12px · 4 16px · 5 20px · 6 24px · 8 32px · 10 40px · 12 48px · 16 64px
- Radius (`rounded-*`): sm 6px · md 8px · lg 10px · xl 16px · 2xl 20px (multiples of `--radius` = 10px); `rounded-control` pill
- Depth: `shadow-sm` (controls, cards), `shadow-md` (raised, popovers), `shadow-lg` (menus, dialogs) are the theme's three elevation levels; no shadow colour modifiers on surfaces (thumbs and floating elements may add `shadow-black/20`)
- Border `border` 1px · icon stroke 2 (an Icon's `strokeWidth` is relative to 2)
- Styles: solid buttons, outline fields
- Components (one theme for both kits; never restyle them by hand): Button 48px tall (small 40, large 56), 20px padding, pill, 16px text; Chip 36px, pill; selected is foreground with background text; Badge pill, 14px text; Input, Textarea and Select 48px, 8px corners. Phones raise any tap target under 44px to 44
- Fonts: headings system, body system, mono system (applied by Text; `font-heading` makes any Text a heading, `font-mono` code and figures)
- Typeset: body 16px, leading 1.75; every `text-*` size below scales by 1
- Theme: `ht1-29B3XC60003T` (`npx halftone-tokens theme show`)
- Font sizes (`text-*`): xs 12px · sm 14px · base 16px · lg 18px · xl 20px · 2xl 24px · 3xl 30px · 4xl 36px
- Durations: fast 150ms · base 200ms · slow 300ms

## Web kit

> A brand-agnostic Next.js prototype kit (App Router, Tailwind 4, shadcn/ui) for dashboards, marketing pages and
> AI product interfaces. Pages are composed ONLY from the components listed below; nothing else exists.

Generated by `npm run registry:build` from registry/components.ts — do not edit by hand.

### Read first

- [AGENTS.md](https://github.com/itsHendri/halftone/blob/main/apps/web/AGENTS.md): stack, commands, how to build a prototype, gotchas
- [DESIGN_SYSTEM.md](https://github.com/itsHendri/halftone/blob/main/apps/web/DESIGN_SYSTEM.md): tokens, the component registry, patterns, anti-patterns, the hallucination guard
- [DESIGN.md](https://github.com/itsHendri/halftone/blob/main/apps/web/DESIGN.md): the design tokens in the DESIGN.md format

### Rules

- Use only the components below, by their exact names. Missing something: stop and say so (the `add-component` skill adds it properly).
- Style with semantic Tailwind classes only. No hex, no Tailwind palette colours, no inline colour styles.
- `npm run lint` enforces these rules (`halftone/*`): fix every error before calling a page done.
- Icons from lucide-react. Charts take colours from `var(--chart-1)`…`--chart-5`.
- Check every page in light and dark, at 375px and 1280px wide.

### Components

#### Actions

- [Button / `buttonVariants`](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/button.tsx): `variant` default/secondary/outline/ghost/link/destructive · `size` default/sm/lg/icon · `asChild` for links — `<Button variant? size? asChild?>Label</Button>`
- [Toggle / `toggleVariants`](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/toggle.tsx): a pressed/unpressed button (bold, mute, favourite) — `<Toggle pressed onPressedChange aria-label>…</Toggle>`
- [ToggleGroup / ToggleGroupItem](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/toggle-group.tsx): `type` single (a segmented control) or multiple — `<ToggleGroup type="single" value onValueChange><ToggleGroupItem value>…</ToggleGroupItem></ToggleGroup>`
- [FloatingButton](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/floating-button.tsx): floats OVER the scroll (a Button flows with it) · Material calls it a FAB · `icon label? variant position` · one per page — `<FloatingButton icon label? variant="primary|secondary" position="inline|bottom-right|bottom-center" aria-label? />`
- [IconBadge](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/icon-badge.tsx): icon button with unread count/dot · always labelled — `<IconBadge icon count? dot? aria-label onClick? />`
- [ActionGrid](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/action-grid.tsx): the row of shortcuts under a page hero · 3–4 `items`, one row only, last tile is "More" — `<ActionGrid items={[{icon,label,onClick|href,badge?}]} />`

#### Inputs & selection

- [Input](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/input.tsx): always with a `Label` · `aria-invalid` for errors — `<Label htmlFor="email">Email</Label><Input id="email" type="email" />`
- [Label](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/label.tsx): `htmlFor` the field it names
- [Textarea](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/textarea.tsx): multi-line text, grows with content — `<Textarea id placeholder rows? />`
- [Checkbox](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/checkbox.tsx): `checked onCheckedChange` · pick any — `<Checkbox id checked onCheckedChange /><Label htmlFor>…</Label>`
- [RadioGroup / RadioGroupItem](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/radio-group.tsx): pick exactly one · `RadioGroupItem value id` — `<RadioGroup value onValueChange><RadioGroupItem value id /></RadioGroup>`
- [Switch](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/switch.tsx): a setting that applies at once (no Save button) — `<Switch id checked onCheckedChange />`
- [Select / SelectTrigger / SelectValue / SelectContent / SelectItem](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/select.tsx): one of 5–15 options in a form; fewer → RadioGroup, more → Command — `<Select value onValueChange><SelectTrigger><SelectValue /></SelectTrigger><SelectContent><SelectItem value /></SelectContent></Select>`
- [DatePicker](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/date-picker.tsx): one date in a form · field-styled button → Calendar in a Popover · `value onChange disabled?` — `<DatePicker id value onChange placeholder? disabled? />`
- [Calendar / CalendarDayButton](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/calendar.tsx): a month grid (react-day-picker) · `mode` single/range/multiple · use DatePicker for a form field — `<Calendar mode="single" selected onSelect disabled? />`
- [Slider](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/slider.tsx): a value on a range · two thumbs for a range — `<Slider value onValueChange min max step aria-label />`
- [FilterChip / FilterChipRow](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/filter-chip.tsx): filter chips in a scrolling row · selected is the theme's Chip colour (inverted by default) — `<FilterChipRow><FilterChip label selected onClick icon? /></FilterChipRow>`
- [SegmentedControl](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/segmented-control.tsx): 2–4 options, sliding thumb — `<SegmentedControl segments={[{value,label}]} value onChange aria-label />`
- [SearchField](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/search-field.tsx): Input + search icon + clear — `<SearchField value onChangeText placeholder />`
- [QuantityStepper](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/quantity-stepper.tsx): − value + · `min max step` — `<QuantityStepper value onChange min? max? step? aria-label />`
- [Rating](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/rating.tsx): stars · display (half stars, `showValue`, `count`) or input with `onChange` — `<Rating value onChange? showValue? count? size? aria-label? />`
- [AmountInput](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/amount-input.tsx): hero money field · MAX and currency switch — `<AmountInput value onChangeText symbol helper? onMax? onToggleCurrency? error? />`
- [OtpInput](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/otp-input.tsx): N-digit code, paste-aware — `<OtpInput length value onChange onComplete error? />`
- [PasswordInput](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/password-input.tsx): Input + show/hide — `<PasswordInput id value onChange />`
- [SelectableCard](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/selectable-card.tsx): card as a radio/checkbox choice — `<SelectableCard title description? icon? detail? selected onClick mode="radio|checkbox" />`
- [RangeSelector](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/range-selector.tsx): chart range (1D·1W·1M·1Y·ALL), the active one inverts — `<RangeSelector options value onChange aria-label />`

#### Navigation

- [AppShell](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/app-shell.tsx): sidebar of 4–8 destinations on desktop, a sheet on mobile · active item follows the URL — `<AppShell brand nav={[{href,label,icon}]} footer? topbar?>{page}</AppShell>`
- [Tabs / TabsList / TabsTrigger / TabsContent](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/tabs.tsx): switch views of the same thing in place; not page navigation — `<Tabs defaultValue><TabsList><TabsTrigger value /></TabsList><TabsContent value /></Tabs>`
- [NavigationMenu / NavigationMenuList / NavigationMenuItem / NavigationMenuTrigger / NavigationMenuContent / NavigationMenuLink / `navigationMenuTriggerStyle`](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/navigation-menu.tsx): a marketing site’s top nav with dropdown panels · not for app navigation (AppShell) — `<NavigationMenu><NavigationMenuList><NavigationMenuItem><NavigationMenuTrigger /><NavigationMenuContent /></NavigationMenuItem></NavigationMenuList></NavigationMenu>`
- [Breadcrumb / BreadcrumbList / BreadcrumbItem / BreadcrumbLink / BreadcrumbPage / BreadcrumbSeparator](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/breadcrumb.tsx): where a detail page sits · the last item is the current page — `<Breadcrumb><BreadcrumbList><BreadcrumbItem><BreadcrumbLink href /></BreadcrumbItem>…</BreadcrumbList></Breadcrumb>`
- [Pagination / PaginationContent / PaginationItem / PaginationLink / PaginationPrevious / PaginationNext / PaginationEllipsis](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/pagination.tsx): pages of a long list or table · Previous/Next + page links · `isActive` on the current page — `<Pagination><PaginationContent><PaginationItem><PaginationPrevious href /></PaginationItem>…</PaginationContent></Pagination>`
- [Command / CommandDialog / CommandInput / CommandList / CommandEmpty / CommandGroup / CommandItem](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/command.tsx): search-as-you-type list · `CommandDialog` for a ⌘K palette — `<Command><CommandInput /><CommandList><CommandGroup heading><CommandItem /></CommandGroup></CommandList></Command>`
- [Menubar / MenubarMenu / MenubarTrigger / MenubarContent / MenubarItem / MenubarSeparator / MenubarShortcut / MenubarCheckboxItem](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/menubar.tsx): desktop-app menus (File · Edit · View) across the top of an editor — `<Menubar><MenubarMenu><MenubarTrigger /><MenubarContent><MenubarItem /></MenubarContent></MenubarMenu></Menubar>`
- [Stepper](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/stepper.tsx): `numbered` / `compact` flow progress — `<Stepper current total labels? variant="numbered|compact" />`
- [SectionHeader](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/section-header.tsx): title + action, outside the card — `<SectionHeader title action? onAction? actionHref? level? />`
- [PagerDots](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/pager-dots.tsx): page indicator · HorizontalPager renders them for you — `<PagerDots count activeIndex />`
- [HorizontalPager](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/horizontal-pager.tsx): CSS scroll-snap pager + dots · keyboard scrollable — `<HorizontalPager itemWidth? gap? showDots? onIndexChange?>{cards}</HorizontalPager>`

#### Data display

- [DataTable](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/data-table.tsx): sortable columns + built-in empty state · `columns rows rowKey caption?` — `<DataTable columns={[{key,header,cell?,sortValue?,align?}]} rows rowKey caption? />`
- [Table / TableHeader / TableBody / TableRow / TableHead / TableCell / TableCaption](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/table.tsx): the primitive under DataTable; use it directly for small static tables
- [StatTile](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/stat-tile.tsx): one KPI with a signed change · `invert` when down is good — `<StatTile label value delta? deltaLabel? invert? />`
- [ChartContainer / ChartTooltip / ChartTooltipContent / ChartLegend / ChartLegendContent](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/chart.tsx): Recharts with the theme · series colours from `var(--chart-1)`…`--chart-5` — `<ChartContainer config={{ key: { label, color: "var(--chart-1)" } }}><BarChart data>…</BarChart></ChartContainer>`
- [Badge / `badgeVariants`](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/badge.tsx): a status or tag · a status is an outline Badge with a coloured dot (`bg-success` …), the word in foreground text — `<Badge variant?>Label</Badge>`
- [Avatar / AvatarImage / AvatarFallback](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/avatar.tsx): image with initials fallback — `<Avatar><AvatarImage src alt /><AvatarFallback>AM</AvatarFallback></Avatar>`
- [Separator](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/separator.tsx): a hairline between groups · prefer spacing
- [AvatarGroup](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/avatar-group.tsx): overlapping avatars + "+N" — `<AvatarGroup items={[{id,initials,src?}]} max? size? />`
- [ListRow](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/list-row.tsx): ONE row · the canonical row · `last` on the final row · `select={{mode,selected}}` makes it a radio/checkbox row — `<ListRow leading title subtitle? value? sublabel? trailing? chevron? onClick? href? last? />`
- [ListGroup](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/list-group.tsx): the CONTAINER around rows: title, dividers, footnote, card/plain surface · sets `last` for you — `<ListGroup title? footnote? variant="card|plain">{rows}</ListGroup>`
- [IconCircle](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/icon-circle.tsx): leading icon well, row scale (≤64px) · `shape` circle/square · `tone` — `<IconCircle as size? shape="circle|square" tone? />`
- [KeyValueList / SummaryCard](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/key-value-list.tsx): label/value rows, optionally in a Card — `<SummaryCard title? rows={[{label,value}]} /> · <KeyValueList rows />`
- [PercentChange](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/percent-change.tsx): signed % with trend icon — `<PercentChange value decimals? showIcon? />`
- [ProgressRing](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/progress-ring.tsx): circular determinate progress — `<ProgressRing value size? tone? aria-label>{centre}</ProgressRing>`
- [StatusDot](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/status-dot.tsx): small semantic status indicator, beside its label — `<StatusDot tone size />`
- [Timeline](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/timeline.tsx): vertical status steps joined by a line · each `done` / `current` / `upcoming` with time and note — `<Timeline items={[{ title, time?, description?, state }]} tone? />`
- [ValueHeader](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/value-header.tsx): hero figure + caption · `maskable` adds the eye toggle — `<ValueHeader value label? caption? captionTone? maskable? align? />`

#### Feedback & status

- [Alert / AlertTitle / AlertDescription](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/alert.tsx): inline and persistent · `variant` default/destructive — `<Alert variant?><Icon /><AlertTitle /><AlertDescription /></Alert>`
- [Toaster](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/sonner.tsx): transient confirmation · `toast()` from `sonner` · the Toaster is in the root layout — `import { toast } from 'sonner'; toast.success('Saved')`
- [Progress](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/progress.tsx): determinate 0–100 — `<Progress value aria-label />`
- [Skeleton](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/skeleton.tsx): the shape of content that is loading — `<Skeleton className="h-4 w-48" />`
- [EmptyState](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/empty-state.tsx): nothing here yet, and the way out · `default` page / `compact` in a card — `<EmptyState icon title description? action? variant? />`
- [Spinner](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/spinner.tsx): themed loading indicator · announced as "Loading" — `<Spinner size="small|large" tone="primary|primary-foreground|foreground|muted" aria-label? />`
- [SuccessScreen](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/success-screen.tsx): the one success template — `<SuccessScreen title body? amount? amountSubtitle? loading?>{extra}</SuccessScreen>`

#### Containers & layout

- [PageHeader](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/page-header.tsx): title, description and actions · one per page, first in the content — `<PageHeader eyebrow? title description? actions? />`
- [Prose](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/prose.tsx): long-form text (articles, docs, rendered markdown) at the theme's typeset: measure, leading, flow — `<Prose as?="div|article|section">{html}</Prose>`
- [Card / CardHeader / CardTitle / CardDescription / CardAction / CardContent / CardFooter](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/card.tsx): a raised surface for one group · never nest cards — `<Card><CardHeader><CardTitle /><CardDescription /></CardHeader><CardContent /></Card>`
- [Accordion / AccordionItem / AccordionTrigger / AccordionContent](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/accordion.tsx): FAQs and long optional detail
- [Collapsible / CollapsibleTrigger / CollapsibleContent](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/collapsible.tsx): one show/hide region
- [ScrollArea / ScrollBar](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/scroll-area.tsx): a fixed-height region that scrolls on its own
- [StickyBottomBar](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/sticky-bottom-bar.tsx): action bar that sticks to the bottom of its scroll container · safe-area aware — `<StickyBottomBar transparent?>{buttons}</StickyBottomBar>`
- [PromoCard](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/promo-card.tsx): tinted offer/nudge card · arrow CTA, dismiss X, generated art · one per page — `<PromoCard title body? action? onDismiss? tone? seed? icon? />`
- [Footnote](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/footnote.tsx): small print / disclosure, last on the page — `<Footnote action?={{label,href|onClick}}>{copy}</Footnote>`

#### Overlays

- [Dialog / DialogTrigger / DialogContent / DialogHeader / DialogTitle / DialogDescription / DialogFooter / DialogClose](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/dialog.tsx): a short task on top of the page (an edit form) — `<Dialog><DialogTrigger asChild /><DialogContent><DialogHeader><DialogTitle /></DialogHeader>…</DialogContent></Dialog>`
- [AlertDialog / AlertDialogTrigger / AlertDialogContent / AlertDialogAction / AlertDialogCancel](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/alert-dialog.tsx): confirm something destructive · name the action on the button
- [Sheet / SheetTrigger / SheetContent / SheetHeader / SheetTitle / SheetDescription / SheetFooter](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/sheet.tsx): a side panel: filters, a record’s details, mobile navigation · `side`
- [Drawer / DrawerTrigger / DrawerContent / DrawerHeader / DrawerTitle / DrawerDescription / DrawerFooter / DrawerClose](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/drawer.tsx): a bottom sheet you can drag down (vaul) · mobile-first quick actions and filters — `<Drawer><DrawerTrigger asChild /><DrawerContent><DrawerHeader><DrawerTitle /></DrawerHeader>…<DrawerFooter /></DrawerContent></Drawer>`
- [Popover / PopoverTrigger / PopoverContent](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/popover.tsx): a small panel anchored to a control
- [DropdownMenu / DropdownMenuTrigger / DropdownMenuContent / DropdownMenuItem / DropdownMenuLabel / DropdownMenuSeparator](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/dropdown-menu.tsx): actions on a thing (row menu, account menu) · `variant="destructive"` items last
- [Tooltip / TooltipTrigger / TooltipContent](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/tooltip.tsx): names an icon button · never the only place information lives
- [ContextMenu / ContextMenuTrigger / ContextMenuContent / ContextMenuItem / ContextMenuSeparator / ContextMenuShortcut](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/context-menu.tsx): right-click menu on a thing — `<ContextMenu><ContextMenuTrigger /><ContextMenuContent><ContextMenuItem /></ContextMenuContent></ContextMenu>`
- [HoverCard / HoverCardTrigger / HoverCardContent](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/hover-card.tsx): a preview on hover or focus (a profile, a link) — `<HoverCard><HoverCardTrigger asChild /><HoverCardContent /></HoverCard>`

#### Media

- [Logo](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/logo.tsx): the brand from lib/brand.ts (Studio › Use system › Brand assets) · one-colour logos take the text colour · placeholder + name without one — `<Logo variant?="full|mark" size? name? />`
- [ImageTile](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/image-tile.tsx): rounded image · `seed` draws generated art when there is no `src` — `<ImageTile src? alt? ratio? caption? fallbackIcon? seed? />`
- [AspectRatio](https://github.com/itsHendri/halftone/blob/main/apps/web/components/ui/aspect-ratio.tsx): holds a box at a ratio (video, map, embed) — `<AspectRatio ratio={16 / 9}>…</AspectRatio>`
- [Placeholder](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/placeholder.tsx): deterministic abstract SVG art from a `seed` · the kit ships no raster imagery — `<Placeholder seed ratio? palette="chart|mono|primary" icon? />`
- [Spot](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/spot.tsx): an icon at illustration scale (≥64px) · SuccessScreen uses it — `<Spot icon size="md|lg|xl" tone? shape="circle|square" ring? />`

#### Marketing

- [Hero](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/hero.tsx): one promise, one primary action · `media` for a product shot, omit for centred — `<Hero eyebrow? title description? actions? media? />`
- [FeatureGrid](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/feature-grid.tsx): 3–6 short blocks · `columns` 2/3 — `<FeatureGrid features={[{icon,title,description}]} columns? />`
- [PricingCard](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/pricing-card.tsx): one plan · 2–4 side by side · `highlighted` on one — `<PricingCard name price period? description? features action highlighted? />`

#### AI product

- [ChatMessage](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/chat-message.tsx): one turn · user = bubble on the right, assistant = plain text on the left — `<ChatMessage role="user|assistant" initials?>{content}</ChatMessage>`
- [ChatComposer](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/chat-composer.tsx): Enter sends, Shift+Enter breaks · `busy` turns Send into Stop · `accept` turns on attachments (paperclip, drop, chips) — `<ChatComposer onSend={(text, files) => …} busy? onStop? placeholder? accept? maxFiles? />`
- [AttachmentChip / `formatBytes`](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/attachment-chip.tsx): a file in a conversation: icon by type, name, size · `onRemove` while composing — `<AttachmentChip file={{ name, size, type? }} onRemove? />`
- [ChatThreadList](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/chat-thread-list.tsx): past conversations, grouped by when · `threads activeId onSelect onNew?` — `<ChatThreadList threads={[{id,title,preview?,group?}]} activeId onSelect onNew? />`
- [SourceList / CitedText / `stripCitations`](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/sources.tsx): what an answer is based on · numbered chips with previews · `[n]` in text → inline citations — `<CitedText text="… [1]" sources={[{ title, meta?, snippet?, href? }]} /><SourceList sources />`
- [FollowUpSuggestions](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/follow-up-suggestions.tsx): next questions under the latest answer · picking one sends it — `<FollowUpSuggestions suggestions={["…"]} onSelect />`
- [StreamingText / `useStreamingText`](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/streaming-text.tsx): an answer arriving · all at once under reduced motion · screen readers get it once — `<StreamingText text onDone? />`
- [ThinkingIndicator](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/thinking-indicator.tsx): the model is working · say what it is doing when you can — `<ThinkingIndicator label? />`
- [ToolCallCard](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/tool-call-card.tsx): an action the assistant took · `status` running/done/error/stopped · details collapsed — `<ToolCallCard title status input? output? />`
- [ApprovalCard](https://github.com/itsHendri/halftone/blob/main/apps/web/components/kit/approval-card.tsx): consent before consequence · says what changes and whether it can be undone — `<ApprovalCard title description? details? onApprove onDeny />`

### Tokens

Colours are semantic names only, used as Tailwind classes (`bg-primary`, `text-muted-foreground`,
`border-border`, `bg-success/15`). Never hex, never Tailwind palette colours. Both themes are
required; every fill/foreground pairing clears WCAG AA (4.5:1); `npm run tokens:build` names any that falls short (`--strict` fails on it).
A tone's own text on its own tint (`text-success` on `bg-success/15`) clears AA only for these
tints; on a stronger one, put `text-foreground` on the tint:
primary up to /5, success up to /5, warning up to /5, info up to /15, destructive up to /5.

| Name | Light | Dark |
|---|---|---|
| `background` | #ffffff | #09090b |
| `foreground` | #09090b | #fafafa |
| `card` | #ffffff | #18181b |
| `card-foreground` | #09090b | #fafafa |
| `popover` | #ffffff | #18181b |
| `popover-foreground` | #09090b | #fafafa |
| `primary` | #2563eb | #448bff |
| `primary-foreground` | #ffffff | #09090b |
| `secondary` | #f4f4f5 | #27272a |
| `secondary-foreground` | #18181b | #fafafa |
| `muted` | #f4f4f5 | #27272a |
| `muted-foreground` | #52525b | #a1a1aa |
| `accent` | #f4f4f5 | #27272a |
| `accent-foreground` | #18181b | #fafafa |
| `destructive` | #d92223 | #fb504e |
| `destructive-foreground` | #ffffff | #09090b |
| `success` | #15803d | #22c55e |
| `success-foreground` | #ffffff | #09090b |
| `warning` | #b45309 | #fbbf24 |
| `warning-foreground` | #ffffff | #09090b |
| `info` | #0369a1 | #0ea5e9 |
| `info-foreground` | #ffffff | #09090b |
| `border` | #e4e4e7 | #27272a |
| `input` | #e4e4e7 | #27272a |
| `ring` | #2563eb | #448bff |
| `sidebar` | #fafafa | #18181b |
| `sidebar-foreground` | #09090b | #fafafa |
| `sidebar-primary` | #2563eb | #448bff |
| `sidebar-primary-foreground` | #ffffff | #09090b |
| `sidebar-accent` | #f4f4f5 | #27272a |
| `sidebar-accent-foreground` | #18181b | #fafafa |
| `sidebar-border` | #e4e4e7 | #27272a |
| `sidebar-ring` | #2563eb | #448bff |
| `chart-1` | #3b82f6 | #60a5fa |
| `chart-2` | #22c55e | #4ade80 |
| `chart-3` | #f59e0b | #fbbf24 |
| `chart-4` | #ef4444 | #f87171 |
| `chart-5` | #0ea5e9 | #38bdf8 |
| `button` | #2563eb | #448bff |
| `button-foreground` | #ffffff | #09090b |
| `button-edge` | #2563eb | #448bff |
| `field` | #e4e4e7 | #27272a |
| `field-edge` | #e4e4e7 | #27272a |

- Spacing (4-pt grid, Tailwind numeric scale): 0 0px · 1 4px · 2 8px · 3 12px · 4 16px · 5 20px · 6 24px · 8 32px · 10 40px · 12 48px · 16 64px
- Radius (`rounded-*`): sm 6px · md 8px · lg 10px · xl 16px · 2xl 20px (multiples of `--radius` = 10px); `rounded-control` pill
- Depth: `shadow-sm` (controls, cards), `shadow-md` (raised, popovers), `shadow-lg` (menus, dialogs) are the theme's three elevation levels; no shadow colour modifiers on surfaces (thumbs and floating elements may add `shadow-black/20`)
- Border `border` 1px · icon stroke 2 (an Icon's `strokeWidth` is relative to 2)
- Styles: solid buttons, outline fields
- Components (one theme for both kits; never restyle them by hand): Button 48px tall (small 40, large 56), 20px padding, pill, 16px text; Chip 36px, pill; selected is foreground with background text; Badge pill, 14px text; Input, Textarea and Select 48px, 8px corners. Phones raise any tap target under 44px to 44
- Fonts: headings system, body system, mono system (applied by Text; `font-heading` makes any Text a heading, `font-mono` code and figures)
- Typeset: body 16px, leading 1.75; every `text-*` size below scales by 1
- Theme: `ht1-29B3XC60003T` (`npx halftone-tokens theme show`)
- Font sizes (`text-*`): xs 12px · sm 14px · base 16px · lg 18px · xl 20px · 2xl 24px · 3xl 30px · 4xl 36px
- Durations: fast 150ms · base 200ms · slow 300ms

# Docs


- **Get started**
- [How it works](/docs): One brand on phone and web, built by your agent.
- [Install](/docs/install): Two kits, three ways in, and the one prompt that sets an agent up.
- [Start a prototype](/docs/start): A guided brief or a transcript in, one prompt out. Your agent plans first and waits for your go-ahead.
- [Native setup](/docs/mobile): Run the native kit, make it yours, and share it.
- [Web setup](/docs/web): Run the web kit, make it yours, and share it.

- **Design system**
- [Foundations](/docs/foundations): Colour, spacing, radius, type and motion, from one token file.
- [Themes](/docs/themes): Pick a theme on this site, watch both kits change live, then commit it to your project with one code.
- [Patterns](/docs/patterns): How screens are put together in each kit, and what to avoid. Generated from the kits' DESIGN_SYSTEM.md.

- **Project**
- [Changelog](/docs/changelog): What changed, newest first.