harebear-ui 0.7.0 → 0.8.1

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 {
   * {
@@ -210,3 +285,26 @@
     background-color: color-mix(in oklab, var(--muted-foreground) 60%, transparent);
   }
 }
+
+/* Toasts clear floating controls. AppNav (tab bar, action button) and AssistantDock (launcher) set --hb-toast-* on
+   <html> while mounted (src/lib/toast-clearance.ts); this adds them to Sonner's bottom offset. Unlayered and
+   !important because Sonner injects its own unlayered rule at runtime. Breakpoints: AppNav's tab bar shows under
+   768px; Sonner switches to full-width mobile toasts under 600px. */
+[data-sonner-toaster][data-y-position="bottom"] {
+  bottom: calc(var(--offset-bottom) + var(--hb-toast-launcher, 0px)) !important;
+}
+@media (max-width: 767px) {
+  [data-sonner-toaster][data-y-position="bottom"] {
+    bottom: calc(
+      var(--offset-bottom) + var(--hb-toast-nav, 0px) + var(--hb-toast-fab, 0px) + var(--hb-toast-launcher, 0px)
+    ) !important;
+  }
+}
+@media (max-width: 600px) {
+  [data-sonner-toaster][data-y-position="bottom"] {
+    bottom: calc(
+      var(--mobile-offset-bottom) + var(--hb-toast-nav, 0px) + var(--hb-toast-fab, 0px) +
+        var(--hb-toast-launcher, 0px)
+    ) !important;
+  }
+}

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,44 @@ 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. Toasts stack above the tab bar, the action button and the dock launcher on their own; no `Toaster` offset needed.
+
+### `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.
@@ -266,6 +335,10 @@ Thumbnail (`image`, `imageShape`: `poster | square | wide`), a two-line `title`
 
 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`
@@ -310,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`.
@@ -438,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.
@@ -486,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/theming.md

