@brijbyte/agentic-ui 0.0.1 → 0.0.2

package/README.md

@@ -1,17 +1,17 @@
 # @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.
+A developer-focused React component library with an aesthetic loosely inspired by native desktop and mobile UI. 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.
+- **Serif display font for headings.** Titles use a serif font stack ("New York" where available) with a graceful fallback chain.
 - **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.
+- **Layered component styles.** Component CSS modules live in `@layer components`. The layer order is `theme` (lowest) → `base` → `components` → `utilities` (highest). Declared once in `tokens.css` and exposed via `@brijbyte/agentic-ui/layer-order` — not repeated in every module file. Tokens in `@layer theme`; resets in `@layer base`; components beat both; Tailwind utilities beat everything.
 
 ---
 
@@ -31,11 +31,6 @@ Peer dependencies: `react ^19`, `react-dom ^19`.
 
 **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";
 ```
@@ -60,6 +55,7 @@ Every component has a plain `/<name>.css` subpath export. The JS and CSS are alw
 /* app/globals.css */
 @import "tailwindcss";
 
+/* tokens.css includes the layer order declaration */
 @import "@brijbyte/agentic-ui/tokens";
 @import "@brijbyte/agentic-ui/reset";
 @import "@brijbyte/agentic-ui/tailwind-theme";
@@ -69,16 +65,16 @@ Every component has a plain `/<name>.css` subpath export. The JS and CSS are alw
 
 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)`           |
+| Token             | Tailwind class             | CSS output                              |
+| ----------------- | -------------------------- | --------------------------------------- |
+| `--color-canvas`  | `bg-canvas`                | `background-color: var(--color-canvas)` |
+| `--color-primary` | `text-primary`             | `color: var(--color-primary)`           |
+| `--color-line`    | `border-line`              | `border-color: var(--color-line)`       |
+| `--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.
 
@@ -86,24 +82,23 @@ Because `@theme inline` references live CSS variables (not baked-in values), **d
 
 ### CSS layer order
 
-Every component CSS module file begins with:
+The cascade order `base → components → utilities` is declared in `tokens.css`, so importing tokens is sufficient in most setups.
+
+If you're importing component CSS without tokens — for example, using a pre-built `button.css` in isolation — import `layer-order` first:
 
 ```css
-@layer theme, base, components, utilities;
+@import "@brijbyte/agentic-ui/layer-order";
+@import "@brijbyte/agentic-ui/button.css";
 ```
 
-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)
+@layer theme       ← design tokens (CSS custom properties)   ← lowest priority
+@layer base        ← element resets + Tailwind preflight      ← beats theme
+@layer components  ← component CSS modules                    ← beats base
+@layer utilities   ← Tailwind utilities                       ← beats 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.
+CSS only honours the **first** time each layer name appears in an ordering statement — subsequent declarations from other files are harmless.
 
 ### Dark mode
 
@@ -111,8 +106,8 @@ Tokens adapt automatically via `prefers-color-scheme`. To override programmatica
 
 ```ts
 document.documentElement.dataset.theme = "light"; // force light
-document.documentElement.dataset.theme = "dark"; // follow OS again
-delete document.documentElement.dataset.theme; // follow OS again
+document.documentElement.dataset.theme = "dark"; // force dark
+delete document.documentElement.dataset.theme; // follow OS
 ```
 
 ---
@@ -129,34 +124,45 @@ All tokens are CSS custom properties defined at `:root` under `@layer base`. Ove
 --font-sans     -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Arial
 ```
 
