harebear-ui 0.6.0 → 0.8.0

package/dist/styles.css

@@ -53,6 +53,12 @@
   --color-chart-4: var(--chart-4);
   --color-chart-5: var(--chart-5);
   --color-chart-grid: var(--chart-grid);
+  --color-category-1: var(--category-1);
+  --color-category-2: var(--category-2);
+  --color-category-3: var(--category-3);
+  --color-category-4: var(--category-4);
+  --color-category-5: var(--category-5);
+  --color-category-6: var(--category-6);
   --color-sidebar: var(--sidebar);
   --color-sidebar-foreground: var(--sidebar-foreground);
   --color-sidebar-primary: var(--sidebar-primary);
@@ -108,6 +114,13 @@
   --chart-4: #0f8a7e;
   --chart-5: #8b5cc9;
   --chart-grid: #eeeef0;
+  /* Category palette for members, lists and calendars: 1 blue, 2 teal, 3 violet, 4 rose, 5 slate, 6 cyan. Never a status color. */
+  --category-1: #3166d4;
+  --category-2: #0d8578;
+  --category-3: #7a4cc7;
+  --category-4: #c03a78;
+  --category-5: #5a6578;
+  --category-6: #0a7fa3;
   --elevation: 0 1px 2px rgb(24 24 27 / 0.04), 0 6px 20px rgb(24 24 27 / 0.05);
 
   --sidebar: var(--background);
@@ -149,6 +162,12 @@
   --chart-4: #3cb8a8;
   --chart-5: #a98ae0;
   --chart-grid: #242427;
+  --category-1: #76a0f2;
+  --category-2: #3dbcac;
+  --category-3: #ad8de6;
+  --category-4: #ec7fae;
+  --category-5: #9ba6b8;
+  --category-6: #4cbde0;
   --elevation: 0 1px 2px rgb(0 0 0 / 0.3), 0 8px 24px rgb(0 0 0 / 0.22);
 
   color-scheme: dark;
@@ -187,6 +206,62 @@
   animation: hb-typing 1.2s infinite ease-in-out;
 }
 
