diff --git a/ui/.claude/skills/nebari-ui/SKILL.md b/ui/.claude/skills/nebari-ui/SKILL.md
new file mode 100644
index 0000000..6f64df3
--- /dev/null
+++ b/ui/.claude/skills/nebari-ui/SKILL.md
@@ -0,0 +1,655 @@
+---
+name: nebari-ui
+description: >-
+  Add and use components from the Nebari design system (the @nebari shadcn
+  registry) in this app. Use when asked to "add a nebari component", "use the
+  nebari button/badge/alert/spinner/skeleton", "install the nebari theme", "animate,
+  add a transition, make it feel polished, or add an entrance animation with
+  nebari", "build <something> with nebari components", or "build/update the app
+  header (top bar, navigation bar, profile menu, notifications menu, theme
+  picker) to match nebari". Covers registry setup (the @nebari namespace in
+  components.json + the shadcn add command), the component catalog (variants,
+  sizes, props), the Base UI render-prop composition convention, theming (the
+  @nebari/theme tokens, CSS variables, and light/dark), the canonical app
+  header recipe (MenuBar composition, header tokens, notifications and profile
+  menus, the menuitemradio theme picker), and motion (duration/easing tokens,
+  entrance animations, overlay transitions, accessibility guardrails).
+---
+
+# Using the Nebari design system
+
+[Nebari design](https://github.com/nebari-dev/nebari-design) is a
+[shadcn component registry](https://ui.shadcn.com/docs/registry) styled with the
+Nebari brand. You install its components into this app with the `shadcn` CLI —
+they're copied into your codebase, but Nebari treats them as **upstream-managed
+source**: you extend them at the call site rather than editing the installed
+files (see [Treat installed components as managed](#treat-installed-components-as-managed)).
+This skill covers setup, the catalog, the composition convention, theming, and
+the canonical app-header recipe.
+
+## Step 1 — register the `@nebari` namespace (once)
+
+Add the `@nebari` registry to the consumer's `components.json` so
+`shadcn add @nebari/<name>` resolves. The items are served as JSON from the
+project's GitHub Pages site:
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "registries": {
+    "@nebari": "https://nebari-dev.github.io/nebari-design/r/{name}.json"
+  }
+}
+```
+
+`{name}` is the placeholder shadcn substitutes per item. This block sits
+alongside the app's existing `style` / `tailwind` / `aliases` config — it does
+not replace them. A standard shadcn-initialized project (run `npx shadcn init`
+first if `components.json` doesn't exist yet) is the only prerequisite.
+
+## Step 2 — install components
+
+```sh
+npx shadcn add @nebari/<name>
+```
+
+Most components depend on the shared `cn()` helper (the `utils` item) and the
+theme tokens, and shadcn pulls those `registryDependencies` in automatically —
+you don't list them yourself. Install the theme explicitly the first time (see
+[Theming](#theming)):
+
+```sh
+npx shadcn add @nebari/theme
+npx shadcn add @nebari/button
+```
+
+Installed files land under the app's configured aliases (`@/ui`, `@/hooks`,
+`@/lib`), so
+imports look like `import { Button } from '@/components/ui/button'` — match the
+host app's existing alias resolution.
+
+## Treat installed components as managed
+
+`shadcn add` copies the source into your repo, but treat the installed `ui/*`
+and `lib/*` files as **upstream-managed, not app-owned**. Don't edit them.
+
+- **Why** — these files are regenerated by `shadcn add` on every upgrade, so any
+  local edit is silently overwritten and lost. Editing also forks you away from
+  the shared design system: the next consumer of the same component gets
+  different behavior than yours, which is exactly what a design system exists to
+  prevent.
+- **To change look or behavior, do it at the call site, never in the file:**
+  - Pass extra classes via `className` — they're merged with `cn()`, so your
+    classes win without touching the source.
+  - Swap the rendered element with the Base UI `render` prop (link button, etc.)
+    instead of rewrapping or editing.
+  - Build a thin **wrapper component** in your own app that composes the Nebari
+    component when you need app-specific defaults or behavior.
+  - Put custom styling and motion in your own `globals.css` or a CSS module — the
+    only files you edit are ones you own.
+- **If a component genuinely can't express what you need** through the above,
+  don't fork it locally — request the change upstream in
+  [nebari-design](https://github.com/nebari-dev/nebari-design) so every app gets
+  it and stays consistent. Until then, wrap rather than edit.
+
+## Discovering what's available
+
+The registry is the source of truth for the catalog — don't rely on a
+hard-coded list here, which would drift as components are added. To see what
+exists and learn a component's exact API:
+
+- **List every item** — fetch the registry index, which names and describes each
+  installable item (components, the `utils` helper, the `theme`, this skill):
+
+  ```sh
+  curl -s https://nebari-dev.github.io/nebari-design/r/registry.json
+  ```
+
+- **Inspect one before installing** — `shadcn view` prints an item's
+  description, dependencies, and its full source:
+
+  ```sh
+  npx shadcn view @nebari/button
+  ```
+
+- **After installing, read the source** — components are copied into your repo
+  (treat them as managed — see
+  [Treat installed components as managed](#treat-installed-components-as-managed)).
+  The exact `variant`/`size` names and props live in the
+  component's `cva` block and its props type; open the installed `.tsx` (e.g.
+  `@/components/ui/button.tsx`) — that file, not any doc, is authoritative.
+
+## How Nebari components are built
+
+Every component follows the same shape, so once you've seen one you can use any:
+
+- Styled with **semantic theme tokens** (`bg-primary`, `text-muted-foreground`,
+  …), so it follows light/dark automatically — never restyle with raw hex or
+  `dark:` variants.
+- Sets stable `data-slot` / `data-variant` / `data-size` attributes you can
+  target in CSS or tests.
+- Exports its `cva` class function (`buttonVariants`, `badgeVariants`, …)
+  alongside the component for reuse.
+- `variant` / `size` (where present) select the look; read the source for the
+  exact set a given component offers.
+
+`Button` is a representative example — variants, sizes, a `loading` state, and
+`render`-prop composition:
+
+```tsx
+import { Button } from '@/components/ui/button';
+
+<Button>Save</Button>
+<Button variant="outline" size="sm">Cancel</Button>
+<Button variant="destructive" loading loadingText="Deleting…">Delete</Button>
+<Button size="icon" aria-label="Settings"><Settings /></Button>
+```
+
+Composed components (e.g. `Alert` with `AlertTitle` / `AlertDescription` /
+`AlertAction`) export their parts as named exports from the same module — the
+installed source and `shadcn view` show how the pieces fit together.
+
+## Composition (Base UI `render` prop)
+
+Polymorphic components (`Button`, `Badge`) use **Base UI's `render` prop** to
+change the rendered element while keeping their styling — this is Nebari's
+equivalent of Radix's `asChild`. Pass an element and the component merges its
+classes, `data-*` attributes, and props onto it:
+
+```tsx
+// Render a Button as a link
+<Button render={<a href="/docs" />}>Docs</Button>
+
+// Render a Badge as a link
+<Badge variant="outline" render={<a href="/tag/new" />}>new</Badge>
+```
+
+The component's `data-slot` and styling are preserved on the swapped element, so
+a `<Button render={<a />}>` is still a fully-styled button that's semantically a
+link.
+
+## Theming
+
+Install the theme once; it writes the Nebari brand color tokens and radius into
+the app's global stylesheet as CSS variables for both light and dark modes:
+
+```sh
+npx shadcn add @nebari/theme
+```
+
+- Tokens are **semantic** (`--primary`, `--muted-foreground`, `--destructive`,
+  `--info`, `--success`, `--warning`, `--border`, `--ring`, chart + sidebar
+  tokens, …) and consumed in components via Tailwind utilities like
+  `bg-primary` / `text-muted-foreground`. **Never** hard-code brand hex values or
+  add `dark:` variants — the tokens flip automatically.
+- **Surface stack.** Four distinct background layers, in stacking order:
+  `--canvas` (the page — nothing sits below it) → `--header` (app chrome: top
+  bar, sidebar, toolbars, table headers; `--sidebar` is the same layer) →
+  `--card` / `--popover` (raised surfaces; popovers share the card fill and are
+  differentiated by elevation) → `--muted` (recessed — only *inside* a card or
+  chrome: input fills, zebra rows, slider/progress tracks, disabled states).
+  Muted text sitting on `--muted` must use `text-muted-foreground-strong`, not
+  `text-muted-foreground`. `--background` is the legacy page token, kept for
+  backwards compatibility — prefer `bg-canvas` for new page shells.
+- **Light/dark:** the theme defines a `light` set on `:root` and a `dark` set;
+  toggle by adding/removing the `.dark` class on an ancestor (typically `<html>`).
+  Every Nebari component re-themes from the active token set with no per-component
+  changes.
+- **Fonts:** the tokens reference `Geist` (sans) and `IBM Plex Mono` (mono) but
+  don't ship the webfonts. To actually load them, install and import them at the
+  app entry point (otherwise they fall back to the system stacks):
+
+  ```sh
+  npm i @fontsource-variable/geist @fontsource/ibm-plex-mono
+  ```
+
+  ```ts
+  import '@fontsource-variable/geist';
+  import '@fontsource/ibm-plex-mono/400.css';
+  import '@fontsource/ibm-plex-mono/500.css';
+  ```
+
+### Dark mode state (`useThemePreference`)
+
+Don't hand-roll the `.dark`-class toggling — install the shared hook:
+
+```sh
+npx shadcn add @nebari/use-theme-preference
+```
+
+It installs two files under your hooks alias:
+
+- `use-theme-preference` — `useThemePreference()` persists a
+  `'light' | 'dark' | 'system'` preference in `localStorage`, follows the OS
+  (`prefers-color-scheme`) while in `system` mode, and toggles the `.dark`
+  class on `<html>`. Returns `{ themeMode, isDarkMode, setThemeMode }`. Also
+  exports `THEME_MODES`, `ThemeMode`, `isThemeMode`, and
+  `themeBootstrapScript`. SSR-safe, and storage failures (private browsing)
+  fall back to in-memory state.
+- `theme-provider` — `ThemeProvider` / `useTheme` for sharing **one** hook
+  instance app-wide. Mount the hook exactly once; multiple instances would
+  compete over the `<html>` class.
+
+```tsx
+// App root — mount once
+import { ThemeProvider } from '@/hooks/theme-provider';
+
+<ThemeProvider>
+  <App />
+</ThemeProvider>
+
+// Anywhere below it
+import { useTheme } from '@/hooks/theme-provider';
+
+function ThemeToggle() {
+  const { themeMode, isDarkMode, setThemeMode } = useTheme();
+  return <Button onClick={() => setThemeMode(isDarkMode ? 'light' : 'dark')}>…</Button>;
+}
+```
+
+- **Storage key:** defaults to `nebari:themeMode`. An app that already
+  persists a preference must pass its existing key so users keep it:
+  `<ThemeProvider storageKey="nebari-chat:themeMode">` (or
+  `useThemePreference({ storageKey: '…' })`).
+
+- **Flash prevention:** the saved theme is applied from a React effect, so a
+  dark-preference user sees a light flash while the bundle loads — unless the
+  class is set pre-paint. `themeBootstrapScript(storageKey?)` is the single
+  source of truth for that snippet: it resolves `dark` exactly like the hook,
+  from the same storage key and default. Paste its output into a `<script>`
+  at the top of `<head>` in `index.html` (or inject it from your HTML
+  template/SSR layer). For the default key it emits:
+
+  ```html
+  <script>
+    (function () {
+      try {
+        var mode = localStorage.getItem("nebari:themeMode");
+        var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+        var isDark = mode === 'dark' || (mode !== 'light' && prefersDark);
+        document.documentElement.classList.toggle('dark', isDark);
+      } catch (e) {}
+    })();
+  </script>
+  ```
+
+  If you use a non-default storage key, regenerate the snippet with
+  `themeBootstrapScript('your:key')` instead of editing it by hand.
+
+## App header
+
+Nebari apps in one deployment share a single header, so users read them as one
+product. Don't re-derive the layout from another app's source — this section is
+the canonical recipe. The reference implementation is
+[nebari-landing's `Header.tsx`](https://github.com/nebari-dev/nebari-landing/blob/main/frontend/src/components/Header.tsx).
+
+### Composition and sizing
+
+The header is built from `@nebari/navigation-menu` (its menus also need
+`@nebari/dropdown-menu`, `@nebari/avatar`, and `@nebari/button`):
+
+```sh
+npx shadcn add @nebari/navigation-menu @nebari/dropdown-menu @nebari/avatar @nebari/button
+```
+
+- **`NavigationMenu`** (alias of `MenuBar`, a semantic `<header>`) is the bar.
+  Its default is `h-12 px-3`; the canonical app header overrides to **`h-14`**
+  with **`pl-4`** (keeping the default `pr-3`) and the header tokens:
+
+  ```tsx
+  <NavigationMenu className="h-14 justify-between border-border bg-header pl-4 text-header-foreground">
+  ```
+
+- **`MenuBarBrand`** holds the logo, left-aligned, linking home:
+
+  ```tsx
+  <MenuBarBrand href="/" aria-label="Go to homepage">
+    <img src={logoSrc} alt="Nebari" className="h-8 w-auto" />
+  </MenuBarBrand>
+  ```
+
+  The logo is **`h-8 w-auto`**. Apps with light/dark logo variants pick by
+  `isDarkMode` from [`useTheme`](#dark-mode-state-usethemepreference).
+- **`MenuBarNav`** (optional) holds center `NavLink` / `NavDropdownMenu` items.
+- **`MenuBarActions`** is the right-side slot (use `className="gap-2"`) holding,
+  in order: the notifications menu (if the app has notifications) and the
+  profile/account menu.
+
+### Header token contract
+
+The header is styled **only** with semantic tokens — no hardcoded colors.
+The chrome surface itself ships with `@nebari/theme`: **`--header`** /
+**`--header-foreground`** are the app-chrome layer of the surface stack
+(`--canvas` → `--header` → `--card`/`--popover` → `--muted`), so use
+`bg-header text-header-foreground` with the plain `border-border`. Only the
+interaction and status colors below are **app-defined** — declare them in your
+theme CSS in both light and dark, plus the Tailwind `@theme` mappings that make
+`bg-header-action-hover` etc. resolve:
+
+```css
+:root {
+  --header-action-hover: #d9d9dc;
+  --notification-badge: #d00000;
+  --sign-out-foreground: #d2161c;
+}
+
+.dark {
+  --header-action-hover: #4a4a50;
+  --notification-badge: #e00000;
+  --sign-out-foreground: #ff6b6b;
+}
+
+@theme inline {
+  --color-header-action-hover: var(--header-action-hover);
+  --color-notification-badge: var(--notification-badge);
+  --color-sign-out-foreground: var(--sign-out-foreground);
+}
+```
+
+Registry-provided vs. app-defined:
+
+| Token | Source |
+|---|---|
+| `--primary`, `--muted`, `--card`, `--border`, … | `@nebari/theme` (registry) |
+| `--canvas`, `--header`, `--header-foreground` | `@nebari/theme` (registry) |
+| `--header-action-hover`, `--notification-badge`, `--sign-out-foreground` | **app-defined** (values above) |
+
+### Notifications menu
+
+A ghost icon `DropdownMenuTrigger` with a `Bell`, an unread-count badge on
+`bg-notification-badge`, and a **552px** menu. `modal={false}` keeps the page
+scrollable while the menu is open — don't omit it:
+
+```tsx
+<DropdownMenu modal={false} onOpenChange={(open) => open && markViewed()}>
+  <DropdownMenuTrigger
+    variant="ghost"
+    aria-label="Notifications"
+    className="relative w-8 px-0 hover:bg-header-action-hover hover:no-underline focus-visible:ring-offset-0 active:bg-header-action-hover"
+  >
+    <Bell />
+    {unreadCount > 0 && (
+      <span className="absolute -right-0.5 -top-0.5 z-10 flex h-4 min-w-4 items-center justify-center rounded-full bg-notification-badge px-1 pt-px text-[9px] font-semibold leading-none text-white tabular-nums">
+        {unreadCount}
+      </span>
+    )}
+  </DropdownMenuTrigger>
+  <DropdownMenuPortal>
+    <DropdownMenuContent align="end" className="max-h-(--available-height) w-[552px] overflow-y-auto p-0">
+      {/* one DropdownMenuItem per notification; unread items get a
+          h-2 w-2 rounded-full bg-primary dot */}
+    </DropdownMenuContent>
+  </DropdownMenuPortal>
+</DropdownMenu>
+```
+
+Only render the bell if the app actually has notifications — don't ship an
+empty menu.
+
+### Profile / account menu
+
+Avatar + user name + `ChevronDown` as the trigger; a **248px** menu
+(`w-[248px] p-2`) with a name/email section, the theme picker, then a red
+sign-out item:
+
+```tsx
+<DropdownMenu modal={false}>
+  <DropdownMenuTrigger
+    variant="ghost"
+    aria-label="Account menu"
+    className="h-auto px-2.5 py-1 hover:bg-header-action-hover hover:no-underline focus-visible:ring-offset-0 active:bg-header-action-hover data-[popup-open]:bg-header-action-hover data-[popup-open]:no-underline"
+  >
+    <Avatar>
+      {user.image && <AvatarImage src={user.image} alt={user.name} />}
+      <AvatarFallback className="bg-primary font-semibold text-primary-foreground">
+        {initials}
+      </AvatarFallback>
+    </Avatar>
+    <span>{user.name}</span>
+    <ChevronDown />
+  </DropdownMenuTrigger>
+  <DropdownMenuPortal>
+    <DropdownMenuContent align="end" className="w-[248px] p-2">
+      <div className="border-b px-1.5 pb-2">
+        <p className="text-sm font-medium text-foreground">{user.name}</p>
+        <p className="text-xs text-muted-foreground">{user.email}</p>
+      </div>
+
+      {/* Theme picker — see below */}
+
+      <DropdownMenuSeparator />
+
+      <DropdownMenuItem
+        className="leading-5 text-sign-out-foreground data-[highlighted]:text-sign-out-foreground"
+        onClick={signOut}
+      >
+        <LogOut className="size-4 shrink-0" aria-hidden="true" />
+        Sign out
+      </DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenuPortal>
+</DropdownMenu>
+```
+
+When no user is signed in, render a plain `<Button>` sign-in trigger in
+`MenuBarActions` instead of the menu.
+
+### Theme picker — a menu radio group, not tabs
+
+The Light/Dark/System control lives **inside the profile menu** (not as a
+standalone header button) and is a **menu radio group**: Base UI's
+`Menu.RadioGroup` / `Menu.RadioItem`, which render `role="menuitemradio"` with
+`aria-checked`. It only *looks* like a segmented control.
+
+Tabs are the wrong semantics here: `role="tab"` promises that selecting one
+reveals an associated `tabpanel`, which doesn't exist — a screen reader would
+announce a relationship that isn't there, and tab keyboard conventions fight
+the menu's own arrow-key navigation. "Pick exactly one of three values from a
+menu" is precisely what `menuitemradio` means.
+
+Wire it to the registry hook's state
+([`useTheme`](#dark-mode-state-usethemepreference) from
+`@nebari/use-theme-preference`) — never a bespoke theme store:
+
+```tsx
+import { Menu as MenuPrimitive } from '@base-ui/react/menu';
+import { isThemeMode } from '@/hooks/use-theme-preference';
+import { useTheme } from '@/hooks/theme-provider';
+
+const { themeMode, setThemeMode } = useTheme();
+
+<div className="py-2">
+  <MenuPrimitive.RadioGroup
+    aria-label="Theme"
+    value={themeMode}
+    onValueChange={(value) => {
+      if (isThemeMode(value)) setThemeMode(value);
+    }}
+    className="flex h-[34px] items-center gap-1 rounded-md bg-muted p-1"
+  >
+    {/* one per mode: light / dark / system */}
+    <MenuPrimitive.RadioItem
+      value="light"
+      aria-label="Light mode"
+      title="Light mode"
+      closeOnClick={false}
+      className={cn(
+        'flex h-auto flex-1 cursor-pointer items-center justify-center gap-1 rounded-sm border border-transparent px-1.5 py-0.5 text-sm font-medium outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        'text-muted-foreground-strong hover:text-foreground',
+        'data-checked:border-border-strong data-checked:bg-card data-checked:text-foreground data-checked:shadow-[0_1px_3px_0_rgba(0,0,0,0.10)]',
+      )}
+    >
+      <Sun className="h-4 w-4" />
+      <span>Light</span>
+    </MenuPrimitive.RadioItem>
+    {/* Dark → <Moon />, System → <Monitor />, same classes */}
+  </MenuPrimitive.RadioGroup>
+</div>
+```
+
+`closeOnClick={false}` lets the user try modes without the menu snapping shut.
+In tests, assert the picker exposes three `menuitemradio` items and that the
+active mode has `aria-checked="true"`.
+
+## Motion
+
+The `@nebari/theme` item ships motion tokens alongside the color and radius
+tokens. Use them to add consistent, accessible, on-brand animation at the
+**call site** — never by editing the installed `ui/*` component source (which
+`shadcn add` would overwrite on the next upgrade).
+
+### Available tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `--duration-fast` | `100ms` | Micro-interactions (icon swap, badge count) |
+| `--duration-base` | `200ms` | Standard enter/exit (tooltip, dropdown) |
+| `--duration-slow` | `350ms` | Page-level overlays (dialog, sheet, drawer) |
+| `--duration-loading` | `1600ms` | Non-essential loading pulse (skeleton) |
+| `--ease-standard` | `cubic-bezier(0.4, 0, 0.2, 1)` | Most transitions |
+| `--ease-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | Overlays sliding into view |
+
+And five ready-made Tailwind `animate-*` utilities (backed by `@keyframes`
+that the theme installs):
+
+| Utility | Effect |
+|---|---|
+| `animate-fade-in` | `opacity: 0 → 1` |
+| `animate-fade-out` | `opacity: 1 → 0` |
+| `animate-slide-up-fade` | fade + `translateY(6px → 0)` |
+| `animate-slide-down-fade` | fade + `translateY(0 → 6px)` |
+| `animate-skeleton-pulse` | repeating `opacity: 1 → 0.5 → 1` |
+
+### Hard rules
+
+1. **Always gate on `motion-safe:`** — Nebari targets WCAG 2.1 SC 2.3.3.
+   Every animation class must be prefixed: `motion-safe:animate-fade-in`.
+2. **Use tokens, never hardcode durations** — write `var(--duration-base)` in
+   custom CSS, or use the pre-built `animate-*` utilities. Never `0.2s`.
+   In Tailwind class names, reference a token with **parentheses, not
+   brackets**: `motion-safe:duration-(--duration-base)`,
+   `motion-safe:ease-(--ease-emphasized)`. Tailwind v3's bracket form
+   `duration-[--duration-base]` is invalid in v4 — `transition-duration` resets
+   to `0s` and the transition silently does nothing.
+3. **Animate `opacity` and `transform` only** — layout properties (`height`,
+   `width`, `padding`, `top`) force reflows; don't animate them.
+4. **CSS + Base UI first** — reach for JS animation libraries only when the
+   CSS primitives are insufficient (see the escape hatch below).
+
+### Recipes
+
+#### Entrance — fade / slide into view
+
+```tsx
+// Fade a card in on mount
+<Card className="motion-safe:animate-fade-in" />
+
+// Slide a list item up as it appears
+<li className="motion-safe:animate-slide-up-fade">…</li>
+```
+
+#### Press feedback — scale on active
+
+```tsx
+<Button className="motion-safe:active:scale-95 transition-transform">
+  Submit
+</Button>
+```
+
+#### Overlay enter/exit — Base UI `data-starting-style` / `data-ending-style`
+
+Base UI popups (Dialog, Select, Tooltip, …) apply `data-starting-style` and
+`data-ending-style` attributes during CSS transitions so you can define enter
+and exit animations purely in CSS. Use a plain `<style>` block or a CSS
+module — do **not** add inline styles to the component source:
+
+```css
+/* globals.css or a CSS module */
+[data-starting-style] {
+  opacity: 0;
+  transform: translateY(4px);
+}
+
+/* animate both opacity and transform so the color transition on the
+ * component itself still works — re-enumerate the properties here  */
+[data-starting-style],
+[data-ending-style] {
+  transition-property: opacity, transform;
+  transition-duration: var(--duration-base);
+  transition-timing-function: var(--ease-emphasized);
+}
+```
+
+#### Loading / skeleton pulse
+
+Use the `Skeleton` component for decorative loading placeholders. Its pulse is
+already reduced-motion gated and token-driven:
+
+```tsx
+import { Skeleton } from '@/components/ui/skeleton';
+
+<Skeleton className="w-48" />
+<Skeleton className="size-10" shape="circle" />
+<Skeleton className="h-40" shape="block" />
+```
+
+For app-specific loading artwork, reuse
+`motion-safe:animate-skeleton-pulse` instead of hardcoding a duration.
+
+### `cn()` / tailwind-merge gotcha
+
+When you add `transition-*` classes to a Nebari component via `className`,
+`tailwind-merge` (inside `cn()`) will deduplicate them against any transition
+classes already applied by the component's `cva` block. **Re-enumerate every
+transition property you need** so no property silently disappears:
+
+```tsx
+// ✅ Explicit — preserves component's existing color transition AND adds scale
+<Button
+  className={cn(
+    'motion-safe:transition-[color,background-color,transform]',
+    'motion-safe:duration-(--duration-base)',
+    'motion-safe:active:scale-95',
+  )}
+/>
+
+// ❌ Shorthand — 'transition' alone overwrites the component's transition-property
+<Button className="motion-safe:transition motion-safe:active:scale-95" />
+```
+
+### Call-site guardrail
+
+Never edit files under `ui/` to add animation. Those files are managed by
+`shadcn add` and will be overwritten on upgrade. All motion belongs in your
+app's `globals.css`, a CSS module, or a wrapper component that uses the Base
+UI `render` prop.
+
+### JS escape hatch — Motion via Base UI `render`
+
+For sequences that CSS alone can't express (exit animations that depend on JS
+state, staggered lists, spring physics), use the
+[Motion](https://motion.dev) library through Base UI's `render` prop. This
+keeps the original component's classes and `data-*` attributes intact:
+
+```tsx
+import { motion } from 'motion/react';
+import { Button } from '@/components/ui/button';
+
+<Button render={<motion.button animate={{ scale: [1, 0.96, 1] }} />}>
+  Save
+</Button>
+```
+
+Install Motion only when needed — it's not a default dependency of the
+registry.
+
+## Conventions when building with Nebari components
+
+- Prefer composing the existing components and variants over restyling them; pass
+  extra classes via `className` (it's merged with `cn()`, so your classes win).
+- Reach for `render` when you need a different element (link button, etc.) rather
+  than rewrapping.
+- Use the semantic tokens for any custom styling so the result stays
+  light/dark-correct and on-brand.
+- Need a component that isn't in the catalog yet? Fall back to the upstream
+  shadcn component, then style it with the same semantic tokens.
diff --git a/ui/components.json b/ui/components.json
index 0b8c1c2..ff48a1b 100644
--- a/ui/components.json
+++ b/ui/components.json
@@ -15,7 +15,7 @@
   "aliases": {
     "components": "@/components",
     "utils": "@/lib/utils",
-    "ui": "@/ui",
+    "ui": "@/components/ui",
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
diff --git a/ui/src/components/app-bits.tsx b/ui/src/components/app-bits.tsx
index ba9b163..319e254 100644
--- a/ui/src/components/app-bits.tsx
+++ b/ui/src/components/app-bits.tsx
@@ -1,8 +1,8 @@
 import { CheckCircle2, CircleDashed, Loader2, PauseCircle, XCircle } from 'lucide-react';
 import { type ReactNode, useState } from 'react';
-import { Badge } from '@/ui/badge';
-import { Button } from '@/ui/button';
-import { Card, CardContent } from '@/ui/card';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
 import {
   Dialog,
   DialogClose,
@@ -11,9 +11,9 @@ import {
   DialogFooter,
   DialogHeader,
   DialogTitle,
-} from '@/ui/dialog';
-import { Input } from '@/ui/input';
-import { Label } from '@/ui/label';
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
 import { cn } from '@/lib/utils';
 
 export function PhaseBadge({ phase }: { phase: string }) {
diff --git a/ui/src/components/app-form.tsx b/ui/src/components/app-form.tsx
index 582cbf0..b6721aa 100644
--- a/ui/src/components/app-form.tsx
+++ b/ui/src/components/app-form.tsx
@@ -1,13 +1,13 @@
 import { Plus, Trash2, UploadCloud } from 'lucide-react';
 import { useMemo, useState } from 'react';
 import type { App, AppCreate, AppPatch, AppSource, EnvVar } from '@/lib/types';
-import { Button } from '@/ui/button';
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/ui/card';
-import { Input } from '@/ui/input';
-import { Label } from '@/ui/label';
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/ui/select';
-import { Switch } from '@/ui/switch';
-import { Tabs, TabsList, TabsPanel, TabsTab } from '@/ui/tabs';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import { Switch } from '@/components/ui/switch';
+import { Tabs, TabsList, TabsPanel, TabsTab } from '@/components/ui/tabs';
 
 const SUBDOMAIN_RE = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/;
 
diff --git a/ui/src/ui/avatar.tsx b/ui/src/components/avatar.tsx
similarity index 100%
rename from ui/src/ui/avatar.tsx
rename to ui/src/components/avatar.tsx
diff --git a/ui/src/components/header.tsx b/ui/src/components/header.tsx
index 33af988..b634db8 100644
--- a/ui/src/components/header.tsx
+++ b/ui/src/components/header.tsx
@@ -16,7 +16,7 @@ import nebariLogoDark from '@/assets/nebari-logo_dark.svg';
 import { isThemeMode, type ThemeMode } from '@/hooks/use-theme-preference';
 import { getBranding } from '@/lib/branding';
 import { cn } from '@/lib/utils';
-import { Avatar, AvatarFallback } from '@/ui/avatar';
+import { Avatar, AvatarFallback } from '@/components/avatar';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -24,14 +24,14 @@ import {
   DropdownMenuPortal,
   DropdownMenuSeparator,
   DropdownMenuTrigger,
-} from '@/ui/dropdown-menu';
+} from '@/components/ui/dropdown-menu';
 import {
   MenuBarActions,
   MenuBarBrand,
   MenuBarNav,
   NavigationMenu,
   NavLink,
-} from '@/ui/navigation-menu';
+} from '@/components/ui/navigation-menu';
 
 const NAV = [
   { to: '/', label: 'Dashboard', icon: LayoutDashboard, end: true },
@@ -78,7 +78,7 @@ export function Header({
   const brandedLogo = isDarkMode ? (logoUrlDark ?? logoUrl) : logoUrl;
 
   return (
-    <NavigationMenu className="h-14 justify-between border-header-border bg-header-background pl-4 text-header-foreground">
+    <NavigationMenu className="h-14 justify-between border-header-border bg-header pl-4 text-header-foreground">
       <MenuBarBrand href="/" aria-label="Go to homepage">
         {brandedLogo ? (
           <img src={brandedLogo} alt={title || 'Nebari'} className="h-8 w-auto" />
diff --git a/ui/src/components/layout.tsx b/ui/src/components/layout.tsx
index 1f8a7d8..c4c2dbe 100644
--- a/ui/src/components/layout.tsx
+++ b/ui/src/components/layout.tsx
@@ -4,7 +4,7 @@ import { Header } from '@/components/header';
 import { useTheme } from '@/hooks/theme-provider';
 import { getUser, logout } from '@/lib/auth';
 import { getBranding } from '@/lib/branding';
-import { TooltipProvider } from '@/ui/tooltip';
+import { TooltipProvider } from '@/components/ui/tooltip';
 
 export function Layout() {
   const user = getUser();
@@ -26,7 +26,7 @@ export function Layout() {
           onSignOut={() => void logout()}
         />
 
-        <main className="min-w-0 flex-1 bg-body-background px-10 py-8">
+        <main className="min-w-0 flex-1 bg-canvas px-10 py-8">
           <Outlet />
         </main>
 
diff --git a/ui/src/components/onboarding.tsx b/ui/src/components/onboarding.tsx
index 2566d82..1bbfa58 100644
--- a/ui/src/components/onboarding.tsx
+++ b/ui/src/components/onboarding.tsx
@@ -1,10 +1,10 @@
 import { BookOpen, Copy, Rocket, Sparkles } from 'lucide-react';
 import { type ReactNode, useState } from 'react';
 import { Link } from 'react-router-dom';
-import { Button } from '@/ui/button';
-import { Card, CardContent } from '@/ui/card';
-import { toast } from '@/ui/toast';
-import { copyText } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+import { toast } from '@/components/ui/toast';
+import { copyText } from '@/lib/clipboard';
 
 /** First-run guidance shown when no apps exist yet. */
 export function Onboarding() {
@@ -17,7 +17,7 @@ export function Onboarding() {
       setCopied(true);
       setTimeout(() => setCopied(false), 1500);
     } catch {
-      toast.error('Could not copy to clipboard');
+      toast.add({ type: 'error', title: 'Could not copy to clipboard' });
     }
   };
 
diff --git a/ui/src/ui/alert.tsx b/ui/src/components/ui/alert.tsx
similarity index 100%
rename from ui/src/ui/alert.tsx
rename to ui/src/components/ui/alert.tsx
diff --git a/ui/src/ui/badge.tsx b/ui/src/components/ui/badge.tsx
similarity index 100%
rename from ui/src/ui/badge.tsx
rename to ui/src/components/ui/badge.tsx
diff --git a/ui/src/ui/button.tsx b/ui/src/components/ui/button.tsx
similarity index 96%
rename from ui/src/ui/button.tsx
rename to ui/src/components/ui/button.tsx
index c5d7c11..aba0feb 100644
--- a/ui/src/ui/button.tsx
+++ b/ui/src/components/ui/button.tsx
@@ -2,10 +2,10 @@ import { useRender } from '@base-ui/react/use-render';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { Children, isValidElement, type ReactNode } from 'react';
 import { cn } from '@/lib/utils';
-import { Spinner } from '@/ui/spinner';
+import { Spinner } from '@/components/ui/spinner';
 
 const buttonVariants = cva(
-  "inline-flex shrink-0 items-center justify-center gap-2 whitespace-nowrap rounded-md font-medium underline-offset-4 outline-none motion-safe:transition-[color,background-color,border-color,opacity,transform] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard] motion-safe:active:scale-[0.97] hover:underline focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background data-[disabled]:pointer-events-none data-[disabled]:text-muted-foreground data-[disabled]:no-underline data-[disabled]:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  "inline-flex shrink-0 items-center justify-center gap-2 whitespace-nowrap rounded-md font-medium underline-offset-4 outline-none motion-safe:transition-[color,background-color,border-color,opacity,transform] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard) motion-safe:active:scale-[0.97] hover:underline focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background data-[disabled]:pointer-events-none data-[disabled]:text-muted-foreground data-[disabled]:no-underline data-[disabled]:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
   {
     variants: {
       // Disabled and loading collapse to a muted look (Figma): the component
diff --git a/ui/src/ui/card.tsx b/ui/src/components/ui/card.tsx
similarity index 100%
rename from ui/src/ui/card.tsx
rename to ui/src/components/ui/card.tsx
diff --git a/ui/src/ui/checkbox.tsx b/ui/src/components/ui/checkbox.tsx
similarity index 100%
rename from ui/src/ui/checkbox.tsx
rename to ui/src/components/ui/checkbox.tsx
diff --git a/ui/src/ui/code-block.tsx b/ui/src/components/ui/code-block.tsx
similarity index 92%
rename from ui/src/ui/code-block.tsx
rename to ui/src/components/ui/code-block.tsx
index 4095a1f..299aa6f 100644
--- a/ui/src/ui/code-block.tsx
+++ b/ui/src/components/ui/code-block.tsx
@@ -8,7 +8,7 @@ import {
   useContext,
   useState,
 } from 'react';
-import { cn, copyText } from '@/lib/utils';
+import { cn } from '@/lib/utils';
 
 interface CodeBlockContextValue {
   /** The raw snippet, shared so descendants don't re-thread the text. */
@@ -25,6 +25,14 @@ interface CodeBlockContextValue {
 
 const CodeBlockContext = createContext<CodeBlockContextValue | null>(null);
 
+/**
+ * Reads the snippet and layout flags shared by the nearest {@link CodeBlock}.
+ * Use it to author a custom part — a line counter, a download button, a
+ * language badge — without re-threading `code` through props. Pass the calling
+ * component's name so a missing root reports which part failed; the context has
+ * no default value, so a call outside {@link CodeBlock} throws rather than
+ * rendering against an empty snippet.
+ */
 function useCodeBlockContext(component: string): CodeBlockContextValue {
   const context = useContext(CodeBlockContext);
   if (!context) {
@@ -230,7 +238,7 @@ function CodeBlockBody({
 }
 
 const codeBlockCopyButtonVariants = cva(
-  'inline-flex shrink-0 items-center justify-center rounded-md text-muted-foreground outline-none motion-safe:transition-[color,background-color,opacity,transform] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard] motion-safe:active:scale-[0.97] hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring [&_svg]:pointer-events-none',
+  'inline-flex shrink-0 items-center justify-center rounded-md text-muted-foreground outline-none motion-safe:transition-[color,background-color,opacity,transform] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard) motion-safe:active:scale-[0.97] hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring [&_svg]:pointer-events-none',
   {
     variants: {
       size: {
@@ -288,12 +296,12 @@ function CodeBlockCopyButton({
     async (event: React.MouseEvent<HTMLButtonElement>) => {
       onClick?.(event);
       try {
-        await copyText(code);
+        await navigator.clipboard.writeText(code);
         setCopied(true);
         window.setTimeout(() => setCopied(false), 2000);
       } catch {
-        // A denied permission rejects — keep the button resting rather than
-        // flashing a false confirmation.
+        // Insecure context or a denied permission rejects writeText — keep the
+        // button resting rather than flashing a false confirmation.
         setCopied(false);
       }
     },
@@ -321,11 +329,17 @@ function CodeBlockCopyButton({
   );
 }
 
-export type { CodeBlockBodyProps, CodeBlockCopyButtonProps, CodeBlockProps };
+export type {
+  CodeBlockBodyProps,
+  CodeBlockContextValue,
+  CodeBlockCopyButtonProps,
+  CodeBlockProps,
+};
 export {
   CodeBlock,
   CodeBlockBody,
   CodeBlockCopyButton,
   CodeBlockHeader,
   codeBlockCopyButtonVariants,
+  useCodeBlockContext,
 };
diff --git a/ui/src/ui/dialog.tsx b/ui/src/components/ui/dialog.tsx
similarity index 96%
rename from ui/src/ui/dialog.tsx
rename to ui/src/components/ui/dialog.tsx
index 8690216..2722cc5 100644
--- a/ui/src/ui/dialog.tsx
+++ b/ui/src/components/ui/dialog.tsx
@@ -2,7 +2,7 @@ import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
 import { XIcon } from 'lucide-react';
 import type * as React from 'react';
 import { cn } from '@/lib/utils';
-import { Button } from '@/ui/button';
+import { Button } from '@/components/ui/button';
 
 type DialogProps = DialogPrimitive.Root.Props;
 
@@ -49,7 +49,7 @@ function DialogOverlay({ className, ...props }: DialogOverlayProps) {
       data-slot="dialog-overlay"
       className={(state) =>
         cn(
-          'fixed inset-0 z-50 bg-scrim data-[starting-style]:opacity-0 data-[ending-style]:opacity-0 motion-safe:transition-[opacity] motion-safe:duration-[--duration-base] motion-safe:ease-[--ease-standard]',
+          'fixed inset-0 z-50 bg-scrim data-[starting-style]:opacity-0 data-[ending-style]:opacity-0 motion-safe:transition-[opacity] motion-safe:duration-(--duration-base) motion-safe:ease-(--ease-standard)',
           typeof className === 'function' ? className(state) : className,
         )
       }
@@ -85,7 +85,7 @@ function DialogContent({
           data-slot="dialog-content"
           className={(state) =>
             cn(
-              'relative grid max-h-[min(calc(100vh-2rem),42rem)] w-full max-w-lg gap-4 overflow-hidden rounded-md border border-border bg-popover p-6 text-popover-foreground shadow-lg outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background data-[starting-style]:translate-y-2 data-[starting-style]:scale-95 data-[starting-style]:opacity-0 data-[ending-style]:translate-y-2 data-[ending-style]:scale-95 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-[--duration-base] motion-safe:ease-[--ease-emphasized]',
+              'relative grid max-h-[min(calc(100vh-2rem),42rem)] w-full max-w-lg gap-4 overflow-hidden rounded-md border border-border bg-popover p-6 text-popover-foreground shadow-lg outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background data-[starting-style]:translate-y-2 data-[starting-style]:scale-95 data-[starting-style]:opacity-0 data-[ending-style]:translate-y-2 data-[ending-style]:scale-95 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-(--duration-base) motion-safe:ease-(--ease-emphasized)',
               typeof className === 'function' ? className(state) : className,
             )
           }
diff --git a/ui/src/ui/dropdown-menu.tsx b/ui/src/components/ui/dropdown-menu.tsx
similarity index 97%
rename from ui/src/ui/dropdown-menu.tsx
rename to ui/src/components/ui/dropdown-menu.tsx
index 0614d8e..dde50c5 100644
--- a/ui/src/ui/dropdown-menu.tsx
+++ b/ui/src/components/ui/dropdown-menu.tsx
@@ -3,10 +3,10 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { CheckIcon, ChevronRightIcon, ChevronsUpDownIcon } from 'lucide-react';
 import type * as React from 'react';
 import { cn } from '@/lib/utils';
-import { Button, type ButtonProps } from '@/ui/button';
+import { Button, type ButtonProps } from '@/components/ui/button';
 
 const dropdownMenuItemVariants = cva(
-  'relative flex w-full cursor-default items-center gap-2 rounded-[calc(var(--radius-md)-var(--spacing))] px-1.5 py-1 text-sm outline-hidden select-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring motion-safe:transition-[color,background-color] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard]',
+  'relative flex w-full cursor-default items-center gap-2 rounded-[calc(var(--radius-md)-var(--spacing))] px-1.5 py-1 text-sm outline-hidden select-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring motion-safe:transition-[color,background-color] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard)',
   {
     variants: {
       variant: {
@@ -155,7 +155,7 @@ function DropdownMenuContent({
       <MenuPrimitive.Popup
         data-slot="dropdown-menu-content"
         className={cn(
-          'z-50 min-w-60 origin-(--transform-origin) rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 data-[starting-style]:translate-y-1 data-[starting-style]:opacity-0 data-[ending-style]:translate-y-1 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-[--duration-base] motion-safe:ease-[--ease-emphasized]',
+          'z-50 min-w-60 origin-(--transform-origin) rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 data-[starting-style]:translate-y-1 data-[starting-style]:opacity-0 data-[ending-style]:translate-y-1 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-(--duration-base) motion-safe:ease-(--ease-emphasized)',
           className,
         )}
         {...props}
diff --git a/ui/src/ui/field.tsx b/ui/src/components/ui/field.tsx
similarity index 100%
rename from ui/src/ui/field.tsx
rename to ui/src/components/ui/field.tsx
diff --git a/ui/src/ui/input.tsx b/ui/src/components/ui/input.tsx
similarity index 94%
rename from ui/src/ui/input.tsx
rename to ui/src/components/ui/input.tsx
index 9f302b3..3fcbde3 100644
--- a/ui/src/ui/input.tsx
+++ b/ui/src/components/ui/input.tsx
@@ -24,7 +24,7 @@ function Input({ className, ...props }: InputProps) {
       <InputPrimitive
         data-slot="input"
         className={cn(
-          'peer flex w-full rounded-md border border-input bg-background px-3 py-1.5 text-foreground text-sm outline-none placeholder:text-muted-foreground motion-safe:transition-[color,background-color,border-color,box-shadow] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard] hover:border-border-strong focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:bg-muted disabled:opacity-50 aria-invalid:border-destructive-foreground aria-invalid:pr-9 aria-invalid:ring-2 aria-invalid:ring-destructive-foreground aria-invalid:focus-visible:ring-destructive-foreground data-[invalid]:border-destructive-foreground data-[invalid]:pr-9 data-[invalid]:ring-2 data-[invalid]:ring-destructive-foreground',
+          'peer flex w-full rounded-md border border-input bg-background px-3 py-1.5 text-foreground text-sm outline-none placeholder:text-muted-foreground motion-safe:transition-[color,background-color,border-color,box-shadow] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard) hover:border-border-strong focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:bg-muted disabled:opacity-50 aria-invalid:border-destructive-foreground aria-invalid:pr-9 aria-invalid:ring-2 aria-invalid:ring-destructive-foreground aria-invalid:focus-visible:ring-destructive-foreground data-[invalid]:border-destructive-foreground data-[invalid]:pr-9 data-[invalid]:ring-2 data-[invalid]:ring-destructive-foreground',
           className,
         )}
         {...props}
diff --git a/ui/src/ui/label.tsx b/ui/src/components/ui/label.tsx
similarity index 100%
rename from ui/src/ui/label.tsx
rename to ui/src/components/ui/label.tsx
diff --git a/ui/src/ui/navigation-menu.tsx b/ui/src/components/ui/navigation-menu.tsx
similarity index 94%
rename from ui/src/ui/navigation-menu.tsx
rename to ui/src/components/ui/navigation-menu.tsx
index 067510d..7a86aad 100644
--- a/ui/src/ui/navigation-menu.tsx
+++ b/ui/src/components/ui/navigation-menu.tsx
@@ -10,7 +10,7 @@ import {
   type DropdownMenuProps,
   DropdownMenuTrigger,
   type DropdownMenuTriggerProps,
-} from '@/ui/dropdown-menu';
+} from '@/components/ui/dropdown-menu';
 
 type NavLinkProps = useRender.ComponentProps<'a'> & {
   /** Marks the link as the current page or section. */
@@ -54,7 +54,7 @@ type MenuBarActionsProps = ComponentProps<'div'>;
  * Shared styles for application-level navigation links and dropdown triggers.
  */
 const navLinkVariants = cva(
-  'relative inline-flex h-10 shrink-0 items-center justify-center gap-1.5 whitespace-nowrap rounded-md px-2.5 font-medium text-foreground text-sm underline-offset-4 outline-none hover:bg-muted hover:underline focus-visible:ring-2 focus-visible:ring-ring data-[active=true]:after:absolute data-[active=true]:after:right-2 data-[active=true]:after:bottom-0 data-[active=true]:after:left-2 data-[active=true]:after:h-0.5 data-[active=true]:after:bg-primary data-[active=true]:after:content-[""] data-[disabled]:pointer-events-none data-[disabled]:bg-muted/50 data-[disabled]:text-muted-foreground data-[disabled]:no-underline motion-safe:transition-[color,background-color,border-color,opacity,transform] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard] motion-safe:active:scale-[0.97] [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*="size-"])]:size-4',
+  'relative inline-flex h-10 shrink-0 items-center justify-center gap-1.5 whitespace-nowrap rounded-md px-2.5 font-medium text-foreground text-sm underline-offset-4 outline-none hover:bg-muted hover:underline focus-visible:ring-2 focus-visible:ring-ring data-[active=true]:after:absolute data-[active=true]:after:right-2 data-[active=true]:after:bottom-0 data-[active=true]:after:left-2 data-[active=true]:after:h-0.5 data-[active=true]:after:bg-primary data-[active=true]:after:content-[""] data-[disabled]:pointer-events-none data-[disabled]:bg-muted/50 data-[disabled]:text-muted-foreground-strong data-[disabled]:no-underline motion-safe:transition-[color,background-color,border-color,opacity,transform] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard) motion-safe:active:scale-[0.97] [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*="size-"])]:size-4',
 );
 
 /**
diff --git a/ui/src/ui/radio-group.tsx b/ui/src/components/ui/radio-group.tsx
similarity index 100%
rename from ui/src/ui/radio-group.tsx
rename to ui/src/components/ui/radio-group.tsx
diff --git a/ui/src/ui/select.tsx b/ui/src/components/ui/select.tsx
similarity index 69%
rename from ui/src/ui/select.tsx
rename to ui/src/components/ui/select.tsx
index 07b3cb9..c2ec354 100644
--- a/ui/src/ui/select.tsx
+++ b/ui/src/components/ui/select.tsx
@@ -18,7 +18,7 @@ type SelectContentProps = SelectPrimitive.Popup.Props &
 const Select = SelectPrimitive.Root;
 
 const selectTriggerClassName =
-  "flex h-9 w-full items-center justify-between gap-1.5 rounded-md border border-input bg-background py-2 pr-2 pl-2.5 text-sm whitespace-nowrap shadow-xs outline-none hover:border-border-strong focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring focus-visible:hover:border-ring data-[pressed]:border-ring data-[pressed]:ring-2 data-[pressed]:ring-ring data-[pressed]:hover:border-ring data-[popup-open]:border-ring data-[popup-open]:ring-2 data-[popup-open]:ring-ring data-[popup-open]:hover:border-ring disabled:cursor-not-allowed disabled:border-border disabled:bg-muted disabled:text-muted-foreground aria-invalid:border-destructive-foreground aria-invalid:ring-2 aria-invalid:ring-destructive-foreground aria-invalid:hover:border-destructive-foreground aria-invalid:focus-visible:border-destructive-foreground aria-invalid:focus-visible:ring-destructive-foreground aria-invalid:data-[pressed]:border-destructive-foreground aria-invalid:data-[pressed]:ring-destructive-foreground aria-invalid:data-[popup-open]:border-destructive-foreground aria-invalid:data-[popup-open]:ring-destructive-foreground data-placeholder:text-muted-foreground *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
+  "flex min-h-8 w-full items-center justify-between gap-1.5 rounded-md border border-input bg-background py-1.5 pr-2 pl-2.5 text-sm whitespace-nowrap shadow-xs outline-none hover:border-border-strong focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring focus-visible:hover:border-ring data-[pressed]:border-ring data-[pressed]:ring-2 data-[pressed]:ring-ring data-[pressed]:hover:border-ring data-[popup-open]:border-ring data-[popup-open]:ring-2 data-[popup-open]:ring-ring data-[popup-open]:hover:border-ring disabled:cursor-not-allowed disabled:border-border disabled:bg-muted disabled:text-muted-foreground-strong aria-invalid:border-destructive-foreground aria-invalid:ring-2 aria-invalid:ring-destructive-foreground aria-invalid:hover:border-destructive-foreground aria-invalid:focus-visible:border-destructive-foreground aria-invalid:focus-visible:ring-destructive-foreground aria-invalid:data-[pressed]:border-destructive-foreground aria-invalid:data-[pressed]:ring-destructive-foreground aria-invalid:data-[popup-open]:border-destructive-foreground aria-invalid:data-[popup-open]:ring-destructive-foreground data-placeholder:text-muted-foreground *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
 
 /** Groups related options inside the popup list. */
 function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props) {
@@ -88,7 +88,7 @@ function SelectContent({
           data-slot="select-content"
           data-align-trigger={alignItemWithTrigger}
           className={cn(
-            'relative isolate z-50 max-h-(--available-height) w-(--anchor-width) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-md bg-popover text-popover-foreground opacity-100 shadow-md ring-1 ring-foreground/10 data-[starting-style]:translate-y-1 data-[starting-style]:opacity-0 data-[ending-style]:translate-y-1 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-[--duration-base] motion-safe:ease-[--ease-emphasized]',
+            'relative isolate z-50 max-h-(--available-height) w-(--anchor-width) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg bg-popover text-popover-foreground opacity-100 shadow-md ring-1 ring-foreground/10 data-[starting-style]:translate-y-1 data-[starting-style]:opacity-0 data-[ending-style]:translate-y-1 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-(--duration-base) motion-safe:ease-(--ease-emphasized)',
             className,
           )}
           {...props}
@@ -113,7 +113,7 @@ function SelectLabel({
     <SelectPrimitive.GroupLabel
       data-slot="select-label"
       className={cn(
-        'px-2 py-1.5 text-xs uppercase text-muted-foreground',
+        'px-1.5 py-1.5 font-medium text-muted-foreground text-xs uppercase tracking-[0.8px]',
         className,
       )}
       {...props}
@@ -121,7 +121,13 @@ function SelectLabel({
   );
 }
 
-/** Selectable option row. Disabled items are announced and cannot be selected. */
+/**
+ * Selectable option row (28px), styled like `ComboboxItem` — Figma shares the
+ * "Select Menu / Item" row between the two. Highlight uses `bg-muted`; a
+ * trailing check marks the selected value. Disabled items are announced, stay
+ * reachable by keyboard, and cannot be selected — they never get the highlight
+ * treatment from either pointer or keyboard.
+ */
 function SelectItem({
   className,
   children,
@@ -131,17 +137,17 @@ function SelectItem({
     <SelectPrimitive.Item
       data-slot="select-item"
       className={cn(
-        "relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        "relative flex w-full cursor-default items-center gap-2 rounded-md px-1.5 py-1 text-sm outline-hidden select-none not-data-[disabled]:data-[highlighted]:bg-muted not-data-[disabled]:data-[highlighted]:text-foreground data-[disabled]:cursor-not-allowed data-[disabled]:text-muted-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       {...props}
     >
-      <SelectPrimitive.ItemText className="flex flex-1 shrink-0 gap-2 whitespace-nowrap">
+      <SelectPrimitive.ItemText className="flex min-w-0 flex-1 gap-2 truncate whitespace-nowrap">
         {children}
       </SelectPrimitive.ItemText>
       <SelectPrimitive.ItemIndicator
         render={
-          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+          <span className="pointer-events-none flex size-4 shrink-0 items-center justify-center" />
         }
       >
         <CheckIcon className="pointer-events-none" />
diff --git a/ui/src/ui/slider.tsx b/ui/src/components/ui/slider.tsx
similarity index 96%
rename from ui/src/ui/slider.tsx
rename to ui/src/components/ui/slider.tsx
index d12231f..789a9cb 100644
--- a/ui/src/ui/slider.tsx
+++ b/ui/src/components/ui/slider.tsx
@@ -107,7 +107,7 @@ function Slider({
           <SliderPrimitive.Thumb
             className={(state) =>
               cn(
-                "relative block size-4 shrink-0 cursor-pointer rounded-full border border-primary bg-background shadow-sm outline-none select-none before:absolute before:top-1/2 before:left-1/2 before:size-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-[''] hover:border-primary-hover has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring has-[:focus-visible]:ring-offset-2 has-[:focus-visible]:ring-offset-background data-[disabled]:cursor-not-allowed data-[disabled]:border-border data-[disabled]:bg-muted data-[disabled]:shadow-none data-[dragging]:cursor-grabbing data-[dragging]:border-primary-hover data-[invalid]:border-destructive-foreground data-[invalid]:has-[:focus-visible]:ring-destructive-foreground motion-safe:transition-[border-color,background-color,box-shadow] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard]",
+                "relative block size-4 shrink-0 cursor-pointer rounded-full border border-primary bg-background shadow-sm outline-none select-none before:absolute before:top-1/2 before:left-1/2 before:size-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-[''] hover:border-primary-hover has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring has-[:focus-visible]:ring-offset-2 has-[:focus-visible]:ring-offset-background data-[disabled]:cursor-not-allowed data-[disabled]:border-border data-[disabled]:bg-muted data-[disabled]:shadow-none data-[dragging]:cursor-grabbing data-[dragging]:border-primary-hover data-[invalid]:border-destructive-foreground data-[invalid]:has-[:focus-visible]:ring-destructive-foreground motion-safe:transition-[border-color,background-color,box-shadow] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard)",
                 state.activeThumbIndex === thumb.index &&
                   '[&_[data-slot=slider-value-tooltip]]:visible [&_[data-slot=slider-value-tooltip]]:opacity-100',
               )
@@ -124,7 +124,7 @@ function Slider({
             {showValueTooltip && (
               <SliderPrimitive.Value
                 aria-hidden="true"
-                className="invisible pointer-events-none absolute z-10 min-w-8 rounded-sm bg-foreground px-2 py-1 text-background text-center text-xs opacity-0 shadow-md ring-1 ring-foreground/10 data-[orientation=horizontal]:bottom-full data-[orientation=horizontal]:left-1/2 data-[orientation=horizontal]:mb-2 data-[orientation=horizontal]:-translate-x-1/2 data-[orientation=vertical]:right-full data-[orientation=vertical]:top-1/2 data-[orientation=vertical]:mr-2 data-[orientation=vertical]:-translate-y-1/2 motion-safe:transition-opacity motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard]"
+                className="invisible pointer-events-none absolute z-10 min-w-8 rounded-sm bg-foreground px-2 py-1 text-background text-center text-xs opacity-0 shadow-md ring-1 ring-foreground/10 data-[orientation=horizontal]:bottom-full data-[orientation=horizontal]:left-1/2 data-[orientation=horizontal]:mb-2 data-[orientation=horizontal]:-translate-x-1/2 data-[orientation=vertical]:right-full data-[orientation=vertical]:top-1/2 data-[orientation=vertical]:mr-2 data-[orientation=vertical]:-translate-y-1/2 motion-safe:transition-opacity motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard)"
                 data-slot="slider-value-tooltip"
               >
                 {(formattedValues) => formattedValues[thumb.index]}
diff --git a/ui/src/ui/spinner.tsx b/ui/src/components/ui/spinner.tsx
similarity index 100%
rename from ui/src/ui/spinner.tsx
rename to ui/src/components/ui/spinner.tsx
diff --git a/ui/src/ui/switch.tsx b/ui/src/components/ui/switch.tsx
similarity index 87%
rename from ui/src/ui/switch.tsx
rename to ui/src/components/ui/switch.tsx
index f41da23..453f513 100644
--- a/ui/src/ui/switch.tsx
+++ b/ui/src/components/ui/switch.tsx
@@ -19,14 +19,14 @@ function Switch({ className, ...props }: SwitchProps) {
     <SwitchPrimitive.Root
       data-slot="switch"
       className={cn(
-        'relative inline-flex h-[18px] w-8 shrink-0 cursor-pointer items-center rounded-full p-0.5 outline-none motion-safe:transition-colors motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard] before:absolute before:left-1/2 before:top-1/2 before:h-full before:min-h-6 before:w-full before:min-w-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-[""] focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background data-[checked]:bg-primary data-[checked]:hover:bg-primary-hover data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 data-[unchecked]:bg-muted-foreground/40 data-[unchecked]:hover:bg-muted-foreground/70',
+        'relative inline-flex h-[18px] w-8 shrink-0 cursor-pointer items-center rounded-full p-0.5 outline-none motion-safe:transition-colors motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard) before:absolute before:left-1/2 before:top-1/2 before:h-full before:min-h-6 before:w-full before:min-w-6 before:-translate-x-1/2 before:-translate-y-1/2 before:content-[""] focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background data-[checked]:bg-primary data-[checked]:hover:bg-primary-hover data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 data-[unchecked]:bg-muted-foreground/40 data-[unchecked]:hover:bg-muted-foreground/70',
         className,
       )}
       {...props}
     >
       <SwitchPrimitive.Thumb
         data-slot="switch-thumb"
-        className="pointer-events-none block size-3.5 rounded-full bg-background shadow-sm motion-safe:transition-transform motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard] data-[checked]:translate-x-3.5 data-[unchecked]:translate-x-0"
+        className="pointer-events-none block size-3.5 rounded-full bg-background shadow-sm motion-safe:transition-transform motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard) data-[checked]:translate-x-3.5 data-[unchecked]:translate-x-0"
       />
     </SwitchPrimitive.Root>
   );
diff --git a/ui/src/ui/table.tsx b/ui/src/components/ui/table.tsx
similarity index 70%
rename from ui/src/ui/table.tsx
rename to ui/src/components/ui/table.tsx
index cc4f296..940e4f1 100644
--- a/ui/src/ui/table.tsx
+++ b/ui/src/components/ui/table.tsx
@@ -1,13 +1,17 @@
 // biome-ignore-all lint/a11y/noNoninteractiveTabindex: table scroll containers need keyboard access when content overflows.
 import type * as React from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { cn } from '@/lib/utils';
 
 type TableProps = React.ComponentProps<'table'> & {
-  /** Accessible name for the keyboard-focusable horizontal scroll container. */
+  /** Accessible name for the horizontal scroll container. */
   scrollContainerLabel?: string;
   /** Additional classes for the horizontal scroll container. */
   scrollContainerClassName?: string;
-  /** Props forwarded to the horizontal scroll container. */
+  /**
+   * Props forwarded to the horizontal scroll container. Its `tabIndex`
+   * overrides the automatic focusability applied when the table overflows.
+   */
   scrollContainerProps?: Omit<React.ComponentProps<'section'>, 'children'>;
 };
 
@@ -34,9 +38,27 @@ function Table({
     className: scrollContainerPropsClassName,
     'aria-label': scrollContainerAriaLabel,
     'aria-labelledby': scrollContainerAriaLabelledBy,
+    ref: scrollContainerRef,
     tabIndex: scrollContainerTabIndex,
     ...resolvedScrollContainerProps
   } = scrollContainerProps ?? {};
+  const internalScrollContainerRef = useRef<HTMLElement>(null);
+  const [isHorizontallyScrollable, setIsHorizontallyScrollable] =
+    useState(false);
+  const setScrollContainerRef = useCallback(
+    (element: HTMLElement | null) => {
+      internalScrollContainerRef.current = element;
+
+      if (typeof scrollContainerRef === 'function') {
+        return scrollContainerRef(element);
+      }
+
+      if (scrollContainerRef) {
+        scrollContainerRef.current = element;
+      }
+    },
+    [scrollContainerRef],
+  );
   const resolvedScrollContainerLabel =
     scrollContainerAriaLabel ??
     scrollContainerLabel ??
@@ -44,6 +66,38 @@ function Table({
       ? 'Table scroll area'
       : `${ariaLabel} scroll area`);
 
+  useEffect(() => {
+    const scrollContainer = internalScrollContainerRef.current;
+    if (!scrollContainer) {
+      return;
+    }
+
+    const updateScrollability = () => {
+      setIsHorizontallyScrollable(
+        scrollContainer.scrollWidth > scrollContainer.clientWidth,
+      );
+    };
+
+    updateScrollability();
+    window.addEventListener('resize', updateScrollability);
+
+    const resizeObserver =
+      typeof ResizeObserver === 'undefined'
+        ? undefined
+        : new ResizeObserver(updateScrollability);
+    resizeObserver?.observe(scrollContainer);
+
+    const table = scrollContainer.querySelector('table');
+    if (table) {
+      resizeObserver?.observe(table);
+    }
+
+    return () => {
+      window.removeEventListener('resize', updateScrollability);
+      resizeObserver?.disconnect();
+    };
+  }, []);
+
   return (
     <section
       {...resolvedScrollContainerProps}
@@ -54,7 +108,10 @@ function Table({
       }
       aria-labelledby={scrollContainerAriaLabelledBy}
       data-slot="table-container"
-      tabIndex={scrollContainerTabIndex ?? 0}
+      ref={setScrollContainerRef}
+      tabIndex={
+        scrollContainerTabIndex ?? (isHorizontallyScrollable ? 0 : undefined)
+      }
       className={cn(
         'relative w-full overflow-x-auto rounded-md border border-border bg-card outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
         scrollContainerClassName,
@@ -79,7 +136,7 @@ function TableHeader({ className, ...props }: React.ComponentProps<'thead'>) {
   return (
     <thead
       data-slot="table-header"
-      className={cn('bg-muted', className)}
+      className={cn('bg-background', className)}
       {...props}
     />
   );
@@ -113,7 +170,7 @@ function TableRow({ className, ...props }: React.ComponentProps<'tr'>) {
     <tr
       data-slot="table-row"
       className={cn(
-        'border-b border-border hover:bg-muted/50 data-[state=selected]:bg-muted data-[state=selected]:hover:bg-muted motion-safe:transition-[color,background-color] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard]',
+        'border-b border-border hover:bg-muted/50 data-[state=selected]:bg-muted data-[state=selected]:hover:bg-muted motion-safe:transition-[color,background-color] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard)',
         className,
       )}
       {...props}
@@ -139,14 +196,14 @@ function TableHead({
       data-slot="table-head"
       tabIndex={isInteractive ? undefined : tabIndex}
       className={cn(
-        'relative h-10 text-left align-middle font-medium text-foreground text-sm leading-5 tracking-normal whitespace-nowrap [&:has([role=checkbox])]:pr-0',
+        'relative h-10 bg-background text-left align-middle font-medium text-foreground text-sm leading-5 tracking-normal whitespace-nowrap [&:has([role=checkbox])]:pr-0',
         isInteractive ? 'p-0' : 'px-4',
         className,
       )}
     >
       {isInteractive ? (
         <button
-          className="inline-flex h-10 w-full cursor-pointer items-center justify-start gap-1 bg-transparent px-4 text-left font-medium text-foreground text-sm leading-5 tracking-normal underline-offset-4 outline-none hover:bg-muted-foreground/10 hover:underline focus-visible:bg-muted-foreground/10 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset motion-safe:transition-[color,background-color] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard]"
+          className="inline-flex h-10 w-full cursor-pointer items-center justify-start gap-1 bg-transparent px-4 text-left font-medium text-foreground text-sm leading-5 tracking-normal underline-offset-4 outline-none hover:bg-muted-foreground/10 hover:underline focus-visible:bg-muted-foreground/10 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset motion-safe:transition-[color,background-color] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard)"
           data-slot="table-head-button"
           onClick={onClick}
           onKeyDown={onKeyDown}
diff --git a/ui/src/ui/tabs.tsx b/ui/src/components/ui/tabs.tsx
similarity index 92%
rename from ui/src/ui/tabs.tsx
rename to ui/src/components/ui/tabs.tsx
index 7eb50d9..a3466e8 100644
--- a/ui/src/ui/tabs.tsx
+++ b/ui/src/components/ui/tabs.tsx
@@ -27,11 +27,11 @@ const tabsTabVariants = cva(
   {
     variants: {
       variant: {
-        pill: 'h-[calc(100%-1px)] rounded-sm border border-border bg-card px-2 py-1 data-[active]:border-border-strong data-[active]:shadow-[0_1px_1.5px_rgb(0_0_0_/_0.1)] data-[disabled]:bg-muted data-[orientation=vertical]:h-8',
+        pill: 'h-[calc(100%-1px)] rounded-sm border border-transparent px-2 py-1 data-[active]:border-border-strong data-[active]:bg-card data-[active]:shadow-[0_1px_1.5px_rgb(0_0_0_/_0.1)] data-[disabled]:bg-muted data-[orientation=vertical]:h-8',
         underline: 'rounded-none px-0 pb-2',
         line: 'rounded-none px-0 pb-2',
         toggle:
-          'h-[calc(100%-1px)] rounded-sm border border-border bg-card px-2 py-1 data-[active]:border-border-strong data-[active]:shadow-[0_1px_1.5px_rgb(0_0_0_/_0.1)] data-[disabled]:bg-muted data-[orientation=vertical]:h-8',
+          'h-[calc(100%-1px)] rounded-sm border border-transparent px-2 py-1 data-[active]:border-border-strong data-[active]:bg-card data-[active]:shadow-[0_1px_1.5px_rgb(0_0_0_/_0.1)] data-[disabled]:bg-muted data-[orientation=vertical]:h-8',
       },
     },
     defaultVariants: {
diff --git a/ui/src/ui/textarea.tsx b/ui/src/components/ui/textarea.tsx
similarity index 97%
rename from ui/src/ui/textarea.tsx
rename to ui/src/components/ui/textarea.tsx
index f638f0d..566f15d 100644
--- a/ui/src/ui/textarea.tsx
+++ b/ui/src/components/ui/textarea.tsx
@@ -22,7 +22,7 @@ function Textarea({ className, ...props }: TextareaProps) {
       <textarea
         data-slot="textarea"
         className={cn(
-          'peer flex min-h-16 w-full rounded-md border border-input bg-background px-3 py-1.5 text-foreground text-sm outline-none placeholder:text-muted-foreground motion-safe:transition-[color,background-color,border-color,box-shadow] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-standard] hover:border-border-strong focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:resize-none disabled:bg-muted disabled:opacity-50 aria-invalid:border-destructive-foreground aria-invalid:pr-9 aria-invalid:ring-2 aria-invalid:ring-destructive-foreground aria-invalid:focus-visible:ring-destructive-foreground data-[invalid]:border-destructive-foreground data-[invalid]:pr-9 data-[invalid]:ring-2 data-[invalid]:ring-destructive-foreground',
+          'peer flex min-h-16 w-full rounded-md border border-input bg-background px-3 py-1.5 text-foreground text-sm outline-none placeholder:text-muted-foreground motion-safe:transition-[color,background-color,border-color,box-shadow] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard) hover:border-border-strong focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:resize-none disabled:bg-muted disabled:opacity-50 aria-invalid:border-destructive-foreground aria-invalid:pr-9 aria-invalid:ring-2 aria-invalid:ring-destructive-foreground aria-invalid:focus-visible:ring-destructive-foreground data-[invalid]:border-destructive-foreground data-[invalid]:pr-9 data-[invalid]:ring-2 data-[invalid]:ring-destructive-foreground',
           className,
         )}
         {...props}
diff --git a/ui/src/components/ui/toast.tsx b/ui/src/components/ui/toast.tsx
new file mode 100644
index 0000000..b48446b
--- /dev/null
+++ b/ui/src/components/ui/toast.tsx
@@ -0,0 +1,590 @@
+import {
+  type ToastManager,
+  type ToastManagerPromiseOptions,
+  Toast as ToastPrimitive,
+  type UseToastManagerReturnValue,
+} from '@base-ui/react/toast';
+import { cva, type VariantProps } from 'class-variance-authority';
+import {
+  Bell,
+  CircleCheck,
+  CircleX,
+  Info,
+  LoaderCircle,
+  TriangleAlert,
+  X,
+} from 'lucide-react';
+import { type ReactNode, useMemo } from 'react';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+
+/** Semantic color treatment for each toast status icon. */
+const toastIconVariants = cva(
+  'flex shrink-0 items-start overflow-hidden pt-px [&_svg]:pointer-events-none [&_svg]:size-[18px]',
+  {
+    variants: {
+      variant: {
+        default: 'text-muted-foreground',
+        success: 'text-success-foreground',
+        warning: 'text-warning-foreground',
+        error: 'text-destructive-foreground',
+        info: 'text-info-foreground',
+        loading: 'text-muted-foreground',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+/** Status treatments supported by Nebari's built-in toast renderer. */
+type ToastType = NonNullable<VariantProps<typeof toastIconVariants>['variant']>;
+
+/** Optional behavior flags stored on a toast manager item. */
+interface ToastData {
+  /** Hides the leading status icon when set to `false`. */
+  showIcon?: boolean;
+  /**
+   * Hides the close button when set to `false`. Ignored on a toast carrying an
+   * `actionProps` action, which always keeps a way to dismiss it.
+   */
+  dismissible?: boolean;
+}
+
+/** Props for an individual Base UI toast root. */
+type ToastProps = Omit<ToastPrimitive.Root.Props, 'toast'> & {
+  /** Toast manager item rendered by the root. */
+  toast?: ToastPrimitive.Root.ToastObject<ToastData>;
+};
+
+/** Props for the complete toast renderer installed at the application root. */
+interface ToasterProps extends ToastPrimitive.Provider.Props {
+  /** Props forwarded to the portal that contains the toast viewport. */
+  portalProps?: Omit<ToastPrimitive.Portal.Props, 'children'>;
+  /** Props forwarded to the fixed bottom-right toast viewport. */
+  viewportProps?: Omit<ToastPrimitive.Viewport.Props, 'children'>;
+}
+
+/**
+ * Status types announced assertively. Base UI mirrors a `priority: 'high'` item
+ * into a visually hidden `role="alert"` node, which interrupts the screen
+ * reader; every other type is announced through the viewport's polite
+ * `aria-live` region so it doesn't cut off whatever the user is doing. The split
+ * mirrors the `role` mapping the `Alert` component applies to its own variants.
+ */
+const assertiveToastTypes = new Set<ToastType>(['warning', 'error']);
+
+/** The subset of a manager item Nebari derives accessibility defaults from. */
+interface ToastA11yOptions {
+  actionProps?: unknown;
+  priority?: 'low' | 'high';
+  timeout?: number;
+  type?: string;
+}
+
+/**
+ * Applies Nebari's accessibility rules to a manager item:
+ *
+ * - `priority` follows the status type, so `warning` and `error` interrupt.
+ *   This one is a default: an explicit `priority` is left alone, and it is only
+ *   assigned when the caller named a `type`, so a partial `update` that says
+ *   nothing about the type cannot reassign the item's priority.
+ * - a toast carrying an action never auto-dismisses, so the action cannot
+ *   disappear before it is used (WCAG 2.2.1). This one is not a default —
+ *   it overrides an explicit `timeout` rather than deferring to it. A toast is
+ *   either a notification, which may time out, or a prompt to act, which waits.
+ *   A caller who wants the timer keeps the action out of the toast.
+ *   {@link ToastList} pairs it with a close control that cannot be switched
+ *   off, so such a toast is dismissible rather than permanent.
+ *
+ * Both read the patch in front of them, not the item it will be merged onto:
+ * Base UI merges an update shallowly, so an `update` that changes the timeout
+ * of an already-actionable toast without restating `actionProps` is not
+ * re-checked. Keys are only added when they have a value, since emitting
+ * `undefined` would erase what is already on the item.
+ */
+function withToastA11yDefaults<T extends ToastA11yOptions>(options: T): T {
+  const patch: ToastA11yOptions = {};
+
+  if (options.priority === undefined && options.type !== undefined) {
+    patch.priority = assertiveToastTypes.has(getToastType(options.type))
+      ? 'high'
+      : 'low';
+  }
+
+  if (options.actionProps != null) {
+    patch.timeout = 0;
+  }
+
+  return Object.keys(patch).length > 0 ? { ...options, ...patch } : options;
+}
+
+/** Applies {@link withToastA11yDefaults} to one state of a promise toast. */
+function withPromiseStateA11yDefaults<State>(state: State): State {
+  // Base UI resolves the string form to a description-only toast, which carries
+  // neither a type nor an action, so there is nothing to default.
+  if (typeof state === 'string') {
+    return state;
+  }
+
+  if (typeof state === 'function') {
+    return ((result: unknown) =>
+      withPromiseStateA11yDefaults(
+        (state as (value: unknown) => unknown)(result),
+      )) as State;
+  }
+
+  return withToastA11yDefaults(state as ToastA11yOptions) as State;
+}
+
+/** Applies {@link withToastA11yDefaults} to all three states of `promise`. */
+function withPromiseA11yDefaults<Value, Data extends object>(
+  options: ToastManagerPromiseOptions<Value, Data>,
+): ToastManagerPromiseOptions<Value, Data> {
+  return {
+    loading: withPromiseStateA11yDefaults(options.loading),
+    success: withPromiseStateA11yDefaults(options.success),
+    error: withPromiseStateA11yDefaults(options.error),
+  };
+}
+
+/**
+ * Creates an isolated toast manager for a scoped renderer or a test. Wraps
+ * Base UI's factory so `add`, `update`, and `promise` all apply
+ * {@link withToastA11yDefaults}.
+ */
+function createToastManager<
+  Data extends ToastData = ToastData,
+>(): ToastManager<Data> {
+  const manager = ToastPrimitive.createToastManager<Data>();
+
+  return {
+    ...manager,
+    add: (options) => manager.add(withToastA11yDefaults(options)),
+    update: (id, updates) => manager.update(id, withToastA11yDefaults(updates)),
+    promise: (promiseValue, options) =>
+      manager.promise(promiseValue, withPromiseA11yDefaults(options)),
+  };
+}
+
+/**
+ * Reads the nearest provider's toasts and its imperative methods, which apply
+ * the same accessibility defaults as {@link createToastManager}. Use this in a
+ * custom renderer, or to raise a toast from a component below {@link Toaster}.
+ */
+function useToastManager<
+  Data extends ToastData = ToastData,
+>(): UseToastManagerReturnValue<Data> {
+  const manager = ToastPrimitive.useToastManager<Data>();
+
+  return useMemo(
+    () => ({
+      ...manager,
+      add: (options) => manager.add(withToastA11yDefaults(options)),
+      update: (id, updates) =>
+        manager.update(id, withToastA11yDefaults(updates)),
+      promise: (promiseValue, options) =>
+        manager.promise(promiseValue, withPromiseA11yDefaults(options)),
+    }),
+    [manager],
+  );
+}
+
+/** Global manager used by the default {@link Toaster}. */
+const toast = createToastManager<ToastData>();
+
+/**
+ * Class list for a toast root. Base UI publishes the geometry of the stack as
+ * CSS custom properties on each root — `--toast-index` (0 is frontmost),
+ * `--toast-height`, `--toast-offset-y`, and `--toast-swipe-movement-{x,y}` —
+ * and this list turns them into the Figma stack:
+ *
+ * - `--gap` / `--peek` are the expanded spacing and the collapsed sliver of
+ *   each toast behind the frontmost one.
+ * - `--scale` shrinks each toast a further 10% per step back, and `--shrink`
+ *   is the height that shrinking gives back, so collapsed toasts stay pinned
+ *   to the frontmost one's bottom edge.
+ * - `--offset-y` is the expanded translation: the viewport offset plus one
+ *   `--gap` per step back, adjusted by any in-flight swipe.
+ *
+ * Collapsed (default) uses `--peek`/`--scale`; `data-expanded` (viewport
+ * hovered or focused) switches to full height and `--offset-y`. The `after`
+ * pseudo-element bridges the `--gap` so pointer travel between stacked toasts
+ * doesn't collapse the stack. The `data-ending-style` rules send an exiting
+ * toast off the edge it was swiped toward, falling back to downward when it
+ * was dismissed without a swipe.
+ */
+const toastRootClassName = cn(
+  'group/toast pointer-events-auto absolute right-0 bottom-0 z-[calc(1000-var(--toast-index))] h-(--height) w-full origin-bottom rounded-md border border-border bg-popover text-popover-foreground shadow-lg will-change-transform outline-none select-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+  '[--gap:0.75rem] [--height:var(--toast-frontmost-height,var(--toast-height))] [--offset-y:calc(var(--toast-offset-y)*-1+calc(var(--toast-index)*var(--gap)*-1)+var(--toast-swipe-movement-y))] [--peek:0.75rem] [--scale:calc(max(0,1-(var(--toast-index)*0.1)))] [--shrink:calc(1-var(--scale))]',
+  '[transform:translateX(var(--toast-swipe-movement-x))_translateY(calc(var(--toast-swipe-movement-y)-(var(--toast-index)*var(--peek))-(var(--shrink)*var(--toast-height))))_scale(var(--scale))]',
+  "after:absolute after:top-full after:left-0 after:h-[calc(var(--gap)+1px)] after:w-full after:content-['']",
+  'data-expanded:h-(--toast-height) data-expanded:[transform:translateX(var(--toast-swipe-movement-x))_translateY(var(--offset-y))]',
+  'data-limited:opacity-0 data-starting-style:translate-y-[150%]',
+  '[&[data-ending-style]:not([data-limited]):not([data-swipe-direction])]:translate-y-[150%]',
+  'data-ending-style:data-[swipe-direction=down]:[transform:translateY(calc(var(--toast-swipe-movement-y)+150%))]',
+  'data-ending-style:data-[swipe-direction=left]:[transform:translateX(calc(var(--toast-swipe-movement-x)-150%))_translateY(var(--offset-y))]',
+  'data-ending-style:data-[swipe-direction=right]:[transform:translateX(calc(var(--toast-swipe-movement-x)+150%))_translateY(var(--offset-y))]',
+  'data-ending-style:data-[swipe-direction=up]:[transform:translateY(calc(var(--toast-swipe-movement-y)-150%))]',
+  'data-expanded:data-ending-style:data-[swipe-direction=down]:[transform:translateY(calc(var(--toast-swipe-movement-y)+150%))]',
+  'data-expanded:data-ending-style:data-[swipe-direction=left]:[transform:translateX(calc(var(--toast-swipe-movement-x)-150%))_translateY(var(--offset-y))]',
+  'data-expanded:data-ending-style:data-[swipe-direction=right]:[transform:translateX(calc(var(--toast-swipe-movement-x)+150%))_translateY(var(--offset-y))]',
+  'data-expanded:data-ending-style:data-[swipe-direction=up]:[transform:translateY(calc(var(--toast-swipe-movement-y)-150%))]',
+  'data-swiping:motion-safe:duration-0 motion-safe:transition-[opacity,transform] motion-safe:duration-(--duration-slow) motion-safe:ease-(--ease-emphasized)',
+);
+
+/** Normalizes arbitrary Base UI toast types to a supported visual treatment. */
+function getToastType(type: string | undefined): ToastType {
+  switch (type) {
+    case 'success':
+    case 'warning':
+    case 'error':
+    case 'info':
+    case 'loading':
+      return type;
+    default:
+      return 'default';
+  }
+}
+
+/** Provides toast state and timing to descendant toast primitives. */
+function ToastProvider(props: ToastPrimitive.Provider.Props) {
+  return <ToastPrimitive.Provider {...props} />;
+}
+
+/** Portals the toast viewport to the document body. */
+function ToastPortal(props: ToastPrimitive.Portal.Props) {
+  return <ToastPrimitive.Portal data-slot="toast-portal" {...props} />;
+}
+
+/**
+ * Fixed bottom-right region that contains the toast stack. It is responsive on
+ * small screens and matches Figma's 400 px desktop width.
+ */
+function ToastViewport({ className, ...props }: ToastPrimitive.Viewport.Props) {
+  return (
+    <ToastPrimitive.Viewport
+      data-slot="toast-viewport"
+      className={cn(
+        'pointer-events-none fixed inset-x-4 bottom-4 z-50 mx-auto w-auto max-w-[400px] outline-none sm:right-4 sm:left-auto sm:mx-0 sm:w-full',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Root for one managed toast. Base UI supplies stacking, focus pause, and swipe
+ * dismissal; Nebari supplies the neutral Figma surface and tokenized motion.
+ * A root is normally rendered for you by {@link Toaster}; render it directly
+ * only when composing a custom renderer around {@link useToastManager}.
+ * Without a `toast` item there is nothing to render, so — like `Dialog` and
+ * `Tooltip` — it falls back to a hidden placeholder rather than an empty
+ * surface, which also keeps the registry's SSR probe safe.
+ *
+ * The surface is not a focus stop; see {@link Toaster} for the keyboard model.
+ * A caller who gives it something to do on click opts back in by passing
+ * `tabIndex={0}`, and owns the key handler that makes it operable.
+ */
+function Toast({
+  className,
+  tabIndex,
+  toast: toastItem,
+  ...props
+}: ToastProps) {
+  const variant = getToastType(toastItem?.type);
+
+  if (!toastItem) {
+    return <div data-slot="toast" data-variant={variant} hidden />;
+  }
+
+  return (
+    <ToastPrimitive.Root
+      data-slot="toast"
+      data-variant={variant}
+      // A `loading` toast is reporting work still in flight, so the surface is
+      // marked busy until the manager updates it to a settled type.
+      aria-busy={variant === 'loading' || undefined}
+      className={cn(toastRootClassName, className)}
+      // Base UI makes every toast root tabbable by default, which is a stop on
+      // a surface that does nothing when activated — and a second stop ahead of
+      // the action on a toast that carries one. Nothing is lost by dropping it:
+      // the surface keeps its `dialog` role and name for a screen reader's
+      // virtual cursor, and Base UI's `F6` entry focuses it programmatically,
+      // which `tabIndex={-1}` still permits.
+      tabIndex={tabIndex ?? -1}
+      toast={toastItem}
+      {...props}
+    />
+  );
+}
+
+/** Lays out a toast's icon, copy, action, and close control. */
+function ToastContent({ className, ...props }: ToastPrimitive.Content.Props) {
+  return (
+    <ToastPrimitive.Content
+      data-slot="toast-content"
+      className={cn(
+        'flex h-full items-center gap-3 overflow-hidden p-3 opacity-100 has-data-[slot=toast-description]:items-start data-behind:opacity-0 data-expanded:opacity-100 motion-safe:transition-opacity motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-standard)',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** Renders the toast's concise heading. */
+function ToastTitle({ className, ...props }: ToastPrimitive.Title.Props) {
+  return (
+    <ToastPrimitive.Title
+      data-slot="toast-title"
+      className={cn('text-sm leading-5 font-medium', className)}
+      {...props}
+    />
+  );
+}
+
+/** Renders supporting text below the toast title. */
+function ToastDescription({
+  className,
+  ...props
+}: ToastPrimitive.Description.Props) {
+  return (
+    <ToastPrimitive.Description
+      data-slot="toast-description"
+      className={cn('text-muted-foreground text-sm leading-5', className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Optional short action rendered from a manager item's `actionProps`. Defaults
+ * to Nebari's 28 px outline button from the Figma design.
+ *
+ * Base UI treats an action as a button, so composing one into a link takes
+ * three parts. Without `nativeButton={false}` it warns and keeps applying
+ * native button semantics to an element that has none; with it, it applies
+ * `role="button"` instead — and the render element's own `role` is what wins
+ * that back. Omit either and the anchor stops being a link.
+ *
+ * ```tsx
+ * <ToastAction
+ *   nativeButton={false}
+ *   render={<a href="/deployments" role="link" />}
+ * />
+ * ```
+ *
+ * A linter may call that `role` redundant on an anchor. It is not: without it
+ * the rendered element announces as a button.
+ */
+function ToastAction({
+  className,
+  render = <Button variant="outline" size="sm" />,
+  ...props
+}: ToastPrimitive.Action.Props) {
+  return (
+    <ToastPrimitive.Action
+      data-slot="toast-action"
+      render={render}
+      // `Button` offsets its focus ring in `background`, which is the page
+      // colour, not this surface — on a `popover` toast that paints a visibly
+      // different band between the button's border and its ring, reading as a
+      // second border. Re-point it at the surface the button actually sits on,
+      // the way `Sidebar` does for its own.
+      className={cn(
+        'shrink-0 shadow-none focus-visible:ring-offset-popover',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Dismisses its containing toast and defaults to the Figma close icon button.
+ * Base UI keeps the control out of the accessibility tree while the stack is
+ * collapsed and exposes it once the viewport is hovered or focused, so its
+ * label is only ever announced in the context of a focused toast.
+ */
+function ToastClose({
+  className,
+  children,
+  'aria-label': ariaLabel = 'Dismiss',
+  render = <Button variant="ghost" size="icon-sm" />,
+  ...props
+}: ToastPrimitive.Close.Props) {
+  return (
+    <ToastPrimitive.Close
+      data-slot="toast-close"
+      aria-label={ariaLabel}
+      render={render}
+      // Offset the focus ring in the toast's own surface, not the page's — see
+      // {@link ToastAction}.
+      className={cn(
+        "relative shrink-0 text-foreground after:absolute after:-inset-2 after:content-[''] focus-visible:ring-offset-popover",
+        className,
+      )}
+      {...props}
+    >
+      {children ?? <X aria-hidden="true" className="size-4" />}
+    </ToastPrimitive.Close>
+  );
+}
+
+/** Props accepted by {@link ToastIcon}. */
+interface ToastIconProps {
+  /** Additional classes merged after the icon variant classes. */
+  className?: string;
+  /**
+   * Visual status represented by the icon. Any value outside {@link ToastType}
+   * — including the `undefined` a manager item carries when no type was set —
+   * falls back to the neutral `default` treatment.
+   */
+  type?: string;
+}
+
+/** Selects the status icon and semantic color associated with a toast type. */
+function ToastIcon({ className, type }: ToastIconProps) {
+  const variant = getToastType(type);
+  let icon: ReactNode;
+
+  switch (variant) {
+    case 'success':
+      icon = <CircleCheck aria-hidden="true" />;
+      break;
+    case 'warning':
+      icon = <TriangleAlert aria-hidden="true" />;
+      break;
+    case 'error':
+      icon = <CircleX aria-hidden="true" />;
+      break;
+    case 'info':
+      icon = <Info aria-hidden="true" />;
+      break;
+    case 'loading':
+      icon = (
+        <LoaderCircle aria-hidden="true" className="motion-safe:animate-spin" />
+      );
+      break;
+    default:
+      icon = <Bell aria-hidden="true" />;
+  }
+
+  return (
+    <span
+      data-slot="toast-icon"
+      data-variant={variant}
+      className={cn(toastIconVariants({ variant }), className)}
+    >
+      {icon}
+    </span>
+  );
+}
+
+/** Renders every active item from the nearest toast manager. */
+function ToastList() {
+  // Reads through Nebari's wrapper rather than Base UI's hook so there is one
+  // way into the manager from this file, and adding an imperative call here
+  // later can't quietly skip {@link withToastA11yDefaults}.
+  const { toasts } = useToastManager<ToastData>();
+
+  return toasts.map((toastItem) => {
+    const showIcon = toastItem.data?.showIcon !== false;
+    // An action must never be the only way out of a toast: one that carries an
+    // action keeps its close control even if `data.dismissible` says otherwise,
+    // which pairs with the timer `withToastA11yDefaults` clears for it.
+    const dismissible =
+      toastItem.actionProps != null || toastItem.data?.dismissible !== false;
+
+    return (
+      <Toast key={toastItem.id} toast={toastItem}>
+        <ToastContent>
+          {showIcon && <ToastIcon type={toastItem.type} />}
+          <div className="flex min-w-0 flex-1 flex-col gap-1 overflow-hidden break-words">
+            <ToastTitle />
+            <ToastDescription />
+          </div>
+          <ToastAction />
+          {dismissible && <ToastClose />}
+        </ToastContent>
+      </Toast>
+    );
+  });
+}
+
+/**
+ * Complete Nebari toast renderer. Mount once near the application root, then
+ * call `add`, `update`, or `promise` on the global {@link toast} manager (or on
+ * a scoped one passed as `toastManager`) from application code. The visible
+ * stack is capped at five items by default to match Figma.
+ *
+ * Accessibility, all supplied by Base UI unless noted:
+ *
+ * - **Announcements.** The viewport is one standing polite `aria-live` region
+ *   labelled "Notifications". `warning` and `error` toasts are raised to
+ *   `priority: 'high'` by {@link withToastA11yDefaults} and additionally
+ *   mirrored into a visually hidden `role="alert"`, so they interrupt. Two
+ *   standing regions rather than one that retags itself per toast: a screen
+ *   reader reads a live region's configuration when the region is registered,
+ *   so swapping `aria-live` on the viewport would not take effect for the toast
+ *   that triggered the swap — and one viewport can hold a `warning` and an
+ *   `info` at the same time, which leaves nothing to swap to. For the same
+ *   reason it is a named `region` with `aria-atomic="false"` rather than a
+ *   `role="status"`: it stays a navigable landmark, and only the toast that
+ *   just arrived is read out instead of the whole stack on every add.
+ * - **Keyboard.** `F6` from anywhere moves focus onto the viewport and pauses
+ *   the timers. `Tab` from there enters the frontmost toast — Base UI's focus
+ *   guard puts focus on the surface itself, so the title and description are
+ *   announced as one dialog — then reaches its action and close control in DOM
+ *   order. That surface is deliberately not in the sequential tab order, so it
+ *   is never a stop ahead of the action for someone tabbing through the page;
+ *   `F6` is the way in. `Escape` is handled per toast, so it dismisses
+ *   whichever one holds focus — the keyboard equivalent of swipe-to-dismiss —
+ *   and does nothing while focus is still on the viewport itself. `Shift+Tab`
+ *   off the viewport restores focus to where it was and resumes the timers.
+ * - **Timers.** Auto-dismiss pauses while the viewport is hovered, holds a
+ *   focus-visible element, or the window is blurred, and on touch pointer-down;
+ *   it resumes on leave or blur. A `loading` toast never auto-dismisses, and
+ *   neither does one carrying an action — whatever `timeout` it was given.
+ */
+function Toaster({
+  children,
+  limit = 5,
+  portalProps,
+  toastManager = toast,
+  viewportProps,
+  ...props
+}: ToasterProps) {
+  return (
+    <ToastProvider limit={limit} toastManager={toastManager} {...props}>
+      {children}
+      <ToastPortal {...portalProps}>
+        <ToastViewport {...viewportProps}>
+          <ToastList />
+        </ToastViewport>
+      </ToastPortal>
+    </ToastProvider>
+  );
+}
+
+export type { ToastData, ToasterProps, ToastIconProps, ToastProps, ToastType };
+export {
+  createToastManager,
+  Toast,
+  ToastAction,
+  ToastClose,
+  ToastContent,
+  ToastDescription,
+  Toaster,
+  ToastIcon,
+  ToastPortal,
+  ToastProvider,
+  ToastTitle,
+  ToastViewport,
+  toast,
+  toastIconVariants,
+  useToastManager,
+};
diff --git a/ui/src/ui/tooltip.tsx b/ui/src/components/ui/tooltip.tsx
similarity index 97%
rename from ui/src/ui/tooltip.tsx
rename to ui/src/components/ui/tooltip.tsx
index 86bfee6..e4057a1 100644
--- a/ui/src/ui/tooltip.tsx
+++ b/ui/src/components/ui/tooltip.tsx
@@ -115,7 +115,7 @@ function TooltipContent({
           role="tooltip"
           className={(state) =>
             cn(
-              'pointer-events-auto relative z-50 w-max max-w-xs origin-(--transform-origin) rounded-sm bg-foreground px-2.5 py-1.5 text-background text-xs leading-4 shadow-md outline-none data-[starting-style]:scale-95 data-[starting-style]:opacity-0 data-[ending-style]:scale-95 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-[--duration-fast] motion-safe:ease-[--ease-emphasized] has-data-[slot=kbd]:pr-1.5 **:data-[slot=kbd]:ml-1.5 **:data-[slot=kbd]:rounded-sm **:data-[slot=kbd]:bg-background/10 **:data-[slot=kbd]:px-1.5 **:data-[slot=kbd]:py-0.5 **:data-[slot=kbd]:font-mono **:data-[slot=kbd]:text-[0.6875rem] **:data-[slot=kbd]:leading-3',
+              'pointer-events-auto relative z-50 w-max max-w-xs origin-(--transform-origin) rounded-sm bg-foreground px-2.5 py-1.5 text-background text-xs leading-4 shadow-md outline-none data-[starting-style]:scale-95 data-[starting-style]:opacity-0 data-[ending-style]:scale-95 data-[ending-style]:opacity-0 motion-safe:transition-[opacity,transform] motion-safe:duration-(--duration-fast) motion-safe:ease-(--ease-emphasized) has-data-[slot=kbd]:pr-1.5 **:data-[slot=kbd]:ml-1.5 **:data-[slot=kbd]:rounded-sm **:data-[slot=kbd]:bg-background/10 **:data-[slot=kbd]:px-1.5 **:data-[slot=kbd]:py-0.5 **:data-[slot=kbd]:font-mono **:data-[slot=kbd]:text-[0.6875rem] **:data-[slot=kbd]:leading-3',
               typeof className === 'function' ? className(state) : className,
             )
           }
diff --git a/ui/src/index.css b/ui/src/index.css
index 950e282..ce6b6b9 100644
--- a/ui/src/index.css
+++ b/ui/src/index.css
@@ -18,14 +18,21 @@
  * Keep this file and the `theme` item in `registry.json` in sync: the installable
  * theme ships the same semantic values (flattened to their resolved oklch).
  *
- * One deliberate departure from the flattened form: the semantic tokens that are
- * pure shades of --primary / --ring (--primary-hover, --sidebar-primary,
- * --sidebar-primary-foreground, --sidebar-ring) reference those tokens instead of
- * naming a primitive, so a runtime `primary` / `primaryForeground` / `ring`
- * override from /config.json (see lib/branding.ts) propagates to them. Each still
- * resolves to its previous value for an unbranded install. Re-pulling the theme
- * with `shadcn add @nebari/theme` would restore the primitives, so
- * tests/lib/index-css.test.ts guards the derivation.
+ * Two deliberate departures from the registry file, both guarded by tests:
+ *
+ *   - The semantic tokens that are pure shades of --primary / --ring
+ *     (--primary-hover, --sidebar-primary, --sidebar-primary-foreground,
+ *     --sidebar-ring) reference those tokens instead of naming a primitive, so a
+ *     runtime `primary` / `primaryForeground` / `ring` override from /config.json
+ *     (see lib/branding.ts) propagates to them. Each still resolves to its
+ *     previous value for an unbranded install. Re-pulling the theme with
+ *     `shadcn add @nebari/theme` would restore the primitives, so
+ *     tests/lib/index-css.test.ts guards the derivation.
+ *   - The app-defined header tokens from the nebari-ui skill's "Header token
+ *     contract" (--header-border, --header-action-hover, --notification-badge,
+ *     --sign-out-foreground) are declared next to the registry's --header /
+ *     --header-foreground surface tokens, with matching `@theme inline`
+ *     mappings. The registry does not ship them.
  */
 :root {
   /* ── Primitives: Primary Magenta ─────────────────────────────────────── */
@@ -92,6 +99,7 @@
   --zinc-800: oklch(39.94% 0.0066 286.10); /* #47474b */
   --zinc-900: oklch(33.01% 0.0052 286.11); /* #353538 */
   --zinc-950: oklch(26.94% 0.0037 286.15); /* #262628 */
+  --zinc-975: oklch(21.86% 0.0039 286.08); /* #1a1a1c */
 
   /* ── Primitives: Blue ────────────────────────────────────────────────── */
   --blue-50: oklch(97.93% 0.0083 271.33); /* #f6f8fe */
@@ -160,24 +168,41 @@
 :root {
   --radius: 0.625rem;
 
+  /*
+   * Surface stack (Figma "color/background/*"). Four layers, stacked:
+   *   canvas → header → card / popover → muted.
+   * `--background` is Figma's background/default, which is DEPRECATED: its
+   * light value is identical to the header layer, which made headers invisible
+   * on pages painted with it. It is kept so existing consumers do not shift —
+   * migrate uses to canvas, header, card, or muted.
+   */
   --background: var(--zinc-50);
   --foreground: var(--zinc-950);
   --scrim: rgba(0, 0, 0, 0.5);
 
-  /* Top bar and page fills shared across Nebari apps (landing, llm-serving, …). */
-  --header-background: var(--zinc-50);
-  --header-border: var(--zinc-300);
-  --header-foreground: var(--zinc-950);
-  --header-action-hover: #d9d9dc; /* between zinc-200 and zinc-300; matches nebari-landing */
-  --body-background: var(--white);
+  /* Layer 0 — PAGE. The app body. Use on every page root. Nothing sits below. */
+  --canvas: var(--white);
+  --canvas-foreground: var(--zinc-950);
 
-  /* Header accents shared across Nebari apps (values mirror nebari-landing). */
+  /* Layer 1 — CHROME. App furniture framing the page: top bar / MenuBar,
+   * sidebar, toolbars, table head, sticky footer. Sits directly on canvas. */
+  --header: var(--zinc-50);
+  --header-foreground: var(--zinc-950);
+  /* App-defined header tokens (values mirror nebari-landing). --header-border
+   * follows the theme border so the bar renders as the canonical `border-border`
+   * while staying overridable through the `headerBorder` branding token. */
+  --header-border: var(--border);
+  --header-action-hover: #d9d9dc; /* between zinc-200 and zinc-300 */
   --notification-badge: #d00000;
   --sign-out-foreground: var(--red-600);
 
+  /* Layer 2 — RAISED. Cards, panels, dialogs, sheets. In light mode this is
+   * separated from canvas by border/default, NOT by fill. */
   --card: var(--white);
   --card-foreground: var(--zinc-950);
 
+  /* Layer 2 — RAISED, FLOATING. Popovers, dropdowns, tooltips, comboboxes.
+   * Same fill as card; differentiated by elevation shadow, not colour. */
   --popover: var(--white);
   --popover-foreground: var(--zinc-950);
 
@@ -196,9 +221,14 @@
   --secondary: var(--neutral-100);
   --secondary-foreground: var(--neutral-900);
 
+  /* Layer 3 — RECESSED. Only INSIDE a card or chrome: input fills, table zebra
+   * rows, progress/slider tracks, disabled states. In dark mode recesses lift,
+   * they do not dig. Muted text on this surface must use
+   * `--muted-foreground-strong`, not `--muted-foreground`. */
   --muted: var(--zinc-100);
   --muted-foreground: var(--zinc-600);
-  /* Figma color/foreground/muted-strong — pressed interactive text. */
+  /* Figma color/foreground/muted-strong — pressed interactive text, and any
+   * muted text sitting on `--muted`. */
   --muted-foreground-strong: var(--zinc-700);
 
   --accent: var(--neutral-100);
@@ -206,6 +236,9 @@
 
   /* Feedback pairs: a soft background fill + a strong foreground for text and
    * borders. Mirrors Figma's color/background/* and color/foreground/* roles. */
+  --info: var(--blue-100);
+  --info-foreground: var(--blue-600);
+
   --destructive: var(--red-100);
   --destructive-foreground: var(--red-600);
 
@@ -244,6 +277,7 @@
   --duration-fast: 100ms;
   --duration-base: 200ms;
   --duration-slow: 350ms;
+  --duration-loading: 1600ms;
   --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
   --ease-emphasized: cubic-bezier(0.2, 0, 0, 1);
 }
@@ -254,19 +288,20 @@
   --foreground: var(--zinc-50);
   --scrim: rgba(0, 0, 0, 0.6);
 
-  --header-background: var(--zinc-900);
-  --header-border: var(--zinc-700);
-  --header-foreground: var(--zinc-50);
-  --header-action-hover: #4a4a50; /* between zinc-800 and zinc-700; matches nebari-landing */
-  --body-background: var(--zinc-950);
+  --canvas: var(--zinc-975);
+  --canvas-foreground: var(--zinc-50);
 
+  --header: var(--zinc-950);
+  --header-foreground: var(--zinc-50);
+  --header-border: var(--border);
+  --header-action-hover: #4a4a50; /* between zinc-800 and zinc-700 */
   --notification-badge: #e00000;
   --sign-out-foreground: #ff6b6b; /* lighter than red-300 for contrast on dark popovers */
 
   --card: var(--zinc-900);
   --card-foreground: var(--zinc-50);
 
-  --popover: var(--zinc-950);
+  --popover: var(--zinc-900);
   --popover-foreground: var(--zinc-50);
 
   --primary: var(--primary-magenta-500);
@@ -280,13 +315,16 @@
   --secondary: var(--neutral-800);
   --secondary-foreground: var(--neutral-100);
 
-  --muted: var(--zinc-900);
+  --muted: var(--zinc-800);
   --muted-foreground: var(--zinc-400);
   --muted-foreground-strong: var(--zinc-300);
 
   --accent: var(--neutral-800);
   --accent-foreground: var(--neutral-100);
 
+  --info: var(--blue-900);
+  --info-foreground: var(--blue-400);
+
   --destructive: var(--red-900);
   --destructive-foreground: var(--red-300);
 
@@ -357,6 +395,16 @@
   }
 }
 
+@keyframes nebari-skeleton-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
 @theme inline {
   --font-sans: 'Geist Variable', ui-sans-serif, system-ui, sans-serif;
   --font-mono: 'IBM Plex Mono', ui-monospace, SFMono-Regular, monospace;
@@ -364,11 +412,14 @@
   --color-background: var(--background);
   --color-foreground: var(--foreground);
   --color-scrim: var(--scrim);
-  --color-header-background: var(--header-background);
-  --color-header-border: var(--header-border);
+
+  --color-canvas: var(--canvas);
+  --color-canvas-foreground: var(--canvas-foreground);
+
+  --color-header: var(--header);
   --color-header-foreground: var(--header-foreground);
+  --color-header-border: var(--header-border);
   --color-header-action-hover: var(--header-action-hover);
-  --color-body-background: var(--body-background);
   --color-notification-badge: var(--notification-badge);
   --color-sign-out-foreground: var(--sign-out-foreground);
 
@@ -392,6 +443,9 @@
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
 
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+
   --color-destructive: var(--destructive);
   --color-destructive-foreground: var(--destructive-foreground);
 
@@ -430,6 +484,7 @@
   --animate-fade-out: nebari-fade-out var(--duration-base) var(--ease-standard) both;
   --animate-slide-up-fade: nebari-slide-up-fade var(--duration-base) var(--ease-emphasized) both;
   --animate-slide-down-fade: nebari-slide-down-fade var(--duration-base) var(--ease-emphasized) both;
+  --animate-skeleton-pulse: nebari-skeleton-pulse var(--duration-loading) var(--ease-standard) infinite;
 }
 
 @layer base {
diff --git a/ui/src/lib/branding.ts b/ui/src/lib/branding.ts
index 3cf2e9a..9ff9def 100644
--- a/ui/src/lib/branding.ts
+++ b/ui/src/lib/branding.ts
@@ -28,7 +28,9 @@
  *
  * The first seventeen are the tokens every Nebari pack accepts. The `header*`
  * and `bodyBackground` tokens are extras specific to this pack, whose chrome is
- * a full-width top bar - see index.css.
+ * a full-width top bar - see index.css. `headerBackground` and `bodyBackground`
+ * land on the registry theme's surface tokens (`--header` and `--canvas`, see
+ * TOKEN_ALIASES) so the header and page keep following the design system.
  *
  * `primaryHover` (the button/badge/control hover and pressed fill),
  * `sidebarPrimary`, `sidebarPrimaryForeground` and `sidebarRing` are derived
@@ -176,12 +178,25 @@ export function getBranding(): BrandingConfig {
 
 const toKebab = (s: string) => s.replace(/([A-Z])/g, '-$1').toLowerCase();
 
+/**
+ * Branding keys whose CSS custom property is not the plain kebab-case of the
+ * key. The public config names predate the @nebari/theme surface tokens, so
+ * they keep working while mapping onto the registry's `--header` / `--canvas`.
+ */
+const TOKEN_ALIASES: Partial<Record<keyof ThemeTokens, string>> = {
+  headerBackground: 'header',
+  bodyBackground: 'canvas',
+};
+
+const toCssVarName = (key: string) =>
+  TOKEN_ALIASES[key as keyof ThemeTokens] ?? toKebab(key);
+
 /** Renders a token map to CSS declarations, dropping empty/unsafe values. */
 function toCssVars(tokens: ThemeTokens): string {
   return Object.entries(tokens)
     .map(([key, value]) => [key, safeCssValue(value)] as const)
     .filter((entry): entry is readonly [string, string] => entry[1] !== undefined)
-    .map(([key, value]) => `  --${toKebab(key)}: ${value};`)
+    .map(([key, value]) => `  --${toCssVarName(key)}: ${value};`)
     .join('\n');
 }
 
diff --git a/ui/src/lib/clipboard.ts b/ui/src/lib/clipboard.ts
new file mode 100644
index 0000000..19e9c9b
--- /dev/null
+++ b/ui/src/lib/clipboard.ts
@@ -0,0 +1,24 @@
+/**
+ * Copy text to the clipboard. `navigator.clipboard` only exists in secure
+ * contexts (HTTPS / localhost); on plain-HTTP deployments (e.g. local dev
+ * with tls.enabled=false) fall back to the legacy hidden-textarea approach.
+ * Rejects when neither path succeeds.
+ */
+export async function copyText(text: string): Promise<void> {
+  if (navigator.clipboard) {
+    await navigator.clipboard.writeText(text);
+    return;
+  }
+  const ta = document.createElement('textarea');
+  ta.value = text;
+  ta.setAttribute('readonly', '');
+  ta.style.position = 'fixed';
+  ta.style.opacity = '0';
+  document.body.appendChild(ta);
+  ta.select();
+  try {
+    if (!document.execCommand('copy')) throw new Error('copy command rejected');
+  } finally {
+    ta.remove();
+  }
+}
diff --git a/ui/src/lib/utils.ts b/ui/src/lib/utils.ts
index 3741c1c..9ad0df4 100644
--- a/ui/src/lib/utils.ts
+++ b/ui/src/lib/utils.ts
@@ -4,28 +4,3 @@ import { twMerge } from 'tailwind-merge';
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
-
-/**
- * Copy text to the clipboard. `navigator.clipboard` only exists in secure
- * contexts (HTTPS / localhost); on plain-HTTP deployments (e.g. local dev
- * with tls.enabled=false) fall back to the legacy hidden-textarea approach.
- * Rejects when neither path succeeds.
- */
-export async function copyText(text: string): Promise<void> {
-  if (navigator.clipboard) {
-    await navigator.clipboard.writeText(text);
-    return;
-  }
-  const ta = document.createElement('textarea');
-  ta.value = text;
-  ta.setAttribute('readonly', '');
-  ta.style.position = 'fixed';
-  ta.style.opacity = '0';
-  document.body.appendChild(ta);
-  ta.select();
-  try {
-    if (!document.execCommand('copy')) throw new Error('copy command rejected');
-  } finally {
-    ta.remove();
-  }
-}
diff --git a/ui/src/main.tsx b/ui/src/main.tsx
index 04d7b12..2fd4051 100644
--- a/ui/src/main.tsx
+++ b/ui/src/main.tsx
@@ -12,7 +12,7 @@ import { DashboardPage } from '@/pages/dashboard';
 import { EditPage } from '@/pages/edit';
 import { LaunchPage } from '@/pages/launch';
 import { MetricsPage } from '@/pages/metrics';
-import { Toaster } from '@/ui/toast';
+import { Toaster } from '@/components/ui/toast';
 import '@/index.css';
 
 // Branding comes from /config.json (ui.branding.* in the chart). Start the
diff --git a/ui/src/pages/app-detail.tsx b/ui/src/pages/app-detail.tsx
index 584dcfc..d911f0d 100644
--- a/ui/src/pages/app-detail.tsx
+++ b/ui/src/pages/app-detail.tsx
@@ -17,15 +17,15 @@ import { Link, useNavigate, useParams } from 'react-router-dom';
 import { AppThumbnail, ConfirmDeleteDialog, KindBadge, metricValue, PhaseBadge, Sparkline, SourceBadge } from '@/components/app-bits';
 import { api } from '@/lib/api';
 import type { App } from '@/lib/types';
-import { Alert, AlertDescription, AlertTitle } from '@/ui/alert';
-import { Button } from '@/ui/button';
-import { Card, CardContent, CardHeader, CardTitle } from '@/ui/card';
-import { CodeBlock, CodeBlockBody } from '@/ui/code-block';
-import { Input } from '@/ui/input';
-import { Spinner } from '@/ui/spinner';
-import { Switch } from '@/ui/switch';
-import { Tabs, TabsList, TabsPanel, TabsTab } from '@/ui/tabs';
-import { toast } from '@/ui/toast';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { CodeBlock, CodeBlockBody } from '@/components/ui/code-block';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { Switch } from '@/components/ui/switch';
+import { Tabs, TabsList, TabsPanel, TabsTab } from '@/components/ui/tabs';
+import { toast } from '@/components/ui/toast';
 
 const MAX_SAMPLES = 30;
 const errMessage = (err: unknown) => (err instanceof Error ? err.message : String(err));
@@ -85,34 +85,34 @@ export function AppDetailPage() {
     mutationFn: () => api.stopApp(namespace, name),
     onSuccess: () => {
       invalidate();
-      toast.success(`Stopped ${label()}`);
+      toast.add({ type: 'success', title: `Stopped ${label()}` });
     },
-    onError: (err) => toast.error(`Failed to stop ${label()}`, errMessage(err)),
+    onError: (err) => toast.add({ type: 'error', title: `Failed to stop ${label()}`, description: errMessage(err) }),
   });
   const start = useMutation({
     mutationFn: () => api.startApp(namespace, name),
     onSuccess: () => {
       invalidate();
-      toast.success(`Started ${label()}`);
+      toast.add({ type: 'success', title: `Started ${label()}` });
     },
-    onError: (err) => toast.error(`Failed to start ${label()}`, errMessage(err)),
+    onError: (err) => toast.add({ type: 'error', title: `Failed to start ${label()}`, description: errMessage(err) }),
   });
   const restart = useMutation({
     mutationFn: () => api.restartApp(namespace, name),
     onSuccess: () => {
       invalidate();
-      toast.success(`Restarting ${label()}`, 'Pods are rolling now.');
+      toast.add({ type: 'success', title: `Restarting ${label()}`, description: 'Pods are rolling now.' });
     },
-    onError: (err) => toast.error(`Failed to restart ${label()}`, errMessage(err)),
+    onError: (err) => toast.add({ type: 'error', title: `Failed to restart ${label()}`, description: errMessage(err) }),
   });
   const remove = useMutation({
     mutationFn: () => api.deleteApp(namespace, name),
     onSuccess: () => {
       invalidate();
-      toast.success(`Deleted ${label()}`);
+      toast.add({ type: 'success', title: `Deleted ${label()}` });
       void navigate('/apps');
     },
-    onError: (err) => toast.error(`Failed to delete ${label()}`, errMessage(err)),
+    onError: (err) => toast.add({ type: 'error', title: `Failed to delete ${label()}`, description: errMessage(err) }),
   });
 
   if (app.isLoading) {
diff --git a/ui/src/pages/apps.tsx b/ui/src/pages/apps.tsx
index 1c6f753..f0721c2 100644
--- a/ui/src/pages/apps.tsx
+++ b/ui/src/pages/apps.tsx
@@ -18,8 +18,8 @@ import { AppThumbnail, ConfirmDeleteDialog, PhaseBadge, SourceBadge } from '@/co
 import { Onboarding } from '@/components/onboarding';
 import { api } from '@/lib/api';
 import type { App } from '@/lib/types';
-import { Button } from '@/ui/button';
-import { Checkbox } from '@/ui/checkbox';
+import { Button } from '@/components/ui/button';
+import { Checkbox } from '@/components/ui/checkbox';
 import {
   Dialog,
   DialogClose,
@@ -28,12 +28,12 @@ import {
   DialogFooter,
   DialogHeader,
   DialogTitle,
-} from '@/ui/dialog';
-import { Input } from '@/ui/input';
-import { Spinner } from '@/ui/spinner';
-import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/ui/table';
-import { toast } from '@/ui/toast';
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/ui/tooltip';
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';
+import { toast } from '@/components/ui/toast';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 import { cn } from '@/lib/utils';
 
 const appLabel = (app: App) => app.displayName || app.name;
@@ -69,26 +69,26 @@ export function AppsPage() {
     mutationFn: (app: App) => api.stopApp(app.namespace, app.name),
     onSuccess: (_d, app) => {
       invalidate();
-      toast.success(`Stopped ${appLabel(app)}`);
+      toast.add({ type: 'success', title: `Stopped ${appLabel(app)}` });
     },
-    onError: (err, app) => toast.error(`Failed to stop ${appLabel(app)}`, errMessage(err)),
+    onError: (err, app) => toast.add({ type: 'error', title: `Failed to stop ${appLabel(app)}`, description: errMessage(err) }),
   });
   const start = useMutation({
     mutationFn: (app: App) => api.startApp(app.namespace, app.name),
     onSuccess: (_d, app) => {
       invalidate();
-      toast.success(`Started ${appLabel(app)}`);
+      toast.add({ type: 'success', title: `Started ${appLabel(app)}` });
     },
-    onError: (err, app) => toast.error(`Failed to start ${appLabel(app)}`, errMessage(err)),
+    onError: (err, app) => toast.add({ type: 'error', title: `Failed to start ${appLabel(app)}`, description: errMessage(err) }),
   });
   const remove = useMutation({
     mutationFn: (app: App) => api.deleteApp(app.namespace, app.name),
     onSuccess: (_d, app) => {
       invalidate();
       setDeleteTarget(null);
-      toast.success(`Deleted ${appLabel(app)}`);
+      toast.add({ type: 'success', title: `Deleted ${appLabel(app)}` });
     },
-    onError: (err, app) => toast.error(`Failed to delete ${appLabel(app)}`, errMessage(err)),
+    onError: (err, app) => toast.add({ type: 'error', title: `Failed to delete ${appLabel(app)}`, description: errMessage(err) }),
   });
 
   const list = apps.data ?? [];
@@ -164,9 +164,9 @@ export function AppsPage() {
       setBulkDeleteOpen(false);
       setBulkConfirm('');
       setSelected(new Set());
-      toast.success(`${action === 'delete' ? 'Deleted' : action === 'stop' ? 'Stopped' : 'Started'} ${selectedApps.length} app(s)`);
+      toast.add({ type: 'success', title: `${action === 'delete' ? 'Deleted' : action === 'stop' ? 'Stopped' : 'Started'} ${selectedApps.length} app(s)` });
     },
-    onError: (err) => toast.error('Bulk action failed', errMessage(err)),
+    onError: (err) => toast.add({ type: 'error', title: 'Bulk action failed', description: errMessage(err) }),
   });
 
   const toggleSort = (col: SortCol) =>
diff --git a/ui/src/pages/dashboard.tsx b/ui/src/pages/dashboard.tsx
index 2544118..d5eacfd 100644
--- a/ui/src/pages/dashboard.tsx
+++ b/ui/src/pages/dashboard.tsx
@@ -4,9 +4,9 @@ import { Link } from 'react-router-dom';
 import { AppThumbnail, BarList, KindBadge, PhaseBadge, SourceBadge, StatCard } from '@/components/app-bits';
 import { Onboarding } from '@/components/onboarding';
 import { api } from '@/lib/api';
-import { Button } from '@/ui/button';
-import { Card, CardContent, CardHeader, CardTitle } from '@/ui/card';
-import { Spinner } from '@/ui/spinner';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Spinner } from '@/components/ui/spinner';
 
 export function DashboardPage() {
   const analytics = useQuery({ queryKey: ['analytics'], queryFn: api.analytics });
diff --git a/ui/src/pages/edit.tsx b/ui/src/pages/edit.tsx
index 0c21309..a01a912 100644
--- a/ui/src/pages/edit.tsx
+++ b/ui/src/pages/edit.tsx
@@ -4,9 +4,9 @@ import { Link, useNavigate, useParams } from 'react-router-dom';
 import { AppForm, type SubmitPayload } from '@/components/app-form';
 import { api } from '@/lib/api';
 import { getConfig } from '@/lib/auth';
-import { Alert, AlertDescription, AlertTitle } from '@/ui/alert';
-import { Spinner } from '@/ui/spinner';
-import { toast } from '@/ui/toast';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { Spinner } from '@/components/ui/spinner';
+import { toast } from '@/components/ui/toast';
 
 export function EditPage() {
   const { namespace = '', name = '' } = useParams();
@@ -27,10 +27,10 @@ export function EditPage() {
     onSuccess: (updated) => {
       void queryClient.invalidateQueries({ queryKey: ['app', namespace, name] });
       void queryClient.invalidateQueries({ queryKey: ['apps'] });
-      toast.success(`Saved ${updated.displayName || updated.name}`);
+      toast.add({ type: 'success', title: `Saved ${updated.displayName || updated.name}` });
       void navigate(`/apps/${namespace}/${name}`);
     },
-    onError: (err) => toast.error('Save failed', err instanceof Error ? err.message : String(err)),
+    onError: (err) => toast.add({ type: 'error', title: 'Save failed', description: err instanceof Error ? err.message : String(err) }),
   });
 
   if (app.isLoading) {
diff --git a/ui/src/pages/launch.tsx b/ui/src/pages/launch.tsx
index 662ec68..2d7a358 100644
--- a/ui/src/pages/launch.tsx
+++ b/ui/src/pages/launch.tsx
@@ -4,7 +4,7 @@ import { AppForm, type SubmitPayload } from '@/components/app-form';
 import { api } from '@/lib/api';
 import { getConfig } from '@/lib/auth';
 import type { AppCreate } from '@/lib/types';
-import { toast } from '@/ui/toast';
+import { toast } from '@/components/ui/toast';
 
 export function LaunchPage() {
   const navigate = useNavigate();
@@ -21,13 +21,14 @@ export function LaunchPage() {
       throw new Error('unexpected payload for launch');
     },
     onSuccess: (app) => {
-      toast.success(
-        `Launched ${app.displayName || app.name}`,
-        'Deploying now — status will update on the app page.',
-      );
+      toast.add({
+        type: 'success',
+        title: `Launched ${app.displayName || app.name}`,
+        description: 'Deploying now — status will update on the app page.',
+      });
       void navigate(`/apps/${app.namespace}/${app.name}`);
     },
-    onError: (err) => toast.error('Launch failed', err instanceof Error ? err.message : String(err)),
+    onError: (err) => toast.add({ type: 'error', title: 'Launch failed', description: err instanceof Error ? err.message : String(err) }),
   });
 
   return (
diff --git a/ui/src/pages/metrics.tsx b/ui/src/pages/metrics.tsx
index fccf130..50cc0d4 100644
--- a/ui/src/pages/metrics.tsx
+++ b/ui/src/pages/metrics.tsx
@@ -4,8 +4,8 @@ import type { ReactNode } from 'react';
 import { Link } from 'react-router-dom';
 import { api } from '@/lib/api';
 import type { App } from '@/lib/types';
-import { Card, CardContent, CardHeader, CardTitle } from '@/ui/card';
-import { Spinner } from '@/ui/spinner';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Spinner } from '@/components/ui/spinner';
 
 export function MetricsPage() {
   const metrics = useQuery({
diff --git a/ui/src/ui/toast.tsx b/ui/src/ui/toast.tsx
deleted file mode 100644
index 80ffcf2..0000000
--- a/ui/src/ui/toast.tsx
+++ /dev/null
@@ -1,98 +0,0 @@
-import { Toast as ToastPrimitive } from '@base-ui/react/toast';
-import { CheckCircle2, X, XCircle } from 'lucide-react';
-import { cn } from '@/lib/utils';
-
-const toastManager = ToastPrimitive.createToastManager();
-
-/**
- * Imperative toast helpers, callable from anywhere (mutation callbacks, event
- * handlers) — no hook or context needed. Rendered by the app-level
- * {@link Toaster}.
- */
-const toast = {
-  success(title: string, description?: string) {
-    return toastManager.add({ type: 'success', title, description });
-  },
-  // Errors are announced urgently and stick around longer so the message can
-  // actually be read.
-  error(title: string, description?: string) {
-    return toastManager.add({
-      type: 'error',
-      title,
-      description,
-      priority: 'high',
-      timeout: 8_000,
-    });
-  },
-};
-
-function ToastIcon({ type }: { type?: string }) {
-  if (type === 'success') {
-    return <CheckCircle2 className="mt-0.5 size-4 shrink-0 text-success-foreground" />;
-  }
-  if (type === 'error') {
-    return <XCircle className="mt-0.5 size-4 shrink-0 text-destructive-foreground" />;
-  }
-  return null;
-}
-
-function ToastList() {
-  const { toasts } = ToastPrimitive.useToastManager();
-  return toasts.map((t) => (
-    <ToastPrimitive.Root
-      key={t.id}
-      toast={t}
-      data-slot="toast"
-      className={cn(
-        'absolute right-0 bottom-0 flex w-full select-none items-start gap-2.5 rounded-md border border-border bg-popover bg-clip-padding p-3 pr-8 text-popover-foreground shadow-lg',
-        // Collapsed stack: newest toast sits on top, older ones peek out
-        // behind it, nudged up and scaled down by their index. The swipe
-        // offsets keep swipe-to-dismiss tracking the pointer.
-        'z-[calc(1000-var(--toast-index))] [--gap:0.625rem] [transform:translateX(var(--toast-swipe-movement-x))_translateY(calc(var(--toast-swipe-movement-y)+min(var(--toast-index),10)*-0.875rem))_scale(max(0,1-var(--toast-index)*0.05))]',
-        // Invisible spacer above each toast bridging the expanded gap, so the
-        // stack stays hovered (expanded) while the pointer moves between toasts.
-        'after:absolute after:bottom-full after:left-0 after:h-[calc(var(--gap)+1px)] after:w-full after:content-[""]',
-        // Expanded (hover/focus) layout: full-height list with a fixed gap.
-        'data-[expanded]:[transform:translateX(var(--toast-swipe-movement-x))_translateY(calc(-1*var(--toast-offset-y)+var(--toast-index)*-1*var(--gap)+var(--toast-swipe-movement-y)))]',
-        'data-[starting-style]:[transform:translateY(150%)]',
-        'data-[ending-style]:opacity-0 data-[ending-style]:[transform:translateY(150%)] data-[ending-style]:data-[swipe-direction=right]:[transform:translateX(calc(var(--toast-swipe-movement-x)+150%))]',
-        'data-[limited]:opacity-0',
-        'motion-safe:transition-[transform,opacity] motion-safe:duration-[var(--duration-slow)] motion-safe:ease-[var(--ease-emphasized)]',
-      )}
-    >
-      <ToastIcon type={t.type} />
-      <div className="min-w-0 flex-1 space-y-0.5">
-        <ToastPrimitive.Title className="font-medium text-sm" />
-        <ToastPrimitive.Description className="break-words text-muted-foreground text-sm" />
-      </div>
-      <ToastPrimitive.Close
-        aria-label="Dismiss notification"
-        className="absolute top-2 right-2 rounded-sm p-1 text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
-      >
-        <X className="size-3.5" />
-      </ToastPrimitive.Close>
-    </ToastPrimitive.Root>
-  ));
-}
-
-/**
- * App-level toast outlet. Mount once (next to the router); fire notifications
- * from anywhere with {@link toast}. Toasts stack bottom-right, expand on
- * hover, and can be swiped away.
- */
-function Toaster() {
-  return (
-    <ToastPrimitive.Provider toastManager={toastManager}>
-      <ToastPrimitive.Portal>
-        <ToastPrimitive.Viewport
-          data-slot="toast-viewport"
-          className="fixed right-4 bottom-4 z-50 flex w-[22rem] max-w-[calc(100vw-2rem)] sm:right-6 sm:bottom-6"
-        >
-          <ToastList />
-        </ToastPrimitive.Viewport>
-      </ToastPrimitive.Portal>
-    </ToastPrimitive.Provider>
-  );
-}
-
-export { toast, Toaster };
diff --git a/ui/tests/lib/branding.test.ts b/ui/tests/lib/branding.test.ts
index 019d628..3e63219 100644
--- a/ui/tests/lib/branding.test.ts
+++ b/ui/tests/lib/branding.test.ts
@@ -74,7 +74,7 @@ describe('applyBranding', () => {
     expect(css).toContain(':root {');
     expect(css).toContain('--primary: #0066cc;');
     expect(css).toContain('--primary-foreground: #ffffff;');
-    expect(css).toContain('--header-background: #f5f5f5;');
+    expect(css).toContain('--header: #f5f5f5;');
     expect(css).toContain('.dark {');
     expect(css).toContain('--primary: #4da6ff;');
   });
diff --git a/ui/tsconfig.json b/ui/tsconfig.json
index 1ffef60..50f795e 100644
--- a/ui/tsconfig.json
+++ b/ui/tsconfig.json
@@ -1,7 +1,19 @@
 {
   "files": [],
   "references": [
-    { "path": "./tsconfig.app.json" },
-    { "path": "./tsconfig.node.json" }
-  ]
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.node.json"
+    }
+  ],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    }
+  }
 }