-**`--font-display`** is used for `h1`–`h6` and prominent page titles.  
+**`--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>`.
+Token names describe **what the colour is**, not which CSS property it maps to. Tailwind's utility prefix (`bg-`, `text-`, `border-`) adds the property context — so `--color-canvas` becomes `bg-canvas`, `--color-primary` becomes `text-primary`, etc.
+
+All tokens live in `@layer theme` — the lowest-priority layer. `@layer base` (resets) beats them, `@layer components` beats base, and `@layer utilities` beats everything. Any unlayered `:root` override also beats all layers without needing `!important`.
+
+Shadows are theme-aware — light mode uses low-opacity black shadows; dark mode uses higher-opacity values so elevation is visible against dark surfaces.
+
+| Token                                                     | Tailwind class       | Role                                        |
+| --------------------------------------------------------- | -------------------- | ------------------------------------------- |
+| `--color-canvas`                                          | `bg-canvas`          | Page background                             |
+| `--color-elevated`                                        | `bg-elevated`        | Cards, popovers                             |
+| `--color-sunken`                                          | `bg-sunken`          | Code blocks, inset areas                    |
+| `--color-overlay`                                         | `bg-overlay`         | Backdrop-blurred surfaces                   |
+| `--color-sidebar`                                         | `bg-sidebar`         | Sidebar / navigation panels                 |
+| `--color-surface-1/2/3`                                   | `bg-surface-1/2/3`   | Layered surface hierarchy                   |
+| `--color-hover`                                           | `bg-hover`           | Hovered interactive surface                 |
+| `--color-active`                                          | `bg-active`          | Pressed interactive surface                 |
+| `--color-selected`                                        | `bg-selected`        | Selected interactive surface                |
+| `--color-primary`                                         | `text-primary`       | Primary text                                |
+| `--color-secondary`                                       | `text-secondary`     | Secondary text                              |
+| `--color-tertiary`                                        | `text-tertiary`      | Tertiary / hint text                        |
+| `--color-disabled`                                        | `text-disabled`      | Disabled text                               |
+| `--color-inverse`                                         | `text-inverse`       | Text on inverse (dark) backgrounds          |
+| `--color-on-accent`                                       | `text-on-accent`     | Text on filled accent backgrounds           |
+| `--color-code`                                            | `text-code`          | Inline code text                            |
+| `--color-line`                                            | `border-line`        | Base border                                 |
+| `--color-line-strong`                                     | `border-line-strong` | Stronger border                             |
+| `--color-line-subtle`                                     | `border-line-subtle` | Subtle / decorative border                  |
+| `--color-accent`                                          | `bg-accent`          | macOS blue — solid interactive colour       |
+| `--color-accent-hover`                                    | —                    | Accent on hover                             |
+| `--color-accent-pressed`                                  | —                    | Accent on press                             |
+| `--color-accent-tint`                                     | `bg-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                              |
 
 ### Spacing
 
@@ -176,7 +182,7 @@ Theme-aware — defined inside the light/dark token blocks so they adapt automat
 
 `--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.
+`--shadow-focus` uses a two-layer technique: `0 0 0 2px --color-canvas, 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
 
@@ -188,11 +194,11 @@ Theme-aware — defined inside the light/dark token blocks so they adapt automat
 --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) */
+--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) /* physics-based, slight overshoot */
+--easing-linear    linear                             /* constant motion (spinners, progress) */
 ```
 
 ### Z-index scale
@@ -208,31 +214,36 @@ Theme-aware — defined inside the light/dark token blocks so they adapt automat
 
 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/layer-order     ← layer order declaration only
+@brijbyte/agentic-ui/tokens          ← CSS custom properties (includes layer-order)
+@brijbyte/agentic-ui/reset           ← element resets
 @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/alert-dialog    @brijbyte/agentic-ui/number-field
+@brijbyte/agentic-ui/badge           @brijbyte/agentic-ui/progress
+@brijbyte/agentic-ui/button          @brijbyte/agentic-ui/select
+@brijbyte/agentic-ui/card            @brijbyte/agentic-ui/separator
+@brijbyte/agentic-ui/checkbox        @brijbyte/agentic-ui/slider
 @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
+@brijbyte/agentic-ui/context-menu    @brijbyte/agentic-ui/tabs
+@brijbyte/agentic-ui/dialog          @brijbyte/agentic-ui/toast
+@brijbyte/agentic-ui/drawer          @brijbyte/agentic-ui/tooltip
+@brijbyte/agentic-ui/input
 
 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
+@brijbyte/agentic-ui/accordion.css    @brijbyte/agentic-ui/menu.css
+@brijbyte/agentic-ui/alert-dialog.css @brijbyte/agentic-ui/number-field.css
+@brijbyte/agentic-ui/badge.css        @brijbyte/agentic-ui/progress.css
+@brijbyte/agentic-ui/button.css       @brijbyte/agentic-ui/select.css
+@brijbyte/agentic-ui/card.css         @brijbyte/agentic-ui/separator.css
+@brijbyte/agentic-ui/checkbox.css     @brijbyte/agentic-ui/slider.css
+@brijbyte/agentic-ui/collapsible.css  @brijbyte/agentic-ui/switch.css
+@brijbyte/agentic-ui/context-menu.css @brijbyte/agentic-ui/tabs.css
+@brijbyte/agentic-ui/dialog.css       @brijbyte/agentic-ui/toast.css
+@brijbyte/agentic-ui/drawer.css       @brijbyte/agentic-ui/tooltip.css
+@brijbyte/agentic-ui/input.css
 ```
 
 ---
@@ -257,11 +268,13 @@ import { Button, Dialog, Input } from "@brijbyte/agentic-ui";
 | Import path     | High-level wrapper                                  | Styled parts                                                                                                                                                                                          |
 | --------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/accordion`    | `Accordion`                                         | `AccordionItemPart`, `AccordionHeader`, `AccordionTrigger`, `AccordionPanel`                                                                                                                          |