@@ -68,15 +68,16 @@ Use CSS rather than props when the first paint must be right (SSR apps): `ThemeP
 
 The full token list, with what each is for, is in the [component catalog](../COMPONENTS.md#tokens) (`npx harebear-ui docs Tokens`). The ones you will use most:
 
-| Token                               | Tailwind utilities                                |
-| ----------------------------------- | ------------------------------------------------- |
-| `background`, `foreground`          | `bg-background`, `text-foreground`                |
-| `card`                              | `bg-card` (raised surfaces)                       |
-| `muted`, `muted-foreground`         | `bg-muted` (inputs, quiet panels), secondary text |
-| `primary`, `primary-soft`           | `bg-primary`, `bg-primary-soft text-primary`      |
-| `success`, `warning`, `destructive` | `text-success`, `bg-success/12`, and so on        |
-| `border`                            | `border-border` (the default border color)        |
-| elevation                           | `shadow-card` (the one shadow)                    |
+| Token                               | Tailwind utilities                                        |
+| ----------------------------------- | --------------------------------------------------------- |
+| `background`, `foreground`          | `bg-background`, `text-foreground`                        |
+| `card`                              | `bg-card` (raised surfaces)                               |
+| `muted`, `muted-foreground`         | `bg-muted` (inputs, quiet panels), secondary text         |
+| `primary`, `primary-soft`           | `bg-primary`, `bg-primary-soft text-primary`              |
+| `success`, `warning`, `destructive` | `text-success`, `bg-success/12`, and so on                |
+| `category-1` … `category-6`         | `bg-category-2` (members, lists, calendars; never status) |
+| `border`                            | `border-border` (the default border color)                |
+| elevation                           | `shadow-card` (the one shadow)                            |
 
 ## Rules that keep a themed app consistent
 

package/llms.txt

@@ -13,7 +13,8 @@
 
 - Use harebear-ui components before writing new UI. Primitives keep shadcn/ui names and props.
 - Style with theme tokens only: bg-background, bg-card, bg-muted, text-muted-foreground, bg-primary, bg-primary-soft, text-success, text-warning, text-destructive, border-border, shadow-card, rounded-md/lg/xl. No hex colors or Tailwind palette colors.
-- Status is a tone: success | warning | danger | info | neutral.
+- Status is a tone: success | warning | danger | info | neutral. Members, lists and calendars use category-1..6 (bg-category-3), never status colors.
+- Agent-first apps (assistant on every page, undoable actions): AppNav + AssistantProvider/AssistantDock + SectionedList + toastUndo + FocusLayout/SettingsSection. Recipe: `npx harebear-ui docs "Agent-first apps"`.
 - Icons: lucide-react elements, e.g. `<SearchIcon />`. Icon-only buttons need aria-label.
 - Change the brand with `<ThemeProvider accent="#hex" radius={14}>` or `--brand` / `--radius` in CSS.
 
@@ -31,11 +32,13 @@
 ## Component index
 
 Theme: ThemeProvider, useTheme, ThemeToggle, ThemeScript
-Layout/admin: SidebarLayout, SidebarCollapseButton, AppShell, AppBrand, PageHeader, StatCard, SearchInput, StatusDot, StatusBadge, UsageMeter, ActivityFeed, Timeline, KeyValueGrid, UserChip, UserMenu, Callout, LinkTile, ConfirmDialog, CopyField
-Layout and text: Stack, Row, Grid, Text, Heading, Metric, MetricGroup, MediaItem, ShowMore
-Data: DataTable, createDataTableColumnHelper, TrendChart, TrendLegend, BarList, Sparkline, StatusBars
+Layout/admin: SidebarLayout, SidebarCollapseButton, AppShell, AppNav, FocusLayout, SettingsSection, SettingsRow, AppBrand, PageHeader, StatCard, SearchInput, StatusDot, StatusBadge, UsageMeter, ActivityFeed, Timeline, KeyValueGrid, UserChip, UserMenu, Callout, LinkTile, ConfirmDialog, CopyField
+Layout and text: Stack, Row, Grid, Text, Heading, Metric, MetricGroup, MediaItem, ShowMore, Collapse
+Data: TaskRow, SectionedList, DataTable, createDataTableColumnHelper, TrendChart, TrendLegend, BarList, Sparkline, StatusBars
+Assistant layer: AssistantProvider, useAssistant, useAssistantPage, AssistantDock, AskBox, DictationButton, useDictation, browserSpeechSource, ActionReceipt
 AI/chat composites: ChatShell, ChatPanel, ChatThread, ChatMessage, AssistantAvatar, MessageActions, PromptInput, PromptInputChip, PromptInputSelect, ModelPicker, ConversationList, NewConversationButton, groupByDate, formatWhen, ToolCall, ToolGroup, ToolStep, ToolStatusIcon, ApprovalCard, ApprovalResult, TypingIndicator, CodeSnippet, InlineCode, Prose
 AI/chat primitives (shadcn): Message, Bubble, MessageScroller, Attachment, Trace, Marker, Questionnaire, CodeBlock
 Auth: AuthLayout, LoginForm, SignupForm, GitHubIcon, GoogleIcon, AppleIcon
+Feedback: Toaster, toastUndo, CheckCircle
 Primitives (the full shadcn/ui registry): Accordion, Alert, AlertDialog, AspectRatio, Attachment, Avatar, Badge, Breadcrumb, Bubble, Button, ButtonGroup, Calendar, Card, Carousel, Chart, Checkbox, CodeBlock, Collapsible, Combobox, Command, ContextMenu, Dialog, DirectionProvider, Drawer, DropdownMenu, Empty, Field, HoverCard, Input, InputGroup, InputOTP, Item, Kbd, Label, Marker, Menubar, Message, MessageScroller, NativeSelect, NavigationMenu, Pagination, Popover, Progress, Questionnaire, RadioGroup, Resizable, ScrollArea, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Spinner, Switch, Table, Tabs, Textarea, Toaster, Toggle, ToggleGroup, Tooltip, Trace
 Hooks/utils: useCopyToClipboard, useHighlightedCode, useIsMobile, useMediaQuery, useSidebarOptional, cn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harebear-ui",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Opinionated, pre-themed shadcn/ui component library for React 19 + Tailwind CSS v4. Admin, data, and AI chat building blocks, ready for agents.",
   "license": "MIT",
   "author": "Harrison Milbradt",

package/skills/harebear-ui/SKILL.md

@@ -26,6 +26,7 @@ This project uses `harebear-ui` for all UI. Its theme, tokens, and components ar
 - DataTable columns: define with `createDataTableColumnHelper<Row>()` at module scope, pass `getRowId`.
 - Chat apps: `ChatShell` (sidebar: `AppBrand`, `NewConversationButton`, `ConversationList` + `groupByDate`, `UserMenu`; optional `details` panel) around a `ChatPanel` (title, actions, `notice`, `composer`). Don't hand-build the sidebar, rail or panel.
 - Chat content: `ChatMessage role="user" | "assistant"`; render model output inside `Prose`; composer is `PromptInput` (+ `PromptInputChip`, `PromptInputSelect`); code is `CodeSnippet`; agent tool calls are `ToolGroup`/`ToolStep` (or the lighter `Trace`); permission prompts are `ApprovalCard`/`ApprovalResult`; working state is `TypingIndicator label`; clarifying questions are `Questionnaire`.
+- Agent-first and household apps: `AppNav` (sidebar on desktop, tab bar on phones) around pages; `AssistantProvider` + `AssistantDock` (pages call `useAssistantPage`); `AskBox` with `DictationButton`; `ActionReceipt` for each action the agent took; `toastUndo` after undoable changes; to-dos are `SectionedList` / `TaskRow` / `CheckCircle`; settings are `FocusLayout` + `SettingsSection` + `SettingsRow`. Recipe: `npx harebear-ui docs "Agent-first apps"`. Categories (members, lists) use `category-1..6`.
 - Notices: `Alert variant="warning" | "success" | "info" | "destructive"`. Confirmations: `ConfirmDialog`. Copyable IDs: `CopyField`. Live status: `StatusDot`/`StatusBadge` with `pulse`.
 - If you need a className to fix spacing, color, wrapping or borders on a harebear component, that is a library gap: report it instead of overriding.
 - Sign-in and sign-up pages: `AuthLayout` + `LoginForm` / `SignupForm`. Don't hand-build auth forms.