+/*
+ * Composite focus: the box around a bare field shows the focus ring (AskBox, SectionedList's add box).
+ * Pair with a border and fill: `rounded-xl border border-transparent bg-muted focus-box`.
+ */
+@utility focus-box {
+  transition-property: border-color, background-color, box-shadow;
+  transition-duration: 150ms;
+  &:focus-within {
+    border-color: var(--primary);
+    background-color: var(--card);
+    box-shadow: 0 0 0 4px color-mix(in oklab, var(--primary) 15%, transparent);
+  }
+}
+
+/* Check pop: a short scale bump when a CheckCircle is ticked. */
+@keyframes hb-check-pop {
+  0% {
+    transform: scale(1);
+  }
+  40% {
+    transform: scale(1.18);
+  }
+  100% {
+    transform: scale(1);
+  }
+}
+
+@utility animate-check-pop {
+  animation: hb-check-pop 260ms cubic-bezier(0.3, 0.7, 0.4, 1.4);
+}
+
+/* Listening bars for DictationButton. */
+@keyframes hb-listening {
+  0%,
+  100% {
+    transform: scaleY(0.35);
+  }
+  50% {
+    transform: scaleY(1);
+  }
+}
+
+@utility animate-listening {
+  animation: hb-listening 900ms infinite ease-in-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-check-pop,
+  .animate-listening {
+    animation: none;
+  }
+  .focus-box {
+    transition: none;
+  }
+}
+
 /* Thin, quiet scrollbars in the theme's colors. Firefox and Chromium use the standard properties; Safari the ::-webkit rules. */
 @layer base {
   * {

package/docs/COMPONENTS.md

@@ -16,6 +16,36 @@ Full working screens that combine these live in the repo under `playground/scree
 - **Icons are lucide-react elements.** Pass `<SearchIcon />`, not the component. Buttons size icons automatically.
 - **Status uses tones**, not colors: `"success" | "warning" | "danger" | "info" | "neutral"`.
 
+## Agent-first apps
+
+A household or personal app where an assistant sits on every page and safe actions run on their own, with Undo.
+
+```tsx
+<ThemeProvider>
+  <TooltipProvider>
+    <AssistantProvider onSend={(text, { page, append }) => runAgent(text, page, append)}>
+      <AppNav
+        brand={<AppBrand name="Homeclub" icon={<HouseIcon />} />}
+        places={[{ label: "Today", icon: <SunIcon />, href: "/", active: true, count: 3 }, ...]}
+        group={{ label: "Lists", items: lists, onAdd: newList, addLabel: "New list" }}
+        action={{ label: "New to-do", icon: <PlusIcon />, onSelect: openQuickAdd }}
+        footer={<UserMenu name={user.name} onSignOut={signOut} />}
+      >
+        <Outlet /> {/* pages call useAssistantPage({ id, title, suggestions }) */}
+        <AssistantDock title="HomeBot" fullScreenHref="/chat" />
+      </AppNav>
+      <Toaster />
+    </AssistantProvider>
+  </TooltipProvider>
+</ThemeProvider>
+```
+
+- Lists: `SectionedList` (`TaskRow` rows); when the agent or a bulk action changes data, confirm with `toastUndo`.
+- In the assistant thread, each action it took is an `ActionReceipt` with Undo (append it from `onSend`).
+- Settings and setup flows leave the frame: `FocusLayout` around `SettingsSection`s of `SettingsRow`s.
+- Members, lists and calendars take a `category-1..6` color; status colors never double as categories.
+- Live example: `playground/screens/household.tsx` (`#household`) and `settings.tsx` (`#settings`).
+
 ## Theme
 
 | Export          | Use                                                                                                                                                                                                                                                                             |
@@ -57,6 +87,7 @@ Every component in the shadcn registry is included. (shadcn's `form` item is an
 | Carousel         | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `useCarousel`, type `CarouselApi`                                                                                                                                                                                                                                                                                                                                         | embla.                                                                                                                                                                                                                                                                                                                                                                    |
 | Chart            | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`                                                                                                                                                                                                                                                                                                                                                   | Recharts wrappers. Prefer `TrendChart` for line/area; use these for custom charts.                                                                                                                                                                                                                                                                                        |
 | Checkbox         | `Checkbox`                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                                                                                                                                                                                                                                                                                                                           |
+| Check circle     | `CheckCircle`                                                                                                                                                                                                                                                                                                                                                                                                                                                | harebear. 24px round checkbox for to-do rows (44px touch target), pops when ticked. `tone="important"` tints it; pair with a word. Name it with `aria-labelledby` the row title.                                                                                                                                                                                          |
 | Collapsible      | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`                                                                                                                                                                                                                                                                                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                           |
 | Combobox         | `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxGroup`, `ComboboxLabel`, `ComboboxCollection`, `ComboboxEmpty`, `ComboboxSeparator`, `ComboboxChips`, `ComboboxChip`, `ComboboxChipsInput`, `ComboboxTrigger`, `ComboboxValue`, `useComboboxAnchor`                                                                                                                                                                 | Searchable select (Base UI). `<Combobox items={list}>` + `<ComboboxList>{(item) => <ComboboxItem value={item}>…}</ComboboxList>`. Chips for multi-select.                                                                                                                                                                                                                 |
 | Command          | `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandShortcut`, `CommandSeparator`                                                                                                                                                                                                                                                                                                              | Use for ⌘K palettes.                                                                                                                                                                                                                                                                                                                                                      |
@@ -98,7 +129,7 @@ Every component in the shadcn registry is included. (shadcn's `form` item is an
 | Table            | `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`                                                                                                                                                                                                                                                                                                                                                     | Borderless rows with rounded hover; quiet 12px headers. `data-state="selected"` tints a row.                                                                                                                                                                                                                                                                              |
 | Tabs             | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `tabsListVariants`                                                                                                                                                                                                                                                                                                                                                                                         | `TabsList variant`: `default` (segmented control), `pill` (rounded top-level nav), `line`. Use `Tabs` as a segmented filter too (date ranges, status filters).                                                                                                                                                                                                            |
 | Textarea         | `Textarea`                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Same filled style as `Input`, auto-grows.                                                                                                                                                                                                                                                                                                                                 |
-| Toast            | `Toaster`                                                                                                                                                                                                                                                                                                                                                                                                                                                    | sonner. Mount once; call `toast("Saved")` from `sonner`. Follows the theme mode.                                                                                                                                                                                                                                                                                          |
+| Toast            | `Toaster`                                                                                                                                                                                                                                                                                                                                                                                                                                                    | sonner. Mount once; call `toast("Saved")` from `sonner`. Follows the theme mode. `toastUndo(message, { onUndo, undoLabel?, duration = 9000 })` shows an Undo toast for something already done.                                                                                                                                                                            |
 | Toggle           | `Toggle`, `toggleVariants`, `ToggleGroup`, `ToggleGroupItem`                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                           |
 | Tooltip          | `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent`                                                                                                                                                                                                                                                                                                                                                                                             | Mount `TooltipProvider` once near the root.                                                                                                                                                                                                                                                                                                                               |
 | Trace            | `Trace`, `TraceLine`, `TraceIcon`, `TraceTitle`, `TraceDescription`, `TraceCollapsible`, `TraceCollapsibleTrigger`, `TraceCollapsibleContent`                                                                                                                                                                                                                                                                                                                | Agent step log (searched, read, ran). `TraceLine status`: `running` (shimmer), `error`, `pending`.                                                                                                                                                                                                                                                                        |
@@ -242,6 +273,72 @@ Quiet note with an icon (sparkle by default). Props: `icon?`, `tone?` (`"muted"
 
 Muted tile that lifts on hover, for service launchers. Props: `title`, `subtitle?` (mono), `icon?`, `status?: { tone; label }`, `href`, or `asChild` with your router `<Link>` as the only child.
 
+### `AppNav`
+
+One nav config, two renderings: on desktop a `SidebarLayout` sidebar (brand, action button, places, one collapsible group, footer; active place is a raised card; collapses to the icon rail), under 768px a bottom tab bar (first 5 places, 56px targets, `aria-current="page"`) plus a round floating action button. Use it instead of `AppShell` for consumer apps that need phone navigation.
+
+Props: `places: AppNavPlace[]` (`label`, `icon?`, `href?` or `onSelect?`, `active?`, `count?`, `tab?: false` to keep out of the tab bar), `group?: AppNavGroup` (`label`, `items`, `defaultOpen?`, `onAdd?`, `addLabel?`), `action?: { label; icon; onSelect }`, `brand?`, `footer?` (usually `UserMenu`), `label?` (nav name, default "Main"), `linkComponent?`, `collapsible?`, `storageKey?`, `defaultOpen?`, `width?`, `children`.
+On phones the group and footer live in the sidebar sheet: put a `SidebarTrigger` in the page header if users need them there. Render `AssistantDock` inside `children` so it clears the tab bar, and mount `<Toaster mobileOffset={{ bottom: "5.5rem" }} />` so toasts do too.
+
+### `FocusLayout`
+
+A page outside the app frame (settings, onboarding, setup): slim sticky top bar, one centred column. Props: `title?`, `back?` (close or back link; icon-only needs `aria-label`), `actions?`, `width?` (`sm | md | lg`, default `md` = 42rem).
+
+### `SettingsSection`, `SettingsRow`
+
+`SettingsSection`: card with `title`, `description?` and rows divided by hairlines (a labelled `region`). `SettingsRow`: `label`, `description?`, `control?` (Switch, Select, ToggleGroup, Button), `htmlFor?` (makes the label a `<label>` for the control). Add `content` to expand inline (change password, add a connection): without a `control` the row gets a "Change"/"Cancel" button (`expandLabel?`); control it with `open`/`onOpenChange` or `defaultOpen`.
+
+```tsx
+;<FocusLayout
+  title="Settings"
+  back={
+    <Button asChild variant="ghost" size="icon">
+      <a href="/" aria-label="Close">
+        <XIcon />
+      </a>
+    </Button>
+  }
+>
+  <SettingsSection title="Notifications">
+    <SettingsRow
+      label="Daily summary"
+      description="Every morning at 7"
+      htmlFor="daily"
+      control={<Switch id="daily" />}
+    />
+    <SettingsRow label="Password" content={<ChangePasswordForm />} />
+  </SettingsSection>
+</FocusLayout>
+```
+
+## Layout and text
+
+Props instead of class names, for blocks that should look right without styling (dashboard widgets, generated UI). Every class string is a literal, so Tailwind finds them.
+
+### `Stack`, `Row`, `Grid`
+
+`Stack` stacks children vertically, `Row` lays them out horizontally (`align`, `justify`, `wrap`). Both take a named `gap`: `none | xs | sm | md | lg | xl`. `Grid` makes equal columns: `cols={3}` or `cols={{ base: 1, sm: 2, md: 3 }}`. With `query="container"` the breakpoints measure the nearest `@container` ancestor (sm 28rem, md 42rem, lg 56rem) instead of the screen, for blocks that sit in cards of any width.
+
+### `Text`, `Heading`
+
+`Text` takes `size` (`xs | sm | base | lg | xl | 2xl`), `tone` (`default | muted | success | warning | danger | info`), `weight`, `mono`, `truncate`, `lines` (1 to 3) and `tabular`, and renders `as` a span, p or div. `Heading` is a card section title (`level={3}`) or a small uppercase group label (`level={4}`).
+
+### `Metric`, `MetricGroup`
+
+A number with `value`, `unit`, `label` and an optional `delta` in percent, green when it improves (`lowerIsBetter` for latency and the like). `MetricGroup` sets metrics side by side, evenly spaced.
+
+### `MediaItem`
+
+Thumbnail (`image`, `imageShape`: `poster | square | wide`), a two-line `title` (linked when `href` is set, new tab), a `meta` line and a two-line `description`.
+
+### `ShowMore`
+
+Shows the first `initial` children (default 5) and a "Show N more" button for the rest.
+
+### `Collapse`
+
+Animates children between full height and 0 (CSS `grid-template-rows`), so neighbours slide instead of jumping. Closed content is `inert` and `aria-hidden`. Props: `open`, `contentClassName?`. No motion under `prefers-reduced-motion`.
+
 ## Data display
 
 ### `DataTable`
@@ -286,6 +383,23 @@ Tiny trend line. Props: `data: number[]`, `color?`, `area?` (fill, default true)
 
 Mini bar history (pings, uptime). Props: `data: (number | { value; tone?; label? })[]`, `max?`, `tone?` (default for plain numbers). Default size 96x26.
 
+### `TaskRow`
+
+One to-do: `CheckCircle` aligned with the first line, title, one meta line, optional assignee avatar. Props: `title`, `checked`, `onCheckedChange(checked)`, `meta?`, `assignee?: { name; avatarUrl? }`, `important?` (say it in `meta` too), `onOpen?` (title becomes a button, e.g. to open a sheet), `disabled?`.
+
+### `SectionedList`
+
+A to-do list: one add box at the top, sections with headings, done items folded into a "Show N done" toggle, an empty state. A ticked row stays visible for a moment, then folds away with `Collapse`. Props: `sections: { id; title?; items: SectionedListItem[] }[]` (item: `id`, `title`, `meta?`, `done?`, `important?`, `assignee?`), `onToggle(id, done)`, `onAdd?(text)`, `addPlaceholder?` (default "Add a to-do"), `onOpen?(id)`, `empty?`, `defaultShowDone?`.
+
+```tsx
+;<SectionedList
+  sections={[{ id: "today", title: "Today", items: todos }]}
+  onToggle={(id, done) => setDone(id, done)}
+  onAdd={addTodo}
+  empty={<Empty title="All clear" />}
+/>
+```
+
 ## AI and chat
 
 A chat screen is `ChatShell` (sidebar with `AppBrand`, `NewConversationButton`, `ConversationList`, `UserMenu`; optional details panel) around a `ChatPanel` (header, thread, `PromptInput`). Agent apps add `ToolGroup`/`ToolStep` for tool calls and `ApprovalCard`/`ApprovalResult` for permission prompts. See `playground/screens/chat.tsx` and `playground/screens/agent.tsx`.
@@ -414,6 +528,27 @@ Agent tool calls as a bordered, collapsible card. `ToolStatus = "queued" | "wait
 `ApprovalCard`: warning-ringed card for anything the agent waits on the user for. Props: `title`, `description?`, `icon?` (default shield, `null` for none), `reason?` (shown first after a bold "Why:"), `code?` + `codeLabel?` (wrapped code block with copy), `actions?` (buttons), `footer?`, `children` (more body).
 `ApprovalResult`: one-line record in the thread. Props: `decision: "approved" | "denied"`, `time?`, `children`.
 
+### `AssistantProvider`, `useAssistant`, `useAssistantPage`
+
+One assistant conversation across pages. `AssistantProvider` props: `onSend(text, { page, messages, append, update })` (return the reply, or `append`/`update` messages yourself for streaming and receipts; a thrown error becomes the reply), `initialMessages?`, `defaultOpen?`. `useAssistant()` returns `{ open, setOpen, toggle, messages, pending, page, setPage, send, append, update, clear }`. A page calls `useAssistantPage({ id, title?, data?, suggestions? })` to become the context while mounted.
+
+### `AssistantDock`
+
+The assistant as a floating panel over the page (never reflows it): header (icon, title, full-screen link, close), empty state with suggestions, thread, `AskBox`. Closed, it is a soft launcher button. Escape closes and returns focus to the launcher. Props: `title?` (default "Assistant"), `icon?`, `fullScreenHref?`, `emptyTitle?`, `emptyDescription?`, `suggestions?` (default: the page's), `placeholder?`, `dictation?`, `launcher?` (false when another control opens it), `launcherLabel?`.
+
+### `AskBox`
+
+Large rounded composer: auto-growing text, `chips` shown while there is text, suggestion pills, `DictationButton`. The focus ring is on the box (`focus-box`). Props: `value`, `onValueChange`, `onSubmit(text)`, `placeholder?` (also the label, default "Ask anything"), `chips?`, `suggestions?`, `onSuggestion?` (default submits), `dictation?` (`SpeechSource`, or `false` to hide the mic), `lang?`, `disabled?`.
+
+### `DictationButton`, `useDictation`, `browserSpeechSource`
+
+`DictationButton`: one round button that is a mic when the text is empty, stop with listening bars while listening (announces "Listening" politely), send once there is text. Props: `value`, `onTranscript(text)`, `onSend?` (else it submits the form), `source?`, `lang?`, `disabled?`. Without a supported source the mic is hidden.
+`SpeechSource` is `{ isSupported(); start(handlers, { lang }) => stop }`; `browserSpeechSource` (default) uses the Web Speech API. `useDictation({ source?, lang?, onTranscript })` returns `{ supported, listening, interim, error, start, stop }` for custom controls.
+
+### `ActionReceipt`
+
+What the assistant did, as a compact card: round check, `title` (past tense), `meta?`, Undo (`onUndo?`, `undoLabel?`). `undone` strikes it through and shows "Undone".
+
 ### `CodeSnippet`, `InlineCode`, `Prose`
 
 `CodeSnippet`: one-prop code panel with language label, copy button and shiki syntax highlighting (each language loads on first use). Props: `code`, `language?` (`bash`, `tsx`, `ts`, `js`, `json`, `python`, `sql`, `yaml`, `css`, `html`, `markdown`, `diff`; others render plain), `highlight?` (default true), `lineNumbers?`, `hideCopy?`. Built on the `CodeBlock` primitives; drop to those for diffs or highlighted lines.
@@ -462,34 +597,38 @@ Props: `onSubmit?({ name?, email, password })`, `nameField?` (default true), `co
 
 ## Hooks and utilities
 
-| Export                                                       | Use                                                                                                        |
-| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `useCopyToClipboard(resetMs?)`                               | `{ copied, copy(text) }` for copy buttons.                                                                 |
-| `useHighlightedCode(code, language)`                         | Shiki-highlighted lines (one node per line) for custom `CodeBlock`s; plain lines until the language loads. |
-| `loadHighlighter(language)`, `highlightCode(code, language)` | Async shiki access outside React.                                                                          |
-| `useIsMobile()`                                              | `true` under 768px.                                                                                        |
-| `useMediaQuery(query)`                                       | `true` while the media query matches; `false` during SSR.                                                  |
-| `cn(...classes)`                                             | clsx + tailwind-merge. Use for every `className` you compose.                                              |
+| Export                                                              | Use                                                                                                                                                     |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useCopyToClipboard(resetMs?)`                                      | `{ copied, copy(text) }` for copy buttons.                                                                                                              |
+| `useHighlightedCode(code, language)`                                | Shiki-highlighted lines (one node per line) for custom `CodeBlock`s; plain lines until the language loads.                                              |
+| `loadHighlighter(language)`, `highlightCode(code, language)`        | Async shiki access outside React.                                                                                                                       |
+| `useIsMobile()`                                                     | `true` under 768px.                                                                                                                                     |
+| `useAssistant()`, `useAssistantPage(page)`, `useDictation(options)` | See [`AssistantProvider`](#assistantprovider-useassistant-useassistantpage) and [`DictationButton`](#dictationbutton-usedictation-browserspeechsource). |
+| `useMediaQuery(query)`                                              | `true` while the media query matches; `false` during SSR.                                                                                               |
+| `cn(...classes)`                                                    | clsx + tailwind-merge. Use for every `className` you compose.                                                                                           |
 
 ## Tokens
 
 Use these as Tailwind utilities (`bg-*`, `text-*`, `border-*`, `ring-*`, `fill-*`, `stroke-*`):
 
-| Token                               | Use                                                                                               |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `background` / `foreground`         | Page background and body text.                                                                    |
-| `card` / `card-foreground`          | Raised surfaces (cards, active nav item, popovers via `popover`).                                 |
-| `muted` / `muted-foreground`        | Inputs, segmented controls, quiet panels; secondary text and labels.                              |
-| `primary` / `primary-foreground`    | Brand accent (from `--brand`). Primary buttons, links, chart line.                                |
-| `primary-soft`                      | Tinted primary background for selected rows, soft badges, icon circles. Pair with `text-primary`. |
-| `secondary`, `accent`               | Same as muted; kept for shadcn compatibility.                                                     |
-| `success`, `warning`, `destructive` | Status colors. Use `bg-success/12 text-success` for soft status fills.                            |
-| `border`, `input`, `ring`           | Hairlines, input borders, focus rings.                                                            |
-| `chart-1` … `chart-5`, `chart-grid` | Data series and gridlines.                                                                        |
-| `sidebar-*`                         | Sidebar surfaces (default to the page tokens).                                                    |
+| Token                               | Use                                                                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `background` / `foreground`         | Page background and body text.                                                                          |
+| `card` / `card-foreground`          | Raised surfaces (cards, active nav item, popovers via `popover`).                                       |
+| `muted` / `muted-foreground`        | Inputs, segmented controls, quiet panels; secondary text and labels.                                    |
+| `primary` / `primary-foreground`    | Brand accent (from `--brand`). Primary buttons, links, chart line.                                      |
+| `primary-soft`                      | Tinted primary background for selected rows, soft badges, icon circles. Pair with `text-primary`.       |
+| `secondary`, `accent`               | Same as muted; kept for shadcn compatibility.                                                           |
+| `success`, `warning`, `destructive` | Status colors. Use `bg-success/12 text-success` for soft status fills.                                  |
+| `border`, `input`, `ring`           | Hairlines, input borders, focus rings.                                                                  |
+| `chart-1` … `chart-5`, `chart-grid` | Data series and gridlines.                                                                              |
+| `category-1` … `category-6`         | Members, lists, calendars: blue, teal, violet, rose, slate, cyan, each with a dark value. Never status. |
+| `sidebar-*`                         | Sidebar surfaces (default to the page tokens).                                                          |
 
 Other theme values: `rounded-sm/md/lg/xl/2xl` scale from `--radius` (default 14px; cards use `xl`, buttons and inputs `md`), `shadow-card` (the one elevation), `font-sans` (Geist), `font-mono` (Geist Mono), `animate-typing`.
 
+Utilities: `focus-box` gives the box around a bare field the focus ring (primary border, card fill, 4px halo); pair it with `border border-transparent bg-muted`. `animate-check-pop` and `animate-listening` are the check and dictation animations. All motion is off under `prefers-reduced-motion`.
+
 Override any token in your CSS after the import:
 
 ```css

package/docs/ROADMAP.md

@@ -0,0 +1,95 @@
+# Roadmap: components for household and agent-first apps
+
+Status: the "Build first" list shipped in 0.8.0 (2026-11-11). Everything else is still proposed. Built items name their exports; see `docs/COMPONENTS.md` and the "Agent-first apps" recipe there.
+
+These come from designing Homeclub, a household app with shared to-dos, calendars, docs and an assistant (HomeBot) on every page. The design and its notes live in the `HMilbradt/homeclub` repository (`design/`, `docs/missing-components.md`, `docs/research/`). Everything below was drawn there as plain markup with harebear-ui tokens. The aim is that the next app like it needs none of that markup: the library covers the common cases.
+
+Judged against harebear-ui 0.7.0 (`src/components/`). Props of existing components were not checked one by one; an item marked "extends" may already be partly covered.
+
+## Reuse before building
+
+These already exist and the Homeclub designs map onto them; new work should extend them, not fork them.
+
+SidebarLayout, AppShell, UserMenu, ChatShell, ChatMessage, PromptInput, ConversationList, ToolSteps, TypingIndicator, ApprovalCard, Sheet, Drawer, Dialog, Popover, Sonner (Toaster), ToggleGroup, Tabs, Calendar, Empty, Avatar, Badge, Status, LinkTile, CopyField, Prose, AuthLayout.
+
+## Build first
+
+Most reuse across apps, and Homeclub needs each on day one.
+
+All built in 0.8.0:
+
+1. **AppNav** (`AppNav`, types `AppNavPlace`, `AppNavGroup`, `AppNavAction`): one config, desktop sidebar on SidebarLayout and a phone tab bar with a floating action button.
+2. **Assistant layer**: `AssistantProvider`, `useAssistant`, `useAssistantPage`, `AssistantDock`, `AskBox`, `DictationButton`, `useDictation`, `browserSpeechSource`, `ActionReceipt`.
+3. **Undo toast and motion**: `toastUndo` (Sonner), `Collapse`, `animate-check-pop`, all CSS and off under reduced motion.
+4. **Lists**: `CheckCircle`, `TaskRow`, `SectionedList`.
+5. **Settings**: `FocusLayout`, `SettingsSection`, `SettingsRow` (a settings page is FocusLayout plus sections; no separate SettingsLayout).
+6. **Foundations**: `category-1` to `category-6` tokens and the `focus-box` utility.
+
+Calendar views and SmartInput follow when a second app needs them.
+
+## 1. Layouts and app frame (`admin/` or `layout/`)
+
+| Component                            | What it does                                                                                                                                                                                                                                                                                        | Notes                                                      |
+| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------- |
+| AppNav (built)                       | Takes one config (places, a collapsible group such as Lists, an "add" action, the profile menu). Renders the desktop sidebar (no border, active item as a raised card, profile popover at the bottom, sticky on long pages) and, under a breakpoint, a bottom tab bar with one round action button. | Extends SidebarLayout and UserMenu. The phone half is new. |
+| FocusLayout (built)                  | A page outside the app frame: slim top bar with a close or back link and a title, then one centred column.                                                                                                                                                                                          | Settings, onboarding, setup flows.                         |
+| SettingsSection, SettingsRow (built) | Card with a heading; rows with label, one-line description and a control slot (switch, select, segmented control, button). Rows can expand inline (change password, add a connection).                                                                                                              | Most settings pages become composition only.               |
+| DetailSheet                          | A record's details: side sheet on desktop, full-screen sheet on a phone, with a close button and a scrollable body.                                                                                                                                                                                 | Extends Sheet and Drawer with one responsive API.          |
+| ReaderLayout                         | Back link, title, author and updated line, actions at the top (Edit, Chat with HomeBot), then Prose.                                                                                                                                                                                                | Docs, help, notes.                                         |
+| PageColumn                           | Centred column with a standard header slot (greeting or title, filter, primary input).                                                                                                                                                                                                              | Today, Upcoming, list pages.                               |
+| AuthLayout, single card variant      | Calm centred card with the product mark, for sign in, invite and first-run setup.                                                                                                                                                                                                                   | Extends AuthLayout.                                        |
+
+## 2. Assistant layer (`ai/`)
+
+| Component                               | What it does                                                                                                                                                                                                             | Notes                                             |
+| :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |
+| AssistantProvider (built)               | Holds the current conversation across pages and knows which page is open, so the assistant can use it as context.                                                                                                        | Hook: `useAssistant()`.                           |
+| AssistantDock (built)                   | Floating panel over the page (never reflows it) with header, empty state, thread, receipts and composer; a soft launcher button when closed; a link to full screen. Same on every page; pages pass suggestions only.     | Extends ChatShell.                                |
+| AskBox (built)                          | Large rounded input with chips that appear as you type, suggestion pills under it, and the dictation button. Focus ring on the box, not the field.                                                                       | One placeholder per app ("Ask HomeBot anything"). |
+| DictationButton, `useDictation` (built) | One button that is a microphone when empty, a stop button while listening (with listening bars and a live region), and send once there is text. The speech source plugs in (browser speech recognition, a server model). | Off-animation under reduced motion.               |
+| ActionReceipt (built)                   | What the assistant did, as a compact card: round check, title, one meta line, Undo. One per action.                                                                                                                      | The core of "safe actions run on their own".      |
+| WhatIDid                                | Collapsed list of plain past-tense steps under an answer.                                                                                                                                                                | A plain-language variant of ToolSteps.            |
+| ProgressCard                            | A long-running job: title, status word, progress bar, time left, an action when finished.                                                                                                                                | Downloads, imports, syncs.                        |
+| ChatsHome                               | Recent chats grouped Today, This week, Earlier, with search and a row menu (Rename, Delete with inline confirm).                                                                                                         | Extends ConversationList.                         |
+| CitationChip                            | Pill link to the source an answer used.                                                                                                                                                                                  |                                                   |
+| AssistantStatus                         | Working, needs you, done, shown on the launcher and in chat lists.                                                                                                                                                       |                                                   |
+
+## 3. Items, lists and calendar
+
+| Component                                  | What it does                                                                                                                           | Notes                                 |
+| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
+| CheckCircle (built)                        | 24px round check, top-aligned with the first line, a pop when ticked, an "important" tint paired with a word.                          | `ui/` primitive.                      |
+| TaskRow (built)                            | Check, title, one meta line, optional assignee avatar, opens a DetailSheet.                                                            | Works in any to-do or checklist app.  |
+| SectionedList (built)                      | Sections, one add box, finished items folded into "Show N done", empty state, items leaving without layout shift.                      | Uses the motion helpers below.        |
+| SmartInput                                 | A text input that turns phrases into removable chips; the app supplies the rules (dates, people, lists).                               | Shared by quick add and the AskBox.   |
+| AgendaRow, DayStrip, WeekScroll, MiniMonth | Time, icon or check, title and whose dot; a strip of day buttons that jump to a day; stacked days you scroll; a month with event dots. | Calendar today is a date picker only. |
+| SegmentedControl                           | Two or three options, raised selected segment (Mine / Everyone, Agenda / Week).                                                        | Restyle of ToggleGroup.               |
+| FilterChips, VisibilityBadge               | On/off chips; "Only you" with a lock or "Everyone" with faces.                                                                         |                                       |
+| InlineConfirm                              | A plain confirmation shown in place, for the few destructive actions that keep one.                                                    | Lighter than ConfirmDialog.           |
+| ChoiceCards                                | Two or three large side-by-side options (Google or Calendar link, Adult or Child).                                                     |                                       |
+| SearchHero, CardGrid                       | Big search box over a grid of LinkTiles grouped by topic.                                                                              |                                       |
+
+## 4. People
+
+| Component         | What it does                                                                                |
+| :---------------- | :------------------------------------------------------------------------------------------ |
+| MemberAvatar      | Photo, falling back to initial on the member's colour; sizes; ring variant. Extends Avatar. |
+| AvatarStack       | Overlapping faces with a "+N".                                                              |
+| AvatarUpload      | Upload, change or remove a photo with live preview.                                         |
+| ColorSwatchPicker | Radio group of category colours; colours used by someone else are marked and disabled.      |
+
+## 5. Feedback and motion
+
+| Item                  | What it does                                                                                                       | Notes                                                                                                                                                 |
+| :-------------------- | :----------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toastUndo()` (built) | Standard wrapper around Sonner: action label, Undo, 9 second window, pause on hover, stacking and entry animation. | Sonner is already the toast layer. Check its current API before building.                                                                             |
+| Motion helpers        | Check pop, collapse without layout shift, an optimistic list hook (`useOptimisticList`).                           | Built as CSS with no new dependency: `animate-check-pop`, `Collapse`. `useOptimisticList` is still proposed (React 19 `useOptimistic` may be enough). |
+| Celebration           | Occasional confetti when a day is cleared. Off under reduced motion.                                               | Candidate: canvas-confetti.                                                                                                                           |
+
+## 6. Foundations (`src/styles.css`)
+
+- **Category palette (built: `category-1..6`).** Six or so non-status colours for members, lists and calendars, each with a dark-mode value. Homeclub hard-codes hex values that stay the same in dark mode. Status colours (`success`, `warning`, `destructive`) must never double as category colours.
+- **Composite focus (built: `focus-box`).** A documented class or token for "the box around a bare field shows the focus ring" (`focus-within`), so apps stop working around inline styles.
+- **Size floors.** Checks 24px, phone touch targets 44px, no text under 12px. New components follow them; existing avatar initials and `kbd` are still 11px.
+- **Brand mark slot.** AppNav (`brand`) and AuthLayout (`brand`) take the product mark as a prop.
+- **Design canvas loading.** The design system artifact's README names `window.HarebearUI` but not which files to load on a Design canvas, so designs copy components as markup. Add a "Consuming this system" section listing the bundle and stylesheet.

package/docs/guides/agents.md

@@ -0,0 +1,75 @@
+# Working with AI agents
+
+harebear-ui is built to be used by coding agents (Claude Code, Codex, Cursor, Copilot and the like). The package ships its own instructions, so an agent in your repo knows which components exist, how to style them, and how to check its work, without you pasting docs into the prompt.
+
+![What init sets up for your agent](../../.github/assets/agents.webp)
+
+## What ships in the package
+
+| File (in `node_modules/harebear-ui/`) | What it is                                                                                    |
+| ------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `llms.txt`                            | Short index: setup, the styling rules, every export by group. Small enough to paste anywhere. |
+| `docs/COMPONENTS.md`                  | The catalog: every export with props, variants and examples. A test keeps it complete.        |
+| `docs/guides/`                        | These guides: setup per framework, theming, agents.                                           |
+| `skills/harebear-ui/SKILL.md`         | A Claude Code skill that loads whenever the agent builds or changes UI.                       |
+| `AGENTS.md`                           | Instructions for agents working on harebear-ui itself (not needed in your app).               |
+
+## Set up your repo
+
+```bash
+npx harebear-ui init
+```
+
+This writes two things your agent reads automatically:
+
+1. **A harebear-ui section in `AGENTS.md`** (or in `CLAUDE.md` if that file exists and `AGENTS.md` does not). It points at the catalog and states the rules: import from the package root, tokens only, check light and dark mode and phone width. The section sits between `<!-- harebear-ui:start -->` and `<!-- harebear-ui:end -->` markers, and running `init` again after an upgrade replaces it in place.
+2. **A Claude Code skill** at `.claude/skills/harebear-ui/SKILL.md`. Claude Code loads it on UI tasks; it adds the composition rules (which composite to use for which screen) and the visual checks.
+
+Commit both. Re-run `npx harebear-ui init` after upgrading harebear-ui to refresh them.
+
+### Per tool
+
+| Tool          | What it reads                                                                                                        |
+| ------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Claude Code   | `CLAUDE.md` and `.claude/skills/`. If your instructions live in `AGENTS.md`, add a line `@AGENTS.md` to `CLAUDE.md`. |
+| Codex, Cursor | `AGENTS.md`. See [agents.md](https://agents.md) for the tools that follow the convention.                            |
+| Anything else | Point it at `node_modules/harebear-ui/llms.txt` in your own instructions file.                                       |
+
+## Look things up instead of reading everything
+
+The full catalog is long. Agents (and you) can pull just the entries a task needs:
+
+```bash
+npx harebear-ui docs DataTable            # one export
+npx harebear-ui docs DataTable StatCard   # several
+npx harebear-ui docs Prompt               # every export starting with "Prompt"
+npx harebear-ui docs Tokens               # a whole section: Theme, Tokens, Auth, "AI and chat", ...
+npx harebear-ui docs                      # everything
+```
+
+A lookup prints the matching `###` sections, or the primitive's table row with its header. It exits with status 1 when nothing matches, so an agent notices a wrong name instead of guessing.
+
+## Prompts that work well
+
+The instructions already cover style rules, so prompts can stay about the product:
+
+- "Build a settings page with a profile card, a notifications card with switches, and a danger zone with a delete-account ConfirmDialog."
+- "Turn `orders.json` into an orders screen: DataTable with status badges, a detail panel when a row is clicked, and a KPI row above it."
+- "Make a chat UI for our support bot with a conversation list, tool calls shown as ToolSteps and approval prompts for refunds."
+- "Start from the admin reference screen and adapt it to our metrics endpoint."
+
+Pointing at a reference screen is the fastest way to a good result. The playground has six, built only from public exports: [`playground/screens/`](https://github.com/HMilbradt/harebear-ui/tree/main/playground/screens) (admin dashboard, AI chat, agent with approvals, records table with detail panel, status home, auth).
+
+## Review what the agent built
+
+Things to check before you accept a UI change:
+
+- **Both modes.** Toggle light and dark. Anything that only works in one used a palette color instead of a token.
+- **Phone width.** At 375px rows wrap, tables scroll inside their card, and the sidebar becomes a sheet.
+- **No forks.** The agent imported from `harebear-ui` rather than copying component source into the app.
+- **No color overrides.** `className` on harebear components is for layout. A `bg-*` or `text-*` color override on a library component means the agent hit a gap; ask it to report the gap instead.
+- **Accessible icons.** Icon-only buttons have an `aria-label`.
+
+## Working on harebear-ui itself
+
+Agents contributing to this repo should read [AGENTS.md](../../AGENTS.md) at the repo root. It covers the layout, the conventions for new components, the checks (`pnpm check`), and how to regenerate the README images (`pnpm shots`).