+| `/alert-dialog` | `AlertDialog`                                       | `AlertDialogBackdrop`, `AlertDialogPopup`, `AlertDialogTitle`, `AlertDialogDescription`                                                                                                               |
 | `/badge`        | `Badge`                                             | —                                                                                                                                                                                                     |
 | `/button`       | `Button`                                            | —                                                                                                                                                                                                     |
 | `/card`         | `Card`, `CardHeader`, `CardBody`, `CardFooter`      | —                                                                                                                                                                                                     |
 | `/checkbox`     | `Checkbox`                                          | `CheckboxRoot`, `CheckboxIndicator`                                                                                                                                                                   |
 | `/collapsible`  | `Collapsible`                                       | `CollapsibleRoot`, `CollapsibleTrigger`, `CollapsiblePanel`                                                                                                                                           |
+| `/context-menu` | `ContextMenu`                                       | `ContextMenuPopup`, `ContextMenuItem`, `ContextMenuSeparator`, `ContextMenuGroup`, `ContextMenuGroupLabel`, `ContextMenuSubmenuTrigger`                                                               |
 | `/dialog`       | `Dialog`                                            | `DialogBackdrop`, `DialogViewport`, `DialogPopup`, `DialogTitle`, `DialogDescription`, `DialogClose`                                                                                                  |
 | `/drawer`       | `Drawer`                                            | `DrawerBackdrop`, `DrawerViewport`, `DrawerPopup`, `DrawerContent`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`, `DrawerHandleBar`, `DrawerFooter`                                              |
 | `/input`        | `Input`                                             | —                                                                                                                                                                                                     |
@@ -270,6 +283,7 @@ import { Button, Dialog, Input } from "@brijbyte/agentic-ui";
 | `/progress`     | `Progress`                                          | `ProgressTrack`, `ProgressIndicator`                                                                                                                                                                  |
 | `/select`       | `Select`                                            | `SelectTrigger`, `SelectValue`, `SelectPositioner`, `SelectPopup`, `SelectList`, `SelectItem`, `SelectItemText`, `SelectItemIndicator`, `SelectGroupContainer`, `SelectGroupLabel`, `SelectSeparator` |
 | `/separator`    | `Separator`                                         | —                                                                                                                                                                                                     |
+| `/slider`       | `Slider`                                            | `SliderControl`, `SliderTrack`, `SliderIndicator`, `SliderThumb`, `SliderLabel`, `SliderValue`                                                                                                        |
 | `/switch`       | `Switch`                                            | `SwitchRoot`, `SwitchThumb`                                                                                                                                                                           |
 | `/tabs`         | `Tabs`                                              | `TabsList`, `TabsTab`, `TabsPanel`                                                                                                                                                                    |
 | `/toast`        | `ToastViewport`, `ToastProvider`, `useToastManager` | `ToastRoot`, `ToastTitle`, `ToastDescription`, `ToastClose`, `ToastViewportPart`                                                                                                                      |
@@ -442,9 +456,7 @@ import { Checkbox, CheckboxRoot, CheckboxIndicator } from "@brijbyte/agentic-ui/
 // Composed — custom icon
 <label htmlFor="cb">
   <CheckboxRoot id="cb">
-    <CheckboxIndicator>
-      <StarIcon />
-    </CheckboxIndicator>
+    <CheckboxIndicator><StarIcon /></CheckboxIndicator>
   </CheckboxRoot>
   Favourite
 </label>
@@ -483,6 +495,8 @@ import { Select } from "@brijbyte/agentic-ui/select";
 />
 ```
 
