@brijbyte/agentic-ui 0.0.1-beta → 0.0.1

package/README.md

@@ -0,0 +1,736 @@
+# @brijbyte/agentic-ui
+
+A developer-focused React component library with a macOS/iOS-inspired aesthetic. Built on top of [`@base-ui/react`](https://base-ui.com) for accessible behaviour, styled with CSS modules under `@layer` rules so every component style is overridable downstream.
+
+---
+
+## Design philosophy
+
+- **Monospace-first UI.** All chrome (buttons, labels, inputs, badges) uses a monospace font stack — feels native in developer tools and dashboards.
+- **Serif display font for headings.** Titles use Apple's "New York" serif with a graceful fallback chain, giving the macOS/iOS native feel.
+- **Semantic CSS custom properties.** Every visual value — colour, spacing, radius, shadow, easing — is a CSS variable. Dark mode and per-app theming are done by re-declaring variables, not by shipping a separate stylesheet.
+- **Generic styled parts.** Every complex component exports both a high-level wrapper _and_ individual styled primitives. You can swap in a raw `@base-ui/react` root while keeping the styled children — or the other way around.
+- **CSS-free JS output.** The built JavaScript never imports CSS. You import the stylesheet yourself, explicitly. This is standards-compliant and works with any bundler.
+- **Layered component styles.** Component CSS modules live in `@layer components`. Every module file begins with `@layer theme, base, components, utilities` — because bundlers like Vite can inject module CSS before the app's entry stylesheet loads. Without this per-file declaration the browser would see `@layer base` (from Tailwind's preflight) after `@layer components`, making preflight higher priority. The per-file declaration ensures the correct order is established whichever file the browser sees first.
+
+---
+
+## Installation
+
+```bash
+pnpm add @brijbyte/agentic-ui @base-ui/react react react-dom
+```
+
+Peer dependencies: `react ^19`, `react-dom ^19`.
+
+---
+
+## CSS setup
+
+### Without Tailwind
+
+**Option A — full bundle (simplest):** one import loads all tokens, resets, and component CSS:
+
+```ts
+// main.tsx / entry.ts
+import "@brijbyte/agentic-ui/styles";
+```
+
+```css
+@import "@brijbyte/agentic-ui/styles";
+```
+
+**Option B — per-component (smallest bundle):** import tokens + reset once, then add one `/<name>.css` import per component you actually use:
+
+```css
+@import "@brijbyte/agentic-ui/tokens";
+@import "@brijbyte/agentic-ui/reset";
+
+/* One line per component you use */
+@import "@brijbyte/agentic-ui/button.css";
+@import "@brijbyte/agentic-ui/dialog.css";
+@import "@brijbyte/agentic-ui/toast.css";
+```
+
+Every component has a plain `/<name>.css` subpath export. The JS and CSS are always separate explicit imports — the JS module never auto-injects CSS.
+
+### With Tailwind v4
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+
+@import "@brijbyte/agentic-ui/tokens";
+@import "@brijbyte/agentic-ui/reset";
+@import "@brijbyte/agentic-ui/tailwind-theme";
+```
+
+`tokens.css` declares `@layer theme, base, components, utilities` — the same order Tailwind v4 uses — so component styles in `@layer components` always beat preflight resets in `@layer base`, and Tailwind utilities in `@layer utilities` always beat component styles.
+
+After this, every token is available as a Tailwind utility class:
+
+| Token                  | Tailwind class             | CSS output                               |
+| ---------------------- | -------------------------- | ---------------------------------------- |
+| `--color-bg-base`      | `bg-bg-base`               | `background-color: var(--color-bg-base)` |
+| `--color-text-primary` | `text-text-primary`        | `color: var(--color-text-primary)`       |
+| `--color-border-base`  | `border-border-base`       | `border-color: var(--color-border-base)` |
+| `--color-accent`       | `bg-accent`, `text-accent` | references live CSS variable             |
+| `--font-mono`          | `font-mono`                | `font-family: var(--font-mono)`          |
+| `--font-display`       | `font-display`             | `font-family: var(--font-display)`       |
+| `--radius-md`          | `rounded-md`               | `border-radius: var(--radius-md)`        |
+| `--shadow-sm`          | `shadow-sm`                | `box-shadow: var(--shadow-sm)`           |
+
+Because `@theme inline` references live CSS variables (not baked-in values), **dark mode switches automatically** — no `dark:` prefix, no extra configuration.
+
+> The `tailwind-theme` file contains `@theme inline {}` which is a Tailwind directive, not plain CSS. It must be processed by your Tailwind pipeline (`@tailwindcss/vite` or `@tailwindcss/postcss`).
+
+### CSS layer order
+
+Every component CSS module file begins with:
+
+```css
+@layer theme, base, components, utilities;
+```
+
+This declaration appears at the top of each `.module.css` file rather than only in an entry stylesheet. The reason: bundlers like Vite inject CSS module files into the document asynchronously and potentially **before** the app's entry CSS (`styles.css`) loads. If a module file declares `@layer components { ... }` without first establishing the full order, the browser would later see `@layer base` from Tailwind's preflight and treat it as higher priority — causing preflight resets like `* { border: 0 solid }` to override component styles.
+
+By placing the full layer declaration in every module file, the correct cascade order is fixed whichever file the browser processes first:
+
+```
+@layer theme       ← Tailwind defaults
+@layer base        ← tokens + element resets + Tailwind preflight  (lowest priority)
+@layer components  ← component CSS modules   (beat base)
+@layer utilities   ← Tailwind utilities       (beat everything)
+```
+
+Subsequent declarations of the same order (from `tailwindcss`, `tokens.css`, or other files) are harmless — CSS only honours the **first** time each layer name appears in an ordering statement.
+
+### Dark mode
+
+Tokens adapt automatically via `prefers-color-scheme`. To override programmatically, set `data-theme` on `<html>`:
+
+```ts
+document.documentElement.dataset.theme = "light"; // force light
+document.documentElement.dataset.theme = "dark"; // follow OS again
+delete document.documentElement.dataset.theme; // follow OS again
+```
+
+---
+
+## Design tokens
+
+All tokens are CSS custom properties defined at `:root` under `@layer base`. Override any of them after importing the stylesheet.
+
+### Typography
+
+```css
+--font-display  "New York", "Iowan Old Style", "Palatino Linotype", Georgia, serif
+--font-mono     "Berkeley Mono", "JetBrains Mono", "Fira Code", "SF Mono", "Menlo", ui-monospace
+--font-sans     -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Arial
+```
+
+**`--font-display`** is used for `h1`–`h6` and prominent page titles.  
+**`--font-mono`** is used for all UI chrome — buttons, inputs, labels, badges, body text.
+
+### Colour roles (semantic, light + dark)
+
+Shadows are theme-aware — light mode uses low-opacity black shadows; dark mode automatically uses higher-opacity values so elevation is visible against dark surfaces.
+
+| Token                                                     | Role                                        |
+| --------------------------------------------------------- | ------------------------------------------- |
+| `--color-bg-base`                                         | Page background                             |
+| `--color-bg-elevated`                                     | Cards, popovers                             |
+| `--color-bg-overlay`                                      | Backdrop-blurred surfaces                   |
+| `--color-bg-sidebar`                                      | Sidebar / navigation panels                 |
+| `--color-surface-1/2/3`                                   | Layered surface hierarchy                   |
+| `--color-surface-hover/active/selected`                   | Interactive surface states                  |
+| `--color-text-primary/secondary/tertiary/disabled`        | Text hierarchy                              |
+| `--color-text-on-accent`                                  | Text on filled accent backgrounds           |
+| `--color-text-code`                                       | Inline code text                            |
+| `--color-border-base/strong/subtle`                       | Border hierarchy                            |
+| `--color-accent`                                          | macOS blue — solid interactive colour       |
+| `--color-accent-hover`                                    | Accent on hover                             |
+| `--color-accent-pressed`                                  | Accent on press                             |
+| `--color-accent-tint`                                     | Subtle accent fill (badges, soft buttons)   |
+| `--color-accent-tint-hover`                               | Tint on hover                               |
+| `--color-focus-ring`                                      | Focus ring colour (semi-transparent accent) |
+| `--color-success/warning/error/info-bg/border/text/solid` | Status colours                              |
+
+Dark mode is handled by `@media (prefers-color-scheme: dark)` and `[data-theme="dark"]` on `<html>`.
+
+### Spacing
+
+Full 4 px grid with no gaps. Tokens: `--space-px` (1px), `--space-0-5` (2px), `--space-1` (4px), `--space-1-5` (6px), `--space-2` (8px), `--space-2-5` (10px), `--space-3` (12px), `--space-4` (16px), `--space-5` (20px), `--space-6` (24px), `--space-7` (28px), `--space-8` (32px), `--space-9` (36px), `--space-10` (40px) … `--space-24` (96px).
+
+### Border radius
+
+`--radius-none`, `--radius-sm` (4px), `--radius-md` (6px), `--radius-lg` (8px), `--radius-xl` (10px), `--radius-2xl` (12px), `--radius-full` (9999px).
+
+### Border width
+
+`--border-width-base` (1px), `--border-width-medium` (1.5px), `--border-width-thick` (2px).
+
+### Shadows
+
+Theme-aware — defined inside the light/dark token blocks so they adapt automatically.
+
+`--shadow-xs/sm/md/lg/xl`, `--shadow-popover` (dropdown/tooltip), `--shadow-focus` (two-layer ring: offset gap + coloured ring), `--shadow-inset`.
+
+`--shadow-focus` uses a two-layer technique: `0 0 0 2px --color-bg-base, 0 0 0 4px --color-focus-ring`. The inner ring punches a gap in the page background colour, making the focus ring clearly visible on any background — light or dark.
+
+### Animation
+
+```css
+/* Durations */
+--duration-fast    100ms
+--duration-normal  150ms
+--duration-slow    200ms
+--duration-slower  300ms
+
+/* Easings — use the right one for the job */
+--easing-ease-out  cubic-bezier(0, 0, 0.2, 1)    /* entering elements — starts fast */
+--easing-ease-in   cubic-bezier(0.4, 0, 1, 1)    /* exiting elements  — ends fast  */
+--easing-standard  cubic-bezier(0.4, 0, 0.2, 1)  /* on-screen movement / morphing  */
+--easing-spring    cubic-bezier(0.34, 1.56, 0.64, 1) /* playful / physics-based    */
+--easing-linear    linear                         /* constant motion (spinners, progress) */
+```
+
+### Z-index scale
+
+`--z-dropdown` (100), `--z-sticky` (200), `--z-overlay` (300), `--z-modal` (400), `--z-popover` (500), `--z-toast` (600), `--z-tooltip` (700).
+
+---
+
+## Package exports
+
+```
+@brijbyte/agentic-ui                 ← barrel (all components + StylesObjects)
+
+CSS bundles
+@brijbyte/agentic-ui/styles          ← full bundle: tokens + reset + all components
+@brijbyte/agentic-ui/tokens          ← CSS custom properties only (required)
+@brijbyte/agentic-ui/reset           ← element resets only (required)
+@brijbyte/agentic-ui/tailwind-theme  ← @theme inline block for Tailwind v4
+
+Per-component JS  (also exports <Name>Styles class-name map)
+@brijbyte/agentic-ui/accordion       @brijbyte/agentic-ui/menu
+@brijbyte/agentic-ui/badge           @brijbyte/agentic-ui/number-field
+@brijbyte/agentic-ui/button          @brijbyte/agentic-ui/progress
+@brijbyte/agentic-ui/card            @brijbyte/agentic-ui/select
+@brijbyte/agentic-ui/checkbox        @brijbyte/agentic-ui/separator
+@brijbyte/agentic-ui/collapsible     @brijbyte/agentic-ui/switch
+@brijbyte/agentic-ui/dialog          @brijbyte/agentic-ui/tabs
+@brijbyte/agentic-ui/drawer          @brijbyte/agentic-ui/toast
+@brijbyte/agentic-ui/input           @brijbyte/agentic-ui/tooltip
+
+Per-component CSS  (/<name>.css mirrors each JS subpath)
+@brijbyte/agentic-ui/accordion.css   @brijbyte/agentic-ui/menu.css
+@brijbyte/agentic-ui/badge.css       @brijbyte/agentic-ui/number-field.css
+@brijbyte/agentic-ui/button.css      @brijbyte/agentic-ui/progress.css
+@brijbyte/agentic-ui/card.css        @brijbyte/agentic-ui/select.css
+@brijbyte/agentic-ui/checkbox.css    @brijbyte/agentic-ui/separator.css
+@brijbyte/agentic-ui/collapsible.css @brijbyte/agentic-ui/switch.css
+@brijbyte/agentic-ui/dialog.css      @brijbyte/agentic-ui/tabs.css
+@brijbyte/agentic-ui/drawer.css      @brijbyte/agentic-ui/toast.css
+@brijbyte/agentic-ui/input.css       @brijbyte/agentic-ui/tooltip.css
+```
+
+---
+
+## Components
+
+Each component is available at its own deep-import path for tree-shaking:
+
+```ts
+import { Button } from "@brijbyte/agentic-ui/button";
+import { Dialog, DialogPopup, DialogTitle } from "@brijbyte/agentic-ui/dialog";
+```
+
+Or import everything from the barrel (convenient for prototyping):
+
+```ts
+import { Button, Dialog, Input } from "@brijbyte/agentic-ui";
+```
+
+### Component list
+
+| Import path     | High-level wrapper                                  | Styled parts                                                                                                                                                                                          |
+| --------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/accordion`    | `Accordion`                                         | `AccordionItemPart`, `AccordionHeader`, `AccordionTrigger`, `AccordionPanel`                                                                                                                          |
+| `/badge`        | `Badge`                                             | —                                                                                                                                                                                                     |
+| `/button`       | `Button`                                            | —                                                                                                                                                                                                     |
+| `/card`         | `Card`, `CardHeader`, `CardBody`, `CardFooter`      | —                                                                                                                                                                                                     |
+| `/checkbox`     | `Checkbox`                                          | `CheckboxRoot`, `CheckboxIndicator`                                                                                                                                                                   |
+| `/collapsible`  | `Collapsible`                                       | `CollapsibleRoot`, `CollapsibleTrigger`, `CollapsiblePanel`                                                                                                                                           |
+| `/dialog`       | `Dialog`                                            | `DialogBackdrop`, `DialogViewport`, `DialogPopup`, `DialogTitle`, `DialogDescription`, `DialogClose`                                                                                                  |
+| `/drawer`       | `Drawer`                                            | `DrawerBackdrop`, `DrawerViewport`, `DrawerPopup`, `DrawerContent`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`, `DrawerHandleBar`, `DrawerFooter`                                              |
+| `/input`        | `Input`                                             | —                                                                                                                                                                                                     |
+| `/menu`         | `Menu`                                              | `MenuPositioner`, `MenuPopup`, `MenuItem`, `MenuSeparator`, `MenuGroupLabel`, `MenuArrow`, `MenuItemShortcut`                                                                                         |
+| `/number-field` | `NumberField`                                       | `NumberFieldGroup`, `NumberFieldInput`, `NumberFieldDecrement`, `NumberFieldIncrement`, `NumberFieldScrubArea`, `NumberFieldScrubAreaCursor`                                                          |
+| `/progress`     | `Progress`                                          | `ProgressTrack`, `ProgressIndicator`                                                                                                                                                                  |
+| `/select`       | `Select`                                            | `SelectTrigger`, `SelectValue`, `SelectPositioner`, `SelectPopup`, `SelectList`, `SelectItem`, `SelectItemText`, `SelectItemIndicator`, `SelectGroupContainer`, `SelectGroupLabel`, `SelectSeparator` |
+| `/separator`    | `Separator`                                         | —                                                                                                                                                                                                     |
+| `/switch`       | `Switch`                                            | `SwitchRoot`, `SwitchThumb`                                                                                                                                                                           |
+| `/tabs`         | `Tabs`                                              | `TabsList`, `TabsTab`, `TabsPanel`                                                                                                                                                                    |
+| `/toast`        | `ToastViewport`, `ToastProvider`, `useToastManager` | `ToastRoot`, `ToastTitle`, `ToastDescription`, `ToastClose`, `ToastViewportPart`                                                                                                                      |
+| `/tooltip`      | `Tooltip`                                           | `TooltipPositioner`, `TooltipPopup`, `TooltipArrow`                                                                                                                                                   |
+
+Every deep-import path also exports a `<ComponentName>Styles` object — the CSS module class name map. See [Accessing class names](#accessing-class-names).
+
+---
+
+## Usage patterns
+
+### High-level wrapper (batteries included)
+
+```tsx
+import "@brijbyte/agentic-ui/styles";
+import { Button } from "@brijbyte/agentic-ui/button";
+import { Dialog } from "@brijbyte/agentic-ui/dialog";
+
+<Button variant="solid" tone="primary" size="md">Deploy</Button>
+
+<Dialog
+  trigger={<Button>Open settings</Button>}
+  title="API Settings"
+  description="Configure your endpoint."
+  footer={<Button size="sm">Save</Button>}
+>
+  <Input placeholder="https://api.example.com" />
+</Dialog>
+```
+
+### Composed: raw base-ui root + styled parts
+
+Use a raw `@base-ui/react` Root for full control over behaviour (controlled state, custom refs, delays), while keeping all the pre-styled child parts:
+
+```tsx
+import * as BaseDialog from "@base-ui/react/dialog";
+import { DialogBackdrop, DialogViewport, DialogPopup, DialogTitle, DialogClose } from "@brijbyte/agentic-ui/dialog";
+
+<BaseDialog.Root open={open} onOpenChange={setOpen}>
+  <BaseDialog.Trigger render={<button>Open</button>} />
+  <BaseDialog.Portal>
+    <DialogBackdrop />
+    <BaseDialog.Viewport>
+      <DialogPopup>
+        <DialogTitle>Custom Dialog</DialogTitle>
+        <DialogClose aria-label="Close">✕</DialogClose>
+        {children}
+      </DialogPopup>
+    </BaseDialog.Viewport>
+  </BaseDialog.Portal>
+</BaseDialog.Root>;
+```
+
+The same pattern applies to every component with sub-parts.
+
+### Overriding component styles
+
+Every styled part accepts `className`. Add your own classes — they append after the built-in ones. Because component styles live in `@layer components`, any `@layer utilities` rule or unlayered rule you write will win in the cascade.
+
+```tsx
+<Button className="my-custom-button">Click</Button>
+```
+
+```css
+/* utility class → beats @layer components */
+.my-custom-button {
+  border-radius: 0;
+}
+```
+
+### Overriding tokens
+
+Re-declare any CSS variable after importing the library stylesheet:
+
+```css
+@import "@brijbyte/agentic-ui/styles";
+
+:root {
+  --font-mono: "Cascadia Code", monospace; /* swap the mono font */
+  --color-accent: #7c3aed; /* purple accent instead of blue */
+  --radius-md: 2px; /* sharper corners */
+}
+```
+
+### Accessing class names
+
+Every deep-import path exports a `<ComponentName>Styles` object — the CSS module class name map. Keys are the local names from source, values are the hashed runtime names. Useful for tests, runtime class lookups, or extending styles:
+
+```ts
+import { ButtonStyles } from "@brijbyte/agentic-ui/button";
+
+// In a test — assert a class was applied
+expect(el.className).toContain(ButtonStyles.root);
+
+// At runtime — read the hashed name
+const solidClass = ButtonStyles["variant-solid"]; // → "variant-solid_a1b2c3d4"
+```
+
+---
+
+## Components reference
+
+### Button
+
+```tsx
+import { Button } from "@brijbyte/agentic-ui/button";
+
+// variant: solid | soft | outline | ghost
+// tone:    primary | secondary | destructive | success | warning
+// size:    xs | sm | md | lg
+<Button variant="solid" tone="primary" size="md">Deploy</Button>
+<Button variant="soft" tone="destructive">Delete</Button>
+<Button variant="outline" size="sm" loading>Saving…</Button>
+<Button variant="ghost" loading loadingText="Deploying…">Deploy</Button>
+<Button variant="soft" nativeButton={false} render={<a href="/docs" />}>Docs</Button>
+```
+
+**`variant`** controls visual shape — `solid` (filled), `soft` (tinted), `outline` (bordered), `ghost` (borderless).
+
+**`tone`** controls semantic colour — any tone works with any variant:
+
+| Tone          | Use case                        |
+| ------------- | ------------------------------- |
+| `primary`     | Default. Primary action         |
+| `secondary`   | Neutral / less prominent action |
+| `destructive` | Irreversible / dangerous action |
+| `success`     | Confirm / complete action       |
+| `warning`     | Caution required                |
+
+**`loading`** disables the button and shows a centred spinner. The button width stays stable — children are hidden with `visibility: hidden` so they still contribute to layout.
+
+**`loadingText`** overrides the stable-width behaviour. When set, children swap to this text during loading (no spinner). Use when the loading state needs to communicate progress via text.
+
+**`render`** passes through to `@base-ui/react` Button's `render` prop — use it to render an `<a>` or any custom element while keeping button behaviour. Set `nativeButton={false}` when rendering a non-`<button>` element.
+
+### Badge
+
+```tsx
+import { Badge } from "@brijbyte/agentic-ui/badge";
+
+// variants: default | solid | soft | success | warning | error | info
+<Badge variant="success" dot>Active</Badge>
+<Badge variant="error">Failed</Badge>
+```
+
+`dot` shows a small coloured dot before the label text.
+
+### Input
+
+```tsx
+import { Input } from "@brijbyte/agentic-ui/input";
+
+// sizes: sm | md | lg
+<Input size="md" placeholder="Search…" leftAdornment={<SearchIcon />} />
+<Input invalid defaultValue="bad-value" />
+```
+
+`size` overrides the native HTML `size` attribute — it maps to height and font-size design tokens.
+
+### Checkbox
+
+```tsx
+import { Checkbox, CheckboxRoot, CheckboxIndicator } from "@brijbyte/agentic-ui/checkbox";
+
+// High-level
+<Checkbox checked={val} onCheckedChange={(v) => setVal(v as boolean)}>
+  Accept terms
+</Checkbox>
+
+// Composed — custom icon
+<label htmlFor="cb">
+  <CheckboxRoot id="cb">
+    <CheckboxIndicator>
+      <StarIcon />
+    </CheckboxIndicator>
+  </CheckboxRoot>
+  Favourite
+</label>
+```
+
+### Switch
+
+```tsx
+import { Switch } from "@brijbyte/agentic-ui/switch";
+
+<Switch checked={enabled} onCheckedChange={(v) => setEnabled(v as boolean)}>
+  Enable notifications
+</Switch>;
+```
+
+### Select
+
+```tsx
+import { Select } from "@brijbyte/agentic-ui/select";
+
+<Select
+  placeholder="Choose a model…"
+  options={[
+    { value: "claude-3-5-sonnet", label: "Claude 3.5 Sonnet" },
+    { value: "gpt-4o", label: "GPT-4o", disabled: true },
+  ]}
+  onValueChange={(v) => console.log(v)}
+/>
+
+// With groups
+<Select
+  groups={[
+    { label: "Anthropic", options: [{ value: "claude", label: "Claude" }] },
+    { label: "OpenAI",    options: [{ value: "gpt",    label: "GPT"    }] },
+  ]}
+/>
+```
+
+### Dialog
+
+```tsx
+import { Dialog } from "@brijbyte/agentic-ui/dialog";
+
+<Dialog
+  trigger={<Button>Open</Button>}
+  title="Confirm deletion"
+  description="This cannot be undone."
+  footer={
+    <>
+      <Button variant="ghost" size="sm">
+        Cancel
+      </Button>
+      <Button variant="solid" tone="destructive" size="sm">
+        Delete
+      </Button>
+    </>
+  }
+>
+  Optional body content
+</Dialog>;
+```
+
+### Drawer
+
+```tsx
+import { Drawer, DrawerClose } from "@brijbyte/agentic-ui/drawer";
+
+// sides: left | right (default) | top | bottom
+// Supports swipe-to-dismiss gestures on all sides.
+<Drawer
+  side="right"
+  trigger={<Button>Open</Button>}
+  title="Settings"
+  description="Configure your workspace."
+  footer={
+    <Button size="sm" render={<DrawerClose />}>
+      Done
+    </Button>
+  }
+>
+  Content goes here
+</Drawer>;
+```
+
+### Tooltip
+
+```tsx
+import { Tooltip } from "@brijbyte/agentic-ui/tooltip";
+
+// side: top | bottom | left | right  (default: "top")
+<Tooltip content="Keyboard shortcut: ⌘K" side="bottom">
+  <Button variant="ghost">Open palette</Button>
+</Tooltip>;
+```
+
+Tooltips animate from their trigger's origin using Base UI's `--transform-origin` CSS variable. When the user moves quickly between multiple tooltips, subsequent ones appear instantly (no animation delay) via the `data-instant` attribute.
+
+### Tabs
+
+```tsx
+import { Tabs } from "@brijbyte/agentic-ui/tabs";
+
+<Tabs
+  items={[
+    { value: "overview", label: "Overview", content: <OverviewPanel /> },
+    { value: "api", label: "API", content: <ApiPanel /> },
+    { value: "old", label: "Legacy", content: null, disabled: true },
+  ]}
+/>;
+```
+
+The active tab is indicated by a 3px accent-coloured underline and full-brightness text vs dimmed inactive tabs. Tab panels fade in on switch.
+
+### Accordion
+
+```tsx
+import { Accordion } from "@brijbyte/agentic-ui/accordion";
+
+// multiple: true (default) allows multiple panels open at once
+<Accordion
+  multiple={false}
+  items={[
+    { value: "q1", header: "What is it?", content: "…" },
+    { value: "q2", header: "How does it work?", content: "…" },
+  ]}
+/>;
+```
+
+### Collapsible
+
+```tsx
+import { Collapsible } from "@brijbyte/agentic-ui/collapsible";
+
+<Collapsible trigger="Recovery keys" defaultOpen>
+  <div>alien-bean-pasta</div>
+  <div>wild-irish-burrito</div>
+</Collapsible>;
+```
+
+When open, the trigger's bottom corners square off and connect flush with the content panel. When closing, the corners only round back after the panel has fully collapsed — no visible seam at any point during the animation.
+
+### Menu
+
+```tsx
+import { Menu } from "@brijbyte/agentic-ui/menu";
+import type { MenuEntry } from "@brijbyte/agentic-ui/menu";
+
+const items: MenuEntry[] = [
+  { label: "Edit", shortcut: "⌘E", onSelect: () => {} },
+  { label: "Rename", shortcut: "⌘R", onSelect: () => {} },
+  { type: "separator" },
+  { label: "Delete", onSelect: () => {}, disabled: true },
+];
+
+<Menu
+  trigger={
+    <Button variant="outline" size="sm">
+      Actions ▾
+    </Button>
+  }
+  items={items}
+/>;
+```
+
+Supports `type: "group"` entries with an optional `label` for grouped sections. The popup uses backdrop blur and the highlight uses inset rounded corners — matching macOS native menu aesthetics.
+
+### NumberField
+
+```tsx
+import { NumberField } from "@brijbyte/agentic-ui/number-field";
+
+<NumberField label="Quantity" defaultValue={1} min={0} max={100} />
+<NumberField label="Price" defaultValue={9.99} step={0.01} format={{ style: "currency", currency: "USD" }} />
+```
+
+Click-and-drag on the label (scrub area) to change the value. Supports `min`, `max`, `step`, locale-aware `format`, and `allowWheelScrub`.
+
+### Separator
+
+```tsx
+import { Separator } from "@brijbyte/agentic-ui/separator";
+
+// Horizontal (default)
+<Separator />
+
+// Vertical — stretch to parent height
+<Separator orientation="vertical" style={{ height: "1rem" }} />
+```
+
+### Progress
+
+```tsx
+import { Progress } from "@brijbyte/agentic-ui/progress";
+
+// status: default | success | warning | error
+// size:   sm | md | lg
+<Progress value={72} max={100} label="Uploading" showValue status="success" />
+<Progress value={null} label="Loading…" />  {/* indeterminate — linear animation */}
+```
+
+### Toast
+
+```tsx
+import { ToastProvider, ToastViewport, useToastManager } from "@brijbyte/agentic-ui/toast";
+
+// 1. Wrap your app — limit defaults to 3 (list) or 5 (stacked)
+<ToastProvider variant="list">
+  <App />
+  <ToastViewport variant="list" />
+</ToastProvider>;
+
+// 2. Trigger from anywhere
+function MyComponent() {
+  const toast = useToastManager();
+  toast.add({
+    title: "Deployed",
+    description: "Your app is live.",
+    type: "success", // default | success | warning | error | info
+  });
+}
+```
+
+**`variant="stacked"`** — Sonner-style stacked toasts. Collapsed: toasts fan behind each other (scaled + nudged). Hover/focus expands the stack into a list. Hover gaps between toasts are filled so the stack doesn't collapse mid-hover.
+
+```tsx
+<ToastProvider variant="stacked">
+  <App />
+  <ToastViewport variant="stacked" />
+</ToastProvider>
+```
+
+**`limit`** — maximum toasts shown simultaneously. Defaults to `3` for `list`, `5` for `stacked`. Hard-capped at `5` (list) and `10` (stacked) regardless of what is passed, to prevent viewport overflow.
+
+Each toast type gets a subtle tinted background (`color-mix` of the status colour into the overlay) so variants are distinguishable without relying solely on the icon.
+
+---
+
+## Build system
+
+Built with **[tsdown](https://tsdown.dev)** (powered by Rolldown + Lightning CSS).
+
+```bash
+pnpm build   # tsdown → dist/
+pnpm dev     # tsdown --watch
+```
+
+### Output
+
+```
+dist/
+  index.js                          ← ESM barrel, no CSS imports
+  index.d.ts                        ← Type declarations
+  index.css                         ← All CSS: tokens + reset + every component
+  tokens.css                        ← Tokens only (for Tailwind setups)
+  reset.css                         ← Reset only (for Tailwind setups)
+  tailwind-theme.css                ← @theme inline block for Tailwind v4
+  button/index.js                   ← Per-component ESM (no CSS imports)
+  button/index.d.ts
+  button/button.css                 ← Per-component plain CSS (no .module suffix)
+  …                                 ← All 18 components follow the same pattern
+```
+
+### Two-pass build
+
+The config runs two tsdown passes:
+
+1. **Pass 1** — JS + DTS + `dist/index.css` (all CSS bundled into one file).
+2. **Pass 2** — per-component split CSS. Each component's CSS is written to `dist/<name>/<Name>.css`. An `onSuccess` hook renames `*.module.css` output files to `*.css` (tsdown's CSS modules plugin requires `.module.css` source files, but consumers should see plain `.css`).
+
+### Why no CSS in JS?
+
+`@tsdown/css` with `inject: false` extracts all CSS to separate files and writes zero `import '…css'` statements into JS. Class name mappings from CSS modules are inlined into JS chunks as plain objects — the JS is self-contained, the CSS is an explicit dependency you control.
+
+---
+
+## Tooling
+
+| Tool                                  | Purpose                                    |
+| ------------------------------------- | ------------------------------------------ |
+| `tsdown`                              | Library bundler (Rolldown + Lightning CSS) |
+| `@typescript/native-preview` (`tsgo`) | Fast TypeScript type checking              |
+| `oxlint`                              | ESLint-compatible linter                   |
+| `oxfmt`                               | Opinionated formatter                      |
+
+```bash
+pnpm typecheck   # tsgo --noEmit across all packages
+pnpm lint        # oxlint packages/agentic-ui/src apps/docs/src
+pnpm format      # oxfmt packages/agentic-ui/src apps/docs/src
+```