+The trigger always displays the selected option's `label` (which can be any `ReactNode` — text, icons, etc.) rather than the raw `value` string. Label lookup is memoised.
+
 ### Dialog
 
 ```tsx
@@ -513,12 +527,10 @@ import { Dialog } from "@brijbyte/agentic-ui/dialog";
 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
@@ -540,7 +552,7 @@ import { Tooltip } from "@brijbyte/agentic-ui/tooltip";
 </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.
+Tooltips spring open from the trigger's origin — Base UI sets `--transform-origin` to the trigger side so the scale animation radiates outward from the correct edge. Enter uses `--easing-spring` (overshoot + settle). Exit is a fast `ease-in` fade with no spring. When the user moves quickly between adjacent tooltips, subsequent ones appear instantly via `data-instant`.
 
 ### Tabs
 
@@ -563,7 +575,6 @@ The active tab is indicated by a 3px accent-coloured underline and full-brightne
 ```tsx
 import { Accordion } from "@brijbyte/agentic-ui/accordion";
 
-// multiple: true (default) allows multiple panels open at once
 <Accordion
   multiple={false}
   items={[
@@ -609,7 +620,7 @@ const items: MenuEntry[] = [
 />;
 ```
 
-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.
+Supports `type: "group"` entries with an optional `label` for grouped sections. The popup uses backdrop blur and highlights use inset rounded corners — matching native context menu aesthetics.
 
 ### NumberField
 
@@ -620,17 +631,14 @@ import { NumberField } from "@brijbyte/agentic-ui/number-field";
 <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`.
+Click-and-drag on the label (scrub area) to change the value. Supports `min`, `max`, `step`, locale-aware `format`, and `allowWheelScrub`. The input and step buttons use a thin inset accent ring on focus rather than the standard offset focus ring.
 
 ### Separator
 
 ```tsx
 import { Separator } from "@brijbyte/agentic-ui/separator";
 
-// Horizontal (default)
 <Separator />
-
-// Vertical — stretch to parent height
 <Separator orientation="vertical" style={{ height: "1rem" }} />
 ```
 
@@ -650,7 +658,7 @@ import { Progress } from "@brijbyte/agentic-ui/progress";
 ```tsx
 import { ToastProvider, ToastViewport, useToastManager } from "@brijbyte/agentic-ui/toast";
 
-// 1. Wrap your app — limit defaults to 3 (list) or 5 (stacked)
+// 1. Wrap your app
 <ToastProvider variant="list">
   <App />
   <ToastViewport variant="list" />
@@ -667,7 +675,7 @@ function MyComponent() {
 }
 ```
 
-**`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.
+**`variant="stacked"`** — Sonner-style stacked toasts. Collapsed: toasts fan behind each other. Hover/focus expands the stack into a list. Gaps between toasts are covered by a pseudo-element so the stack doesn't collapse mid-hover.
 
 ```tsx
 <ToastProvider variant="stacked">
@@ -676,9 +684,79 @@ function MyComponent() {
 </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.
+**`limit`** — maximum toasts shown simultaneously. Defaults to `3` (list) / `5` (stacked). Hard-capped at `5` (list) and `10` (stacked) 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.
+Each toast type gets a subtle `color-mix` tinted background so variants are distinguishable without relying solely on the icon.
+
+### AlertDialog
+
+```tsx
+import { AlertDialog } from "@brijbyte/agentic-ui/alert-dialog";
+
+// 2 actions → side-by-side. Cancel (outline) + confirm (solid).
+<AlertDialog
+  trigger={<Button variant="outline">Discard draft</Button>}
+  title="Discard draft?"
+  description="You can't undo this action."
+  actions={[
+    { label: "Cancel" },
+    { label: "Discard", primary: true, destructive: true },
+  ]}
+/>
+
+// 3+ actions → all right-aligned in order.
+<AlertDialog
+  title='Save "Untitled" before closing?'
+  actions={[
+    { label: "Don't Save", destructive: true },
+    { label: "Cancel" },
+    { label: "Save", primary: true },
+  ]}
+/>
+```
+
+**`actions`** array — each entry: `label`, `onAction`, `primary` (solid variant), `destructive` (destructive tone). Actions are rendered right-aligned in the order given. `primary: true` → solid button. `destructive: true` → destructive tone.
+
+Optional `icon` prop renders content above the title (e.g. an app icon or warning symbol).
+
+### ContextMenu
+
+```tsx
+import { ContextMenu } from "@brijbyte/agentic-ui/context-menu";
+
+<ContextMenu
+  items={[
+    { label: "Cut",   shortcut: "⌘X" },
+    { label: "Copy",  shortcut: "⌘C" },
+    { label: "Paste", shortcut: "⌘V", disabled: true },
+    { type: "separator" },
+    { label: "Select All", shortcut: "⌘A" },
+  ]}
+>
+  <div>Right click me</div>
+</ContextMenu>
+```
+
+Activated by right-click or long press on the child element. Supports `items` with `label`, `shortcut`, `icon`, `onSelect`, and `disabled`. Use `type: "separator"` for dividers and `type: "group"` with nested `items` for logical sections.
+
+For submenus, use the composed API with `ContextMenu.SubmenuRoot` + `ContextMenuSubmenuTrigger`:
+
+```tsx
+import { ContextMenu as BaseContextMenu } from "@base-ui/react/context-menu";
+import { ContextMenuPopup, ContextMenuItem, ContextMenuSubmenuTrigger } from "@brijbyte/agentic-ui/context-menu";
+
+<BaseContextMenu.SubmenuRoot>
+  <ContextMenuSubmenuTrigger>Open With</ContextMenuSubmenuTrigger>
+  <BaseContextMenu.Portal>
+    <BaseContextMenu.Positioner alignOffset={-4} sideOffset={-4}>
+      <ContextMenuPopup>
+        <ContextMenuItem>VS Code</ContextMenuItem>
+        <ContextMenuItem>Zed</ContextMenuItem>
+      </ContextMenuPopup>
+    </BaseContextMenu.Positioner>
+  </BaseContextMenu.Portal>
+</BaseContextMenu.SubmenuRoot>
+```
 
 ---
 
@@ -695,25 +773,19 @@ pnpm dev     # tsdown --watch
 
 ```
 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)
+  index.js                 ← ESM barrel, no CSS imports
+  index.d.ts               ← Type declarations
+  index.css                ← All CSS: tokens + reset + every component
+  layer-order.css          ← Layer order declaration only
+  tokens.css               ← Tokens in @layer theme (includes layer-order)
+  reset.css                ← Element resets in @layer base
+  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
+  button/button.css        ← Per-component plain CSS
+  …                        ← All 19 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.

package/dist/accordion/accordion.css

@@ -1,8 +1,6 @@
-@layer theme, base;
-
 @layer components {
   .root_XcG3ua {
-    border: var(--border-width-base) solid var(--color-border-base);
+    border: var(--border-width-base) solid var(--color-line);
     border-radius: var(--radius-lg);
     flex-direction: column;
     gap: 0;
@@ -11,7 +9,7 @@
   }
 
   .item_XcG3ua {
-    border-bottom: var(--border-width-base) solid var(--color-border-subtle);
+    border-bottom: var(--border-width-base) solid var(--color-line-subtle);
   }
 
   .item_XcG3ua:last-child {
@@ -31,7 +29,7 @@
     font-family: var(--font-mono);
     font-size: var(--font-size-sm);
     font-weight: var(--font-weight-medium);
-    color: var(--color-text-primary);
+    color: var(--color-primary);
     cursor: pointer;
     text-align: left;
     transition: background-color var(--duration-fast) var(--easing-standard),
@@ -45,7 +43,7 @@
   }
 
   .trigger_XcG3ua:hover {
-    background-color: var(--color-surface-hover);
+    background-color: var(--color-hover);
   }
 
   .trigger_XcG3ua:focus-visible {
@@ -58,7 +56,7 @@
   }
 
   .trigger-icon_XcG3ua {
-    color: var(--color-text-tertiary);
+    color: var(--color-tertiary);
     transition: transform var(--duration-normal) var(--easing-standard);
     flex-shrink: 0;
   }
@@ -81,9 +79,7 @@
     padding: var(--space-2) var(--space-4) var(--space-4);
     font-family: var(--font-mono);
     font-size: var(--font-size-sm);
-    color: var(--color-text-secondary);
+    color: var(--color-secondary);
     line-height: var(--line-height-relaxed);
   }
 }
-
-@layer utilities;

package/dist/accordion/accordion.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"accordion.module.js","names":[],"sources":["../../src/accordion/accordion.module.css"],"sourcesContent":["@layer theme, base, components, utilities;\n\n@layer components {\n  .root {\n    display: flex;\n    flex-direction: column;\n    gap: 0;\n    border: var(--border-width-base) solid var(--color-border-base);\n    border-radius: var(--radius-lg);\n    overflow: hidden;\n  }\n\n  .item {\n    border-bottom: var(--border-width-base) solid var(--color-border-subtle);\n  }\n\n  .item:last-child {\n    border-bottom: none;\n  }\n\n  .header {\n    display: flex;\n    align-items: center;\n  }\n\n  .trigger {\n    flex: 1;\n    display: flex;\n    align-items: center;\n    justify-content: space-between;\n    gap: var(--space-2);\n    padding: var(--space-3) var(--space-4);\n    font-family: var(--font-mono);\n    font-size: var(--font-size-sm);\n    font-weight: var(--font-weight-medium);\n    color: var(--color-text-primary);\n    background: none;\n    border: none;\n    cursor: pointer;\n    outline: none;\n    text-align: left;\n    transition:\n      background-color var(--duration-fast) var(--easing-standard),\n      color var(--duration-fast) var(--easing-standard);\n    user-select: none;\n  }\n\n  .trigger:hover {\n    background-color: var(--color-surface-hover);\n  }\n\n  .trigger:focus-visible {\n    box-shadow: inset var(--shadow-focus);\n  }\n\n  .trigger[data-disabled] {\n    opacity: 0.44;\n    cursor: not-allowed;\n  }\n\n  .trigger-icon {\n    color: var(--color-text-tertiary);\n    flex-shrink: 0;\n    transition: transform var(--duration-normal) var(--easing-standard);\n  }\n\n  .trigger[data-panel-open] .trigger-icon {\n    transform: rotate(180deg);\n  }\n\n  .panel {\n    height: var(--accordion-panel-height);\n    overflow: hidden;\n    transition: height var(--duration-normal) var(--easing-standard);\n  }\n\n  .panel[data-starting-style],\n  .panel[data-ending-style] {\n    height: 0;\n  }\n\n  .panel-content {\n    padding: var(--space-2) var(--space-4) var(--space-4);\n    font-family: var(--font-mono);\n    font-size: var(--font-size-sm);\n    color: var(--color-text-secondary);\n    line-height: var(--line-height-relaxed);\n  }\n}\n"],"mappings":";AAcA,IAAA,2BAAE;CAAA,UAAA;CAAA,QAAA;CAAA,SAAA;CAAA,iBAAA;CAAA,QAAA;CAAA,WAAA;CAAA,gBAAA;CAAA"}
+{"version":3,"file":"accordion.module.js","names":[],"sources":["../../src/accordion/accordion.module.css"],"sourcesContent":["@layer components {\n  .root {\n    display: flex;\n    flex-direction: column;\n    gap: 0;\n    border: var(--border-width-base) solid var(--color-line);\n    border-radius: var(--radius-lg);\n    overflow: hidden;\n  }\n  .item {\n    border-bottom: var(--border-width-base) solid var(--color-line-subtle);\n  }\n  .item:last-child {\n    border-bottom: none;\n  }\n  .header {\n    display: flex;\n    align-items: center;\n  }\n  .trigger {\n    flex: 1;\n    display: flex;\n    align-items: center;\n    justify-content: space-between;\n    gap: var(--space-2);\n    padding: var(--space-3) var(--space-4);\n    font-family: var(--font-mono);\n    font-size: var(--font-size-sm);\n    font-weight: var(--font-weight-medium);\n    color: var(--color-primary);\n    background: none;\n    border: none;\n    cursor: pointer;\n    outline: none;\n    text-align: left;\n    transition:\n      background-color var(--duration-fast) var(--easing-standard),\n      color var(--duration-fast) var(--easing-standard);\n    user-select: none;\n  }\n  .trigger:hover {\n    background-color: var(--color-hover);\n  }\n  .trigger:focus-visible {\n    box-shadow: inset var(--shadow-focus);\n  }\n  .trigger[data-disabled] {\n    opacity: 0.44;\n    cursor: not-allowed;\n  }\n  .trigger-icon {\n    color: var(--color-tertiary);\n    flex-shrink: 0;\n    transition: transform var(--duration-normal) var(--easing-standard);\n  }\n  .trigger[data-panel-open] .trigger-icon {\n    transform: rotate(180deg);\n  }\n  .panel {\n    height: var(--accordion-panel-height);\n    overflow: hidden;\n    transition: height var(--duration-normal) var(--easing-standard);\n  }\n  .panel[data-starting-style],\n  .panel[data-ending-style] {\n    height: 0;\n  }\n  .panel-content {\n    padding: var(--space-2) var(--space-4) var(--space-4);\n    font-family: var(--font-mono);\n    font-size: var(--font-size-sm);\n    color: var(--color-secondary);\n    line-height: var(--line-height-relaxed);\n  }\n}\n"],"mappings":";AAcA,IAAA,2BAAE;CAAA,UAAA;CAAA,QAAA;CAAA,SAAA;CAAA,iBAAA;CAAA,QAAA;CAAA,WAAA;CAAA,gBAAA;CAAA"}