diff --git a/frontend/DESIGN.md b/frontend/DESIGN.md
new file mode 100644
index 00000000..81a41e0c
--- /dev/null
+++ b/frontend/DESIGN.md
@@ -0,0 +1,502 @@
+# DocsGPT frontend design system
+
+The UI is Tailwind v4 plus the shadcn-style components in
+`src/components/ui/`. `@shadcn/lint` enforces the rules below through
+`npm run lint`; its messages point here. Everything in this file is either a
+token in `src/index.css` or a variant in a `ui/` component, so an agent or a
+contributor can always find the concrete thing to use.
+
+## Rules in one paragraph
+
+Pages compose `ui/` components and choose their look through props
+(`variant`, `size`, `shape`). `className` on a component is for placement
+only: margin, width, flex and grid, positioning. Colours come from the theme
+tokens, never from the raw Tailwind palette. Spacing, type and radii come
+from the Tailwind scale, never from arbitrary `[...]` values. Runtime values
+go in CSS custom properties or, when unavoidable, an inline style with a
+disable comment.
+
+## Colour tokens
+
+Defined in `src/index.css` (`:root` for light, `.dark` for dark) and exposed
+through `@theme inline`, so `bg-`, `text-`, `border-`, `ring-`, `fill-` and
+`stroke-` all accept them, including opacity modifiers such as
+`bg-success/10`. One token class replaces a light + dark pair.
+
+| Token                                   | Use for                                                         | Replaces                                                            |
+| --------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `background`, `foreground`              | page surface and primary text                                   | `bg-white`, `text-gray-700/800/900`, `dark:text-gray-200/300`       |
+| `card`, `card-foreground`               | raised surfaces (cards, dialogs, dropdowns)                     | `bg-white dark:bg-[#2b2c31]`                                        |
+| `popover`, `popover-foreground`         | floating menus and popovers                                     | same as card                                                        |
+| `muted`, `muted-foreground`             | quiet fills and secondary text, icons, placeholders, timestamps | `bg-gray-100/200`, `text-gray-400/500/600`, `dark:text-gray-400`    |
+| `accent`, `accent-foreground`           | hover and selected fills                                        | `hover:bg-gray-100`, `dark:hover:bg-gray-700`                       |
+| `border`, `input`, `ring`               | dividers, field borders, focus rings                            | `border-gray-200/300`, `dark:border-gray-600/700`                   |
+| `primary`, `primary-foreground`         | brand purple: primary actions, links, selected states           | `bg-purple-*`, `text-purple-*`, `#7D54D1`, `#A076F6`                |
+| `secondary`, `secondary-foreground`     | pressed and active toggles (a brand tint), secondary buttons, the question bubble | `bg-accent` on an active icon button                                |
+| `destructive`, `destructive-foreground` | errors, failed states, dangerous actions                        | `text-red-*`, `bg-red-50/100`, `#B42318`, `#E60000`                 |
+| `success`, `success-foreground`         | completed, active, healthy                                      | `text-green-*`, `text-emerald-*`, `bg-green-50/100`                 |
+| `warning`, `warning-foreground`         | paused, pending review, degraded                                | `text-amber-*`, `text-yellow-*`, `text-orange-*`, `bg-amber-50/100` |
+| `info`, `info-foreground`               | running, informational                                          | `text-blue-*`, `bg-blue-50/100`                                     |
+| `sidebar-*`                             | the navigation rail                                             |                                                                     |
+| `chart-1` to `chart-5`                  | data series only, never UI chrome (see below)                   |                                                                     |
+| `answer-bubble`                         | assistant message background                                    |                                                                     |
+
+Status colours are tuned to stay vivid rather than turning brown or olive,
+so their contrast is low. Against white in light mode, `destructive` and
+`success` are about 3.8:1, `warning` is 2.9:1 and `info` is 5.2:1. On the
+dark card, `destructive` is 2.9:1 and the others are 5.5:1 or more. Do not
+use them for long body text; they are for badges, icons, short labels and
+fills.
+
+Chart colours are not a separate palette. `chart-1` to `chart-5` alias
+`primary`, `info`, `success`, `warning` and `destructive`, in that order,
+so the charts use the same colours as the rest of the app in both themes.
+A single series uses `chart-1`, the brand colour. When a series has a
+meaning, use the token for that meaning, not the next one in order:
+failed tool calls use `destructive`, succeeded ones `success`, pending
+ones `warning`. Series with no meaning (models, agents, sources) take
+`chart-1` to `chart-5` in order. When there are more than five, the four
+largest keep `chart-1` to `chart-4` and the rest are summed into one
+"Other" series in `chart-5`, so no colour repeats (`settings/foldSeries.ts`).
+`secondary` is never a chart colour.
+
+Patterns:
+
+- Status pill: `<Badge variant="success">`. Status box: `<Alert variant="warning">`.
+  Reach for `bg-success/10 text-success` directly only on dots and borders.
+- Solid status fill: `bg-warning text-warning-foreground`.
+- Guardrail outcomes: block `destructive`, flag `warning`, redact `info`,
+  not evaluated `neutral`.
+- Status border: `border-destructive/50`.
+- De-emphasised text: `text-muted-foreground`; go lighter with an opacity
+  modifier (`text-muted-foreground/70`) rather than a lighter grey.
+- Text on the brand colour is `text-primary-foreground`, not `text-white`.
+- `secondary` is a brand tint, not a grey: primary at 10% (light) or 15%
+  (dark) over whatever sits behind it, with `primary` text in light and a
+  lighter purple (#b89cf8) in dark. So a pressed toggle (CopyButton's copied
+  state, text-to-speech while speaking) shows on card, background and muted
+  alike, and never reads as the neutral ghost hover. Use it as
+  `variant={active ? 'secondary' : 'ghost-muted'}`.
+- The user's question bubble is `bg-secondary text-foreground`: the brand
+  tint as the fill, with body text in `foreground` (15.7:1 light, 12.4:1
+  dark) rather than `secondary-foreground`, which is only 4.5:1 in light.
+  Controls on it (the collapse chevron) are plain `ghost` with a lucide icon
+  in `currentColor`.
+- `white`, `black`, `transparent`, `current` and `inherit` are allowed; use
+  them only for overlays and imagery, not for text or surfaces.
+
+## Components and their variants
+
+### Button (`ui/button.tsx`)
+
+| Prop      | Values                                                                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant` | `default`, `secondary`, `outline`, `outline-primary`, `ghost`, `ghost-muted`, `ghost-destructive`, `link`, `destructive`, `destructive-outline`, `combobox`, `sidebar-item`, `tab`, `section-toggle` |
+| `size`    | `xs`, `sm`, `default`, `lg`, `field`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `inline`                                                                |
+| `shape`   | `default` (rounded-md), `pill` (rounded-full, wider padding)                                                                                           |
+
+- Round brand buttons (`rounded-3xl px-5`, `rounded-full px-6`): `shape="pill"`,
+  plus `size="lg"` if they were `px-6`.
+- Muted icon buttons (`text-muted-foreground hover:text-foreground`):
+  `variant="ghost-muted"`.
+- Icon actions that remove something (a trash can on a member or shared
+  resource row) are `variant="ghost-destructive"`: muted at rest, red on
+  hover, so the warning shows even where the click deletes without asking.
+- Bordered purple buttons (`border-primary text-primary hover:bg-primary`):
+  `variant="outline-primary"`.
+- Tiny inline actions (`h-auto px-2 py-1 text-xs`): `size="xs"`.
+- A link inside running text (an artifact link in an answer) is
+  `variant="link" size="inline"`: no height or padding, so it wraps with the
+  sentence. Standalone links (toggles, crumbs) keep a normal size.
+- The composer controls under the chat field (Attach, Voice, Tools,
+  Sources) are `size="sm" shape="pill"`. Their icons are `size-3.5 sm:size-4`
+  with no margin; the size's `gap-1.5` spaces them, and the label span keeps
+  `text-xs sm:text-sm` so the row still fits on a phone.
+- Popover comboboxes (`role="combobox"` + `Command`) use `variant="combobox"`,
+  which matches `SelectTrigger`: card fill, normal weight, and muted text
+  while `data-placeholder` is set (`data-placeholder={value ? undefined : ''}`).
+  Pass only layout (`w-full justify-between`) and keep the chevron as the
+  last child.
+- A button or picker that sits in a row of fields is `size="field"`: 42px,
+  the height of `Input` (default) and `SelectTrigger size="lg"`, so a form
+  column has one height. With `shape="pill"` its text starts 21px in, like
+  the Input and Select pills beside it. The agent form's pickers are
+  `combobox field pill`, its Add button `outline-primary field pill`.
+- Rows in the navigation sidebar (`hover:bg-sidebar-accent … pl-3 gap-2.5
+rounded-3xl`) are `variant="sidebar-item"`: left-aligned, full-radius, normal
+  weight, `bg-sidebar-accent` on hover and while `aria-current="page"`. Use it
+  with `asChild` around a `<Link>` for navigation rows.
+- Inline disclosure toggles ("Advanced settings", "Show advanced options")
+  are `variant="link" size="sm"` with only `-ml-3 w-fit justify-start`;
+  a chevron, when the toggle has one, is a lucide `ChevronRight` (so it
+  takes the link colour) as the first child.
+- Underline tabs (FilePicker's My Files / Shared with Me, the agent page
+  sub-nav) are `variant="tab"`: muted text on a transparent 2px bottom border,
+  square corners, no hover fill. Mark the current tab with `data-active`, which
+  gives it `foreground` text and a `primary` underline. Padding-free tabs (a
+  sub-nav with `gap-6`) add `size="inline"`, which keeps 4px above the line;
+  the row draws the 1px baseline, and `-mb-px` lays the underline over it.
+  Tabs that switch a panel in place use `ui/tabs` instead.
+- A section panel's disclosure header (NewAgent's Advanced and Guardrails
+  panels) is `variant="section-toggle" size="sm"` with `-ml-3 w-fit
+  justify-start` and `aria-expanded`: a lucide `ChevronRight` first
+  (`rotate-90` while open) in primary, then the foreground title, with a
+  primary underline on hover. The button draws no focus ring; the panel does,
+  so keyboard focus outlines the whole white block:
+  `has-[[data-variant=section-toggle]:focus-visible]:ring-3 …:ring-ring/50
+  …:ring-inset` on the panel `<div>` (inset, because a scrolling column clips
+  an outset ring). Status badges go beside the button, not inside it, or the
+  hover underline runs under them.
+- Drop `text-white` on default and destructive buttons; the foreground token
+  already provides it. Drop `disabled:cursor-not-allowed`; the base disables
+  pointer events.
+
+### Card (`ui/card.tsx`)
+
+| Prop          | Values                                                                                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`     | `outline` (border + card surface, the default), `filled` (muted fill, no border, for tiles on a card-coloured page), `subtle` (border on the page background) |
+| `padding`     | `none`, `sm` (p-3, stat tiles and panels), `default` (p-4), `lg` (p-6)                                                                                        |
+| `interactive` | whole card is the target: hover, focus ring and `selected` highlight; pair with `asChild` around a `<button>` or `<Link>`                                     |
+
+Parts: `CardHeader` (title left, `CardAction` top-right), `CardTitle`,
+`CardDescription`, `CardContent`, `CardFooter` (meta row, sticks to the
+bottom). One radius for every card (`rounded-2xl`); pass only layout and
+`gap-*` on `Card`. Replaces every hand-rolled
+`rounded-(md|lg|xl|2xl|3xl|4xl) border bg-(card|muted) p-*` box: source and
+tool tiles, team and agent cards, analytics stat tiles and chart panels,
+source-type and agent-type picker tiles.
+
+### OptionCard (`ui/option-card.tsx`)
+
+The picker tile: a whole-card `<button>` with an icon in a tinted square, a
+title and an optional description; `selected` fills the icon square and
+outlines the card. Use it wherever the user picks one of several ways to
+proceed (agent type, source type). Title-only tiles keep the same layout.
+Pass `selected` (true or false) only in a
+single-select picker inside a `role="radiogroup"`; the tile is then a radio.
+Tiles that advance a step or navigate (Upload's source types, the agent-type
+modal) leave it out and stay plain buttons. Only layout classes on it.
+
+### Badge (`ui/badge.tsx`)
+
+`variant`: `default` (brand), `neutral`, `success`, `warning`, `destructive`,
+`info`, `outline`. Replaces every hand-rolled
+`rounded-full bg-<colour>-100 px-2 py-0.5 text-xs text-<colour>-700 dark:...`
+pill, including schedule and run status pills. HTTP method pills take their variant from
+`getMethodBadgeVariant` (`utils/httpMethodColors.ts`): GET `success`, POST
+`info`, PUT `warning`, DELETE `destructive`, PATCH `default`, anything else
+`neutral`.
+
+### Input (`ui/input.tsx`)
+
+| Prop    | Values                                                           |
+| ------- | ---------------------------------------------------------------- |
+| `size`  | `sm` (h-8), `default` (h-10.5, the historical 42px), `lg` (h-12) |
+| `shape` | `default`, `pill`                                                |
+| `variant` | `default`, `bare` (no border, padding, radius, shadow or ring), `filled` (card fill) |
+
+Text alignment classes (`text-right`) and `font-mono` (code fields) are
+allowed on Input and Textarea. A floating
+`label` sits on the field's border, so its background must match the surface
+behind the field: `labelSurface` is `card` (default, forms in cards and
+modals), `background` (fields straight on a page) or `muted` (fields on a
+muted panel). Never pass a background class for it. The chat and hero
+fields (`rounded-3xl px-5 py-3`) are `size="lg" shape="pill"`. A
+default-size pill (42px, the form-row height) pads `px-5` like the large
+one, so its text lines up with the Select pills. Compact table
+filters (`h-auto px-2 py-1 text-sm`) are `size="sm"`. An inset icon (a
+search glass) is `leftIcon`, with or without a `label`; it pads the field
+`pl-10`, so never hand-place an icon over an Input. A field inside a host
+that already draws the frame (the renaming sidebar row, a search strip in a
+bordered panel) is `variant="bare"`; the host shows focus, and any inset
+padding goes on the host, not the field. A field on a muted panel (the
+ImportSpec Base URL box) is `variant="filled"`, so it keeps the card fill
+instead of showing the panel through; never pass `bg-card` for it.
+
+### SelectTrigger (`ui/select.tsx`)
+
+`size`: `sm`, `default`, `lg`; `variant`: `default`, `ghost`; `shape`:
+`default`, `pill`. The large rounded selects (`rounded-3xl px-5 py-3`) are
+`size="lg" shape="pill"`.
+
+### Textarea (`ui/textarea.tsx`)
+
+`size`: `sm`, `default`, `lg` (rounded-2xl, for prompt editors); `resize`:
+`none`, `vertical` (default), `both`. Same border, ring and invalid styling
+as Input. `variant`: `default` (transparent), `filled` (card fill), with
+the same rule as Input: a textarea on a muted panel is `variant="filled"`,
+never `bg-card`. Replaces the 21 raw `<textarea>` elements.
+
+### Tooltip (`ui/tooltip.tsx`)
+
+`Tooltip` + `TooltipTrigger asChild` + `TooltipContent side`. Each tooltip
+carries its own provider. Use it on every icon-only button and wherever a
+`title=` attribute was standing in for a hint; keep `aria-label` on the
+button as well.
+
+### Spinner and Skeleton (`ui/spinner.tsx`, `ui/skeleton.tsx`)
+
+`Spinner size="sm | default | lg"` draws in `currentColor`, so colour it
+with a `text-*` token on it or its parent. `components/Spinner.tsx` is a
+compatibility wrapper (`small | medium | large`) for existing imports.
+`Skeleton` is a pulsing muted block sized with layout classes and rounded
+as needed; `components/SkeletonLoader.tsx` should compose it.
+
+### Progress (`ui/progress.tsx`)
+
+`value` 0 to 100, `variant`: `default`, `success`, `warning`,
+`destructive`, `info`; `size`: `sm`, `default`, `lg`. Replaces the
+width-percent divs in quota, indexing and guardrail views.
+
+### Avatar (`ui/avatar.tsx`)
+
+`size`: `none` (image decides, the default), `sm`, `default`, `lg`, `xl`;
+`shape`: `none`, `circle`, `square`; `variant`: `default`, `primary` (brand
+initials), `muted` (grey initials). Initials boxes pass the letters as
+children.
+
+### Dropzone (`ui/dropzone.tsx`)
+
+`size`: `default` (tall target), `compact` (one row, for forms and modals).
+Props: `onDrop`, `accept`, `multiple`, `maxFiles`, `maxSize`, `disabled`,
+`title`, `description`, `icon`, `error`. Border and fill follow the drag
+state through `data-drag-active` and `data-drag-reject`. Replaces every
+hand-rolled `border-2 border-dashed rounded-3xl` target around
+`useDropzone`; `components/FileUpload.tsx` keeps its preview and validation
+logic and should render this underneath.
+
+### Toast (`ui/toast.tsx`)
+
+Feedback on anything the user did (uploads, runs, approvals, team events)
+is a toast in the bottom-right stack, never an inline box. The app has one
+`ToastViewport`, mounted in `App.tsx`; it is the live region
+(`role="status"`, `aria-live="polite"`) and the fixed stack, so `Toast`
+cards carry no role and no toast renders its own rail or positioning. Top
+to bottom it holds `TeamNotificationToast`, `ToolApprovalToast`,
+`UploadToast` and `ActionToast`, and it moves to the bottom-left while the
+workflow Preview drawer is open. A new toast component returns only its
+`Toast` cards and is added to that viewport. A page that reports the result
+of an action (the admin Users actions) dispatches
+`showActionToast({ variant: 'success' | 'destructive', message })` from
+`notifications/actionToastSlice.ts`; `ActionToast` shows it and dismisses
+it after 4.5s, and a new result replaces the previous one.
+
+Compose `Toast` > `ToastHeader variant` (`default`, `success`, `warning`,
+`destructive`, `info`) with `ToastTitle` and `ToastActions` (collapse and
+close as `Button variant="ghost-muted" size="icon-sm"`), then
+`ToastContent` (add `scrollable` for long lists) with `ToastItem label meta`
+rows (optional `icon` before the label), a `ToastStatus status` circle per
+row (`pending`, `success`, `warning`, `destructive`, `info`),
+`ToastMessage variant` for an explanation and `ToastFooter` for action
+buttons. `ToastTitle` truncates to one line; `wrap` lets a long title (a
+localised string, a team name) wrap instead. `ToastMessage size` is `xs`
+(default, the note under a row) or `sm` (`text-sm leading-4.5`, the whole
+body of a notice). A message that is the only content under the header
+gets its top padding on its own, and a message right after a `ToastItem`
+shares that row's divider. Toasts own their width, radius and shadow; pass
+no width or colour to them.
+
+### Alert (`ui/alert.tsx`)
+
+Inline notice inside a form or modal only, for something the user must
+read before acting (an expiring token above the field, a warning in a
+settings panel). Not for feedback on an action; that is a Toast.
+`variant`: `default`, `success`, `warning`, `info`, `destructive`. Every
+coloured variant is the same shape: `border-<role>/50 bg-<role>/10
+text-<role>`, icon in the role colour; `default` sits on `bg-background`.
+Icon first, then `AlertTitle` and `AlertDescription`. Every variant is
+`role="alert"` except `success`, which is `role="status"` so a confirmation
+is announced politely; pass `role` only to override that. Replaces the hand-rolled
+`rounded-lg border bg-amber-50 text-amber-800` boxes.
+
+### Breadcrumb (`ui/breadcrumb.tsx`)
+
+`BreadcrumbPage`, the current crumb, is always one line and truncates with
+an ellipsis. Pages pass only its width (`w-[16ch]`, `max-w-[32ch]`) and a
+`title` with the full text; never `truncate` or typography. Give every
+current crumb a width cap so a long name cannot push the row past the
+screen. A crumb that runs a handler instead of navigating is
+`BreadcrumbLink asChild` around a `<button type="button">`; the link carries
+the focus ring. The current crumb is never a disabled button.
+
+### Accordion (`ui/accordion.tsx`)
+
+`AccordionTrigger` carries its own inset and type (`px-4 py-3 text-sm
+font-medium`) and an inset focus ring, since `AccordionItem` clips anything
+outside it. Pages pass nothing to the trigger; put the frame (a bordered,
+rounded box) on a wrapper around `Accordion`.
+
+### Modal, not Dialog
+
+`ui/dialog.tsx` is the Radix primitive and is private to `ui/`; ESLint
+rejects imports of it elsewhere. App code uses `Modal` (sizes `sm` to
+`full`, `mobileVariant="sheet"`) or `CommandDialog`.
+
+A search palette is `CommandDialog` on desktop. Pass cmdk options to its
+inner `Command` through `commandProps` (`shouldFilter={false}` when results
+come from a server search, a controlled `value`). On phones the same palette
+goes in `Modal mobileVariant="sheet"` as `<Command variant="palette">`, which
+gives it the dialog's 48px input row and row spacing, so both widths look
+the same (`modals/SearchConversationsModal.tsx`).
+
+In a picker list, mark the item that is currently chosen with
+`CommandItem checked` (a `secondary` brand tint through `data-checked`), not
+with `bg-accent`: cmdk's own `data-selected` highlight is `bg-accent` and
+follows the pointer and arrow keys, so an accent fill would look like hover.
+While a checked item is also highlighted it keeps its tint and text and gains
+a 1px inset `primary` ring, so the chosen row never turns plain grey.
+
+### Table, Label, dialog text
+
+`TableCell` and `TableHeader` accept typography and alignment classes and
+`text-muted-foreground`. `Label`, `DialogTitle`, `DialogDescription`,
+`SheetTitle` and `SheetDescription` accept typography plus
+`text-foreground` and `text-muted-foreground`. `DialogContent`,
+`PopoverContent`, `SheetContent`, `DropdownMenuContent` and `Modal` accept
+`p-0` for edge-to-edge content (MoveToFolderModal's banded folder picker);
+Modal merges it after its own `p-8`, so no `!` is needed. Everything else on these components is layout only.
+
+## Spacing, type and radii
+
+Use the Tailwind scale. Tailwind v4 accepts fractional steps, so
+`h-10.5` is 42px and `ring-3` is a 3px ring; neither needs brackets. Layout
+values (`h-[calc(100dvh-64px)]`, `max-w-[520px]`) and motion values
+(`transition-[color,box-shadow]`, custom easings) are allowed. Font sizes,
+padding, colours and radii in brackets are not; pick the nearest scale step
+or add a token.
+
+## Focus, elevation and stacking
+
+- **Focus ring**: `focus-visible:ring-3 focus-visible:ring-ring/50` plus
+  `focus-visible:border-ring` on fields. Never `focus:` (mouse users see it)
+  and never `ring-2` or `ring-[3px]`; the `ui/` components already carry it,
+  so plain elements should become components rather than copy the classes.
+- **Elevation**: cards have no shadow; fields and outline buttons
+  `shadow-xs`; popovers, menus and select lists `shadow-md`; sheets
+  `shadow-lg`; modals `shadow-modal`; toasts `shadow-toast`. Nothing else
+  uses a shadow class.
+- **Stacking**: `z-10` sticky headers and table heads inside a page;
+  `z-20` in-page floating chrome (banners, scroll-to-bottom, drag
+  handles); `z-50` everything portalled (overlay, modal, sheet, popover,
+  menu, tooltip); `z-200` only for select lists that must open above a
+  modal. Do not invent values in between.
+
+## Inline styles
+
+Allowed without comment in `src/components/MermaidRenderer.tsx` and
+`src/agents/workflow/nodes/**` (third-party renderers and canvas
+positions). Elsewhere, prefer a CSS custom property
+(`style={{ '--progress': pct }}` with `w-(--progress)`), and when a value
+truly is computed at runtime, keep the inline style and add
+`// eslint-disable-next-line shadcn/no-inline-styles -- <reason>`.
+
+## Approved exceptions
+
+Places where a rule is knowingly disabled. Each one carries the same reason
+as a comment at the call site; add a row here when you add a disable so the
+list stays reviewable.
+
+| Where                         | Rule                            | Why                                                                                                                                                                                                                                                  |
+| ----------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `components/Notification.tsx` | `shadcn/no-restyle`             | The promo banner's close control is a bare 16px image on the purple gradient: no `size` fits it, and `ghost`'s accent hover fill would paint a grey square on the gradient.                                                                          |
+| `components/ui/calendar.tsx`  | `shadcn/require-static-classes` | The day button merges `defaultClassNames.day`, which react-day-picker returns from `getDefaultClassNames()` at runtime; no static form exists.                                                                                                       |
+| `navigation/SidebarLevel.tsx` | `shadcn/no-arbitrary-values`    | The incoming sidebar panel casts a strong shadow off its left edge while it slides (`shadow-[-12px_0_24px_-6px_rgba(0,0,0,0.45)]`); no scale shadow is horizontal, and the container clips it once the panel comes to rest.                          |
+| `components/ui/modal.tsx`     | `shadcn/no-arbitrary-values`    | The mobile sheet's `pb-[max(env(safe-area-inset-bottom),1rem)]` keeps its footer clear of the iPhone home indicator (about 34px, since `index.html` sets `viewport-fit=cover`) and equals `pb-4` everywhere else; no scale step can express `env()`. |
+| `components/MessageInput.tsx` | `shadcn/no-restyle` | The empty composer's send button is a grey circle (`bg-muted`, `dark:bg-accent`), not a faded brand one; no variant is neutral while disabled, and `secondary` is the brand-tinted pressed state. |
+| `Hero.tsx` | `shadcn/no-restyle` | The landing page's model picker keeps its hero look: a borderless muted pill at 16px (`rounded-4xl px-6 py-4 text-base`) whose menu hangs from it as one shape. Three disables: `SelectTrigger`, `SelectContent`, `SelectItem`. |
+| `agents/AgentsList.tsx`        | `shadcn/no-restyle`  | Inside a folder, the breadcrumb trail replaces the section `<h2>`, so its `BreadcrumbList` keeps heading typography (`text-foreground text-lg font-semibold gap-2`). It's the only breadcrumb that does. |
+| `settings/Prompts.tsx` | `shadcn/no-restyle` | The row icon buttons (edit, duplicate, share, delete) sit in a cmdk row that is already `bg-accent` while highlighted, so ghost's accent hover would be invisible; they keep a `foreground/15` (delete: `destructive/15`) hover tint. Four disables. |
+| `Navigation.tsx` | `shadcn/no-restyle` | The agent pin is a bare 16px image on a sidebar row that already fills on hover; an accent fill would be invisible on it, so hover dims the icon (`hover:opacity-75`) instead. |
+| `conversation/MarkdownAnswer.tsx`, `components/ArtifactSidebar.tsx` | `shadcn/no-inline-styles` | SyntaxHighlighter's `style` prop is its Prism theme object (`oneLight` / `vscDarkPlus`), picked by theme at runtime. It is not CSS, so no class or custom property can replace it. One disable per file. |
+| `components/MultiSelectPopover.tsx` | `shadcn/no-restyle`, `shadcn/no-arbitrary-values` | The phone bottom sheet (`SheetContent side="bottom"`) keeps its sheet shape: a rounded top, no gap, a card fill in dark so it matches the `Command` inside it, and `pb-[env(safe-area-inset-bottom)]` to clear the iPhone home indicator (the same inset as `ui/modal.tsx`). One disable. |
+| `agents/workflow/WorkflowPreview.tsx` | `shadcn/no-restyle` | The Preview minimap's node rows are status tiles: the fill, border and ring follow the step (success, primary running + pulse, destructive, muted pending; a ring on the active row) and stay pinned on hover, pending and running rows stay unfaded while disabled, and clickable rows dim to 80% on hover. No Button variant is status-tinted. The rule reports each string inside `cn(...)`, so it's a `/* eslint-disable */` … `/* eslint-enable */` pair around the `className` attribute. |
+| `components/MermaidRenderer.tsx` | `shadcn/no-restyle` | The zoom − / + buttons sit on the diagram's `bg-black/70` overlay, where ghost's accent hover paints a light square with dark text; they hover to `white/20` with white text instead (`dark:hover:bg-white/20` too, to beat ghost's dark hover). Two disables. |
+| `conversation/ConversationMessages.tsx`, `agents/workflow/WorkflowPreview.tsx` | `shadcn/no-restyle` | MessageScroller padding. The primitive measures `MessageScrollerContent`'s padding-block for its scroll and spacer math, and the Viewport's top gap must scroll with the messages, so neither can move to a margin or a wrapper. The two callers use different values. Five disables. |
+
+Note that a multi-line reason has to be a `/* ... */` block comment;
+consecutive `//` lines only disable the next comment line, not the code.
+
+## Known dead classes
+
+The lint reports classes Tailwind cannot generate. In this codebase they are
+bugs, not missing configuration:
+
+- `xs:` has never been a breakpoint here (not in the old Tailwind v3 config
+  either), so `xs:px-3`, `xs:text-xs` never applied. Remove them rather than
+  declaring the breakpoint, which would change layouts that were never seen.
+- `text-s`, `dark:text-gray`, `w-inherit` are typos for `text-sm`,
+  `dark:text-gray-*` and `w-[inherit]`.
+- `agents-container`, `conversations-container`, `loader` and `mermaid` are
+  unused hooks; nothing selects them. Before deleting a class like these,
+  grep for it in `querySelector` and `classList` calls too. `star` was
+  defined at runtime by a `<style>` element in `components/Notification.tsx`;
+  it is now the `notification-star` utility in `src/index.css`. `msc-spacer`
+  was a lookup hook for `ConversationMessages`' `querySelector`; the lookup
+  now uses the primitive's `[data-message-scroller-spacer]` attribute.
+
+## Live style guide
+
+`npm run dev`, then open `/design`. The page (`src/design/DesignSystem.tsx`)
+renders every `ui/` component with the variants above, shows the resolved
+value of each colour token and has a theme toggle. It is registered only
+when Vite runs in development mode, so it never ships. When you add a
+variant or token, add it there too.
+
+## Cleanup playbook
+
+The design lint is at `warn` while the app is migrated. Work one file at a
+time, smallest first, and keep every step green.
+
+1. **See the state.** `npm run lint:design` prints warnings by rule and the
+   worst files. `npm run lint:design -- --file src/settings/Teams.tsx` lists
+   every warning in one file with the fix the message proposes;
+   `-- --rule no-raw-colors` lists files for one rule.
+2. **Pick a file, read it whole**, then fix all of its design warnings in
+   one pass. Map raw colours to tokens (table above), replace hand-rolled
+   boxes, pills, tiles, spinners and dropzones with the `ui/` components,
+   and move Button/Input/Select overrides onto `variant`, `size`, `shape`.
+   Delete the `dark:` twin of every class you tokenise. Remove classes the
+   lint calls unknown (`xs:*`, `text-s`, `dark:text-gray`, unused hooks).
+3. **Do not restyle `ui/` components from a page.** If a treatment is used
+   in more than one place and no variant fits, add the variant in the
+   component file, add it to `src/design/DesignSystem.tsx`, and document it
+   here. A one-off gets `// eslint-disable-next-line shadcn/<rule> -- reason`.
+4. **Keep behaviour identical.** Same DOM order, same handlers, same
+   translations (`t(...)` keys stay). Only classes and component choice
+   change. Prettier with the Tailwind plugin reorders classes; run
+   `npm run lint-fix` rather than fighting it.
+5. **Verify per file**: `npx eslint <file>` (zero `shadcn/*` warnings),
+   `npx tsc --noEmit -p tsconfig.json`, `npm test`, and look at the screen
+   in the running app (`npm run dev`, then the page that renders the file)
+   in both themes.
+6. **Promote rules** in `eslint.config.js` from `warn` to `error` when
+   `npm run lint:design -- --rule <rule>` reports zero, in this order:
+   `no-unknown-classes`, `require-static-classes`, `no-inline-styles`,
+   `no-arbitrary-values`, `no-raw-colors`, `no-restyle`.
+
+Known traps:
+
+- `npm run lint` also reports 187 pre-existing Prettier errors in nine
+  files unrelated to design; `npm run lint-fix` clears them.
+- Port 5173 may be held by another checkout; check the Vite banner shows
+  this repo's path before trusting what you see.
+- `components/Spinner.tsx` and `components/StatusBadge.tsx` are transitional
+  wrappers; migrate their callers to `ui/spinner` and `ui/badge`, then
+  delete them. `components/SkeletonLoader.tsx` and
+  `components/FileUpload.tsx` keep their logic but should render `Skeleton`
+  and `Dropzone`.
+
+## Working with the lint
+
+```bash
+cd frontend && npm run lint
+```
+
+All `shadcn/*` rules are `warn` while the backlog is cleaned up. Promote a
+rule to `error` in `eslint.config.js` once `npm run lint` reports zero
+warnings for it; the intended order is `no-unknown-classes`,
+`require-static-classes`, `no-inline-styles`, `no-arbitrary-values`,
+`no-raw-colors`, `no-restyle`. Add a variant or token only when a treatment
+is used in more than one place and none of the existing ones fits; a single
+special case gets a disable comment with a reason.
diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
index 149980b5..511c0b8c 100644
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -1,10 +1,11 @@
-import js from '@eslint/js'
-import tsParser from '@typescript-eslint/parser'
-import tsPlugin from '@typescript-eslint/eslint-plugin'
-import react from 'eslint-plugin-react'
-import unusedImports from 'eslint-plugin-unused-imports'
-import prettier from 'eslint-plugin-prettier'
-import globals from 'globals'
+import js from '@eslint/js';
+import { plugin as shadcn } from '@shadcn/lint';
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import react from 'eslint-plugin-react';
+import unusedImports from 'eslint-plugin-unused-imports';
+import prettier from 'eslint-plugin-prettier';
+import globals from 'globals';
 
 export default [
   {
@@ -49,6 +50,7 @@ export default [
       react,
       'unused-imports': unusedImports,
       prettier,
+      shadcn,
     },
     rules: {
       ...js.configs.recommended.rules,
@@ -68,11 +70,196 @@ export default [
           endOfLine: 'auto',
         },
       ],
+      // The Radix Dialog wrapper is an internal primitive; app code uses
+      // <Modal> (or <CommandDialog>). Only src/components/ui may import it.
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['**/components/ui/dialog'],
+              message:
+                'Use <Modal> from @/components/ui/modal; the Dialog primitive is internal to ui/.',
+            },
+          ],
+        },
+      ],
+      // Design-system rules (@shadcn/lint). Tokens, variants and the
+      // approved exceptions are documented in DESIGN.md. Every rule starts
+      // at `warn`; promote a rule to `error` once its count reaches zero.
+      'shadcn/no-restyle': [
+        'warn',
+        {
+          allow: ['layout'],
+          contracts: [
+            {
+              pattern: '^Button$',
+              allow: ['layout'],
+              message: {
+                shape:
+                  '"{{className}}" is not allowed on <Button>: use shape="pill" for round buttons. Other shapes need a new variant in {{file}}.',
+                spacing:
+                  '"{{className}}" is not allowed on <Button>: use a size ({{sizes}}). shape="pill" already widens the padding; put space around the button on the parent (gap) or as margin here.',
+                color:
+                  '"{{className}}" is not allowed on <Button>: use a variant ({{variants}}). Primary buttons already have white text; muted icon buttons are variant="ghost-muted"; bordered brand buttons are variant="outline-primary".',
+                typography:
+                  '"{{className}}" is not allowed on <Button>: size="xs" gives text-xs; the default size is text-sm. Add a size in {{file}} only if the design explicitly calls for one.',
+                default:
+                  '"{{className}}" is not allowed on <Button>: {{category}} belongs to the component. Use a variant ({{variants}}), a size ({{sizes}}) or a shape (default, pill). See DESIGN.md.',
+              },
+            },
+            {
+              pattern: '^Input$',
+              // font-mono: code fields (JSON, keys) keep a monospace face.
+              allow: [
+                'layout',
+                'text-left',
+                'text-center',
+                'text-right',
+                'font-mono',
+              ],
+              message: {
+                default:
+                  '"{{className}}" is not allowed on <Input>: use size (default, sm, lg) and shape (default, pill); alignment classes are allowed. Add a variant in {{file}} only if the design explicitly calls for one.',
+              },
+            },
+            {
+              pattern: '^SelectTrigger$',
+              allow: ['layout'],
+              message: {
+                default:
+                  '"{{className}}" is not allowed on <SelectTrigger>: use size (sm, default, lg), variant (default, ghost) and shape (default, pill) from {{file}}.',
+              },
+            },
+            {
+              pattern: '^Avatar$',
+              allow: ['layout'],
+              message: {
+                default:
+                  '"{{className}}" is not allowed on <Avatar>: use size (sm, default, lg, xl), shape (circle, square) and variant (primary, muted) from {{file}}.',
+              },
+            },
+            {
+              pattern: '^Card$',
+              allow: ['layout', 'gap-*'],
+              message: {
+                default:
+                  '"{{className}}" is not allowed on <Card>: use variant (outline, filled, subtle), padding (none, sm, default, lg) and interactive/selected from {{file}}.',
+              },
+            },
+            {
+              pattern: '^Textarea$',
+              // font-mono: code editors (JSON schema, workflow code) keep a
+              // monospace face.
+              allow: [
+                'layout',
+                'text-left',
+                'text-center',
+                'text-right',
+                'font-mono',
+              ],
+              message: {
+                default:
+                  '"{{className}}" is not allowed on <Textarea>: use size (sm, default, lg) and resize (none, vertical, both) from {{file}}; min-height and width are layout and allowed.',
+              },
+            },
+            {
+              pattern: '^Skeleton$',
+              allow: ['layout', 'rounded-*'],
+            },
+            {
+              pattern: '^Spinner$',
+              allow: ['layout', 'color'],
+            },
+            {
+              pattern: '^Progress$',
+              allow: ['layout'],
+            },
+            {
+              pattern: '^(Toast|ToastViewport)$',
+              allow: ['layout'],
+            },
+            {
+              pattern: '^(ToastContent|ToastItem|ToastFooter)$',
+              allow: ['layout', 'spacing'],
+            },
+            {
+              pattern: '^OptionCard$',
+              allow: ['layout'],
+            },
+            {
+              pattern: '^(CardHeader|CardContent|CardFooter|CardAction)$',
+              allow: ['layout', 'spacing', 'gap-*', 'bg-muted/*'],
+            },
+            {
+              pattern: '^(CardTitle|CardDescription)$',
+              allow: ['layout', 'typography', 'line-clamp-*'],
+            },
+            {
+              pattern: '^(TableCell|TableHeader)$',
+              allow: ['layout', 'typography', 'text-muted-foreground'],
+            },
+            {
+              pattern:
+                '^(Label|DialogTitle|DialogDescription|SheetTitle|SheetDescription)$',
+              allow: [
+                'layout',
+                'typography',
+                'text-muted-foreground',
+                'text-foreground',
+              ],
+            },
+            {
+              // Modal wraps DialogContent and merges className after its p-8.
+              pattern: '^((Dialog|Popover|Sheet|DropdownMenu)Content|Modal)$',
+              allow: ['layout', 'p-0'],
+            },
+          ],
+        },
+      ],
+      'shadcn/no-raw-colors': [
+        'warn',
+        {
+          message:
+            '"{{className}}" uses the raw Tailwind palette. Map it to a token from {{file}}: grey text -> text-foreground or text-muted-foreground; grey borders -> border-border; grey fills -> bg-muted, bg-accent or bg-card; red -> destructive; green -> success; amber, yellow and orange -> warning; blue -> info; purple -> primary. Soft badge or alert fills use bg-<token>/10 and a single class replaces the light+dark pair. Status pills should be <Badge variant="...">.',
+        },
+      ],
+      'shadcn/no-arbitrary-values': [
+        'warn',
+        // Motion values (`transition-[color,box-shadow]`, custom easings)
+        // have no token scale; everything else must come from the theme.
+        { allow: ['layout', 'transition-*', 'ease-*'] },
+      ],
+      'shadcn/no-inline-styles': 'warn',
+      'shadcn/no-unknown-classes': 'warn',
+      'shadcn/require-static-classes': 'warn',
     },
     settings: {
       react: {
         version: 'detect',
       },
+      shadcn: {
+        note: 'See frontend/DESIGN.md for tokens, component variants and approved exceptions.',
+      },
     },
   },
-]
+  {
+    // The design-system components define the styles; they are not restyled.
+    files: ['src/components/ui/**'],
+    rules: {
+      'shadcn/no-restyle': 'off',
+      'no-restricted-imports': 'off',
+    },
+  },
+  {
+    // Third-party renderers and canvas-positioned nodes take computed
+    // runtime values that Tailwind classes cannot express.
+    files: [
+      'src/components/MermaidRenderer.tsx',
+      'src/agents/workflow/nodes/**',
+    ],
+    rules: {
+      'shadcn/no-inline-styles': 'off',
+    },
+  },
+];
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 41bb0bf8..fbc0c931 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -48,6 +48,7 @@
       },
       "devDependencies": {
         "@eslint/js": "^9.39.5",
+        "@shadcn/lint": "^0.2.0",
         "@tailwindcss/postcss": "^4.3.3",
         "@types/d3-force": "^3.0.10",
         "@types/lodash": "^4.17.25",
@@ -847,6 +848,329 @@
         "node": ">=22.12.0"
       }
     },
+    "node_modules/@oxc-parser/binding-android-arm-eabi": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-android-arm-eabi/-/binding-android-arm-eabi-0.148.0.tgz",
+      "integrity": "sha512-pHASv9g5pASxb7akHERZNSkrEqPhFaUix98o7d9hbTpolnnFWl7UiRrcMhCsV1+iVO4/cJwKsbKRJTFNs2tdBQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-android-arm64": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-android-arm64/-/binding-android-arm64-0.148.0.tgz",
+      "integrity": "sha512-sg/6Ez0KdAygsu0POELux9wN1Po2CP93WY8eNl4DBKIGprsd4QSHBXOb471Pu9i2OCD5sLkISSb2agZEhVn2Zw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-darwin-arm64": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-arm64/-/binding-darwin-arm64-0.148.0.tgz",
+      "integrity": "sha512-yiSJmzGUvCUaJT8X3j40gVcX+ckuHQMuiOtF8DvzTs5+JtB/7XuHFPp4M+vv5u+HlBtDUd4Ks5pyHpWz8mfnkg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-darwin-x64": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-x64/-/binding-darwin-x64-0.148.0.tgz",
+      "integrity": "sha512-6ZeklaamrMy4H2JmhvcJg6iip59tYILtuLaILxyAHT3l5FDxnI5ihVievAft5ZmAbqtlWHErOi1OpJK8gy1wcA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-freebsd-x64": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-freebsd-x64/-/binding-freebsd-x64-0.148.0.tgz",
+      "integrity": "sha512-vFsPx+a/qFECPnz/H8nC6x6MDvnWscLTCo/5muojEF54ERUq1kdgbvnWo95YnkhjF9sTIcG/uDxQBh1gffaufQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-arm-gnueabihf": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.148.0.tgz",
+      "integrity": "sha512-eOr3M+6iGbbxNL4PSS0VtsyQ2eOUxSBh00BqO22SbolDimPSYsBuLr/LCrZBkiqW2BoabhR6V4R8jrRAay7hjg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-arm-musleabihf": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.148.0.tgz",
+      "integrity": "sha512-58ZKDw0mQRbCNfrd2IDyV4o8T7enzGERJn41BH2tjrZVGyiKiFzcfDicuB7Zcpb/1xIOrObovr8Dja6lZi8dLw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-arm64-gnu": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.148.0.tgz",
+      "integrity": "sha512-Fnu95O4eZ5i++GPvIzBEZ8y4ddTLR+D9paYa8JRaRk6ZK7nHQiWP5xtrhcPQsXqgat1d7sU/d5rbbI0p1FTHSQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-arm64-musl": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.148.0.tgz",
+      "integrity": "sha512-3CQy/BMdx7N7H3qrcPxUL+a2CwUZodUcf6oq8iJuNZ9C6Ol1aq3mcWzsgySJ7CHFLvpX21ZDPp1r1X0QLbu/AQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-ppc64-gnu": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.148.0.tgz",
+      "integrity": "sha512-9LkaYvfiF8hMOw900csAvkf1oxE8XlmMeGowu5BcastSSwV8mKvKRMNU7HsV+ycyj1dQD8pX5qgOw8ja6SJacg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-riscv64-gnu": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.148.0.tgz",
+      "integrity": "sha512-2GBiM9h26dR4WJfhoMvnFMnFLf7m/kYs4UMqjvrOfQG4BV1nuTJDH22Zc2MQr3INZF7nSKYQ6xlhD3hQ7A6gug==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-riscv64-musl": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.148.0.tgz",
+      "integrity": "sha512-uPqZexvKJmEgq4mAu36qe2xTfXZE7oyik1R7KtZ5tl8qKlq1U1fIqTFRUEBZqRGvforoTrGIpatRzcoPKO66RA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-s390x-gnu": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.148.0.tgz",
+      "integrity": "sha512-9oUHvnTbp7ZraFsTC8PN6XhdhPSSxZumYvixWl7Smi353gEULvK6yV0sXNVrdFMHQeaDKFCi8TgDhNK7/A+Y+Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-x64-gnu": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.148.0.tgz",
+      "integrity": "sha512-2qhDSJwKzbSZzF7lDqqk8sr/yXsmwr3PeUa4/nazIF+zFAYz1gVPEfC34GQtGxzJUUmklaYAL63368LEfrMeyw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-linux-x64-musl": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-musl/-/binding-linux-x64-musl-0.148.0.tgz",
+      "integrity": "sha512-qQoPDZUFV0bh9xA09XydmkjMBpgc1ukJuhMvzQ9QeVmFaHTS9W5TE5CoLmSl3QQyUP9OuHO3x/WPZTIIZPWR3Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-openharmony-arm64": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-openharmony-arm64/-/binding-openharmony-arm64-0.148.0.tgz",
+      "integrity": "sha512-1UGbaQWEXUCLqAmaR5kwRDjx/R4S5LQKZkM9CHmaHkuKhriOF32aRLfS0jCRNE2yGQJLMEA1z9UucbBVqjXnDw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-win32-arm64-msvc": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.148.0.tgz",
+      "integrity": "sha512-pWKdzRDNG2+NK4h/V6U/CYERcfYD6u28h5IB/VJVsrZaD3muvE58tUj22lieL5vLZ+XFi1GPv9YXckZbJZ9BLA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-win32-ia32-msvc": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.148.0.tgz",
+      "integrity": "sha512-i3p4x+mvwtjcE1J5HM6V7ggsbXiznExN/4MkNyOy3dfXrVV3bnkSfmZxvo6/84qCVX4ShkpNE1SKt9biIF31GQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@oxc-parser/binding-win32-x64-msvc": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.148.0.tgz",
+      "integrity": "sha512-Ye6vB7VQulghWYkYkECOBYFRVEizz4XyRTUAv+t8BuyurhKU7uD0P9eowL+mKG5Mf8MSYx+DI3Cm8SKZvYG7bQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
     "node_modules/@oxc-project/types": {
       "version": "0.149.0",
       "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.149.0.tgz",
@@ -2786,6 +3110,35 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@shadcn/lint": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/@shadcn/lint/-/lint-0.2.0.tgz",
+      "integrity": "sha512-DTYr427BR8cDc0J0Y++u1Uh12NAYGmdPiqgy4wKSogi7RNEhFanIcfBMPRPUvkunt9QiJUfI7B28TW39MrPCFA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@eslint/core": "^0.17.0",
+        "cn": "0.3.2"
+      },
+      "engines": {
+        "node": ">=20.19"
+      },
+      "optionalDependencies": {
+        "oxc-parser": "^0.148.0"
+      },
+      "peerDependencies": {
+        "@typescript-eslint/parser": ">=8.40.0",
+        "eslint": ">=9.30.0"
+      },
+      "peerDependenciesMeta": {
+        "@typescript-eslint/parser": {
+          "optional": true
+        },
+        "eslint": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@shadcn/react": {
       "version": "0.3.1",
       "resolved": "https://registry.npmjs.org/@shadcn/react/-/react-0.3.1.tgz",
@@ -3703,7 +4056,6 @@
       "version": "19.3.0",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
       "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "csstype": "^3.2.2"
@@ -3713,7 +4065,7 @@
       "version": "19.3.0",
       "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.3.0.tgz",
       "integrity": "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "^19.3.0"
@@ -4811,6 +5163,19 @@
         "react-dom": "^18 || ^19 || ^19.0.0-rc"
       }
     },
+    "node_modules/cn": {
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/cn/-/cn-0.3.2.tgz",
+      "integrity": "sha512-RKzY5Edavc8B2Ka6tjJecKFC4nm0p7lADY72xzICmiJSf4TkaxWXt0fHsib2P2G4FkFyXfSDi9oDtIBuCZvY2g==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "cn": "bin/cn.mjs"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -4938,7 +5303,6 @@
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/cytoscape": {
@@ -9848,6 +10212,55 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/oxc-parser": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/oxc-parser/-/oxc-parser-0.148.0.tgz",
+      "integrity": "sha512-syxUKHeUll89RIABQADcI7sikYrwyssvA6gj4phSSIPezKVM8yMaLAiLLSc7fmzVvrwybfFGFbW5zme9sX87rg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@oxc-project/types": "^0.148.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/oxc-project"
+      },
+      "optionalDependencies": {
+        "@oxc-parser/binding-android-arm-eabi": "0.148.0",
+        "@oxc-parser/binding-android-arm64": "0.148.0",
+        "@oxc-parser/binding-darwin-arm64": "0.148.0",
+        "@oxc-parser/binding-darwin-x64": "0.148.0",
+        "@oxc-parser/binding-freebsd-x64": "0.148.0",
+        "@oxc-parser/binding-linux-arm-gnueabihf": "0.148.0",
+        "@oxc-parser/binding-linux-arm-musleabihf": "0.148.0",
+        "@oxc-parser/binding-linux-arm64-gnu": "0.148.0",
+        "@oxc-parser/binding-linux-arm64-musl": "0.148.0",
+        "@oxc-parser/binding-linux-ppc64-gnu": "0.148.0",
+        "@oxc-parser/binding-linux-riscv64-gnu": "0.148.0",
+        "@oxc-parser/binding-linux-riscv64-musl": "0.148.0",
+        "@oxc-parser/binding-linux-s390x-gnu": "0.148.0",
+        "@oxc-parser/binding-linux-x64-gnu": "0.148.0",
+        "@oxc-parser/binding-linux-x64-musl": "0.148.0",
+        "@oxc-parser/binding-openharmony-arm64": "0.148.0",
+        "@oxc-parser/binding-win32-arm64-msvc": "0.148.0",
+        "@oxc-parser/binding-win32-ia32-msvc": "0.148.0",
+        "@oxc-parser/binding-win32-x64-msvc": "0.148.0"
+      }
+    },
+    "node_modules/oxc-parser/node_modules/@oxc-project/types": {
+      "version": "0.148.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.148.0.tgz",
+      "integrity": "sha512-Nm4s/jB+4FpFsPhWGEC4h7rzksesmtnMXomo6rCMcg/b8zLQuOziRgkCS1fxDCXOlJB/6Q8oABOZ/OP6RIPj9A==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "funding": {
+        "url": "https://github.com/sponsors/oxc-project"
+      }
+    },
     "node_modules/p-limit": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
@@ -11746,7 +12159,7 @@
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
       "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
-      "dev": true,
+      "devOptional": true,
       "license": "Apache-2.0",
       "bin": {
         "tsc": "bin/tsc",
diff --git a/frontend/package.json b/frontend/package.json
index 94a74649..4ce56ac0 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -14,6 +14,7 @@
     "test:watch": "vitest",
     "lint": "eslint ./src --ext .jsx,.js,.ts,.tsx",
     "lint-fix": "eslint ./src --ext .jsx,.js,.ts,.tsx --fix",
+    "lint:design": "eslint ./src -f json | node scripts/design-lint-report.mjs",
     "format": "prettier ./src --write",
     "prepare": "cd .. && husky install frontend/.husky"
   },
@@ -64,6 +65,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
+    "@shadcn/lint": "^0.2.0",
     "@tailwindcss/postcss": "^4.3.3",
     "@types/d3-force": "^3.0.10",
     "@types/lodash": "^4.17.25",
diff --git a/frontend/scripts/design-lint-report.mjs b/frontend/scripts/design-lint-report.mjs
new file mode 100644
index 00000000..b7d64e80
--- /dev/null
+++ b/frontend/scripts/design-lint-report.mjs
@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Summarise @shadcn/lint warnings from ESLint JSON output.
+ *
+ *   npm run lint:design              rules × counts, then the 25 worst files
+ *   npm run lint:design -- --rule no-raw-colors   files for one rule
+ *   npm run lint:design -- --file src/settings/Tools.tsx   every message in a file
+ *
+ * Reads ESLint's JSON from stdin; the npm script pipes it in.
+ */
+import { readFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+const opt = (name) => {
+  const i = args.indexOf(name);
+  return i === -1 ? undefined : args[i + 1];
+};
+const onlyRule = opt('--rule');
+const onlyFile = opt('--file');
+
+const input = readFileSync(0, 'utf8');
+const start = input.indexOf('[');
+const results = JSON.parse(input.slice(start));
+
+const rows = [];
+for (const file of results) {
+  const rel = file.filePath.replace(`${process.cwd()}/`, '');
+  for (const m of file.messages) {
+    if (!m.ruleId?.startsWith('shadcn/')) continue;
+    rows.push({
+      file: rel,
+      rule: m.ruleId.slice(7),
+      line: m.line,
+      msg: m.message,
+    });
+  }
+}
+
+const count = (key) => {
+  const c = new Map();
+  for (const r of rows) c.set(r[key], (c.get(r[key]) ?? 0) + 1);
+  return [...c.entries()].sort((a, b) => b[1] - a[1]);
+};
+const pad = (s, n) => String(s).padStart(n);
+
+if (onlyFile) {
+  const mine = rows.filter(
+    (r) => r.file === onlyFile || r.file.endsWith(onlyFile),
+  );
+  console.log(`${mine.length} design warnings in ${onlyFile}\n`);
+  for (const r of mine.sort((a, b) => a.line - b.line)) {
+    console.log(
+      `${pad(r.line, 5)}  ${r.rule}\n       ${r.msg.split(' See frontend/DESIGN.md')[0]}\n`,
+    );
+  }
+} else if (onlyRule) {
+  const mine = rows.filter((r) => r.rule === onlyRule);
+  console.log(`${mine.length} warnings for shadcn/${onlyRule}\n`);
+  const byFile = new Map();
+  for (const r of mine) byFile.set(r.file, (byFile.get(r.file) ?? 0) + 1);
+  for (const [f, n] of [...byFile.entries()].sort((a, b) => b[1] - a[1]))
+    console.log(`${pad(n, 5)}  ${f}`);
+} else {
+  console.log(
+    `${rows.length} design warnings in ${new Set(rows.map((r) => r.file)).size} files\n`,
+  );
+  console.log('By rule:');
+  for (const [rule, n] of count('rule')) console.log(`${pad(n, 5)}  ${rule}`);
+  console.log('\nWorst files:');
+  for (const [file, n] of count('file').slice(0, 25))
+    console.log(`${pad(n, 5)}  ${file}`);
+  console.log(
+    '\nNext: npm run lint:design -- --file <path>   or   -- --rule <rule>',
+  );
+}
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 2772d157..84af38d5 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -1,13 +1,17 @@
 import { envVar } from '@/env';
 import './locale/i18n';
 
-import { useState } from 'react';
+import { lazy, Suspense, useState } from 'react';
 import { useTranslation } from 'react-i18next';
+import { useSelector } from 'react-redux';
 import { Outlet, Route, Routes, useLocation } from 'react-router-dom';
 
+import { cn } from '@/lib/utils';
+
 import Admin from './admin';
 import Agents from './agents';
 import SharedAgentGate from './agents/SharedAgentGate';
+import { selectWorkflowPreviewOpen } from './agents/workflow/workflowPreviewSlice';
 import DocsGPTMark from './assets/logo-b.svg';
 import DocsGPTMarkWhite from './assets/logo-w.svg';
 import ActionButtons from './components/ActionButtons';
@@ -15,6 +19,7 @@ import AdminRoute from './components/AdminRoute';
 import ErrorBoundary from './components/ErrorBoundary';
 import Spinner from './components/Spinner';
 import { Button } from './components/ui/button';
+import { ToastViewport } from './components/ui/toast';
 import UploadToast from './components/UploadToast';
 import Conversation from './conversation/Conversation';
 import { SharedConversation } from './conversation/SharedConversation';
@@ -26,11 +31,18 @@ import Navigation from './Navigation';
 import { getSectionForPath } from './navigation/sections';
 import { SidebarLevelProvider } from './navigation/SidebarLevelProvider';
 import PageNotFound from './PageNotFound';
+
+// Dev-only style guide (see frontend/DESIGN.md). The DEV guard around the
+// import lets the bundler drop the chunk from production builds entirely.
+const DesignSystem = import.meta.env.DEV
+  ? lazy(() => import('./design/DesignSystem'))
+  : null;
 import Setting from './settings';
 import Teams from './settings/Teams';
 import Notification from './components/Notification';
 import ToolApprovalToast from './notifications/ToolApprovalToast';
 import TeamNotificationToast from './notifications/TeamNotificationToast';
+import ActionToast from './notifications/ActionToast';
 
 function AuthWrapper({ children }: { children: React.ReactNode }) {
   const { t } = useTranslation();
@@ -64,7 +76,7 @@ function AuthWrapper({ children }: { children: React.ReactNode }) {
         <Button
           type="button"
           onClick={retryOidcLogin}
-          className="rounded-3xl px-5"
+          shape="pill"
           data-testid="oidc-signin"
         >
           {t('auth.signInWith', { provider: oidcProviderName || 'SSO' })}
@@ -90,6 +102,10 @@ function MainLayout() {
   // the conversation now survives the trip, so "share" would target a chat
   // that isn't on screen.
   const inSection = Boolean(getSectionForPath(location.pathname));
+  // The workflow Preview drawer occupies the right edge; move the toast
+  // stack to the bottom-left while it's open so it stays visible without
+  // covering the drawer's attach/send controls.
+  const previewOpen = useSelector(selectWorkflowPreviewOpen);
 
   return (
     <SidebarLevelProvider>
@@ -109,9 +125,18 @@ function MainLayout() {
             <Outlet />
           </ErrorBoundary>
         </div>
-        <UploadToast />
-        <ToolApprovalToast />
-        <TeamNotificationToast />
+        {/* The one toast stack (and live region) for the app. Each toast
+          renders only its cards, top to bottom: team notifications, tool
+          approvals, uploads, action results. */}
+        <ToastViewport
+          className={cn(previewOpen && 'right-auto left-4')}
+          onMouseDown={(e) => e.stopPropagation()}
+        >
+          <TeamNotificationToast />
+          <ToolApprovalToast />
+          <UploadToast />
+          <ActionToast />
+        </ToastViewport>
       </div>
     </SidebarLevelProvider>
   );
@@ -178,6 +203,16 @@ export default function App() {
         </Route>
         <Route path="/share/:identifier" element={<SharedConversation />} />
         <Route path="/shared/agent/:agentId" element={<SharedAgentGate />} />
+        {DesignSystem && (
+          <Route
+            path="/design"
+            element={
+              <Suspense fallback={null}>
+                <DesignSystem />
+              </Suspense>
+            }
+          />
+        )}
         <Route path="/*" element={<PageNotFound />} />
       </Routes>
     </div>
diff --git a/frontend/src/Hero.tsx b/frontend/src/Hero.tsx
index acdd4648..46c46dd7 100644
--- a/frontend/src/Hero.tsx
+++ b/frontend/src/Hero.tsx
@@ -93,17 +93,27 @@ function HeroModelSelect() {
       disabled={!hasModels}
     >
       <SelectTrigger
+        /* eslint-disable-next-line shadcn/no-restyle --
+           The landing page's one focal control keeps its own look: a
+           borderless muted pill at 16px whose menu joins it (DESIGN.md,
+           Approved exceptions). */
         className="bg-muted dark:bg-card text-foreground hover:bg-muted dark:hover:bg-card w-full justify-between rounded-4xl border-0 px-6 py-4 text-base shadow-none data-[state=open]:rounded-b-none"
         size="lg"
       >
         <SelectValue placeholder="Select Model" />
       </SelectTrigger>
-      <SelectContent className="bg-muted dark:bg-card rounded-t-none rounded-b-4xl border-0 shadow-md data-[side=bottom]:translate-y-0">
+      <SelectContent
+        /* eslint-disable-next-line shadcn/no-restyle --
+           The hero picker's menu hangs from its trigger as one muted
+           shape (DESIGN.md, Approved exceptions). */
+        className="bg-muted dark:bg-card rounded-t-none rounded-b-4xl border-0 shadow-md data-[side=bottom]:translate-y-0"
+      >
         {hasModels ? (
           availableModels?.map((model: Model) => (
             <SelectItem
               key={model.id}
               value={model.id}
+              /* eslint-disable-next-line shadcn/no-restyle -- hero menu rows match its 16px trigger */
               className="px-5 py-3 text-base [&_[data-slot=select-item-indicator]]:right-5"
             >
               {model.display_name}
@@ -169,7 +179,7 @@ export default function Hero({
                   <p className="text-foreground mb-2 font-semibold">
                     {demo.header}
                   </p>
-                  <span className="line-clamp-2 text-gray-700 opacity-60 dark:text-gray-300">
+                  <span className="text-muted-foreground line-clamp-2">
                     {demo.query}
                   </span>
                 </button>
diff --git a/frontend/src/Navigation.tsx b/frontend/src/Navigation.tsx
index 283026f3..0014d8cf 100644
--- a/frontend/src/Navigation.tsx
+++ b/frontend/src/Navigation.tsx
@@ -400,11 +400,10 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
         >
           <Button
             type="button"
-            variant="ghost"
+            variant="ghost-muted"
             size="icon"
             onClick={() => setNavOpen(true)}
             aria-label="Open navigation menu"
-            className="text-muted-foreground hover:text-foreground"
           >
             <PanelLeftOpen className="size-5" strokeWidth={1.75} />
           </Button>
@@ -421,37 +420,34 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
               {queries?.length > 0 && (
                 <Button
                   type="button"
-                  variant="ghost"
+                  variant="ghost-muted"
                   size="icon"
                   onClick={() => newChat()}
                   aria-label="Start new chat"
-                  className="text-muted-foreground hover:text-foreground"
                 >
                   <Plus className="size-5" strokeWidth={1.75} />
                 </Button>
               )}
               <Button
                 type="button"
-                variant="ghost"
+                variant="ghost-muted"
                 size="icon"
                 onClick={() => {
                   dispatch(setSelectedAgent(null));
                   goToLevel(AGENTS_MANAGE_ROOT);
                 }}
                 aria-label={t('manageAgents')}
-                className="text-muted-foreground hover:text-foreground"
               >
                 <LayoutGrid className="size-5" strokeWidth={1.75} />
               </Button>
               {conversations?.data && conversations.data.length > 0 && (
                 <Button
                   type="button"
-                  variant="ghost"
+                  variant="ghost-muted"
                   size="icon"
                   onClick={() => setSearchOpen(true)}
                   aria-label={t('modals.searchConversations.searchPlaceholder')}
                   title={t('modals.searchConversations.searchPlaceholder')}
-                  className="text-muted-foreground hover:text-foreground"
                 >
                   <SearchIcon className="size-5" strokeWidth={1.75} />
                 </Button>
@@ -459,11 +455,10 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
               <div className="mt-auto flex flex-col items-center gap-2">
                 <Button
                   type="button"
-                  variant="ghost"
+                  variant="ghost-muted"
                   size="icon"
                   onClick={() => goToLevel('/settings')}
                   aria-label={t('settings.label')}
-                  className="text-muted-foreground hover:text-foreground"
                 >
                   <SettingsIcon className="size-5" strokeWidth={1.75} />
                 </Button>
@@ -473,9 +468,10 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
         </div>
       )}
       <div
-        className={`${
-          !navOpen && '-ml-96 md:-ml-72'
-        } bg-sidebar dark:border-r-sidebar-border fixed top-0 z-20 flex h-full w-72 flex-col border-r border-b-0 transition-all duration-300 ease-in-out dark:text-white`}
+        className={cn(
+          'bg-sidebar dark:border-r-sidebar-border fixed top-0 z-20 flex h-full w-72 flex-col border-r border-b-0 transition-all duration-300 ease-in-out dark:text-white',
+          !navOpen && '-ml-96 md:-ml-72',
+        )}
       >
         <div
           className={
@@ -493,9 +489,9 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
           </div>
           <Button
             type="button"
-            variant="ghost"
+            variant="ghost-muted"
             size="icon"
-            className="text-muted-foreground hover:text-foreground shrink-0"
+            className="shrink-0"
             onClick={() => {
               setNavOpen(!navOpen);
             }}
@@ -562,27 +558,29 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
                       {t('navigation.agents')}
                     </p>
                   </div>
-                  <div className="agents-container">
+                  <div>
                     <div>
                       {recentAgents.map((agent, idx) => (
                         <div
                           key={idx}
-                          className={`group hover:bg-sidebar-accent mx-4 my-auto mt-4 flex h-9 cursor-pointer items-center justify-between rounded-3xl pl-4 ${
+                          className={`group hover:bg-sidebar-accent mx-4 my-auto mt-4 flex h-9 cursor-pointer items-center justify-between rounded-3xl pl-3 ${
                             agent.id === selectedAgent?.id && !conversationId
                               ? 'bg-sidebar-accent'
                               : ''
                           }`}
                           onClick={() => handleAgentClick(agent)}
                         >
-                          <div className="flex items-center gap-2">
+                          <div className="flex items-center gap-2.5">
                             <div className="flex w-6 justify-center">
                               <Avatar
                                 src={agent.image}
                                 alt="agent-logo"
-                                imgClassName="h-6 w-6 rounded-full object-contain"
+                                shape="circle"
+                                className="overflow-hidden"
+                                imgClassName="h-6 w-6 object-contain"
                               />
                             </div>
-                            <p className="text-foreground dark:text-foreground overflow-hidden text-sm leading-6 text-ellipsis whitespace-nowrap">
+                            <p className="text-foreground overflow-hidden text-sm leading-6 text-ellipsis whitespace-nowrap">
                               {agent.name}
                             </p>
                           </div>
@@ -593,6 +591,7 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
                               type="button"
                               variant="ghost"
                               size="icon-sm"
+                              /* eslint-disable-next-line shadcn/no-restyle -- the pin is a bare 16px image on a sidebar row that already fills on hover; an accent fill would be invisible on it, so hover dims the icon instead */
                               className="h-auto w-auto rounded-full p-0 hover:bg-transparent hover:opacity-75"
                               onClick={(e) => {
                                 e.stopPropagation();
@@ -611,63 +610,65 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
                         </div>
                       ))}
                     </div>
-                    <NavLink
-                      to={AGENTS_MANAGE_ROOT}
-                      end
-                      onClick={(event) => {
-                        if (event.metaKey || event.ctrlKey || event.shiftKey)
-                          return;
-                        event.preventDefault();
-                        dispatch(setSelectedAgent(null));
-                        closeNavOnMobile();
-                        goToLevel(AGENTS_MANAGE_ROOT);
-                      }}
-                      className={({ isActive }) =>
-                        `hover:bg-sidebar-accent mx-4 my-auto mt-2 flex h-9 cursor-pointer items-center gap-2 rounded-3xl pl-4 ${
-                          isActive ? 'bg-sidebar-accent' : ''
-                        }`
-                      }
+                    <Button
+                      variant="sidebar-item"
+                      asChild
+                      className="mx-4 my-auto mt-2 flex"
                     >
-                      <div className="flex w-6 justify-center">
-                        <LayoutGrid
-                          className="text-muted-foreground size-5"
-                          strokeWidth={1.75}
-                          aria-label="manage-agents"
-                        />
-                      </div>
-                      <p className="text-foreground dark:text-foreground overflow-hidden text-sm leading-6 text-ellipsis whitespace-nowrap">
-                        {t('manageAgents')}
-                      </p>
-                    </NavLink>
+                      <NavLink
+                        to={AGENTS_MANAGE_ROOT}
+                        end
+                        onClick={(event) => {
+                          if (event.metaKey || event.ctrlKey || event.shiftKey)
+                            return;
+                          event.preventDefault();
+                          dispatch(setSelectedAgent(null));
+                          closeNavOnMobile();
+                          goToLevel(AGENTS_MANAGE_ROOT);
+                        }}
+                      >
+                        <div className="flex w-6 justify-center">
+                          <LayoutGrid
+                            className="text-muted-foreground size-5"
+                            strokeWidth={1.75}
+                            aria-label="manage-agents"
+                          />
+                        </div>
+                        <p className="text-foreground overflow-hidden text-sm leading-6 text-ellipsis whitespace-nowrap">
+                          {t('manageAgents')}
+                        </p>
+                      </NavLink>
+                    </Button>
                   </div>
                 </div>
               ) : (
-                <NavLink
-                  to={AGENTS_MANAGE_ROOT}
-                  end
-                  onClick={(event) => {
-                    if (event.metaKey || event.ctrlKey || event.shiftKey)
-                      return;
-                    event.preventDefault();
-                    closeNavOnMobile();
-                    dispatch(setSelectedAgent(null));
-                    goToLevel(AGENTS_MANAGE_ROOT);
-                  }}
-                  className={({ isActive }) =>
-                    `hover:bg-sidebar-accent mx-4 my-auto mt-2 flex h-9 cursor-pointer items-center gap-2.5 rounded-3xl pl-3 ${
-                      isActive ? 'bg-sidebar-accent' : ''
-                    }`
-                  }
+                <Button
+                  variant="sidebar-item"
+                  asChild
+                  className="mx-4 my-auto mt-2 flex"
                 >
-                  <LayoutGrid
-                    className="text-muted-foreground size-5 shrink-0"
-                    strokeWidth={1.75}
-                    aria-label="manage-agents"
-                  />
-                  <p className="text-foreground dark:text-foreground overflow-hidden text-sm leading-6 text-ellipsis whitespace-nowrap">
-                    {t('manageAgents')}
-                  </p>
-                </NavLink>
+                  <NavLink
+                    to={AGENTS_MANAGE_ROOT}
+                    end
+                    onClick={(event) => {
+                      if (event.metaKey || event.ctrlKey || event.shiftKey)
+                        return;
+                      event.preventDefault();
+                      closeNavOnMobile();
+                      dispatch(setSelectedAgent(null));
+                      goToLevel(AGENTS_MANAGE_ROOT);
+                    }}
+                  >
+                    <LayoutGrid
+                      className="text-muted-foreground size-5 shrink-0"
+                      strokeWidth={1.75}
+                      aria-label="manage-agents"
+                    />
+                    <p className="text-foreground overflow-hidden text-sm leading-6 text-ellipsis whitespace-nowrap">
+                      {t('manageAgents')}
+                    </p>
+                  </NavLink>
+                </Button>
               )}
               {conversations?.data && conversations.data.length > 0 ? (
                 <div className="mt-7">
@@ -677,10 +678,11 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
                     </p>
                     <Button
                       type="button"
-                      variant="ghost"
+                      variant="ghost-muted"
                       size="icon"
+                      shape="pill"
                       onClick={() => setSearchOpen(true)}
-                      className="text-muted-foreground hover:text-foreground hover:bg-sidebar-accent mr-1 rounded-full"
+                      className="mr-1"
                       aria-label={t(
                         'modals.searchConversations.searchPlaceholder',
                       )}
@@ -693,7 +695,7 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
                       />
                     </Button>
                   </div>
-                  <div className="conversations-container">
+                  <div>
                     {(conversations.data ?? []).map((conversation) => (
                       <ConversationTile
                         key={conversation.id}
@@ -763,25 +765,30 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
               inSection && 'hidden',
             )}
           >
-            <Link
-              to="/settings"
-              onClick={(event) => {
-                if (event.metaKey || event.ctrlKey || event.shiftKey) return;
-                event.preventDefault();
-                closeNavOnMobile();
-                goToLevel('/settings');
-              }}
-              className="hover:bg-sidebar-accent mx-4 my-auto flex h-9 cursor-pointer items-center gap-2.5 rounded-3xl pl-3"
+            <Button
+              variant="sidebar-item"
+              asChild
+              className="mx-4 my-auto flex"
             >
-              <SettingsIcon
-                className="text-muted-foreground size-5 shrink-0"
-                strokeWidth={1.75}
-                aria-label="Settings"
-              />
-              <p className="text-foreground text-sm dark:text-white">
-                {t('settings.label')}
-              </p>
-            </Link>
+              <Link
+                to="/settings"
+                onClick={(event) => {
+                  if (event.metaKey || event.ctrlKey || event.shiftKey) return;
+                  event.preventDefault();
+                  closeNavOnMobile();
+                  goToLevel('/settings');
+                }}
+              >
+                <SettingsIcon
+                  className="text-muted-foreground size-5 shrink-0"
+                  strokeWidth={1.75}
+                  aria-label="Settings"
+                />
+                <p className="text-foreground text-sm dark:text-white">
+                  {t('settings.label')}
+                </p>
+              </Link>
+            </Button>
           </div>
           <div className="text-foreground flex flex-col justify-end dark:text-white">
             <div className="flex items-center justify-between py-1">
@@ -836,9 +843,9 @@ export default function Navigation({ navOpen, setNavOpen }: NavigationProps) {
         <div className="relative flex h-full items-center">
           <Button
             type="button"
-            variant="ghost"
+            variant="ghost-muted"
             size="icon"
-            className="text-muted-foreground hover:text-foreground ml-4 size-9 lg:hidden"
+            className="ml-4 size-9 lg:hidden"
             onClick={() => setNavOpen(true)}
             aria-label="Toggle mobile menu"
           >
diff --git a/frontend/src/PageNotFound.tsx b/frontend/src/PageNotFound.tsx
index 06cf1cc7..2ed64df0 100644
--- a/frontend/src/PageNotFound.tsx
+++ b/frontend/src/PageNotFound.tsx
@@ -6,12 +6,12 @@ export default function PageNotFound() {
 
   return (
     <div className="bg-background grid min-h-screen">
-      <p className="text-foreground dark:bg-card mx-auto my-auto mt-20 flex w-full max-w-6xl flex-col place-items-center gap-6 rounded-3xl bg-gray-100 p-6 lg:p-10 xl:p-16">
+      <p className="text-foreground bg-muted mx-auto my-auto mt-20 flex w-full max-w-6xl flex-col place-items-center gap-6 rounded-3xl p-6 lg:p-10 xl:p-16">
         <h1>{t('pageNotFound.title')}</h1>
         <p>{t('pageNotFound.message')}</p>
         <Link
           to="/"
-          className="bg-primary hover:bg-primary/90 mr-4 inline-flex cursor-pointer items-center justify-center rounded-full px-4 py-2 text-white transition-colors duration-100"
+          className="bg-primary hover:bg-primary/90 text-primary-foreground mr-4 inline-flex cursor-pointer items-center justify-center rounded-full px-4 py-2 transition-colors duration-100"
         >
           {t('pageNotFound.goHome')}
         </Link>
diff --git a/frontend/src/admin/Activity.tsx b/frontend/src/admin/Activity.tsx
index c5494635..633014cc 100644
--- a/frontend/src/admin/Activity.tsx
+++ b/frontend/src/admin/Activity.tsx
@@ -6,6 +6,7 @@ import { useSearchParams } from 'react-router-dom';
 import adminService, {
   type ActivityFilters,
 } from '../api/services/adminService';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { MultiSelect } from '../components/ui/multi-select';
@@ -21,7 +22,6 @@ import {
 import { selectToken } from '../preferences/preferenceSlice';
 import {
   Loading,
-  Pill,
   categoryTone,
   eventLabel,
   eventTone,
@@ -75,7 +75,7 @@ function DetailRow({ label, value }: { label: string; value: unknown }) {
       ? JSON.stringify(value)
       : String(value);
   return (
-    <div className="flex gap-2 text-[13px] break-all">
+    <div className="flex gap-2 text-xs break-all">
       <span className="text-muted-foreground min-w-32 shrink-0">{label}</span>
       <span className="font-mono">{text}</span>
     </div>
@@ -275,7 +275,7 @@ export default function Activity() {
               key={range.label}
               variant={range.days === rangeDays ? 'default' : 'outline'}
               size="sm"
-              className="rounded-3xl"
+              shape="pill"
               onClick={() => withPageReset(setRangeDays)(range.days)}
             >
               {range.label}
@@ -347,7 +347,7 @@ export default function Activity() {
                   const repeat =
                     idx > 0 && rows[idx - 1].actor_id === row.actor_id;
                   return [
-                    <TableRow key={key} className="hover:bg-muted/40">
+                    <TableRow key={key}>
                       <TableCell>
                         <button
                           type="button"
@@ -369,29 +369,29 @@ export default function Activity() {
                       </TableCell>
                       <TableCell>
                         <div className="flex items-center gap-2">
-                          <Pill tone={eventTone(row.event)}>
+                          <Badge variant={eventTone(row.event)}>
                             {eventLabel(row.event)}
-                          </Pill>
+                          </Badge>
                           {row.outcome ? (
-                            <Pill tone={outcomeTone(row.outcome)}>
+                            <Badge variant={outcomeTone(row.outcome)}>
                               {outcomeLabel(row.outcome)}
-                            </Pill>
+                            </Badge>
                           ) : null}
                         </div>
                       </TableCell>
                       <TableCell>
-                        <Pill tone={categoryTone(row.category)}>
+                        <Badge variant={categoryTone(row.category)}>
                           {row.category}
-                        </Pill>
+                        </Badge>
                       </TableCell>
                       <TableCell
-                        className={`font-mono text-[13px] ${
+                        className={`font-mono text-xs ${
                           repeat ? 'text-muted-foreground/50' : ''
                         }`}
                       >
                         {repeat ? '〃' : (row.actor_id ?? '—')}
                       </TableCell>
-                      <TableCell className="font-mono text-[13px]">
+                      <TableCell className="font-mono text-xs">
                         {row.target_id && row.target_id !== row.actor_id
                           ? row.target_id
                           : '—'}
@@ -406,9 +406,7 @@ export default function Activity() {
                             local
                           </span>
                         ) : (
-                          <span className="font-mono text-[13px]">
-                            {row.ip}
-                          </span>
+                          <span className="font-mono text-xs">{row.ip}</span>
                         )}
                       </TableCell>
                       <TableCell className="text-muted-foreground whitespace-nowrap">
@@ -419,7 +417,7 @@ export default function Activity() {
                     </TableRow>,
                     isOpen ? (
                       <TableRow key={`${key}:detail`}>
-                        <TableCell colSpan={7} className="py-2">
+                        <TableCell colSpan={7}>
                           <RowDetail row={row} />
                         </TableCell>
                       </TableRow>
diff --git a/frontend/src/admin/AdminUI.test.ts b/frontend/src/admin/AdminUI.test.ts
index 26d74212..0da1f4eb 100644
--- a/frontend/src/admin/AdminUI.test.ts
+++ b/frontend/src/admin/AdminUI.test.ts
@@ -23,8 +23,8 @@ describe('eventLabel', () => {
 
 describe('eventTone', () => {
   it('flags removals and refusals', () => {
-    expect(eventTone('oidc_login_denied')).toBe('danger');
-    expect(eventTone('agent.deleted')).toBe('danger');
+    expect(eventTone('oidc_login_denied')).toBe('destructive');
+    expect(eventTone('agent.deleted')).toBe('destructive');
   });
 
   it('flags revocations as a warning, not a failure', () => {
@@ -32,18 +32,22 @@ describe('eventTone', () => {
     expect(eventTone('agent.key_regenerated')).toBe('warning');
   });
 
-  it('marks an admin grant with the brand tone', () => {
-    expect(eventTone('role_granted')).toBe('brand');
+  it('marks an admin grant with the brand (default) variant', () => {
+    expect(eventTone('role_granted')).toBe('default');
   });
 
   it('leaves routine events muted', () => {
-    expect(eventTone('oidc_login')).toBe('muted');
-    expect(eventTone('anything_else')).toBe('muted');
+    expect(eventTone('oidc_login')).toBe('neutral');
+    expect(eventTone('anything_else')).toBe('neutral');
   });
 });
 
 describe('categoryTone', () => {
-  it('has a tone for every category the API declares', () => {
+  it('has a variant for every category the API declares', () => {
+    expect(categoryTone('identity')).toBe('outline');
+    expect(categoryTone('access')).toBe('default');
+    expect(categoryTone('safety')).toBe('destructive');
+    expect(categoryTone('other')).toBe('neutral');
     for (const category of [
       'identity',
       'access',
@@ -58,7 +62,7 @@ describe('categoryTone', () => {
   });
 
   it('falls back for an unknown category', () => {
-    expect(categoryTone('invented')).toBe('muted');
+    expect(categoryTone('invented')).toBe('neutral');
   });
 });
 
@@ -66,11 +70,11 @@ describe('outcomeTone', () => {
   // The values below are the only ones the writers produce: guardrails emit
   // triggered/not_evaluated, the device feed emits dispatched.
   it('flags a guardrail that fired', () => {
-    expect(outcomeTone('triggered')).toBe('danger');
+    expect(outcomeTone('triggered')).toBe('destructive');
   });
 
   it('leaves a check that never ran neutral', () => {
-    expect(outcomeTone('not_evaluated')).toBe('muted');
+    expect(outcomeTone('not_evaluated')).toBe('neutral');
   });
 
   it('reads a dispatched device command as a success', () => {
@@ -78,7 +82,7 @@ describe('outcomeTone', () => {
   });
 
   it('leaves an unfamiliar outcome muted', () => {
-    expect(outcomeTone('something-new')).toBe('muted');
+    expect(outcomeTone('something-new')).toBe('neutral');
   });
 });
 
diff --git a/frontend/src/admin/AdminUI.tsx b/frontend/src/admin/AdminUI.tsx
index 250a7410..8f5cd650 100644
--- a/frontend/src/admin/AdminUI.tsx
+++ b/frontend/src/admin/AdminUI.tsx
@@ -1,4 +1,7 @@
+import type { VariantProps } from 'class-variance-authority';
+
 import Spinner from '../components/Spinner';
+import type { badgeVariants } from '../components/ui/badge';
 import { formatDateOnly, formatDateTime } from '../utils/dateTimeUtils';
 
 export function Loading() {
@@ -37,36 +40,8 @@ export function StatCard({
   );
 }
 
-type Tone = 'default' | 'success' | 'danger' | 'muted' | 'brand' | 'warning';
-
-const TONES: Record<Tone, string> = {
-  default: 'bg-muted text-foreground',
-  success:
-    'bg-green-100 text-green-700 dark:bg-green-900/40 dark:text-green-300',
-  danger: 'bg-red-100 text-red-700 dark:bg-red-900/40 dark:text-red-300',
-  muted: 'bg-muted text-muted-foreground',
-  // brand violet — matches the chart's --primary; used for the Admin role.
-  brand:
-    'bg-[#7D54D1]/15 text-[#7D54D1] dark:bg-violet-900/40 dark:text-violet-300',
-  warning:
-    'bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-300',
-};
-
-export function Pill({
-  tone = 'default',
-  children,
-}: {
-  tone?: Tone;
-  children: React.ReactNode;
-}) {
-  return (
-    <span
-      className={`inline-flex rounded-full px-2 py-0.5 text-xs font-medium ${TONES[tone]}`}
-    >
-      {children}
-    </span>
-  );
-}
+// Audit-feed pills render as Badge; these helpers pick its variant.
+type Tone = NonNullable<VariantProps<typeof badgeVariants>['variant']>;
 
 export function fmtDate(value?: string | null): string {
   return value ? formatDateTime(value) : '—';
@@ -202,25 +177,25 @@ const WARNING_EVENTS = new Set([
 ]);
 
 export function eventTone(event: string): Tone {
-  if (DANGER_EVENTS.has(event)) return 'danger';
-  if (event === 'role_granted') return 'brand';
+  if (DANGER_EVENTS.has(event)) return 'destructive';
+  if (event === 'role_granted') return 'default';
   if (WARNING_EVENTS.has(event)) return 'warning';
-  return 'muted';
+  return 'neutral';
 }
 
 // Category facet colors. Mirrors docsgpt/audit_events.py.
 const CATEGORY_TONES: Record<string, Tone> = {
-  identity: 'default',
-  access: 'brand',
+  identity: 'outline',
+  access: 'default',
   config: 'warning',
   data: 'success',
   device: 'warning',
-  safety: 'danger',
-  other: 'muted',
+  safety: 'destructive',
+  other: 'neutral',
 };
 
 export function categoryTone(category: string): Tone {
-  return CATEGORY_TONES[category] ?? 'muted';
+  return CATEGORY_TONES[category] ?? 'neutral';
 }
 
 // Outcome values the two side journals actually write.
@@ -232,13 +207,13 @@ export function categoryTone(category: string): Tone {
 // produced, so every outcome rendered neutral grey -- including a guardrail
 // that fired, which is the one signal the merged feed exists to surface.
 const OUTCOME_TONES: Record<string, Tone> = {
-  triggered: 'danger',
-  not_evaluated: 'muted',
+  triggered: 'destructive',
+  not_evaluated: 'neutral',
   dispatched: 'success',
 };
 
 export function outcomeTone(outcome: string): Tone {
-  return OUTCOME_TONES[outcome] ?? 'muted';
+  return OUTCOME_TONES[outcome] ?? 'neutral';
 }
 
 const OUTCOME_LABELS: Record<string, string> = {
diff --git a/frontend/src/admin/Admins.tsx b/frontend/src/admin/Admins.tsx
index 5a0b3361..e4c7f134 100644
--- a/frontend/src/admin/Admins.tsx
+++ b/frontend/src/admin/Admins.tsx
@@ -2,6 +2,7 @@ import { useEffect, useState } from 'react';
 import { useSelector } from 'react-redux';
 
 import adminService from '../api/services/adminService';
+import { Badge } from '../components/ui/badge';
 import {
   Table,
   TableBody,
@@ -12,7 +13,7 @@ import {
   TableRow,
 } from '../components/ui/table';
 import { selectToken } from '../preferences/preferenceSlice';
-import { Loading, Pill, fmtDate } from './AdminUI';
+import { Loading, fmtDate } from './AdminUI';
 
 type Admin = { user_id: string; granted_at?: string; sources?: string[] };
 
@@ -69,9 +70,9 @@ export default function Admins() {
                   <TableCell>
                     <div className="flex flex-wrap gap-1">
                       {(a.sources ?? []).map((s) => (
-                        <Pill key={s} tone="muted">
+                        <Badge key={s} variant="neutral">
                           {s}
-                        </Pill>
+                        </Badge>
                       ))}
                     </div>
                   </TableCell>
diff --git a/frontend/src/admin/Overview.tsx b/frontend/src/admin/Overview.tsx
index 1ed25f4c..de3afb01 100644
--- a/frontend/src/admin/Overview.tsx
+++ b/frontend/src/admin/Overview.tsx
@@ -88,16 +88,14 @@ export default function Overview() {
           <div
             className={`rounded-2xl border px-6 py-5 ${
               failed > 0
-                ? 'border-red-300 bg-red-50 dark:border-red-900/50 dark:bg-red-950/30'
+                ? 'border-destructive/50 bg-destructive/10'
                 : 'border-border'
             }`}
           >
             <p className="text-muted-foreground text-sm">Failed logins (7d)</p>
             <p
               className={`mt-1 text-2xl font-bold tabular-nums ${
-                failed > 0
-                  ? 'text-red-600 dark:text-red-400'
-                  : 'text-foreground'
+                failed > 0 ? 'text-destructive' : 'text-foreground'
               }`}
             >
               {fmtNumber(failed)}
@@ -105,7 +103,7 @@ export default function Overview() {
             {failed > 0 ? (
               <Link
                 to="/admin/audit?event=oidc_login_denied"
-                className="mt-2 inline-block text-xs text-red-600 hover:underline dark:text-red-400"
+                className="text-destructive mt-2 inline-block text-xs hover:underline"
               >
                 View in Audit →
               </Link>
diff --git a/frontend/src/admin/QuotaEditor.tsx b/frontend/src/admin/QuotaEditor.tsx
index 7b9de108..bebd4e83 100644
--- a/frontend/src/admin/QuotaEditor.tsx
+++ b/frontend/src/admin/QuotaEditor.tsx
@@ -4,6 +4,7 @@ import { useSelector } from 'react-redux';
 import adminService, { type QuotaScope } from '../api/services/adminService';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
+import { Progress } from '../components/ui/progress';
 import {
   Select,
   SelectContent,
@@ -45,11 +46,7 @@ export function UsageBar({
   const fmt = (n: number) => (kind === 'cost' ? fmtUsd(n) : fmtNumber(n));
   const percent = usagePercent(budget.used, budget.limit);
   const tone =
-    percent >= 100
-      ? 'bg-red-500'
-      : percent >= 80
-        ? 'bg-amber-500'
-        : 'bg-[#7D54D1]';
+    percent >= 100 ? 'destructive' : percent >= 80 ? 'warning' : 'default';
   return (
     <div>
       <div className="flex items-baseline justify-between gap-3 text-sm">
@@ -60,19 +57,16 @@ export function UsageBar({
         </span>
       </div>
       {budget.limit !== null ? (
-        <div
-          className="bg-muted mt-1 h-1.5 w-full overflow-hidden rounded-full"
-          role="progressbar"
+        <Progress
+          className="mt-1"
+          size="sm"
+          variant={tone}
+          value={percent}
           aria-label={label}
           aria-valuemin={0}
           aria-valuemax={100}
           aria-valuenow={Math.round(percent)}
-        >
-          <div
-            className={`h-full rounded-full ${tone}`}
-            style={{ width: `${percent}%` }}
-          />
-        </div>
+        />
       ) : null}
       {caption ? (
         <p className="text-muted-foreground mt-1 text-xs">{caption}</p>
@@ -197,7 +191,7 @@ export default function QuotaEditor({
     <div className="space-y-4">
       <p className="text-muted-foreground text-xs">{inheritHint}</p>
       {policy && !policy.enabled ? (
-        <p className="text-xs text-amber-600 dark:text-amber-400">
+        <p className="text-warning text-xs">
           This policy is disabled and is not enforced. Saving keeps it disabled.
         </p>
       ) : null}
@@ -231,7 +225,7 @@ export default function QuotaEditor({
         />
       </div>
       {error ? (
-        <p role="alert" className="text-sm text-red-600 dark:text-red-400">
+        <p role="alert" className="text-destructive text-sm">
           {error}
         </p>
       ) : null}
diff --git a/frontend/src/admin/Quotas.tsx b/frontend/src/admin/Quotas.tsx
index 967f4f00..192c1d46 100644
--- a/frontend/src/admin/Quotas.tsx
+++ b/frontend/src/admin/Quotas.tsx
@@ -3,6 +3,7 @@ import { useSelector } from 'react-redux';
 
 import adminService, { type QuotaScope } from '../api/services/adminService';
 import teamsService from '../api/services/teamsService';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import { Modal } from '../components/ui/modal';
 import {
@@ -22,14 +23,7 @@ import {
   TableRow,
 } from '../components/ui/table';
 import { selectToken } from '../preferences/preferenceSlice';
-import {
-  LoadError,
-  Loading,
-  Pill,
-  fmtDate,
-  fmtNumber,
-  fmtRelative,
-} from './AdminUI';
+import { LoadError, Loading, fmtDate, fmtNumber, fmtRelative } from './AdminUI';
 import QuotaEditor from './QuotaEditor';
 import { describeBudget, type QuotaPolicy } from './quotaUtils';
 
@@ -118,8 +112,10 @@ export default function Quotas() {
 
   const bucketPill = (policy: QuotaPolicy) => (
     <>
-      {isAll(policy) ? null : <Pill tone="muted">{policy.bucket} traffic</Pill>}
-      {policy.enabled ? null : <Pill tone="muted">Disabled</Pill>}
+      {isAll(policy) ? null : (
+        <Badge variant="neutral">{policy.bucket} traffic</Badge>
+      )}
+      {policy.enabled ? null : <Badge variant="neutral">Disabled</Badge>}
     </>
   );
 
@@ -132,7 +128,7 @@ export default function Quotas() {
       </p>
 
       {(data.unpriced_models ?? []).length > 0 ? (
-        <div className="rounded-2xl border border-amber-300 bg-amber-50 px-5 py-4 text-sm dark:border-amber-800 dark:bg-amber-950/30">
+        <div className="border-warning/50 bg-warning/10 rounded-2xl border px-5 py-4 text-sm">
           <p className="text-foreground font-medium">
             Models without a price are invisible to cost limits
           </p>
diff --git a/frontend/src/admin/Usage.tsx b/frontend/src/admin/Usage.tsx
index 4904515b..dbaf9c39 100644
--- a/frontend/src/admin/Usage.tsx
+++ b/frontend/src/admin/Usage.tsx
@@ -104,7 +104,7 @@ export default function Usage() {
               key={range}
               variant={range === days ? 'default' : 'outline'}
               size="sm"
-              className="rounded-3xl"
+              shape="pill"
               onClick={() => setDays(range)}
             >
               {range}d
@@ -130,7 +130,7 @@ export default function Usage() {
           <Button
             variant={metric === 'tokens' ? 'default' : 'outline'}
             size="sm"
-            className="rounded-3xl"
+            shape="pill"
             onClick={() => setMetric('tokens')}
           >
             Tokens
@@ -138,7 +138,7 @@ export default function Usage() {
           <Button
             variant={metric === 'cost' ? 'default' : 'outline'}
             size="sm"
-            className="rounded-3xl"
+            shape="pill"
             onClick={() => setMetric('cost')}
           >
             Cost
@@ -221,8 +221,8 @@ export default function Usage() {
               </TableHead>
               <TableBody>
                 {topUsers.map((user) => (
-                  <TableRow key={user.user_id} className="hover:bg-muted/40">
-                    <TableCell className="font-mono text-[13px] break-all">
+                  <TableRow key={user.user_id}>
+                    <TableCell className="font-mono text-xs break-all">
                       <button
                         type="button"
                         className="hover:text-foreground focus-visible:ring-ring cursor-pointer rounded text-left underline-offset-2 hover:underline focus-visible:ring-2 focus-visible:outline-none"
diff --git a/frontend/src/admin/UserUsageModal.tsx b/frontend/src/admin/UserUsageModal.tsx
index 2a9f853b..fd8ba4b6 100644
--- a/frontend/src/admin/UserUsageModal.tsx
+++ b/frontend/src/admin/UserUsageModal.tsx
@@ -74,7 +74,7 @@ function SplitTable({
             <TableBody>
               {rows.map((row) => (
                 <TableRow key={row.key}>
-                  <TableCell className="text-[13px] break-all">
+                  <TableCell className="text-xs break-all">
                     {labels?.[row.key] ?? row.key}
                   </TableCell>
                   <TableCell align="right" className="tabular-nums">
@@ -170,7 +170,7 @@ export default function UserUsageModal({
             key={range}
             variant={range === days ? 'default' : 'outline'}
             size="sm"
-            className="rounded-3xl"
+            shape="pill"
             onClick={() => setDays(range)}
           >
             {range}d
diff --git a/frontend/src/admin/Users.tsx b/frontend/src/admin/Users.tsx
index 242e678e..dda2fd60 100644
--- a/frontend/src/admin/Users.tsx
+++ b/frontend/src/admin/Users.tsx
@@ -8,10 +8,11 @@ import {
   UserX,
 } from 'lucide-react';
 import { useCallback, useEffect, useState } from 'react';
-import { useSelector } from 'react-redux';
+import { useDispatch, useSelector } from 'react-redux';
 
 import adminService from '../api/services/adminService';
 import ThreeDots from '../assets/three-dots.svg';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import {
   DropdownMenu,
@@ -32,10 +33,10 @@ import {
 } from '../components/ui/table';
 import ConfirmationModal from '../modals/ConfirmationModal';
 import { ActiveState } from '../models/misc';
+import { showActionToast } from '../notifications/actionToastSlice';
 import { selectToken } from '../preferences/preferenceSlice';
 import {
   Loading,
-  Pill,
   eventLabel,
   fmtDateShort,
   fmtNumber,
@@ -62,6 +63,7 @@ type Action = {
 const PAGE_SIZE = 25;
 
 export default function Users() {
+  const dispatch = useDispatch();
   const token = useSelector(selectToken);
   const [users, setUsers] = useState<AdminUser[]>([]);
   const [adminIds, setAdminIds] = useState<Set<string>>(new Set());
@@ -75,10 +77,6 @@ export default function Users() {
   const [detail, setDetail] = useState<any | null>(null);
   const [usageFor, setUsageFor] = useState<string | null>(null);
   const [quotaUserId, setQuotaUserId] = useState<string | null>(null);
-  const [feedback, setFeedback] = useState<{
-    ok: boolean;
-    message: string;
-  } | null>(null);
   const [confirm, setConfirm] = useState<{
     message: string;
     submitLabel: string;
@@ -112,12 +110,15 @@ export default function Users() {
     load();
   }, [load]);
 
-  // Auto-dismiss the inline feedback banner.
-  useEffect(() => {
-    if (!feedback) return;
-    const id = setTimeout(() => setFeedback(null), 4500);
-    return () => clearTimeout(id);
-  }, [feedback]);
+  // The result shows as a toast in the app's shared ToastViewport
+  // (ActionToast), which auto-dismisses it.
+  const setFeedback = (feedback: { ok: boolean; message: string }) =>
+    dispatch(
+      showActionToast({
+        variant: feedback.ok ? 'success' : 'destructive',
+        message: feedback.message,
+      }),
+    );
 
   const run =
     (fn: () => Promise<Response>, userId: string, successMsg: string) =>
@@ -249,18 +250,6 @@ export default function Users() {
 
   return (
     <div className="mt-6">
-      {feedback ? (
-        <div
-          className={`mb-4 rounded-xl border px-4 py-2 text-sm ${
-            feedback.ok
-              ? 'border-green-300 bg-green-50 text-green-700 dark:border-green-900/50 dark:bg-green-950/30 dark:text-green-300'
-              : 'border-red-300 bg-red-50 text-red-700 dark:border-red-900/50 dark:bg-red-950/30 dark:text-red-300'
-          }`}
-        >
-          {feedback.message}
-        </div>
-      ) : null}
-
       <div className="mb-4 flex flex-wrap items-center gap-2">
         <Input
           placeholder="Filter by user id"
@@ -313,12 +302,11 @@ export default function Users() {
                   return (
                     <TableRow
                       key={u.user_id}
-                      className="hover:bg-muted/40 cursor-pointer"
                       onClick={() => openDetail(u.user_id)}
                     >
                       <TableCell className="max-w-[280px]">
                         <span
-                          className="block truncate font-mono text-[13px]"
+                          className="block truncate font-mono text-xs"
                           title={u.user_id}
                         >
                           {u.user_id}
@@ -326,9 +314,11 @@ export default function Users() {
                       </TableCell>
                       <TableCell>
                         <div className="flex flex-wrap gap-1">
-                          {isAdmin ? <Pill tone="brand">Admin</Pill> : null}
+                          {isAdmin ? (
+                            <Badge variant="default">Admin</Badge>
+                          ) : null}
                           {!u.active ? (
-                            <Pill tone="danger">Inactive</Pill>
+                            <Badge variant="destructive">Inactive</Badge>
                           ) : null}
                         </div>
                       </TableCell>
@@ -356,10 +346,10 @@ export default function Users() {
                             <DropdownMenuTrigger asChild>
                               <Button
                                 type="button"
-                                variant="ghost"
+                                variant="ghost-muted"
                                 size="icon"
                                 disabled={disabled}
-                                className="text-muted-foreground hover:text-foreground h-[35px] w-7"
+                                className="h-[35px] w-7"
                                 aria-label="User actions"
                               >
                                 <img
@@ -473,7 +463,7 @@ export default function Users() {
                   size="sm"
                   onClick={() => {
                     // Close the detail dialog before any confirm dialog opens
-                    // (avoids stacked modals); the list + banner reflect the result.
+                    // (avoids stacked modals); the list + toast reflect the result.
                     setDetail(null);
                     act.perform();
                   }}
@@ -494,14 +484,17 @@ export default function Users() {
               </p>
               <div className="flex flex-wrap gap-2">
                 {(detail.roles ?? []).map((r: string) => (
-                  <Pill key={r} tone={r === 'admin' ? 'brand' : 'muted'}>
+                  <Badge
+                    key={r}
+                    variant={r === 'admin' ? 'default' : 'neutral'}
+                  >
                     {r}
-                  </Pill>
+                  </Badge>
                 ))}
                 {detail.user?.active ? (
-                  <Pill tone="success">Active</Pill>
+                  <Badge variant="success">Active</Badge>
                 ) : (
-                  <Pill tone="danger">Inactive</Pill>
+                  <Badge variant="destructive">Inactive</Badge>
                 )}
               </div>
             </div>
diff --git a/frontend/src/agents/AgentCard.tsx b/frontend/src/agents/AgentCard.tsx
index 01564c71..a8849c73 100644
--- a/frontend/src/agents/AgentCard.tsx
+++ b/frontend/src/agents/AgentCard.tsx
@@ -17,6 +17,7 @@ import Trash from '../assets/red-trash.svg';
 import ThreeDots from '../assets/three-dots.svg';
 import UnPin from '../assets/unpin.svg';
 import { Avatar } from '../components/ui/avatar';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import {
   DropdownMenu,
@@ -388,7 +389,7 @@ export default function AgentCard({
       role={agent.status === 'published' ? 'button' : undefined}
       tabIndex={agent.status === 'published' ? 0 : undefined}
       aria-label={agent.status === 'published' ? agent.name : undefined}
-      className={`bg-muted hover:bg-accent focus-visible:ring-ring/50 focus-visible:border-ring relative flex h-44 flex-col justify-between rounded-2xl px-4 py-5 outline-none focus-visible:ring-[3px] sm:w-48 sm:px-6 ${agent.status === 'published' && 'cursor-pointer'}`}
+      className={`bg-muted hover:bg-accent focus-visible:ring-ring/50 focus-visible:border-ring relative flex h-44 flex-col justify-between rounded-2xl px-4 py-5 outline-none focus-visible:ring-3 sm:w-48 sm:px-6 ${agent.status === 'published' && 'cursor-pointer'}`}
       onClick={(e) => {
         e.stopPropagation();
         handleClick();
@@ -453,19 +454,21 @@ export default function AgentCard({
       {/* Team access badge — pinned to the top row, left of the ⋯ menu
           (right-11 clears the 19px trigger at right-4) so the two align. */}
       {agent.ownership === 'team' && (
-        <span className="bg-muted dark:bg-accent text-muted-foreground absolute top-4 right-11 z-10 flex items-center gap-1 rounded-full px-2 py-0.5 text-[11px] font-medium">
+        <Badge variant="neutral" className="absolute top-4 right-11 z-10">
           <Users size={11} strokeWidth={2} aria-hidden="true" />
           {agent.team_access === 'editor'
             ? t('agents.teamBadge.editor')
             : t('agents.teamBadge.viewer')}
-        </span>
+        </Badge>
       )}
       <div className="w-full">
         <div className="flex w-full items-center gap-1 px-1">
           <Avatar
             src={agent.image}
             alt={`${agent.name}`}
-            imgClassName="h-7 w-7 rounded-full object-contain"
+            size="sm"
+            shape="circle"
+            imgClassName="h-7 w-7 object-contain"
           />
           {agent.status === 'draft' && (
             <p className="text-foreground text-xs opacity-50">
@@ -508,7 +511,7 @@ export default function AgentCard({
           <Button
             type="button"
             onClick={() => setExportError(null)}
-            className="rounded-3xl px-5"
+            shape="pill"
           >
             {t('agents.close')}
           </Button>
diff --git a/frontend/src/agents/AgentPageHeader.test.tsx b/frontend/src/agents/AgentPageHeader.test.tsx
new file mode 100644
index 00000000..d3604a1d
--- /dev/null
+++ b/frontend/src/agents/AgentPageHeader.test.tsx
@@ -0,0 +1,56 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { MemoryRouter } from 'react-router-dom';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import AgentPageHeader from './AgentPageHeader';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('AgentPageHeader sub-nav', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it('renders the tabs as underline tab buttons, marking the current page', () => {
+    act(() => {
+      root.render(
+        <MemoryRouter>
+          <AgentPageHeader
+            agentId="a1"
+            agentName="Renewals"
+            currentPage="logs"
+          />
+        </MemoryRouter>,
+      );
+    });
+    const nav = container.querySelector(
+      'nav[aria-label="agents.pageHeader.subnavAriaLabel"]',
+    );
+    const tabs = Array.from(nav?.children ?? []);
+    expect(tabs).toHaveLength(3);
+    for (const tab of tabs) {
+      expect(tab.getAttribute('data-variant')).toBe('tab');
+      expect(tab.getAttribute('data-size')).toBe('inline');
+    }
+    const current = tabs[1];
+    expect(current.tagName).toBe('SPAN');
+    expect(current.getAttribute('aria-current')).toBe('page');
+    expect(current.getAttribute('data-active')).toBe('true');
+    expect(tabs[0].tagName).toBe('A');
+    expect(tabs[0].getAttribute('data-active')).not.toBe('true');
+  });
+});
diff --git a/frontend/src/agents/AgentPageHeader.tsx b/frontend/src/agents/AgentPageHeader.tsx
index 77005df1..38966892 100644
--- a/frontend/src/agents/AgentPageHeader.tsx
+++ b/frontend/src/agents/AgentPageHeader.tsx
@@ -10,6 +10,7 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
 } from '@/components/ui/breadcrumb';
+import { Button } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
 
 import {
@@ -100,7 +101,7 @@ export default function AgentPageHeader({
           <BreadcrumbSeparator />
           <BreadcrumbItem>
             {currentPage === 'overview' ? (
-              <BreadcrumbPage title={displayName} className="w-[16ch] truncate">
+              <BreadcrumbPage title={displayName} className="w-[16ch]">
                 {displayName}
               </BreadcrumbPage>
             ) : (
@@ -133,35 +134,31 @@ export default function AgentPageHeader({
       >
         {tabs.map((tab) => {
           const isActive = tab.id === currentPage;
-          // Always render a 2px bottom border so row height stays constant
-          // between active/inactive; only the color changes.
-          const baseClasses =
-            'whitespace-nowrap border-b-2 pb-1 text-sm font-medium transition-colors';
+          // -mb-px lays the tab's 2px underline over the nav's 1px baseline.
           if (isActive) {
             return (
-              <span
+              <Button
                 key={tab.id}
-                aria-current="page"
-                className={cn(
-                  baseClasses,
-                  'border-primary text-foreground -mb-px',
-                )}
+                asChild
+                variant="tab"
+                size="inline"
+                data-active
+                className="-mb-px"
               >
-                {tab.label}
-              </span>
+                <span aria-current="page">{tab.label}</span>
+              </Button>
             );
           }
           return (
-            <Link
+            <Button
               key={tab.id}
-              to={tab.href}
-              className={cn(
-                baseClasses,
-                'text-muted-foreground hover:text-foreground hover:border-border/60 -mb-px border-transparent',
-              )}
+              asChild
+              variant="tab"
+              size="inline"
+              className="-mb-px"
             >
-              {tab.label}
-            </Link>
+              <Link to={tab.href}>{tab.label}</Link>
+            </Button>
           );
         })}
       </nav>
diff --git a/frontend/src/agents/AgentsList.tsx b/frontend/src/agents/AgentsList.tsx
index 208a85d0..fd3c5265 100644
--- a/frontend/src/agents/AgentsList.tsx
+++ b/frontend/src/agents/AgentsList.tsx
@@ -189,8 +189,8 @@ export default function AgentsList() {
               value={searchQuery}
               onChange={(e) => setSearchQuery(e.target.value)}
               label={t('agents.searchPlaceholder')}
-              labelBgClassName="bg-background"
-              className="rounded-full"
+              labelSurface="background"
+              shape="pill"
               leftIcon={
                 <Search
                   className="text-muted-foreground size-4"
@@ -432,7 +432,7 @@ function AgentSection({
         {config.showNewAgentButton && (
           <Button
             type="button"
-            className="rounded-full text-white"
+            shape="pill"
             onClick={() => {
               setModalFolderId(null);
               setShowAgentTypeModal(true);
@@ -453,6 +453,9 @@ function AgentSection({
             // Drilling into a folder is a trail, not a back button — the
             // sidebar's back is the only thing that means "leave".
             <Breadcrumb>
+              {/* eslint-disable-next-line shadcn/no-restyle -- the folder
+                  trail stands in for the section <h2>, so it keeps heading
+                  typography (DESIGN.md Approved exceptions). */}
               <BreadcrumbList className="text-foreground gap-2 text-lg font-semibold sm:gap-2">
                 <BreadcrumbItem>
                   <BreadcrumbLink asChild>
@@ -469,7 +472,9 @@ function AgentSection({
                     <BreadcrumbSeparator />
                     <BreadcrumbItem>
                       {index === breadcrumbItems.length - 1 ? (
-                        <BreadcrumbPage>{item.name}</BreadcrumbPage>
+                        <BreadcrumbPage className="max-w-[32ch]">
+                          {item.name}
+                        </BreadcrumbPage>
                       ) : (
                         <BreadcrumbLink asChild>
                           <button
@@ -525,7 +530,8 @@ function AgentSection({
               <Button
                 type="button"
                 variant="outline"
-                className="bg-card shrink-0 rounded-full whitespace-nowrap"
+                shape="pill"
+                className="shrink-0 whitespace-nowrap"
                 onClick={() => {
                   setIsCreatingFolder(true);
                   setTimeout(() => newFolderInputRef.current?.focus(), 0);
@@ -538,7 +544,8 @@ function AgentSection({
             <Button
               type="button"
               variant="outline"
-              className="bg-card shrink-0 rounded-full whitespace-nowrap"
+              shape="pill"
+              className="shrink-0 whitespace-nowrap"
               onClick={() => setShowImportModal(true)}
             >
               {t('agents.importAgent')}
@@ -547,7 +554,8 @@ function AgentSection({
           {config.showNewAgentButton && (
             <Button
               type="button"
-              className="shrink-0 rounded-full whitespace-nowrap text-white"
+              shape="pill"
+              className="shrink-0 whitespace-nowrap"
               onClick={() => {
                 setModalFolderId(currentFolderId);
                 setShowAgentTypeModal(true);
@@ -610,7 +618,8 @@ function AgentSection({
                 {config.showNewAgentButton && !currentFolderId && (
                   <Button
                     type="button"
-                    className="ml-2 rounded-full text-white"
+                    shape="pill"
+                    className="ml-2"
                     onClick={() => {
                       setModalFolderId(currentFolderId);
                       setShowAgentTypeModal(true);
diff --git a/frontend/src/agents/FolderCard.tsx b/frontend/src/agents/FolderCard.tsx
index 5a5d6fe6..5476d7d9 100644
--- a/frontend/src/agents/FolderCard.tsx
+++ b/frontend/src/agents/FolderCard.tsx
@@ -82,7 +82,7 @@ export default function FolderCard({
         role="button"
         tabIndex={0}
         aria-pressed={isExpanded}
-        className={`focus-visible:ring-ring/50 focus-visible:border-ring relative flex cursor-pointer items-center justify-between rounded-2xl px-4 py-3 outline-none focus-visible:ring-[3px] sm:w-48 ${
+        className={`focus-visible:ring-ring/50 focus-visible:border-ring relative flex cursor-pointer items-center justify-between rounded-2xl px-4 py-3 outline-none focus-visible:ring-3 sm:w-48 ${
           isExpanded ? 'bg-accent' : 'bg-muted hover:bg-accent'
         }`}
         onClick={() => onToggleExpand(folder.id)}
diff --git a/frontend/src/agents/NewAgent.test.tsx b/frontend/src/agents/NewAgent.test.tsx
new file mode 100644
index 00000000..e7578264
--- /dev/null
+++ b/frontend/src/agents/NewAgent.test.tsx
@@ -0,0 +1,301 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { MemoryRouter } from 'react-router-dom';
+
+import type { MultiSelectPopoverItem } from '../components/MultiSelectPopover';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const mockState = {
+  preference: {
+    token: null,
+    sourceDocs: [],
+    selectedAgent: null,
+    prompts: [],
+    agentFolders: [],
+  },
+};
+
+vi.mock('react-redux', () => ({
+  useSelector: (selector: (state: unknown) => unknown) => selector(mockState),
+  useDispatch: () => vi.fn(),
+}));
+
+const jsonResponse = (body: unknown, ok = true) =>
+  Promise.resolve({ ok, json: () => Promise.resolve(body) });
+
+vi.mock('../api/services/userService', () => ({
+  default: {
+    getUserTools: () =>
+      jsonResponse({
+        tools: [
+          {
+            id: 'tool-1',
+            name: 'remote_device',
+            display_name: 'Laptop',
+            config: { device_id: 'device-1' },
+          },
+        ],
+      }),
+    getAgentFolders: () => jsonResponse({ folders: [] }),
+    getAgent: () => jsonResponse({}),
+    createAgent: () => jsonResponse({ message: 'Name is taken' }, false),
+    updateAgent: () => jsonResponse({}),
+    deleteAgent: () => jsonResponse({}),
+    createPrompt: () => jsonResponse({}),
+  },
+}));
+
+vi.mock('../api/services/devicesService', () => ({
+  default: {
+    list: () =>
+      Promise.resolve({
+        devices: [{ id: 'device-1', last_seen_at: new Date().toISOString() }],
+      }),
+  },
+}));
+
+vi.mock('../api/services/modelService', () => ({
+  default: {
+    getModels: () => jsonResponse({ models: [] }),
+    transformModels: () => [],
+  },
+}));
+
+// The pickers render only their trigger here, plus each item's rich
+// description so the device status pill can be checked.
+vi.mock('../components/MultiSelectPopover', () => ({
+  MultiSelectPopover: ({
+    trigger,
+    items,
+  }: {
+    trigger: React.ReactNode;
+    items: MultiSelectPopoverItem[];
+  }) => (
+    <div data-testid="picker">
+      {trigger}
+      {items.map((item) => (
+        <div key={item.id}>{item.descriptionNode}</div>
+      ))}
+    </div>
+  ),
+}));
+
+vi.mock('./workflow/WorkflowBuilder', () => ({ default: () => null }));
+vi.mock('./AgentPreview', () => ({ default: () => null }));
+vi.mock('../settings/Prompts', () => ({ default: () => null }));
+vi.mock('./components/GuardrailsSection', () => ({
+  default: () => null,
+  guardrailsIncomplete: () => false,
+}));
+vi.mock('../upload/Upload', () => ({ default: () => null }));
+vi.mock('../modals/AgentDetailsModal', () => ({ default: () => null }));
+vi.mock('../teams/ShareToTeamModal', () => ({ default: () => null }));
+vi.mock('../modals/ConfirmationModal', () => ({ default: () => null }));
+vi.mock('../preferences/PromptsModal', () => ({ default: () => null }));
+vi.mock('../navigation/SectionPills', () => ({ default: () => null }));
+vi.mock('../navigation/SectionPageHeader', () => ({
+  CurrentSectionHeader: () => null,
+}));
+vi.mock('../components/FileUpload', () => ({ FileUpload: () => null }));
+vi.mock('../components/SourcesPopoverFooter', () => ({ default: () => null }));
+vi.mock('../components/ToolIcon', () => ({ default: () => null }));
+
+import NewAgent from './NewAgent';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const setNativeValue = (
+  el: HTMLInputElement | HTMLTextAreaElement,
+  value: string,
+) => {
+  const proto =
+    el instanceof HTMLTextAreaElement
+      ? HTMLTextAreaElement.prototype
+      : HTMLInputElement.prototype;
+  Object.getOwnPropertyDescriptor(proto, 'value')!.set!.call(el, value);
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+};
+
+describe('NewAgent form', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async () => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter>
+          <NewAgent mode="new" />
+        </MemoryRouter>,
+      );
+    });
+  };
+
+  const buttonByText = (text: string) =>
+    Array.from(container.querySelectorAll('button')).find((b) =>
+      b.textContent?.includes(text),
+    )!;
+
+  // Decision 63 (3): every field, picker and button in the form is 42px.
+  it('renders the name field as a default-size (42px) pill Input', async () => {
+    await render();
+    const name = container.querySelector<HTMLInputElement>(
+      'input[placeholder="agents.form.placeholders.agentName"]',
+    )!;
+    expect(name.getAttribute('data-slot')).toBe('input');
+    expect(name.getAttribute('data-size')).toBe('default');
+    expect(name.getAttribute('data-shape')).toBe('pill');
+  });
+
+  it('renders the Add prompt button at the field height', async () => {
+    await render();
+    const add = buttonByText('agents.form.buttons.add');
+    expect(add.getAttribute('data-variant')).toBe('outline-primary');
+    expect(add.getAttribute('data-size')).toBe('field');
+    expect(add.getAttribute('data-shape')).toBe('pill');
+  });
+
+  it('renders the token and request limits as default-size pill Inputs', async () => {
+    await render();
+    await act(async () =>
+      buttonByText('agents.form.sections.advanced').click(),
+    );
+    for (const key of ['enterTokenLimit', 'enterRequestLimit']) {
+      const field = container.querySelector(
+        `input[placeholder="agents.form.placeholders.${key}"]`,
+      )!;
+      expect(field.getAttribute('data-size')).toBe('default');
+      expect(field.getAttribute('data-shape')).toBe('pill');
+    }
+  });
+
+  // Decision 64: the Advanced header is a section-toggle with a leading
+  // lucide chevron; the panel draws the focus ring.
+  it('renders the Advanced header as a section-toggle', async () => {
+    await render();
+    const toggle = buttonByText('agents.form.sections.advanced');
+    expect(toggle.getAttribute('data-variant')).toBe('section-toggle');
+    expect(toggle.getAttribute('data-size')).toBe('sm');
+    expect(toggle.getAttribute('aria-expanded')).toBe('false');
+    const chevron = toggle.firstElementChild!;
+    expect(chevron.matches('svg.lucide-chevron-right')).toBe(true);
+    expect(chevron.getAttribute('class')).not.toContain('rotate-90');
+    expect(toggle.querySelectorAll('svg')).toHaveLength(1);
+    expect(toggle.querySelector('h2')).toBeNull();
+    expect(toggle.parentElement!.tagName).toBe('H2');
+    const panel = toggle.closest('.bg-card')!;
+    expect(panel.className).toContain(
+      'has-[[data-variant=section-toggle]:focus-visible]:ring-3',
+    );
+
+    await act(async () => toggle.click());
+    expect(toggle.getAttribute('aria-expanded')).toBe('true');
+    expect(chevron.getAttribute('class')).toContain('rotate-90');
+  });
+
+  it('renders the description as a large ui Textarea', async () => {
+    await render();
+    const description = container.querySelector(
+      'textarea[placeholder="agents.form.placeholders.describeAgent"]',
+    )!;
+    expect(description.getAttribute('data-slot')).toBe('textarea');
+    expect(description.getAttribute('data-size')).toBe('lg');
+  });
+
+  it('renders the pickers as pill comboboxes, muted while empty', async () => {
+    await render();
+    const triggers = Array.from(
+      container.querySelectorAll('[data-testid="picker"] > button'),
+    );
+    // Sources, tools, models.
+    expect(triggers).toHaveLength(3);
+    for (const trigger of triggers) {
+      expect(trigger.getAttribute('data-variant')).toBe('combobox');
+      expect(trigger.getAttribute('data-size')).toBe('field');
+      expect(trigger.getAttribute('data-shape')).toBe('pill');
+      expect(trigger.hasAttribute('data-placeholder')).toBe(true);
+      expect(trigger.querySelector('span.truncate')).not.toBeNull();
+    }
+  });
+
+  it('shows the device status as a Badge', async () => {
+    await render();
+    const badge = container.querySelector('[data-slot="badge"]');
+    expect(badge?.textContent).toBe('settings.devices.online');
+    expect(badge?.getAttribute('data-variant')).toBe('success');
+  });
+
+  it('renders Save draft and Publish as pill button variants', async () => {
+    await render();
+    const draft = buttonByText('agents.form.buttons.saveDraft');
+    expect(draft.getAttribute('data-variant')).toBe('outline-primary');
+    expect(draft.getAttribute('data-shape')).toBe('pill');
+    const publish = buttonByText('agents.form.buttons.publish');
+    expect(publish.getAttribute('data-variant')).toBe('default');
+    expect(publish.getAttribute('data-shape')).toBe('pill');
+    expect(publish.disabled).toBe(true);
+  });
+
+  it('shows a failed save as a destructive alert with an icon', async () => {
+    await render();
+    const draft = buttonByText('agents.form.buttons.saveDraft');
+    await act(async () => draft.click());
+    const alert = container.querySelector('[role="alert"]')!;
+    expect(alert.textContent).toContain('Name is taken');
+    // ui/alert's destructive variant.
+    expect(alert.className).toContain('border-destructive/50');
+    expect(alert.className).toContain('bg-destructive/10');
+    expect(alert.querySelector('svg.lucide-circle-x')).not.toBeNull();
+    // Decision 69 (b): the notice sits above the form panel, not in the
+    // header's button row.
+    expect(draft.parentElement?.contains(alert)).toBe(false);
+  });
+
+  it('marks JSON schema validity with token colours and lucide icons', async () => {
+    await render();
+    await act(async () =>
+      buttonByText('agents.form.sections.advanced').click(),
+    );
+    const schema = Array.from(container.querySelectorAll('textarea')).find(
+      (el) => el.className.includes('font-mono'),
+    )!;
+    expect(schema.getAttribute('data-slot')).toBe('textarea');
+    expect(schema.getAttribute('data-size')).toBe('lg');
+
+    await act(async () => setNativeValue(schema, '{ not json'));
+    const invalid = Array.from(container.querySelectorAll('div')).find(
+      (el) => el.textContent === 'agents.form.advanced.invalidJson',
+    )!;
+    expect(invalid.className).toContain('text-destructive');
+    expect(invalid.querySelector('svg.lucide-circle-x')).not.toBeNull();
+
+    await act(async () => setNativeValue(schema, '{}'));
+    const valid = Array.from(container.querySelectorAll('div')).find(
+      (el) => el.textContent === 'agents.form.advanced.validJson',
+    )!;
+    expect(valid.className).toContain('text-success');
+    expect(valid.querySelector('svg.lucide-circle-check')).not.toBeNull();
+  });
+
+  it('shows the preview placeholder illustration as decorative images', async () => {
+    await render();
+    const images = container.querySelectorAll('img[alt=""]');
+    expect(images).toHaveLength(2);
+    for (const img of images) {
+      expect(img.getAttribute('aria-hidden')).toBe('true');
+    }
+  });
+});
diff --git a/frontend/src/agents/NewAgent.tsx b/frontend/src/agents/NewAgent.tsx
index c071bf8f..1a34ce58 100644
--- a/frontend/src/agents/NewAgent.tsx
+++ b/frontend/src/agents/NewAgent.tsx
@@ -1,5 +1,10 @@
 import isEqual from 'lodash/isEqual';
-import { MoreHorizontal } from 'lucide-react';
+import {
+  ChevronRight,
+  CircleCheck,
+  CircleX,
+  MoreHorizontal,
+} from 'lucide-react';
 import React, {
   useCallback,
   useEffect,
@@ -11,6 +16,8 @@ import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 import { useNavigate, useParams, useSearchParams } from 'react-router-dom';
 
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import {
   DropdownMenu,
@@ -28,10 +35,14 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { cn } from '@/lib/utils';
 
 import devicesService from '../api/services/devicesService';
 import modelService from '../api/services/modelService';
 import userService from '../api/services/userService';
+import ScienceSparkDarkIcon from '../assets/science-spark-dark.svg';
+import ScienceSparkIcon from '../assets/science-spark.svg';
 import SourceIcon from '../assets/source.svg';
 import { FileUpload } from '../components/FileUpload';
 import {
@@ -589,17 +600,14 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
             const meta = devicesById.get(deviceId);
             const online = meta?.online ?? false;
             base.descriptionNode = (
-              <span
-                className={`mt-0.5 inline-flex items-center rounded-full px-2 py-0.5 text-[10px] font-medium ${
-                  online
-                    ? 'bg-green-100 text-green-900 dark:bg-green-900/30 dark:text-green-300'
-                    : 'bg-gray-200 text-gray-700 dark:bg-gray-700/40 dark:text-gray-300'
-                }`}
+              <Badge
+                variant={online ? 'success' : 'neutral'}
+                className="mt-0.5"
               >
                 {online
                   ? t('settings.devices.online')
                   : t('settings.devices.offline')}
-              </span>
+              </Badge>
             );
           }
           return base;
@@ -808,33 +816,19 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
       <div className="flex w-full flex-wrap items-center justify-between gap-2">
         {showAgentNav ? <CurrentSectionHeader /> : <span aria-hidden />}
         <div className="flex flex-wrap items-center gap-2">
-          {submitError && (
-            <div
-              role="alert"
-              className="flex items-center gap-2 text-sm text-red-600 dark:text-red-400"
-            >
-              <span className="h-4 w-4 shrink-0 bg-[url('/src/assets/circle-x.svg')] bg-contain bg-center bg-no-repeat" />
-              {submitError}
-            </div>
-          )}
           {hasChanges && (
-            <Button
-              type="button"
-              variant="ghost"
-              onClick={handleCancel}
-              className="text-primary dark:text-foreground rounded-3xl px-2 hover:bg-transparent"
-            >
+            <Button type="button" variant="link" onClick={handleCancel}>
               {t('agents.form.buttons.cancel')}
             </Button>
           )}
           {modeConfig[effectiveMode].showSaveDraft && (
             <Button
               type="button"
+              variant="outline-primary"
+              shape="pill"
               disabled={isDraftBlocked()}
               onClick={handleSaveDraft}
-              className={`border-primary text-primary hover:bg-primary/90 min-w-28 rounded-3xl border border-solid bg-transparent px-5 whitespace-nowrap hover:text-white ${
-                isDraftBlocked() ? 'disabled:opacity-30' : ''
-              }`}
+              className="min-w-28"
             >
               <span className="flex items-center justify-center transition-all duration-200">
                 {draftLoading ? (
@@ -849,7 +843,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
             type="button"
             disabled={!isPublishable() || !hasChanges}
             onClick={handlePublish}
-            className={`${!isPublishable() || !hasChanges ? 'disabled:opacity-30' : ''} min-w-28 rounded-3xl px-5 whitespace-nowrap text-white`}
+            shape="pill"
+            className="min-w-28"
           >
             <span className="flex items-center justify-center transition-all duration-200">
               {publishLoading ? (
@@ -889,6 +884,12 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
         </div>
       </div>
       {showAgentNav && <SectionPills className="mt-4" />}
+      {submitError && (
+        <Alert variant="destructive" className="mt-3">
+          <CircleX aria-hidden="true" className="size-4" />
+          <AlertDescription>{submitError}</AlertDescription>
+        </Alert>
+      )}
       <div className="bg-muted dark:bg-background mt-3 flex w-full flex-1 grid-cols-5 flex-col gap-10 rounded-2xl p-5 max-[1179px]:overflow-visible min-[1180px]:grid min-[1180px]:gap-5 min-[1180px]:overflow-hidden">
         <div className="scrollbar-overlay col-span-2 flex flex-col gap-5 max-[1179px]:overflow-visible min-[1180px]:max-h-full min-[1180px]:overflow-y-auto min-[1180px]:pr-3">
           <div className="bg-card rounded-2xl px-6 py-3">
@@ -896,14 +897,16 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
               {t('agents.form.sections.meta')}
             </h2>
             <Input
-              className="bg-card mt-3 h-auto rounded-3xl px-5 py-3 text-sm placeholder:text-gray-400 md:text-sm"
+              shape="pill"
+              className="mt-3"
               type="text"
               value={agent.name}
               placeholder={t('agents.form.placeholders.agentName')}
               onChange={(e) => setAgent({ ...agent, name: e.target.value })}
             />
-            <textarea
-              className="border-border text-foreground dark:text-foreground dark:placeholder:text-muted-foreground bg-card dark:border-border focus-visible:ring-ring/50 focus-visible:border-ring mt-3 h-32 w-full rounded-xl border px-5 py-4 text-sm outline-hidden placeholder:text-gray-400 focus-visible:ring-[3px]"
+            <Textarea
+              size="lg"
+              className="mt-3 h-32"
               placeholder={t('agents.form.placeholders.describeAgent')}
               value={agent.description}
               onChange={(e) =>
@@ -913,17 +916,17 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
             <div className="mt-3">
               <FileUpload
                 showPreview
-                className="bg-card"
+                size="compact"
+                previewSize={56}
                 onUpload={handleUpload}
                 onRemove={() => setImageFile(null)}
                 uploadText={[
                   {
                     text: t('agents.form.upload.clickToUpload'),
-                    colorClass: 'text-primary',
+                    highlight: true,
                   },
                   {
                     text: t('agents.form.upload.dragAndDrop'),
-                    colorClass: 'text-[#525252]',
                   },
                 ]}
               />
@@ -960,16 +963,17 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                   trigger={
                     <Button
                       type="button"
-                      variant="outline"
+                      variant="combobox"
+                      size="field"
+                      shape="pill"
                       ref={sourceAnchorButtonRef}
                       title={selectedSourceNames.join(', ')}
-                      className={`bg-card h-auto w-full justify-start truncate rounded-3xl px-5 py-3 text-left text-sm font-normal ${
-                        selectedSourceIds.size > 0
-                          ? 'text-foreground dark:text-foreground'
-                          : 'dark:text-muted-foreground text-gray-400'
-                      }`}
+                      data-placeholder={
+                        selectedSourceIds.size > 0 ? undefined : ''
+                      }
+                      className="w-full justify-start text-left"
                     >
-                      {sourceTriggerLabel}
+                      <span className="truncate">{sourceTriggerLabel}</span>
                     </Button>
                   }
                 />
@@ -1016,8 +1020,11 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
               </div>
               <Button
                 type="button"
+                variant="outline-primary"
+                size="field"
+                shape="pill"
                 onClick={() => setAddPromptModal('ACTIVE')}
-                className="border-primary text-primary hover:bg-primary/90 h-auto min-w-20 shrink-0 basis-full rounded-3xl border border-solid bg-transparent px-5 py-3 whitespace-nowrap hover:text-white sm:basis-auto"
+                className="min-w-20 shrink-0 basis-full sm:basis-auto"
               >
                 {t('agents.form.buttons.add')}
               </Button>
@@ -1059,20 +1066,21 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 trigger={
                   <Button
                     type="button"
-                    variant="outline"
+                    variant="combobox"
+                    size="field"
+                    shape="pill"
                     ref={toolAnchorButtonRef}
-                    className={`bg-card h-auto w-full justify-start truncate rounded-3xl px-5 py-3 text-left text-sm font-normal ${
-                      selectedTools.length > 0
-                        ? 'text-foreground dark:text-foreground'
-                        : 'dark:text-muted-foreground text-gray-400'
-                    }`}
+                    data-placeholder={selectedTools.length > 0 ? undefined : ''}
+                    className="w-full justify-start text-left"
                   >
-                    {selectedTools.length > 0
-                      ? selectedTools
-                          .map((tool) => getToolDisplayName(tool))
-                          .filter(Boolean)
-                          .join(', ')
-                      : t('agents.form.placeholders.selectTools')}
+                    <span className="truncate">
+                      {selectedTools.length > 0
+                        ? selectedTools
+                            .map((tool) => getToolDisplayName(tool))
+                            .filter(Boolean)
+                            .join(', ')
+                        : t('agents.form.placeholders.selectTools')}
+                    </span>
                   </Button>
                 }
               />
@@ -1089,10 +1097,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                   setAgent({ ...agent, agent_type: value })
                 }
               >
-                <SelectTrigger
-                  className="w-full rounded-3xl px-5 py-3 text-sm"
-                  size="lg"
-                >
+                <SelectTrigger className="w-full" shape="pill" size="lg">
                   <SelectValue
                     placeholder={t('agents.form.placeholders.selectType')}
                   />
@@ -1148,20 +1153,23 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                 trigger={
                   <Button
                     type="button"
-                    variant="outline"
+                    variant="combobox"
+                    size="field"
+                    shape="pill"
                     ref={modelAnchorButtonRef}
-                    className={`bg-card h-auto w-full justify-start truncate rounded-3xl px-5 py-3 text-left text-sm font-normal ${
-                      selectedModelIds.size > 0
-                        ? 'text-foreground dark:text-foreground'
-                        : 'dark:text-muted-foreground text-gray-400'
-                    }`}
+                    data-placeholder={
+                      selectedModelIds.size > 0 ? undefined : ''
+                    }
+                    className="w-full justify-start text-left"
                   >
-                    {selectedModelIds.size > 0
-                      ? availableModels
-                          .filter((m) => selectedModelIds.has(m.id))
-                          .map((m) => m.display_name)
-                          .join(', ')
-                      : t('agents.form.placeholders.selectModels')}
+                    <span className="truncate">
+                      {selectedModelIds.size > 0
+                        ? availableModels
+                            .filter((m) => selectedModelIds.has(m.id))
+                            .map((m) => m.display_name)
+                            .join(', ')
+                        : t('agents.form.placeholders.selectModels')}
+                    </span>
                   </Button>
                 }
               />
@@ -1176,10 +1184,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                       setAgent({ ...agent, default_model_id: value })
                     }
                   >
-                    <SelectTrigger
-                      className="w-full rounded-3xl px-5 py-3 text-sm"
-                      size="lg"
-                    >
+                    <SelectTrigger className="w-full" shape="pill" size="lg">
                       <SelectValue
                         placeholder={t(
                           'agents.form.placeholders.selectDefaultModel',
@@ -1200,49 +1205,44 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
               )}
             </div>
           </div>
-          <div className="bg-card rounded-2xl px-6 py-3">
-            <Button
-              type="button"
-              variant="ghost"
-              onClick={() =>
-                setIsAdvancedSectionExpanded(!isAdvancedSectionExpanded)
-              }
-              className="h-auto w-full justify-between px-0 py-0 text-left hover:bg-transparent"
-            >
-              <div>
-                <h2 className="text-lg font-semibold">
+          <div className="bg-card has-[[data-variant=section-toggle]:focus-visible]:ring-ring/50 rounded-2xl px-6 py-3 has-[[data-variant=section-toggle]:focus-visible]:ring-3 has-[[data-variant=section-toggle]:focus-visible]:ring-inset">
+            {/* The heading wraps the toggle: a button's children are
+                presentational, so a heading inside it is lost to screen readers. */}
+            <h2>
+              <Button
+                type="button"
+                variant="section-toggle"
+                onClick={() =>
+                  setIsAdvancedSectionExpanded(!isAdvancedSectionExpanded)
+                }
+                size="sm"
+                aria-expanded={isAdvancedSectionExpanded}
+                className="-ml-3 w-fit justify-start"
+              >
+                <ChevronRight
+                  aria-hidden="true"
+                  className={cn(
+                    'transition-transform',
+                    isAdvancedSectionExpanded && 'rotate-90',
+                  )}
+                />
+                <span className="text-lg font-semibold">
                   {t('agents.form.sections.advanced')}
-                </h2>
-              </div>
-              <div className="ml-4 flex items-center">
-                <svg
-                  className={`size-5 transform transition-transform duration-200 ${
-                    isAdvancedSectionExpanded ? 'rotate-180' : ''
-                  }`}
-                  fill="none"
-                  stroke="currentColor"
-                  viewBox="0 0 24 24"
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={2}
-                    d="M19 9l-7 7-7-7"
-                  />
-                </svg>
-              </div>
-            </Button>
+                </span>
+              </Button>
+            </h2>
             {isAdvancedSectionExpanded && (
               <div className="mt-3">
                 <div>
                   <h2 className="text-sm font-medium">
                     {t('agents.form.advanced.jsonSchema')}
                   </h2>
-                  <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+                  <p className="text-muted-foreground mt-1 text-xs">
                     {t('agents.form.advanced.jsonSchemaDescription')}
                   </p>
                 </div>
-                <textarea
+                <Textarea
+                  size="lg"
                   value={jsonSchemaText}
                   onChange={(e) => validateAndSetJsonSchema(e.target.value)}
                   placeholder={`{
@@ -1255,23 +1255,19 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
   "additionalProperties": false
 }`}
                   rows={9}
-                  className={`border-border text-foreground dark:text-foreground bg-card dark:border-border focus-visible:ring-ring/50 focus-visible:border-ring mt-2 w-full rounded-2xl border px-4 py-3 font-mono text-sm outline-hidden focus-visible:ring-[3px]`}
+                  className="mt-2 font-mono"
                 />
                 {jsonSchemaText.trim() !== '' && (
                   <div
                     className={`mt-2 flex items-center gap-2 text-sm ${
-                      jsonSchemaValid
-                        ? 'text-green-600 dark:text-green-400'
-                        : 'text-red-600 dark:text-red-400'
+                      jsonSchemaValid ? 'text-success' : 'text-destructive'
                     }`}
                   >
-                    <span
-                      className={`h-4 w-4 bg-contain bg-center bg-no-repeat ${
-                        jsonSchemaValid
-                          ? "bg-[url('/src/assets/circle-check.svg')]"
-                          : "bg-[url('/src/assets/circle-x.svg')]"
-                      }`}
-                    />
+                    {jsonSchemaValid ? (
+                      <CircleCheck className="size-4" aria-hidden="true" />
+                    ) : (
+                      <CircleX className="size-4" aria-hidden="true" />
+                    )}
                     {jsonSchemaValid
                       ? t('agents.form.advanced.validJson')
                       : t('agents.form.advanced.invalidJson')}
@@ -1284,7 +1280,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                       <h2 className="text-sm font-medium">
                         {t('agents.form.advanced.tokenLimiting')}
                       </h2>
-                      <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+                      <p className="text-muted-foreground mt-1 text-xs">
                         {t('agents.form.advanced.tokenLimitingDescription')}
                       </p>
                     </div>
@@ -1315,11 +1311,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                     }
                     disabled={!agent.limited_token_mode}
                     placeholder={t('agents.form.placeholders.enterTokenLimit')}
-                    className={`bg-card mt-2 h-auto rounded-3xl px-5 py-3 text-sm placeholder:text-gray-400 md:text-sm ${
-                      !agent.limited_token_mode
-                        ? 'cursor-not-allowed opacity-50'
-                        : ''
-                    }`}
+                    shape="pill"
+                    className="mt-2"
                   />
                 </div>
 
@@ -1329,7 +1322,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                       <h2 className="text-sm font-medium">
                         {t('agents.form.advanced.requestLimiting')}
                       </h2>
-                      <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+                      <p className="text-muted-foreground mt-1 text-xs">
                         {t('agents.form.advanced.requestLimitingDescription')}
                       </p>
                     </div>
@@ -1362,11 +1355,8 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                     placeholder={t(
                       'agents.form.placeholders.enterRequestLimit',
                     )}
-                    className={`bg-card mt-2 h-auto rounded-3xl px-5 py-3 text-sm placeholder:text-gray-400 md:text-sm ${
-                      !agent.limited_request_mode
-                        ? 'cursor-not-allowed opacity-50'
-                        : ''
-                    }`}
+                    shape="pill"
+                    className="mt-2"
                   />
                 </div>
 
@@ -1376,7 +1366,7 @@ export default function NewAgent({ mode }: { mode: 'new' | 'edit' | 'draft' }) {
                       <h2 className="text-sm font-medium">
                         {t('agents.form.advanced.systemPromptOverride')}
                       </h2>
-                      <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+                      <p className="text-muted-foreground mt-1 text-xs">
                         {t(
                           'agents.form.advanced.systemPromptOverrideDescription',
                         )}
@@ -1508,7 +1498,18 @@ function AgentPreviewArea() {
         </div>
       ) : (
         <div className="flex h-full w-full flex-col items-center justify-center gap-2">
-          <span className="block h-12 w-12 bg-[url('/src/assets/science-spark.svg')] bg-contain bg-center bg-no-repeat transition-all dark:bg-[url('/src/assets/science-spark-dark.svg')]" />{' '}
+          <img
+            src={ScienceSparkIcon}
+            alt=""
+            aria-hidden="true"
+            className="block size-12 dark:hidden"
+          />
+          <img
+            src={ScienceSparkDarkIcon}
+            alt=""
+            aria-hidden="true"
+            className="hidden size-12 dark:block"
+          />{' '}
           <p className="text-muted-foreground text-xs">
             {t('agents.form.preview.publishedPreview')}
           </p>
diff --git a/frontend/src/agents/SharedAgent.tsx b/frontend/src/agents/SharedAgent.tsx
index e6b76867..63729dbe 100644
--- a/frontend/src/agents/SharedAgent.tsx
+++ b/frontend/src/agents/SharedAgent.tsx
@@ -155,7 +155,9 @@ export default function SharedAgent() {
         <Avatar
           src={sharedAgent.image}
           alt="agent-logo"
-          imgClassName="h-6 w-6 rounded-full object-contain"
+          shape="circle"
+          className="overflow-hidden"
+          imgClassName="h-6 w-6 object-contain"
         />
         <h2 className="text-foreground text-lg font-semibold">
           {sharedAgent.name}
diff --git a/frontend/src/agents/SharedAgentCard.tsx b/frontend/src/agents/SharedAgentCard.tsx
index a7102cd7..94f8bc9e 100644
--- a/frontend/src/agents/SharedAgentCard.tsx
+++ b/frontend/src/agents/SharedAgentCard.tsx
@@ -29,8 +29,9 @@ export default function SharedAgentCard({
           <Avatar
             src={agent.image}
             alt={agent.name}
-            className="h-full w-full"
-            imgClassName="h-full w-full rounded-full object-contain"
+            shape="circle"
+            className="size-full overflow-hidden"
+            imgClassName="size-full object-contain"
           />
         </div>
         <div className="flex max-h-[92px] flex-1 flex-col gap-px">
@@ -46,8 +47,9 @@ export default function SharedAgentCard({
             type="button"
             variant="outline"
             size="sm"
+            shape="pill"
             onClick={onEdit}
-            className="shrink-0 gap-1.5 rounded-full"
+            className="shrink-0"
             aria-label={t('agents.edit')}
           >
             <img src={EditIcon} alt="" className="h-3.5 w-3.5" />
diff --git a/frontend/src/agents/components/AgentTypeModal.test.tsx b/frontend/src/agents/components/AgentTypeModal.test.tsx
new file mode 100644
index 00000000..8ffa6f2a
--- /dev/null
+++ b/frontend/src/agents/components/AgentTypeModal.test.tsx
@@ -0,0 +1,72 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+const navigate = vi.fn();
+vi.mock('react-router-dom', () => ({
+  useNavigate: () => navigate,
+}));
+
+import AgentTypeModal from './AgentTypeModal';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('AgentTypeModal', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    navigate.mockReset();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async (onClose = vi.fn()) => {
+    await act(async () => {
+      root.render(<AgentTypeModal isOpen onClose={onClose} folderId="f1" />);
+    });
+    return onClose;
+  };
+
+  const tiles = () =>
+    Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>(
+        '[data-slot="option-card"]',
+      ),
+    );
+
+  it('renders the two agent types as OptionCards', async () => {
+    await render();
+    const found = tiles();
+    expect(found).toHaveLength(2);
+    expect(found[0].textContent).toContain('Classic Agent');
+    expect(found[1].textContent).toContain('Workflow Agent');
+    expect(found[0].querySelector('[data-slot="option-card-icon"]')).not.toBe(
+      null,
+    );
+    expect(found[0].querySelector('[data-slot="card-description"]')).not.toBe(
+      null,
+    );
+  });
+
+  it('navigates to the workflow builder and closes', async () => {
+    const onClose = await render();
+    await act(async () => tiles()[1].click());
+    expect(navigate).toHaveBeenCalledTimes(1);
+    expect(String(navigate.mock.calls[0][0])).toContain('workflow');
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('navigates to the classic form and closes', async () => {
+    const onClose = await render();
+    await act(async () => tiles()[0].click());
+    expect(navigate).toHaveBeenCalledTimes(1);
+    expect(String(navigate.mock.calls[0][0])).not.toContain('workflow');
+    expect(onClose).toHaveBeenCalled();
+  });
+});
diff --git a/frontend/src/agents/components/AgentTypeModal.tsx b/frontend/src/agents/components/AgentTypeModal.tsx
index ed219b00..0472795f 100644
--- a/frontend/src/agents/components/AgentTypeModal.tsx
+++ b/frontend/src/agents/components/AgentTypeModal.tsx
@@ -3,6 +3,7 @@ import { agentNewPath } from '../paths';
 import { useNavigate } from 'react-router-dom';
 
 import { Modal } from '../../components/ui/modal';
+import { OptionCard } from '../../components/ui/option-card';
 
 interface AgentTypeModalProps {
   isOpen: boolean;
@@ -35,43 +36,18 @@ export default function AgentTypeModal({
       size="md"
     >
       <div className="flex flex-col gap-4">
-        <button
-          type="button"
+        <OptionCard
+          icon={<Bot />}
+          title="Classic Agent"
+          description="Create a standard AI agent with a single model, tools, and knowledge sources"
           onClick={() => handleSelect('normal')}
-          className="hover:border-primary hover:bg-primary/5 dark:hover:border-primary dark:hover:bg-primary/10 focus-visible:border-ring focus-visible:ring-ring/50 group dark:border-border flex items-start gap-5 rounded-xl border-2 border-gray-200 p-5 text-left transition-all outline-none focus-visible:ring-[3px]"
-        >
-          <div className="dark:bg-primary/20 bg-primary/10 text-primary group-hover:bg-primary/90 flex h-14 w-14 shrink-0 items-center justify-center rounded-xl transition-colors group-hover:text-white dark:text-purple-300">
-            <Bot size={28} />
-          </div>
-          <div className="flex-1">
-            <h3 className="text-foreground dark:text-foreground mb-2 text-lg font-semibold">
-              Classic Agent
-            </h3>
-            <p className="text-sm leading-relaxed text-gray-600 dark:text-gray-400">
-              Create a standard AI agent with a single model, tools, and
-              knowledge sources
-            </p>
-          </div>
-        </button>
-
-        <button
-          type="button"
+        />
+        <OptionCard
+          icon={<Workflow />}
+          title="Workflow Agent"
+          description="Design complex multi-step workflows with different models, conditional logic, and state management"
           onClick={() => handleSelect('workflow')}
-          className="hover:border-primary hover:bg-primary/5 dark:hover:border-primary dark:hover:bg-primary/10 focus-visible:border-ring focus-visible:ring-ring/50 group dark:border-border flex items-start gap-5 rounded-xl border-2 border-gray-200 p-5 text-left transition-all outline-none focus-visible:ring-[3px]"
-        >
-          <div className="dark:bg-primary/20 bg-primary/10 text-primary group-hover:bg-primary flex h-14 w-14 shrink-0 items-center justify-center rounded-xl transition-colors group-hover:text-white dark:text-purple-300">
-            <Workflow size={28} />
-          </div>
-          <div className="flex-1">
-            <h3 className="text-foreground dark:text-foreground mb-2 text-lg font-semibold">
-              Workflow Agent
-            </h3>
-            <p className="text-sm leading-relaxed text-gray-600 dark:text-gray-400">
-              Design complex multi-step workflows with different models,
-              conditional logic, and state management
-            </p>
-          </div>
-        </button>
+        />
       </div>
     </Modal>
   );
diff --git a/frontend/src/agents/components/GuardrailEvents.test.tsx b/frontend/src/agents/components/GuardrailEvents.test.tsx
new file mode 100644
index 00000000..5bb4b6fb
--- /dev/null
+++ b/frontend/src/agents/components/GuardrailEvents.test.tsx
@@ -0,0 +1,92 @@
+import { configureStore } from '@reduxjs/toolkit';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { Provider } from 'react-redux';
+
+// A stable `t`: the component lists it as an effect dependency.
+vi.mock('react-i18next', () => {
+  const t = (key: string) => key;
+  return { useTranslation: () => ({ t }) };
+});
+
+const events = [
+  { id: '1', action: 'block', outcome: 'triggered' },
+  { id: '2', action: 'redact', outcome: 'triggered' },
+  { id: '3', action: 'flag', outcome: 'triggered' },
+  { id: '4', action: 'flag', outcome: 'not_evaluated' },
+].map((e) => ({
+  ...e,
+  check_name: `check-${e.id}`,
+  stage: 'input',
+  category: null,
+  detail: '',
+  created_at: '2026-09-01T00:00:00Z',
+}));
+
+vi.mock('../../api/services/userService', () => ({
+  default: {
+    getGuardrailEvents: () =>
+      Promise.resolve({
+        json: () => Promise.resolve({ success: true, events }),
+      }),
+    getGuardrailSummary: () =>
+      Promise.resolve({
+        json: () =>
+          Promise.resolve({
+            success: true,
+            breakdown: [],
+            totals: { blocked: 1, redacted: 1, flagged: 1, not_evaluated: 1 },
+          }),
+      }),
+  },
+}));
+
+import GuardrailEvents from './GuardrailEvents';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const makeStore = () =>
+  configureStore({ reducer: { preference: () => ({ token: null }) } });
+
+describe('GuardrailEvents tones', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(async () => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    await act(async () => {
+      root.render(
+        <Provider store={makeStore()}>
+          <GuardrailEvents agentId="a1" />
+        </Provider>,
+      );
+    });
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it('colours outcome badges by meaning', () => {
+    const variants = Array.from(
+      container.querySelectorAll(
+        '[data-testid="guardrail-events-rows"] [data-slot="badge"]',
+      ),
+    ).map((b) => b.getAttribute('data-variant'));
+    expect(variants).toEqual(['destructive', 'info', 'warning', 'neutral']);
+  });
+
+  it('colours the stat tiles to match', () => {
+    const tone = (id: string) =>
+      container.querySelector(`[data-testid="${id}"] p:last-child`)?.className;
+    expect(tone('guardrail-stat-blocked')).toContain('text-destructive');
+    expect(tone('guardrail-stat-redacted')).toContain('text-info');
+    expect(tone('guardrail-stat-flagged')).toContain('text-warning');
+    expect(tone('guardrail-stat-not-evaluated')).toContain(
+      'text-muted-foreground',
+    );
+  });
+});
diff --git a/frontend/src/agents/components/GuardrailEvents.tsx b/frontend/src/agents/components/GuardrailEvents.tsx
index da9ec9ea..ef43929a 100644
--- a/frontend/src/agents/components/GuardrailEvents.tsx
+++ b/frontend/src/agents/components/GuardrailEvents.tsx
@@ -9,6 +9,9 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
+import { Badge } from '@/components/ui/badge';
+import { Progress } from '@/components/ui/progress';
+import { cn } from '@/lib/utils';
 
 import userService from '../../api/services/userService';
 import SkeletonLoader from '../../components/SkeletonLoader';
@@ -32,15 +35,18 @@ const ACTION_KEYS: Record<string, string> = {
   block: 'agents.form.guardrails.actions.block',
 };
 
-/** Colour by consequence, so "we refused" reads differently from "we noticed". */
-function actionTone(action: string, outcome: string): string {
-  if (outcome === 'not_evaluated')
-    return 'bg-gray-100 text-gray-700 dark:bg-gray-800 dark:text-gray-300';
-  if (action === 'block')
-    return 'bg-red-100 text-red-800 dark:bg-red-900/40 dark:text-red-300';
-  if (action === 'redact')
-    return 'bg-amber-100 text-amber-800 dark:bg-amber-900/40 dark:text-amber-300';
-  return 'bg-emerald-100 text-emerald-800 dark:bg-emerald-900/40 dark:text-emerald-300';
+/**
+ * Colour by meaning, matching the status tokens used across the app: a block
+ * is a refusal, a flag needs review, a redaction is informational.
+ */
+function actionTone(
+  action: string,
+  outcome: string,
+): 'neutral' | 'destructive' | 'warning' | 'info' {
+  if (outcome === 'not_evaluated') return 'neutral';
+  if (action === 'block') return 'destructive';
+  if (action === 'redact') return 'info';
+  return 'warning';
 }
 
 type Props = { agentId?: string };
@@ -122,8 +128,9 @@ export default function GuardrailEvents({ agentId }: Props) {
           onValueChange={(value) => setDays(Number(value))}
         >
           <SelectTrigger
-            className="w-[150px] rounded-3xl px-5 py-3 text-sm"
+            className="w-[150px]"
             size="lg"
+            shape="pill"
             data-testid="guardrail-events-window"
           >
             <SelectValue />
@@ -148,21 +155,21 @@ export default function GuardrailEvents({ agentId }: Props) {
           value={totals?.blocked}
           loading={loading}
           testId="guardrail-stat-blocked"
-          tone="text-red-700 dark:text-red-400"
+          tone="text-destructive"
         />
         <StatTile
           label={t('agents.guardrailEvents.redacted')}
           value={totals?.redacted}
           loading={loading}
           testId="guardrail-stat-redacted"
-          tone="text-amber-700 dark:text-amber-400"
+          tone="text-info"
         />
         <StatTile
           label={t('agents.guardrailEvents.flagged')}
           value={totals?.flagged}
           loading={loading}
           testId="guardrail-stat-flagged"
-          tone="text-emerald-700 dark:text-emerald-400"
+          tone="text-warning"
         />
         <StatTile
           label={t('agents.guardrailEvents.notEvaluated')}
@@ -179,8 +186,9 @@ export default function GuardrailEvents({ agentId }: Props) {
       <div className="mt-6 flex flex-wrap items-center gap-3">
         <Select value={checkFilter} onValueChange={setCheckFilter}>
           <SelectTrigger
-            className="w-[170px] rounded-3xl px-5 py-3 text-sm"
+            className="w-[170px]"
             size="lg"
+            shape="pill"
             data-testid="guardrail-events-check-filter"
           >
             <SelectValue />
@@ -198,8 +206,9 @@ export default function GuardrailEvents({ agentId }: Props) {
         </Select>
         <Select value={outcomeFilter} onValueChange={setOutcomeFilter}>
           <SelectTrigger
-            className="w-[170px] rounded-3xl px-5 py-3 text-sm"
+            className="w-[170px]"
             size="lg"
+            shape="pill"
             data-testid="guardrail-events-outcome-filter"
           >
             <SelectValue />
@@ -288,16 +297,11 @@ export default function GuardrailEvents({ agentId }: Props) {
                       {t(STAGE_KEYS[event.stage] ?? event.stage)}
                     </td>
                     <td className="px-3 py-2">
-                      <span
-                        className={`rounded-full px-2 py-0.5 text-[11px] font-medium ${actionTone(
-                          event.action,
-                          event.outcome,
-                        )}`}
-                      >
+                      <Badge variant={actionTone(event.action, event.outcome)}>
                         {event.outcome === 'not_evaluated'
                           ? t('agents.guardrailEvents.notEvaluated')
                           : t(ACTION_KEYS[event.action] ?? event.action)}
-                      </span>
+                      </Badge>
                     </td>
                     <td className="text-muted-foreground max-w-[28rem] px-3 py-2">
                       {event.detail || '—'}
@@ -345,7 +349,7 @@ function StatTile({
           <SkeletonLoader count={1} />
         </div>
       ) : (
-        <p className={`mt-1 text-xl font-semibold ${tone}`}>{value ?? 0}</p>
+        <p className={cn('mt-1 text-xl font-semibold', tone)}>{value ?? 0}</p>
       )}
     </div>
   );
@@ -381,12 +385,10 @@ function ByCheck({ summary }: { summary: GuardrailSummary }) {
         {rows.map(([check, total]) => (
           <div key={check} className="flex items-center gap-3">
             <span className="w-32 shrink-0 truncate text-xs">{check}</span>
-            <div className="bg-border/60 h-2 flex-1 overflow-hidden rounded-full">
-              <div
-                className="bg-violets-are-blue h-full rounded-full"
-                style={{ width: `${max ? (total / max) * 100 : 0}%` }}
-              />
-            </div>
+            <Progress
+              className="flex-1"
+              value={max ? (total / max) * 100 : 0}
+            />
             <span className="text-muted-foreground w-10 shrink-0 text-right text-xs">
               {total}
             </span>
diff --git a/frontend/src/agents/components/GuardrailsSection.test.tsx b/frontend/src/agents/components/GuardrailsSection.test.tsx
new file mode 100644
index 00000000..e1e79f57
--- /dev/null
+++ b/frontend/src/agents/components/GuardrailsSection.test.tsx
@@ -0,0 +1,275 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+import type { GuardrailCatalog, GuardrailsConfig } from '../types';
+
+const getGuardrailCatalog = vi.fn();
+vi.mock('../../api/services/userService', () => ({
+  default: {
+    getGuardrailCatalog: (...args: unknown[]) => getGuardrailCatalog(...args),
+  },
+}));
+
+// A stable `t`: the component refetches the catalog whenever `t` changes.
+const t = (key: string) => key;
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t }),
+}));
+
+import GuardrailsSection from './GuardrailsSection';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const catalog: GuardrailCatalog = {
+  enabled: false,
+  checks: [
+    {
+      name: 'pii',
+      label: 'PII',
+      description: 'Detects personal data',
+      stages: ['input', 'output'],
+      supports_redaction: true,
+      latency_hint_ms: 50,
+      remote: false,
+      available: false,
+    },
+    {
+      name: 'policy',
+      label: 'Policy',
+      description: 'LLM judge',
+      stages: ['input'],
+      supports_redaction: false,
+      latency_hint_ms: 1500,
+      remote: true,
+      available: true,
+    },
+  ],
+  stages: ['input', 'output'],
+  modes: ['monitor_only', 'scan_all'],
+  actions_by_stage: {
+    input: ['flag', 'block'],
+    retrieval: ['flag'],
+    tool_result: ['flag'],
+    output: ['flag', 'redact', 'block'],
+  },
+  default_block_message: 'No',
+  pii_entities: ['EMAIL', 'PHONE'],
+  default_pii_entities: ['EMAIL'],
+  floor: {
+    enabled: true,
+    mode: 'scan_all',
+    fail_open: true,
+    timeout_ms: 2000,
+    block_message: '',
+    controls: [
+      {
+        check: 'pii',
+        stage: 'output',
+        action: 'block',
+        enabled: true,
+        settings: {},
+      },
+    ],
+  },
+};
+
+const config: GuardrailsConfig = {
+  enabled: true,
+  mode: 'monitor_only',
+  fail_open: true,
+  timeout_ms: 2000,
+  block_message: 'Sorry',
+  controls: [
+    {
+      check: 'pii',
+      stage: 'input',
+      action: 'flag',
+      enabled: true,
+      settings: { entities: ['EMAIL'] },
+    },
+    {
+      check: 'policy',
+      stage: 'input',
+      action: 'flag',
+      enabled: true,
+      settings: { policy: '' },
+    },
+    {
+      check: 'gone',
+      stage: 'input',
+      action: 'flag',
+      enabled: true,
+      settings: {},
+    },
+  ],
+};
+
+describe('GuardrailsSection', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    getGuardrailCatalog.mockReset();
+    getGuardrailCatalog.mockResolvedValue({
+      json: async () => ({ success: true, ...catalog }),
+    });
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const q = (testId: string) =>
+    container.querySelector<HTMLElement>(`[data-testid="${testId}"]`);
+
+  const render = async (
+    props: Partial<Parameters<typeof GuardrailsSection>[0]> = {},
+  ) => {
+    await act(async () => {
+      root.render(
+        <GuardrailsSection
+          value={config}
+          onChange={() => undefined}
+          token="tok"
+          disabledNotice="Read only"
+          {...props}
+        />,
+      );
+    });
+    await act(async () => {
+      q('guardrails-toggle')?.click();
+    });
+  };
+
+  it('announces whether the section is open with aria-expanded', async () => {
+    await render();
+    expect(q('guardrails-toggle')?.getAttribute('aria-expanded')).toBe('true');
+    await act(async () => {
+      q('guardrails-toggle')?.click();
+    });
+    expect(q('guardrails-toggle')?.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  // Decision 64: the header is a section-toggle with a leading lucide
+  // chevron; the badges sit beside it and the panel draws the focus ring.
+  it('renders the header as a section-toggle with the badges beside it', async () => {
+    await render();
+    const toggle = q('guardrails-toggle')!;
+    expect(toggle.dataset.variant).toBe('section-toggle');
+    expect(toggle.dataset.size).toBe('sm');
+    expect(toggle.getAttribute('aria-expanded')).toBe('true');
+    const chevron = toggle.firstElementChild!;
+    expect(chevron.matches('svg.lucide-chevron-right')).toBe(true);
+    expect(chevron.getAttribute('class')).toContain('rotate-90');
+    expect(toggle.querySelectorAll('svg')).toHaveLength(1);
+    // The heading wraps the button (a button's children are presentational,
+    // so a heading inside it would be lost to screen readers).
+    expect(toggle.querySelector('h2')).toBeNull();
+    const heading = toggle.closest('h2')!;
+    expect(heading.textContent).toBe('agents.form.sections.guardrails');
+
+    const active = q('guardrails-active-badge')!;
+    const incomplete = q('guardrails-incomplete-badge')!;
+    expect(toggle.contains(active)).toBe(false);
+    expect(toggle.contains(incomplete)).toBe(false);
+    expect(active.parentElement).toBe(heading.parentElement);
+    expect(heading.parentElement?.firstElementChild).toBe(heading);
+
+    const panel = q('guardrails-section')!;
+    expect(panel.contains(toggle)).toBe(true);
+    expect(panel.className).toContain(
+      'has-[[data-variant=section-toggle]:focus-visible]:ring-3',
+    );
+    expect(panel.className).toContain('bg-card');
+
+    await act(async () => toggle.click());
+    expect(toggle.getAttribute('aria-expanded')).toBe('false');
+    expect(chevron.getAttribute('class')).not.toContain('rotate-90');
+  });
+
+  it('renders the header pills as badges in their status roles', async () => {
+    await render();
+    expect(q('guardrails-active-badge')?.dataset.slot).toBe('badge');
+    expect(q('guardrails-active-badge')?.dataset.variant).toBe('success');
+    expect(q('guardrails-incomplete-badge')?.dataset.variant).toBe(
+      'destructive',
+    );
+    expect(q('guardrail-latency-pii')?.dataset.variant).toBe('neutral');
+    expect(q('guardrail-latency-pii')?.title).toBe(
+      'agents.form.guardrails.latencyHint',
+    );
+  });
+
+  it('shows the section notices as polite or warning alerts', async () => {
+    await render({ disabled: true });
+    const readOnly = q('guardrails-read-only');
+    expect(readOnly?.getAttribute('role')).toBe('status');
+    expect(readOnly?.textContent).toContain('Read only');
+    const instance = q('guardrails-instance-disabled');
+    expect(instance?.getAttribute('role')).toBe('alert');
+    expect(instance?.className).toContain('text-warning');
+    const floor = Array.from(
+      container.querySelectorAll<HTMLElement>('[role]'),
+    ).find((el) =>
+      el.textContent?.includes('agents.form.guardrails.floorNotice'),
+    );
+    expect(floor?.getAttribute('role')).toBe('status');
+    expect(floor?.className).toContain('text-info');
+  });
+
+  it('uses the pressed-toggle variants for stage chips', async () => {
+    await render();
+    expect(q('guardrail-stage-pii-input')?.dataset.variant).toBe('secondary');
+    const locked = q('guardrail-stage-pii-output');
+    expect(locked?.dataset.variant).toBe('secondary');
+    expect((locked as HTMLButtonElement).disabled).toBe(true);
+    expect(locked?.title).toBe('agents.form.guardrails.lockedByFloor');
+    expect(q('guardrail-stage-policy-input')?.dataset.variant).toBe(
+      'secondary',
+    );
+  });
+
+  it('renders remove actions as ghost-destructive xs buttons', async () => {
+    await render();
+    const remove = q('guardrail-remove-pii-input');
+    expect(remove?.dataset.variant).toBe('ghost-destructive');
+    expect(remove?.dataset.size).toBe('xs');
+    const orphan = q('guardrail-orphan-gone')?.querySelector('button');
+    expect(orphan?.dataset.variant).toBe('ghost-destructive');
+    expect(orphan?.dataset.size).toBe('xs');
+  });
+
+  // Decision 63 (3): the form's fields and selects are all 42px.
+  it('sizes the fields through Input and Textarea props', async () => {
+    await render();
+    const block = q('guardrails-block-message');
+    expect(block?.dataset.size).toBe('default');
+    expect(block?.dataset.shape).toBe('pill');
+    expect(block?.className).not.toContain('bg-card');
+    const timeout = q('guardrails-timeout');
+    expect(timeout?.dataset.variant).toBe('filled');
+    expect(timeout?.dataset.size).toBe('default');
+    expect(timeout?.dataset.shape).toBe('pill');
+    const mode = q('guardrails-mode');
+    expect(mode?.dataset.size).toBe('lg');
+    expect(mode?.dataset.shape).toBe('pill');
+
+    await act(async () => {
+      q('guardrail-configure-policy-input')?.click();
+    });
+    expect(q('guardrail-policy-text')?.dataset.slot).toBe('textarea');
+  });
+
+  it('shows PII entities as toggle chips', async () => {
+    await render();
+    await act(async () => {
+      q('guardrail-configure-pii-input')?.click();
+    });
+    expect(q('guardrail-pii-EMAIL')?.dataset.variant).toBe('secondary');
+    expect(q('guardrail-pii-PHONE')?.dataset.variant).toBe('ghost-muted');
+  });
+});
diff --git a/frontend/src/agents/components/GuardrailsSection.tsx b/frontend/src/agents/components/GuardrailsSection.tsx
index 1ead4ff3..574c70e9 100644
--- a/frontend/src/agents/components/GuardrailsSection.tsx
+++ b/frontend/src/agents/components/GuardrailsSection.tsx
@@ -1,6 +1,9 @@
 import React from 'react';
+import { ChevronRight, Info, Lock, TriangleAlert } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import {
@@ -11,6 +14,8 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { cn } from '@/lib/utils';
 
 import userService from '../../api/services/userService';
 import {
@@ -202,59 +207,49 @@ export default function GuardrailsSection({
 
   return (
     <div
-      className="bg-card rounded-2xl px-6 py-3"
+      className="bg-card has-[[data-variant=section-toggle]:focus-visible]:ring-ring/50 rounded-2xl px-6 py-3 has-[[data-variant=section-toggle]:focus-visible]:ring-3 has-[[data-variant=section-toggle]:focus-visible]:ring-inset"
       data-testid="guardrails-section"
     >
-      <Button
-        type="button"
-        variant="ghost"
-        onClick={() => setExpanded(!expanded)}
-        className="h-auto w-full justify-between px-0 py-0 text-left hover:bg-transparent"
-        data-testid="guardrails-toggle"
-      >
-        <div className="flex flex-wrap items-center gap-3">
-          <h2 className="text-lg font-semibold">
-            {t('agents.form.sections.guardrails')}
-          </h2>
-          {config.enabled && (
-            <span
-              className="rounded-full bg-emerald-100 px-2 py-0.5 text-xs font-medium text-emerald-800 dark:bg-emerald-900/40 dark:text-emerald-300"
-              data-testid="guardrails-active-badge"
-            >
-              {t('agents.form.guardrails.activeCount', {
-                count: config.controls.length + floorControls.size,
-              })}
-            </span>
-          )}
-          {incompleteCount > 0 && (
-            <span
-              className="bg-destructive/10 text-destructive rounded-full px-2 py-0.5 text-xs font-medium"
-              data-testid="guardrails-incomplete-badge"
-            >
-              {t('agents.form.guardrails.needsSetup', {
-                count: incompleteCount,
-              })}
-            </span>
-          )}
-        </div>
-        <div className="ml-4 flex items-center">
-          <svg
-            className={`size-5 transform transition-transform duration-200 ${
-              expanded ? 'rotate-180' : ''
-            }`}
-            fill="none"
-            stroke="currentColor"
-            viewBox="0 0 24 24"
+      <div className="flex flex-wrap items-center gap-2">
+        {/* The heading wraps the toggle: a button's children are
+            presentational, so a heading inside it is lost to screen readers. */}
+        <h2>
+          <Button
+            type="button"
+            variant="section-toggle"
+            size="sm"
+            onClick={() => setExpanded(!expanded)}
+            aria-expanded={expanded}
+            className="-ml-3 w-fit justify-start"
+            data-testid="guardrails-toggle"
           >
-            <path
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              strokeWidth={2}
-              d="M19 9l-7 7-7-7"
+            <ChevronRight
+              aria-hidden="true"
+              className={cn('transition-transform', expanded && 'rotate-90')}
             />
-          </svg>
-        </div>
-      </Button>
+            <span className="text-lg font-semibold">
+              {t('agents.form.sections.guardrails')}
+            </span>
+          </Button>
+        </h2>
+        {config.enabled && (
+          <Badge variant="success" data-testid="guardrails-active-badge">
+            {t('agents.form.guardrails.activeCount', {
+              count: config.controls.length + floorControls.size,
+            })}
+          </Badge>
+        )}
+        {incompleteCount > 0 && (
+          <Badge
+            variant="destructive"
+            data-testid="guardrails-incomplete-badge"
+          >
+            {t('agents.form.guardrails.needsSetup', {
+              count: incompleteCount,
+            })}
+          </Badge>
+        )}
+      </div>
 
       {expanded && (
         <div className="mt-3 pb-3">
@@ -263,29 +258,38 @@ export default function GuardrailsSection({
           )}
 
           {disabled && disabledNotice && (
-            <p
-              className="mt-3 rounded-lg bg-gray-100 px-3 py-2 text-xs text-gray-700 dark:bg-gray-800 dark:text-gray-300"
+            <Alert
+              role="status"
+              className="mt-3"
               data-testid="guardrails-read-only"
             >
-              {disabledNotice}
-            </p>
+              <Lock aria-hidden="true" className="size-4" />
+              <AlertDescription>{disabledNotice}</AlertDescription>
+            </Alert>
           )}
 
           {instanceDisabled && (
-            <p
-              className="mt-3 rounded-lg bg-amber-50 px-3 py-2 text-xs text-amber-800 dark:bg-amber-900/30 dark:text-amber-300"
+            <Alert
+              variant="warning"
+              className="mt-3"
               data-testid="guardrails-instance-disabled"
             >
-              {t('agents.form.guardrails.instanceDisabled')}
-            </p>
+              <TriangleAlert aria-hidden="true" className="size-4" />
+              <AlertDescription>
+                {t('agents.form.guardrails.instanceDisabled')}
+              </AlertDescription>
+            </Alert>
           )}
 
           {floorControls.size > 0 && (
-            <p className="mt-3 rounded-lg bg-blue-50 px-3 py-2 text-xs text-blue-800 dark:bg-blue-900/30 dark:text-blue-300">
-              {t('agents.form.guardrails.floorNotice', {
-                count: floorControls.size,
-              })}
-            </p>
+            <Alert variant="info" role="status" className="mt-3">
+              <Info aria-hidden="true" className="size-4" />
+              <AlertDescription>
+                {t('agents.form.guardrails.floorNotice', {
+                  count: floorControls.size,
+                })}
+              </AlertDescription>
+            </Alert>
           )}
 
           <div className="mt-4 flex items-center justify-between gap-4">
@@ -293,7 +297,7 @@ export default function GuardrailsSection({
               <h3 className="text-sm font-medium">
                 {t('agents.form.guardrails.enable')}
               </h3>
-              <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+              <p className="text-muted-foreground mt-1 text-xs">
                 {t('agents.form.guardrails.enableDescription')}
               </p>
             </div>
@@ -320,8 +324,9 @@ export default function GuardrailsSection({
                   disabled={disabled}
                 >
                   <SelectTrigger
-                    className="w-full rounded-3xl px-5 py-3 text-sm"
+                    className="w-full"
                     size="lg"
+                    shape="pill"
                     data-testid="guardrails-mode"
                   >
                     <SelectValue />
@@ -335,7 +340,7 @@ export default function GuardrailsSection({
                   </SelectContent>
                 </Select>
                 {config.mode === 'monitor_only' && (
-                  <p className="mt-2 text-xs text-amber-700 dark:text-amber-400">
+                  <p className="text-warning mt-2 text-xs">
                     {t('agents.form.guardrails.monitorHint')}
                   </p>
                 )}
@@ -375,10 +380,9 @@ export default function GuardrailsSection({
                       </p>
                       <Button
                         type="button"
-                        variant="ghost"
-                        size="sm"
+                        variant="ghost-destructive"
+                        size="xs"
                         disabled={disabled}
-                        className="text-destructive h-auto px-2 py-1 text-xs"
                         onClick={() =>
                           removeControl(control.check, control.stage)
                         }
@@ -401,9 +405,9 @@ export default function GuardrailsSection({
                   disabled={disabled}
                   data-testid="guardrails-block-message"
                   onChange={(e) => patch({ block_message: e.target.value })}
-                  className="bg-card h-auto rounded-3xl px-5 py-3 text-sm md:text-sm"
+                  shape="pill"
                 />
-                <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+                <p className="text-muted-foreground mt-1 text-xs">
                   {t('agents.form.guardrails.blockMessageDescription')}
                 </p>
               </div>
@@ -413,7 +417,7 @@ export default function GuardrailsSection({
                   <h3 className="text-sm font-medium">
                     {t('agents.form.guardrails.failOpen')}
                   </h3>
-                  <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
+                  <p className="text-muted-foreground mt-1 text-xs">
                     {t('agents.form.guardrails.failOpenDescription')}
                   </p>
                 </div>
@@ -494,7 +498,8 @@ function NumberField({
         setDraft(String(next));
         onCommit(next);
       }}
-      className="bg-card h-auto rounded-3xl px-5 py-3 text-sm md:text-sm"
+      variant="filled"
+      shape="pill"
     />
   );
 }
@@ -566,28 +571,26 @@ function CheckCard({
 
   return (
     <div
-      className="rounded-xl border border-gray-200 px-4 py-3 dark:border-gray-700"
+      className="border-border rounded-xl border px-4 py-3"
       data-testid={`guardrail-check-${info.name}`}
     >
       <div className="min-w-0 flex-1">
         <div className="flex flex-wrap items-center gap-2">
           <h4 className="text-sm font-medium">{info.label}</h4>
-          <span
-            className="rounded-full bg-gray-100 px-2 py-0.5 text-[11px] font-medium text-gray-700 dark:bg-gray-800 dark:text-gray-300"
+          <Badge
+            variant="neutral"
             title={t('agents.form.guardrails.latencyHint')}
             data-testid={`guardrail-latency-${info.name}`}
           >
             {latencyLabel(info.latency_hint_ms)}
-          </span>
+          </Badge>
           {unavailable && (
-            <span className="rounded-full bg-amber-100 px-2 py-0.5 text-[11px] font-medium text-amber-800 dark:bg-amber-900/40 dark:text-amber-300">
+            <Badge variant="warning">
               {t('agents.form.guardrails.notConfigured')}
-            </span>
+            </Badge>
           )}
         </div>
-        <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
-          {info.description}
-        </p>
+        <p className="text-muted-foreground mt-1 text-xs">{info.description}</p>
       </div>
 
       <div className="mt-3 flex flex-wrap gap-2">
@@ -602,25 +605,36 @@ function CheckCard({
           // out a credential strands a control that can never be cleared.
           const canToggle =
             !disabled && !locked && (Boolean(control) || !unavailable);
-          return (
-            <button
+          const chip = (
+            <Button
               key={stage}
               type="button"
+              variant={on ? 'secondary' : 'ghost-muted'}
+              size="xs"
+              shape="pill"
               disabled={!canToggle}
               data-testid={`guardrail-stage-${info.name}-${stage}`}
               onClick={() => toggleControl(info, stage, !control)}
-              className={`rounded-full border px-3 py-1 text-xs transition-colors ${
-                on
-                  ? 'border-violets-are-blue bg-violets-are-blue/10 text-violets-are-blue'
-                  : 'border-gray-300 text-gray-600 dark:border-gray-600 dark:text-gray-400'
-              } ${!canToggle ? 'cursor-not-allowed opacity-60' : ''}`}
               title={
                 locked ? t('agents.form.guardrails.lockedByFloor') : undefined
               }
             >
               {t(STAGE_KEYS[stage] ?? stage)}
               {locked ? ' 🔒' : ''}
-            </button>
+            </Button>
+          );
+          // A disabled Button takes no pointer events, so the locked chip's
+          // hint lives on a wrapper that can still be hovered.
+          return locked ? (
+            <span
+              key={stage}
+              className="inline-flex"
+              title={t('agents.form.guardrails.lockedByFloor')}
+            >
+              {chip}
+            </span>
+          ) : (
+            chip
           );
         })}
       </div>
@@ -628,7 +642,7 @@ function CheckCard({
       {floorForCheck.map(([k, action]) => (
         <div
           key={`floor-${k}`}
-          className="mt-3 rounded-lg bg-blue-50 px-3 py-2 text-xs text-blue-800 dark:bg-blue-900/30 dark:text-blue-300"
+          className="bg-info/10 text-info mt-3 rounded-lg px-3 py-2 text-xs"
           data-testid={`guardrail-floor-${k}`}
         >
           {t('agents.form.guardrails.floorControl', {
@@ -644,11 +658,12 @@ function CheckCard({
         return (
           <div
             key={panelKey}
-            className={`mt-3 rounded-lg px-3 py-2 ${
+            className={cn(
+              'mt-3 rounded-lg px-3 py-2',
               needsSetup
                 ? 'border-destructive/50 bg-destructive/5 border'
-                : 'bg-gray-50 dark:bg-gray-900/40'
-            }`}
+                : 'bg-muted',
+            )}
           >
             <div className="flex flex-wrap items-center justify-between gap-2">
               <span className="text-xs font-medium">
@@ -665,7 +680,8 @@ function CheckCard({
                   }
                 >
                   <SelectTrigger
-                    className="h-auto rounded-full px-3 py-1 text-xs"
+                    size="sm"
+                    shape="pill"
                     data-testid={`guardrail-action-${control.check}-${control.stage}`}
                   >
                     <SelectValue />
@@ -687,8 +703,7 @@ function CheckCard({
                   <Button
                     type="button"
                     variant="ghost"
-                    size="sm"
-                    className="h-auto px-2 py-1 text-xs"
+                    size="xs"
                     data-testid={`guardrail-configure-${control.check}-${control.stage}`}
                     onClick={() =>
                       setOpenSettings(
@@ -701,10 +716,9 @@ function CheckCard({
                 )}
                 <Button
                   type="button"
-                  variant="ghost"
-                  size="sm"
+                  variant="ghost-destructive"
+                  size="xs"
                   disabled={disabled}
-                  className="text-destructive h-auto px-2 py-1 text-xs"
                   data-testid={`guardrail-remove-${control.check}-${control.stage}`}
                   onClick={() => removeControl(control.check, control.stage)}
                 >
@@ -759,8 +773,9 @@ function CheckSettings({
   const listField = (fieldKey: string, label: string, placeholder: string) => (
     <div className="mt-2">
       <label className="mb-1 block text-xs font-medium">{label}</label>
-      <textarea
+      <Textarea
         rows={2}
+        size="sm"
         disabled={disabled}
         data-testid={`guardrail-setting-${control.check}-${fieldKey}`}
         value={(s[fieldKey] ?? []).join('\n')}
@@ -773,21 +788,24 @@ function CheckSettings({
               .filter(Boolean),
           })
         }
-        className="bg-card w-full rounded-xl border border-gray-200 px-3 py-2 text-xs dark:border-gray-700"
+        variant="filled"
       />
     </div>
   );
 
   return (
-    <div className="mt-3 border-t border-gray-200 pt-3 dark:border-gray-700">
+    <div className="border-border mt-3 border-t pt-3">
       {control.check === 'pii' && (
         <div className="flex flex-wrap gap-2">
           {(catalog?.pii_entities ?? []).map((entity) => {
             const on = (s.entities ?? []).includes(entity);
             return (
-              <button
+              <Button
                 key={entity}
                 type="button"
+                variant={on ? 'secondary' : 'ghost-muted'}
+                size="xs"
+                shape="pill"
                 disabled={disabled}
                 data-testid={`guardrail-pii-${entity}`}
                 onClick={() =>
@@ -797,14 +815,9 @@ function CheckSettings({
                       : [...(s.entities ?? []), entity],
                   })
                 }
-                className={`rounded-full border px-2 py-0.5 text-[11px] ${
-                  on
-                    ? 'border-violets-are-blue bg-violets-are-blue/10 text-violets-are-blue'
-                    : 'border-gray-300 text-gray-600 dark:border-gray-600 dark:text-gray-400'
-                }`}
               >
                 {entity}
-              </button>
+              </Button>
             );
           })}
           {(s.entities ?? []).length === 0 && (
@@ -842,13 +855,14 @@ function CheckSettings({
           <label className="mb-1 block text-xs font-medium">
             {t('agents.form.guardrails.policyText')}
           </label>
-          <textarea
+          <Textarea
             rows={4}
+            size="sm"
             value={s.policy ?? ''}
             disabled={disabled}
             data-testid="guardrail-policy-text"
             onChange={(e) => set({ policy: e.target.value })}
-            className="bg-card w-full rounded-xl border border-gray-200 px-3 py-2 text-xs dark:border-gray-700"
+            variant="filled"
           />
         </div>
       )}
@@ -900,7 +914,7 @@ function CheckSettings({
             disabled={disabled}
             onCommit={(confidence_threshold) => set({ confidence_threshold })}
           />
-          <p className="mt-1 text-[11px] text-gray-500">
+          <p className="text-muted-foreground mt-1 text-xs">
             {t('agents.form.guardrails.confidenceHint')}
           </p>
         </div>
diff --git a/frontend/src/agents/schedules/RunDetailDrawer.tsx b/frontend/src/agents/schedules/RunDetailDrawer.tsx
index 4c1359bd..1413c6d2 100644
--- a/frontend/src/agents/schedules/RunDetailDrawer.tsx
+++ b/frontend/src/agents/schedules/RunDetailDrawer.tsx
@@ -43,13 +43,7 @@ export default function RunDetailDrawer({
       >
         <div className="mb-4 flex items-center justify-between">
           <h2 className="text-lg font-semibold">Run details</h2>
-          <Button
-            type="button"
-            variant="outline"
-            size="sm"
-            onClick={onClose}
-            className="text-muted-foreground"
-          >
+          <Button type="button" variant="outline" size="sm" onClick={onClose}>
             Close
           </Button>
         </div>
diff --git a/frontend/src/agents/schedules/RunLog.tsx b/frontend/src/agents/schedules/RunLog.tsx
index 83b0913c..0a95badb 100644
--- a/frontend/src/agents/schedules/RunLog.tsx
+++ b/frontend/src/agents/schedules/RunLog.tsx
@@ -71,9 +71,9 @@ export default function RunLog({ scheduleId, onSelect }: RunLogProps) {
                 <Button
                   type="button"
                   variant="link"
-                  size="sm"
+                  size="xs"
                   onClick={() => onSelect(run)}
-                  className="h-auto p-0 text-xs underline"
+                  className="-mx-2 -my-1"
                 >
                   Details
                 </Button>
diff --git a/frontend/src/agents/schedules/ScheduleFormModal.tsx b/frontend/src/agents/schedules/ScheduleFormModal.tsx
index d94d224d..f14493a7 100644
--- a/frontend/src/agents/schedules/ScheduleFormModal.tsx
+++ b/frontend/src/agents/schedules/ScheduleFormModal.tsx
@@ -17,7 +17,6 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { TimePicker } from '@/components/ui/time-picker';
-import { cn } from '@/lib/utils';
 
 import { Modal } from '../../components/ui/modal';
 import { formatDateOnly } from '../../utils/dateTimeUtils';
@@ -195,7 +194,7 @@ export default function ScheduleFormModal({
       }
       size="md"
       mobileVariant="sheet"
-      className="w-[min(560px,92vw)] sm:p-6"
+      className="w-[min(560px,92vw)]"
       contentClassName="max-h-[80vh]"
     >
       <div className="flex flex-col gap-5">
@@ -273,7 +272,7 @@ export default function ScheduleFormModal({
             type="button"
             disabled={submitting}
             onClick={submit}
-            className="rounded-3xl px-5"
+            shape="pill"
           >
             {submitting
               ? '…'
@@ -302,15 +301,11 @@ function FrequencyTabs({ frequency, onChange, labels }: FrequencyTabsProps) {
           <Button
             key={f}
             type="button"
-            variant="ghost"
-            size="sm"
+            variant={active ? 'outline' : 'ghost-muted'}
+            size="xs"
+            shape="pill"
             onClick={() => onChange(f)}
-            className={cn(
-              'h-auto flex-1 rounded-full px-3 py-1.5 text-xs font-medium',
-              active
-                ? 'bg-card text-foreground hover:bg-card shadow-sm'
-                : 'text-muted-foreground hover:text-foreground hover:bg-transparent',
-            )}
+            className="flex-1"
             aria-pressed={active}
           >
             {labels[f]}
@@ -380,7 +375,7 @@ function OnPicker({ values, onChange, tDay, tMonth, labels }: OnPickerProps) {
                   size="sm"
                   variant={active ? 'default' : 'outline'}
                   onClick={() => set({ dayOfWeek: d.value })}
-                  className="rounded-full"
+                  shape="pill"
                   aria-pressed={active}
                 >
                   {tDay(d.key)}
@@ -464,13 +459,11 @@ function DatePicker({ value, onChange, placeholder }: DatePickerProps) {
       <PopoverTrigger asChild>
         <Button
           type="button"
-          variant="outline"
+          variant="combobox"
           size="sm"
           aria-label={placeholder}
-          className={cn(
-            'h-9 justify-start gap-2 px-3 font-normal',
-            !value && 'text-muted-foreground',
-          )}
+          data-placeholder={value ? undefined : ''}
+          className="h-9 justify-start"
         >
           <CalendarIcon className="size-4 opacity-70" />
           {value ? formatDateLabel(value) : placeholder}
diff --git a/frontend/src/agents/schedules/SchedulerToolCallCard.tsx b/frontend/src/agents/schedules/SchedulerToolCallCard.tsx
index bbfc616b..45d13dd9 100644
--- a/frontend/src/agents/schedules/SchedulerToolCallCard.tsx
+++ b/frontend/src/agents/schedules/SchedulerToolCallCard.tsx
@@ -161,10 +161,10 @@ export default function SchedulerToolCallCard({
       {taskId && !cancelled && (
         <Button
           type="button"
-          variant="outline"
-          size="sm"
+          variant="destructive-outline"
+          size="xs"
           onClick={cancel}
-          className="text-destructive mt-2 text-xs"
+          className="mt-2"
         >
           Cancel
         </Button>
diff --git a/frontend/src/agents/schedules/SchedulesView.tsx b/frontend/src/agents/schedules/SchedulesView.tsx
index e10cea5d..00723f5f 100644
--- a/frontend/src/agents/schedules/SchedulesView.tsx
+++ b/frontend/src/agents/schedules/SchedulesView.tsx
@@ -214,15 +214,18 @@ export default function SchedulesView() {
                           <div className="flex gap-2">
                             <Button
                               type="button"
+                              variant="outline-primary"
                               size="sm"
+                              shape="pill"
                               onClick={() => openEdit(schedule)}
-                              className="border-primary text-primary hover:bg-primary/90 rounded-full border border-solid bg-transparent px-5 hover:text-white"
                             >
                               {t('agents.schedules.edit')}
                             </Button>
                             <Button
                               type="button"
+                              variant="outline-primary"
                               size="sm"
+                              shape="pill"
                               onClick={() =>
                                 dispatch(
                                   setSchedulePaused({
@@ -235,7 +238,6 @@ export default function SchedulesView() {
                                   }),
                                 )
                               }
-                              className="border-primary text-primary hover:bg-primary/90 rounded-full border border-solid bg-transparent px-5 hover:text-white"
                             >
                               {schedule.status === 'active'
                                 ? t('agents.schedules.pause')
@@ -243,13 +245,14 @@ export default function SchedulesView() {
                             </Button>
                             <Button
                               type="button"
+                              variant="outline-primary"
                               size="sm"
+                              shape="pill"
                               onClick={() =>
                                 dispatch(
                                   runScheduleNow({ id: schedule.id, token }),
                                 )
                               }
-                              className="border-primary text-primary hover:bg-primary/90 rounded-full border border-solid bg-transparent px-5 hover:text-white"
                             >
                               {t('agents.schedules.runNow')}
                             </Button>
@@ -257,8 +260,8 @@ export default function SchedulesView() {
                               type="button"
                               variant="destructive-outline"
                               size="sm"
+                              shape="pill"
                               onClick={() => requestDelete(schedule)}
-                              className="rounded-full px-5"
                             >
                               {t('agents.schedules.delete')}
                             </Button>
@@ -267,13 +270,13 @@ export default function SchedulesView() {
                         <Button
                           type="button"
                           variant="link"
-                          size="sm"
+                          size="xs"
                           onClick={() =>
                             setExpanded(
                               expanded === schedule.id ? null : schedule.id,
                             )
                           }
-                          className="mt-2 h-auto p-0 text-xs underline"
+                          className="mt-0.5 -ml-2"
                         >
                           {expanded === schedule.id
                             ? t('agents.schedules.hideRuns')
@@ -324,9 +327,10 @@ export default function SchedulesView() {
                             {schedule.status === 'active' && (
                               <Button
                                 type="button"
+                                variant="outline-primary"
                                 size="sm"
+                                shape="pill"
                                 onClick={() => openEdit(schedule)}
-                                className="border-primary text-primary hover:bg-primary/90 rounded-full border border-solid bg-transparent px-5 hover:text-white"
                               >
                                 {t('agents.schedules.edit')}
                               </Button>
@@ -336,8 +340,8 @@ export default function SchedulesView() {
                                 type="button"
                                 variant="destructive-outline"
                                 size="sm"
+                                shape="pill"
                                 onClick={() => requestDelete(schedule)}
-                                className="rounded-full px-5"
                               >
                                 {t('agents.schedules.cancel')}
                               </Button>
diff --git a/frontend/src/agents/schedules/StatusBadge.test.tsx b/frontend/src/agents/schedules/StatusBadge.test.tsx
index 69c5385a..3a6552ff 100644
--- a/frontend/src/agents/schedules/StatusBadge.test.tsx
+++ b/frontend/src/agents/schedules/StatusBadge.test.tsx
@@ -3,14 +3,14 @@ import { describe, expect, it } from 'vitest';
 
 import ScheduleStatusBadge, {
   formatStatusLabel,
-  getStatusClasses,
+  getStatusVariant,
   type ScheduleStatusBadgeStatus,
 } from './StatusBadge';
 
 type Case = {
   status: ScheduleStatusBadgeStatus;
   label: string;
-  classes: string[];
+  variant: string;
 };
 
 const CASES: Case[] = [
@@ -18,68 +18,67 @@ const CASES: Case[] = [
   {
     status: 'active',
     label: 'Active',
-    classes: ['bg-green-100', 'text-green-700'],
+    variant: 'success',
   },
   {
     status: 'paused',
     label: 'Paused',
-    classes: ['bg-amber-100', 'text-amber-700'],
+    variant: 'warning',
   },
   {
     status: 'completed',
     label: 'Completed',
-    classes: ['bg-blue-100', 'text-blue-700'],
+    variant: 'success',
   },
   {
     status: 'cancelled',
     label: 'Cancelled',
-    classes: ['bg-muted', 'text-muted-foreground'],
+    variant: 'neutral',
   },
   // Run statuses
   {
     status: 'success',
     label: 'Success',
-    classes: ['bg-green-100', 'text-green-700'],
+    variant: 'success',
   },
   {
     status: 'failed',
     label: 'Failed',
-    classes: ['bg-red-100', 'text-red-700'],
+    variant: 'destructive',
   },
   {
     status: 'skipped',
     label: 'Skipped',
-    classes: ['bg-amber-100', 'text-amber-700'],
+    variant: 'warning',
   },
   {
     status: 'running',
     label: 'Running',
-    classes: ['bg-blue-100', 'text-blue-700'],
+    variant: 'info',
   },
   {
     status: 'pending',
     label: 'Pending',
-    classes: ['bg-muted', 'text-muted-foreground'],
+    variant: 'neutral',
   },
   {
     status: 'timeout',
     label: 'Timeout',
-    classes: ['bg-red-100', 'text-red-700'],
+    variant: 'destructive',
   },
 ];
 
 describe('ScheduleStatusBadge', () => {
   it.each(CASES)(
-    'renders $status with label "$label" and the right color classes',
-    ({ status, label, classes }) => {
+    'renders $status with label "$label" as a $variant badge',
+    ({ status, label, variant }) => {
       const html = renderToStaticMarkup(
         <ScheduleStatusBadge status={status} />,
       );
       expect(html).toContain(label);
       expect(html).toContain(`data-status="${status}"`);
-      for (const cls of classes) {
-        expect(html).toContain(cls);
-      }
+      expect(html).toContain('data-slot="badge"');
+      expect(html).toContain(`data-variant="${variant}"`);
     },
   );
 
@@ -101,9 +100,9 @@ describe('formatStatusLabel', () => {
   });
 });
 
-describe('getStatusClasses', () => {
-  it('returns muted classes for an unknown status', () => {
+describe('getStatusVariant', () => {
+  it('returns neutral for an unknown status', () => {
     // @ts-expect-error -- exercising the runtime fallback for unknown values
-    expect(getStatusClasses('unknown')).toContain('text-muted-foreground');
+    expect(getStatusVariant('unknown')).toBe('neutral');
   });
 });
diff --git a/frontend/src/agents/schedules/StatusBadge.tsx b/frontend/src/agents/schedules/StatusBadge.tsx
index c753411d..eaeb2bc1 100644
--- a/frontend/src/agents/schedules/StatusBadge.tsx
+++ b/frontend/src/agents/schedules/StatusBadge.tsx
@@ -1,4 +1,4 @@
-import { cn } from '@/lib/utils';
+import { Badge } from '@/components/ui/badge';
 
 import type { ScheduleRunStatus, ScheduleStatus } from '../types/schedule';
 
@@ -9,23 +9,21 @@ export type ScheduleStatusBadgeProps = {
   className?: string;
 };
 
-const STATUS_CLASSES: Record<ScheduleStatusBadgeStatus, string> = {
+type StatusVariant = 'success' | 'warning' | 'info' | 'destructive' | 'neutral';
+
+const STATUS_VARIANTS: Record<ScheduleStatusBadgeStatus, StatusVariant> = {
   // Schedule statuses
-  active:
-    'bg-green-100 text-green-700 dark:bg-green-900/40 dark:text-green-300',
-  paused:
-    'bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-300',
-  completed: 'bg-blue-100 text-blue-700 dark:bg-blue-900/40 dark:text-blue-300',
-  cancelled: 'bg-muted text-muted-foreground',
+  active: 'success',
+  paused: 'warning',
+  completed: 'success',
+  cancelled: 'neutral',
   // Run statuses
-  success:
-    'bg-green-100 text-green-700 dark:bg-green-900/40 dark:text-green-300',
-  failed: 'bg-red-100 text-red-700 dark:bg-red-900/40 dark:text-red-300',
-  skipped:
-    'bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-300',
-  running: 'bg-blue-100 text-blue-700 dark:bg-blue-900/40 dark:text-blue-300',
-  pending: 'bg-muted text-muted-foreground',
-  timeout: 'bg-red-100 text-red-700 dark:bg-red-900/40 dark:text-red-300',
+  success: 'success',
+  failed: 'destructive',
+  skipped: 'warning',
+  running: 'info',
+  pending: 'neutral',
+  timeout: 'destructive',
 };
 
 /** Maps a status string to a human label (sentence-cased, underscores spaced). */
@@ -34,9 +32,10 @@ export const formatStatusLabel = (status: string): string => {
   return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 };
 
-/** Returns the Tailwind classes for a given schedule/run status pill. */
-export const getStatusClasses = (status: ScheduleStatusBadgeStatus): string =>
-  STATUS_CLASSES[status] ?? 'bg-muted text-muted-foreground';
+/** Returns the Badge variant for a given schedule/run status. */
+export const getStatusVariant = (
+  status: ScheduleStatusBadgeStatus,
+): StatusVariant => STATUS_VARIANTS[status] ?? 'neutral';
 
 /** Colored pill for schedule or run statuses. */
 export default function ScheduleStatusBadge({
@@ -44,15 +43,12 @@ export default function ScheduleStatusBadge({
   className,
 }: ScheduleStatusBadgeProps) {
   return (
-    <span
-      className={cn(
-        'inline-flex items-center rounded-full px-2 py-0.5 text-xs leading-[16px] font-medium',
-        getStatusClasses(status),
-        className,
-      )}
+    <Badge
+      variant={getStatusVariant(status)}
+      className={className}
       data-status={status}
     >
       {formatStatusLabel(status)}
-    </span>
+    </Badge>
   );
 }
diff --git a/frontend/src/agents/schedules/TimezoneCombobox.tsx b/frontend/src/agents/schedules/TimezoneCombobox.tsx
index 4950df11..9f81d0fa 100644
--- a/frontend/src/agents/schedules/TimezoneCombobox.tsx
+++ b/frontend/src/agents/schedules/TimezoneCombobox.tsx
@@ -125,16 +125,12 @@ export default function TimezoneCombobox({
       <PopoverTrigger asChild>
         <Button
           type="button"
-          variant="outline"
+          variant="combobox"
           role="combobox"
-          size="sm"
           aria-expanded={open}
           aria-label={ariaLabel}
-          className={cn(
-            'h-9 w-full justify-between gap-2 px-3 font-normal',
-            !value && 'text-muted-foreground',
-            className,
-          )}
+          data-placeholder={value ? undefined : ''}
+          className={cn('w-full justify-between', className)}
         >
           {value ? (
             <span className="flex min-w-0 flex-1 items-center justify-between gap-3">
diff --git a/frontend/src/agents/workflow/WorkflowBuilder.tsx b/frontend/src/agents/workflow/WorkflowBuilder.tsx
index a31bbf50..e22969b7 100644
--- a/frontend/src/agents/workflow/WorkflowBuilder.tsx
+++ b/frontend/src/agents/workflow/WorkflowBuilder.tsx
@@ -53,6 +53,8 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { Sheet, SheetContent } from '@/components/ui/sheet';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
 
 import modelService from '../../api/services/modelService';
 import userService from '../../api/services/userService';
@@ -1557,8 +1559,8 @@ function WorkflowBuilderInner() {
               <Button
                 type="button"
                 variant="outline"
+                shape="pill"
                 onClick={navigateBackToAgents}
-                className="text-muted-foreground rounded-full px-4 py-2 text-sm font-normal shadow-none"
               >
                 {t('agents.backToAll')}
               </Button>
@@ -1566,7 +1568,7 @@ function WorkflowBuilderInner() {
             {!canManageAgent && (
               <div className="min-w-0">
                 <div
-                  className="max-w-xs truncate text-xl font-bold text-gray-900 dark:text-white"
+                  className="text-foreground max-w-xs truncate text-xl font-bold"
                   title={workflowName || 'New Workflow'}
                 >
                   {workflowName || 'New Workflow'}
@@ -1584,10 +1586,9 @@ function WorkflowBuilderInner() {
             <div className="relative flex items-center">
               <Button
                 type="button"
-                variant="ghost"
-                size="icon-sm"
+                variant="ghost-muted"
+                size="icon-xs"
                 onClick={() => setShowWorkflowSettings(!showWorkflowSettings)}
-                className="text-muted-foreground hover:bg-accent hover:text-foreground size-auto p-1"
                 aria-label="Edit workflow details"
                 title={
                   workflowDescription
@@ -1603,31 +1604,29 @@ function WorkflowBuilderInner() {
                   className="border-border bg-card absolute top-full left-0 z-50 mt-2 w-80 rounded-xl border p-4 shadow-lg"
                 >
                   <div className="mb-3">
-                    <label className="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <label className="text-foreground mb-1 block text-sm font-medium">
                       Workflow Name
                     </label>
                     <Input
                       type="text"
                       value={workflowName}
                       onChange={(e) => setWorkflowName(e.target.value)}
-                      className="bg-card h-auto rounded-lg px-3 py-2 text-sm shadow-none"
                       placeholder="Enter workflow name"
                     />
                   </div>
                   <div className="mb-3">
-                    <label className="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <label className="text-foreground mb-1 block text-sm font-medium">
                       Description
                     </label>
-                    <textarea
+                    <Textarea
                       value={workflowDescription}
                       onChange={(e) => setWorkflowDescription(e.target.value)}
-                      className="focus-visible:ring-ring/50 focus-visible:border-ring border-border bg-card w-full rounded-lg border px-3 py-2 text-sm outline-none focus-visible:ring-2 dark:text-white"
                       rows={3}
                       placeholder="Describe what this workflow does"
                     />
                   </div>
                   <div className="mb-3">
-                    <label className="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                    <label className="text-foreground mb-1 block text-sm font-medium">
                       Agent Image
                     </label>
                     {currentAgentImage && !imageFile && (
@@ -1637,7 +1636,7 @@ function WorkflowBuilderInner() {
                           alt="Agent image"
                           className="h-10 w-10 rounded-full object-cover"
                         />
-                        <span className="text-xs text-gray-500 dark:text-gray-400">
+                        <span className="text-muted-foreground text-xs">
                           Current image
                         </span>
                       </div>
@@ -1646,19 +1645,18 @@ function WorkflowBuilderInner() {
                       showPreview
                       maxFiles={1}
                       previewSize={56}
+                      size="compact"
                       onUpload={handleUpload}
                       onRemove={() => setImageFile(null)}
                       uploadText={[
                         {
                           text: 'Click to upload',
-                          colorClass: 'text-primary',
+                          highlight: true,
                         },
                         {
                           text: ' or drag and drop',
-                          colorClass: 'text-muted-foreground',
                         },
                       ]}
-                      className="border-border rounded-lg border-2 border-dashed p-3 text-center transition-colors"
                     />
                     <p className="text-muted-foreground mt-1 text-xs">
                       Image updates are included the next time you save.
@@ -1667,44 +1665,38 @@ function WorkflowBuilderInner() {
                   <div className="mb-3">
                     <div className="flex items-center justify-between">
                       <div>
-                        <label className="block text-sm font-medium text-gray-700 dark:text-gray-300">
+                        <label
+                          htmlFor="workflow-system-prompt-override"
+                          className="text-foreground block text-sm font-medium"
+                        >
                           {t('agents.form.advanced.systemPromptOverride')}
                         </label>
-                        <p className="mt-0.5 text-xs text-gray-500 dark:text-gray-400">
+                        <p className="text-muted-foreground mt-0.5 text-xs">
                           {t(
                             'agents.form.advanced.systemPromptOverrideDescription',
                           )}
                         </p>
                       </div>
-                      <button
-                        onClick={() =>
+                      <Switch
+                        id="workflow-system-prompt-override"
+                        checked={Boolean(
+                          currentAgent.allow_system_prompt_override,
+                        )}
+                        onCheckedChange={() =>
                           setCurrentAgent((prev) => ({
                             ...prev,
                             allow_system_prompt_override:
                               !prev.allow_system_prompt_override,
                           }))
                         }
-                        className={`relative h-6 w-11 shrink-0 rounded-full transition-colors ${
-                          currentAgent.allow_system_prompt_override
-                            ? 'bg-primary'
-                            : 'bg-gray-300 dark:bg-gray-600'
-                        }`}
-                      >
-                        <span
-                          className={`absolute top-0.5 h-5 w-5 transform rounded-full bg-white transition-transform ${
-                            currentAgent.allow_system_prompt_override
-                              ? ''
-                              : '-translate-x-5'
-                          }`}
-                        />
-                      </button>
+                      />
                     </div>
                   </div>
                   <Button
                     type="button"
                     onClick={handleWorkflowSettingsDone}
                     disabled={isPublishing}
-                    className="w-full rounded-lg text-white"
+                    className="w-full"
                   >
                     Done
                   </Button>
@@ -1717,8 +1709,8 @@ function WorkflowBuilderInner() {
               <Button
                 type="button"
                 variant="outline"
+                shape="pill"
                 onClick={() => setAgentDetails('ACTIVE')}
-                className="rounded-full px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200"
               >
                 <Link size={16} />
                 Access Details
@@ -1728,9 +1720,9 @@ function WorkflowBuilderInner() {
               <Button
                 type="button"
                 variant="destructive-outline"
+                shape="pill"
                 onClick={() => setDeleteConfirmation('ACTIVE')}
                 disabled={isDeletingAgent}
-                className="bg-card rounded-full border-red-200 px-4 py-2 text-sm font-medium text-red-600 hover:bg-red-50 hover:text-red-600 dark:border-red-900/30 dark:text-red-400 dark:hover:bg-red-900/10 dark:hover:text-red-400"
               >
                 <Trash2 size={16} />
                 {isDeletingAgent ? 'Deleting...' : 'Delete'}
@@ -1739,6 +1731,7 @@ function WorkflowBuilderInner() {
             <Button
               type="button"
               variant="outline"
+              shape="pill"
               onClick={() => {
                 const validationErrors = validateWorkflow();
                 if (validationErrors.length > 0) {
@@ -1748,7 +1741,6 @@ function WorkflowBuilderInner() {
                 }
                 setShowPreview(true);
               }}
-              className="rounded-full px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200"
             >
               <Play size={16} />
               Preview
@@ -1757,11 +1749,9 @@ function WorkflowBuilderInner() {
               type="button"
               onClick={handlePrimaryAction}
               disabled={isPrimaryActionDisabled}
-              className={`relative rounded-full px-6 py-2 text-sm font-medium shadow-sm ${
-                canManageAgent && !hasSavableChanges
-                  ? 'dark:bg-accent bg-gray-200 text-gray-500 hover:bg-gray-200 dark:text-gray-400'
-                  : 'text-white'
-              }`}
+              size="lg"
+              shape="pill"
+              className="relative"
             >
               <span
                 className={
@@ -1779,42 +1769,43 @@ function WorkflowBuilderInner() {
 
         {publishErrors.length > 0 && (
           <div className="pointer-events-none absolute top-20 right-0 left-0 z-50 flex justify-center px-4">
-            <Alert
-              variant="destructive"
-              className="pointer-events-auto w-full max-w-md bg-red-50 shadow-lg dark:bg-red-950/20"
-            >
-              <AlertCircle className="h-4 w-4" />
-              <AlertTitle>
-                {errorContext === 'preview'
-                  ? 'Unable to preview workflow'
-                  : canManageAgent
-                    ? 'Unable to save workflow'
-                    : 'Unable to publish workflow'}
-              </AlertTitle>
-              <AlertDescription>
-                <ul className="mt-2 list-inside list-disc space-y-1 wrap-break-word">
-                  {publishErrors.map((error, index) => (
-                    <li key={index}>{error}</li>
-                  ))}
-                </ul>
-              </AlertDescription>
-              <Button
-                type="button"
-                variant="ghost"
-                size="icon-sm"
-                onClick={() => setPublishErrors([])}
-                className="absolute top-4 right-4 size-auto p-0 text-red-700 hover:bg-transparent hover:text-red-900 dark:text-red-300 dark:hover:bg-transparent dark:hover:text-red-100"
-              >
-                <X size={16} />
-              </Button>
-            </Alert>
+            <div className="bg-card pointer-events-auto w-full max-w-md rounded-lg shadow-lg">
+              <Alert variant="destructive">
+                <AlertCircle className="h-4 w-4" />
+                <AlertTitle>
+                  {errorContext === 'preview'
+                    ? 'Unable to preview workflow'
+                    : canManageAgent
+                      ? 'Unable to save workflow'
+                      : 'Unable to publish workflow'}
+                </AlertTitle>
+                <AlertDescription>
+                  <ul className="mt-2 list-inside list-disc space-y-1 wrap-break-word">
+                    {publishErrors.map((error, index) => (
+                      <li key={index}>{error}</li>
+                    ))}
+                  </ul>
+                </AlertDescription>
+                <div className="absolute top-2.5 right-2.5">
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-xs"
+                    onClick={() => setPublishErrors([])}
+                    aria-label={t('agents.close')}
+                  >
+                    <X size={16} aria-hidden />
+                  </Button>
+                </div>
+              </Alert>
+            </div>
           </div>
         )}
 
         <div className="flex flex-1 overflow-hidden">
           <div className="border-border bg-muted dark:bg-background flex w-64 flex-col gap-6 border-r p-4">
             <div>
-              <h3 className="mb-3 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400">
+              <h3 className="text-muted-foreground mb-3 text-xs font-semibold tracking-wider uppercase">
                 Core Nodes
               </h3>
               <div className="flex flex-col gap-2">
@@ -1823,10 +1814,10 @@ function WorkflowBuilderInner() {
                   draggable
                   onDragStart={(e) => handleNodeDragStart(e, 'agent')}
                 >
-                  <div className="text-primary group-hover:bg-primary flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-purple-100 transition-colors group-hover:text-white dark:bg-purple-900/40">
+                  <div className="bg-primary/10 text-primary group-hover:bg-primary group-hover:text-primary-foreground flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors">
                     <Bot size={18} />
                   </div>
-                  <span className="text-sm font-medium text-gray-700 dark:text-gray-200">
+                  <span className="text-foreground text-sm font-medium">
                     AI Agent
                   </span>
                 </div>
@@ -1835,10 +1826,10 @@ function WorkflowBuilderInner() {
                   draggable
                   onDragStart={(e) => handleNodeDragStart(e, 'end')}
                 >
-                  <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-green-100 text-green-600 transition-colors group-hover:bg-green-600 group-hover:text-white dark:bg-green-900/40 dark:text-green-300">
+                  <div className="bg-success/10 text-success group-hover:bg-success group-hover:text-success-foreground flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors">
                     <Flag size={18} />
                   </div>
-                  <span className="text-sm font-medium text-gray-700 dark:text-gray-200">
+                  <span className="text-foreground text-sm font-medium">
                     End
                   </span>
                 </div>
@@ -1847,10 +1838,10 @@ function WorkflowBuilderInner() {
                   draggable
                   onDragStart={(e) => handleNodeDragStart(e, 'note')}
                 >
-                  <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-yellow-100 text-yellow-600 transition-colors group-hover:bg-yellow-500 group-hover:text-white dark:bg-yellow-900/40 dark:text-yellow-300">
+                  <div className="bg-warning/10 text-warning group-hover:bg-warning group-hover:text-warning-foreground flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors">
                     <StickyNote size={18} />
                   </div>
-                  <span className="text-sm font-medium text-gray-700 dark:text-gray-200">
+                  <span className="text-foreground text-sm font-medium">
                     Note
                   </span>
                 </div>
@@ -1858,7 +1849,7 @@ function WorkflowBuilderInner() {
             </div>
 
             <div>
-              <h3 className="mb-3 text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400">
+              <h3 className="text-muted-foreground mb-3 text-xs font-semibold tracking-wider uppercase">
                 Logic & Data
               </h3>
               <div className="flex flex-col gap-2">
@@ -1867,7 +1858,7 @@ function WorkflowBuilderInner() {
                   draggable
                   onDragStart={(e) => handleNodeDragStart(e, 'state')}
                 >
-                  <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-blue-100 text-blue-600 transition-colors group-hover:bg-blue-600 group-hover:text-white dark:bg-blue-900/40 dark:text-blue-300">
+                  <div className="bg-info/10 text-info group-hover:bg-info group-hover:text-info-foreground flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors">
                     <Database size={18} />
                   </div>
                   <div className="flex flex-col">
@@ -1884,7 +1875,7 @@ function WorkflowBuilderInner() {
                   draggable
                   onDragStart={(e) => handleNodeDragStart(e, 'condition')}
                 >
-                  <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-orange-100 text-orange-600 transition-colors group-hover:bg-orange-600 group-hover:text-white dark:bg-orange-900/40 dark:text-orange-300">
+                  <div className="bg-warning/10 text-warning group-hover:bg-warning group-hover:text-warning-foreground flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors">
                     <GitBranch size={18} />
                   </div>
                   <div className="flex flex-col">
@@ -1901,7 +1892,7 @@ function WorkflowBuilderInner() {
                   draggable
                   onDragStart={(e) => handleNodeDragStart(e, 'code')}
                 >
-                  <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-indigo-100 text-indigo-600 transition-colors group-hover:bg-indigo-600 group-hover:text-white dark:bg-indigo-900/40 dark:text-indigo-300">
+                  <div className="bg-info/10 text-info group-hover:bg-info group-hover:text-info-foreground flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors">
                     <Code2 size={18} />
                   </div>
                   <div className="flex flex-col">
@@ -1950,7 +1941,6 @@ function WorkflowBuilderInner() {
                   disabled={!canUndo}
                   title="Undo (Ctrl+Z)"
                   aria-label="Undo"
-                  className="bg-card"
                 >
                   <Undo2 size={16} />
                 </Button>
@@ -1962,7 +1952,6 @@ function WorkflowBuilderInner() {
                   disabled={!canRedo}
                   title="Redo (Ctrl+Shift+Z)"
                   aria-label="Redo"
-                  className="bg-card"
                 >
                   <Redo2 size={16} />
                 </Button>
@@ -1973,7 +1962,7 @@ function WorkflowBuilderInner() {
               <>
                 <div className="border-border bg-card shadow-modal absolute top-4 right-4 z-20 w-96 rounded-2xl border">
                   <div className="border-border flex items-center justify-between border-b p-4">
-                    <h3 className="font-semibold text-gray-900 dark:text-white">
+                    <h3 className="text-foreground font-semibold">
                       {selectedNode.type === 'start' && 'Start Node'}
                       {selectedNode.type === 'end' && 'End Node'}
                       {selectedNode.type === 'agent' && 'AI Agent'}
@@ -1984,22 +1973,21 @@ function WorkflowBuilderInner() {
                     </h3>
                     <Button
                       type="button"
-                      variant="ghost"
-                      size="icon-sm"
+                      variant="ghost-muted"
+                      size="icon-xs"
                       onClick={() => setShowNodeConfig(false)}
-                      className="size-auto p-0 text-gray-400 hover:bg-transparent hover:text-gray-600 dark:hover:bg-transparent dark:hover:text-gray-200 [&_svg:not([class*='size-'])]:size-5"
                     >
-                      <X size={20} />
+                      <X size={20} className="size-5" />
                     </Button>
                   </div>
 
                   <div className="max-h-[calc(100vh-200px)] overflow-y-auto p-4">
                     <div className="mb-4 flex flex-col gap-2">
                       <div className="bg-muted rounded-lg p-3">
-                        <div className="mb-1 text-xs text-gray-500 dark:text-gray-400">
+                        <div className="text-muted-foreground mb-1 text-xs">
                           Node ID
                         </div>
-                        <div className="truncate font-mono text-xs text-gray-700 dark:text-gray-300">
+                        <div className="text-foreground truncate font-mono text-xs">
                           {selectedNode.id}
                         </div>
                       </div>
@@ -2008,7 +1996,7 @@ function WorkflowBuilderInner() {
                         selectedNode.type !== 'end' && (
                           <>
                             <div>
-                              <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                              <label className="text-foreground mb-2 block text-sm font-medium">
                                 Title
                               </label>
                               <Input
@@ -2024,7 +2012,6 @@ function WorkflowBuilderInner() {
                                     label: e.target.value,
                                   })
                                 }
-                                className="bg-card h-auto rounded-xl px-3 py-2 text-sm shadow-none"
                                 placeholder="Enter node title"
                               />
                             </div>
@@ -2032,7 +2019,7 @@ function WorkflowBuilderInner() {
                             {selectedNode.type === 'agent' && (
                               <>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Agent Type
                                   </label>
                                   <Select
@@ -2049,7 +2036,7 @@ function WorkflowBuilderInner() {
                                       })
                                     }
                                   >
-                                    <SelectTrigger className="w-full">
+                                    <SelectTrigger size="lg" className="w-full">
                                       <SelectValue placeholder="Select agent type" />
                                     </SelectTrigger>
                                     <SelectContent>
@@ -2063,7 +2050,7 @@ function WorkflowBuilderInner() {
                                   </Select>
                                 </div>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Model
                                   </label>
                                   <Select
@@ -2085,7 +2072,7 @@ function WorkflowBuilderInner() {
                                       });
                                     }}
                                   >
-                                    <SelectTrigger className="w-full">
+                                    <SelectTrigger size="lg" className="w-full">
                                       <SelectValue placeholder="Select a model" />
                                     </SelectTrigger>
                                     <SelectContent>
@@ -2141,10 +2128,10 @@ function WorkflowBuilderInner() {
                                   </Select>
                                 </div>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     System Prompt
                                   </label>
-                                  <textarea
+                                  <Textarea
                                     value={
                                       selectedNode.data.config?.system_prompt ??
                                       ''
@@ -2157,7 +2144,6 @@ function WorkflowBuilderInner() {
                                         },
                                       })
                                     }
-                                    className="border-border focus-visible:ring-ring/50 focus-visible:border-ring bg-card w-full rounded-xl border px-3 py-2 text-sm transition-all outline-none focus-visible:ring-2 dark:text-white"
                                     rows={3}
                                     placeholder="System prompt for the agent"
                                   />
@@ -2182,7 +2168,7 @@ function WorkflowBuilderInner() {
                                   placeholder="Use {{ agent.variable }} for dynamic content"
                                 />
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Output Variable
                                   </label>
                                   <Input
@@ -2200,7 +2186,6 @@ function WorkflowBuilderInner() {
                                         },
                                       });
                                     }}
-                                    className="bg-card h-auto rounded-xl px-3 py-2 text-sm shadow-none"
                                     placeholder="Variable name for output"
                                   />
                                 </div>
@@ -2224,13 +2209,13 @@ function WorkflowBuilderInner() {
                                   />
                                   <label
                                     htmlFor="stream_to_user"
-                                    className="text-sm text-gray-700 dark:text-gray-300"
+                                    className="text-foreground text-sm"
                                   >
                                     Stream output to user
                                   </label>
                                 </div>{' '}
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Tools
                                   </label>
                                   <MultiSelect
@@ -2255,7 +2240,7 @@ function WorkflowBuilderInner() {
                                   />
                                 </div>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Sources
                                   </label>
                                   <MultiSelect
@@ -2295,7 +2280,7 @@ function WorkflowBuilderInner() {
                                   helpText="Documents passed to this agent from uploads or upstream nodes."
                                 />
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     File passing
                                   </label>
                                   <Select
@@ -2311,7 +2296,7 @@ function WorkflowBuilderInner() {
                                       })
                                     }
                                   >
-                                    <SelectTrigger className="w-full">
+                                    <SelectTrigger size="lg" className="w-full">
                                       <SelectValue />
                                     </SelectTrigger>
                                     <SelectContent>
@@ -2331,23 +2316,23 @@ function WorkflowBuilderInner() {
                                   </p>
                                 </div>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Structured Output (JSON Schema)
                                   </label>
                                   {!selectedAgentModelSupportsStructuredOutput && (
-                                    <p className="mb-2 text-xs text-red-600 dark:text-red-400">
+                                    <p className="text-destructive mb-2 text-xs">
                                       Selected model does not support structured
                                       output.
                                     </p>
                                   )}
-                                  <textarea
+                                  <Textarea
                                     value={selectedAgentJsonSchemaText}
                                     onChange={(e) =>
                                       handleAgentJsonSchemaChange(
                                         e.target.value,
                                       )
                                     }
-                                    className="border-border focus-visible:ring-ring/50 focus-visible:border-ring bg-card w-full rounded-xl border px-3 py-2 font-mono text-xs transition-all outline-none focus-visible:ring-2 dark:text-white"
+                                    className="font-mono"
                                     rows={8}
                                     placeholder={`{
   "type": "object",
@@ -2362,8 +2347,8 @@ function WorkflowBuilderInner() {
                                     <p
                                       className={`mt-2 text-xs ${
                                         selectedAgentJsonSchemaError
-                                          ? 'text-red-600 dark:text-red-400'
-                                          : 'text-green-600 dark:text-green-400'
+                                          ? 'text-destructive'
+                                          : 'text-success'
                                       }`}
                                     >
                                       {selectedAgentJsonSchemaError
@@ -2377,17 +2362,16 @@ function WorkflowBuilderInner() {
 
                             {selectedNode.type === 'note' && (
                               <div>
-                                <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                <label className="text-foreground mb-2 block text-sm font-medium">
                                   Note Content
                                 </label>
-                                <textarea
+                                <Textarea
                                   value={selectedNode.data.content || ''}
                                   onChange={(e) =>
                                     handleUpdateNodeData({
                                       content: e.target.value,
                                     })
                                   }
-                                  className="border-border focus-visible:ring-ring/50 focus-visible:border-ring bg-card w-full rounded-xl border px-3 py-2 text-sm transition-all outline-none focus-visible:ring-2 dark:text-white"
                                   rows={4}
                                   placeholder="Enter note content"
                                 />
@@ -2396,7 +2380,7 @@ function WorkflowBuilderInner() {
 
                             {selectedNode.type === 'state' && (
                               <>
-                                <p className="text-xs text-gray-500 dark:text-gray-400">
+                                <p className="text-muted-foreground text-xs">
                                   Assign values to workflow&apos;s state
                                   variables
                                 </p>
@@ -2415,7 +2399,7 @@ function WorkflowBuilderInner() {
                                       className="border-border rounded-xl border p-3"
                                     >
                                       <div className="mb-2 flex items-center justify-between">
-                                        <span className="text-sm font-medium text-gray-700 dark:text-gray-300">
+                                        <span className="text-foreground text-sm font-medium">
                                           Assign value
                                         </span>
                                         {(
@@ -2424,8 +2408,8 @@ function WorkflowBuilderInner() {
                                         ).length > 1 && (
                                           <Button
                                             type="button"
-                                            variant="ghost"
-                                            size="icon-sm"
+                                            variant="ghost-destructive"
+                                            size="icon-xs"
                                             onClick={() => {
                                               const ops = [
                                                 ...(selectedNode.data.config
@@ -2440,13 +2424,12 @@ function WorkflowBuilderInner() {
                                                 },
                                               });
                                             }}
-                                            className="size-auto p-0 text-gray-400 hover:bg-transparent hover:text-red-500 dark:hover:bg-transparent"
                                           >
                                             <Trash2 size={14} />
                                           </Button>
                                         )}
                                       </div>
-                                      <textarea
+                                      <Textarea
                                         value={op.expression}
                                         onChange={(e) => {
                                           const ops = [
@@ -2465,7 +2448,7 @@ function WorkflowBuilderInner() {
                                             },
                                           });
                                         }}
-                                        className="border-border focus-visible:ring-ring/50 focus-visible:border-ring bg-card dark:bg-accent mb-1 w-full rounded-xl border px-3 py-2 text-sm transition-all outline-none focus-visible:ring-2 dark:text-white"
+                                        className="mb-1"
                                         rows={2}
                                         placeholder="query"
                                       />
@@ -2484,7 +2467,7 @@ function WorkflowBuilderInner() {
                                         </a>
                                       </p>
                                       <div>
-                                        <span className="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                        <span className="text-foreground mb-1 block text-sm font-medium">
                                           To variable
                                         </span>
                                         <Input
@@ -2507,7 +2490,6 @@ function WorkflowBuilderInner() {
                                               },
                                             });
                                           }}
-                                          className="bg-card dark:bg-accent h-auto rounded-xl px-3 py-2 text-sm shadow-none"
                                           placeholder="variable_name"
                                         />
                                       </div>
@@ -2516,7 +2498,7 @@ function WorkflowBuilderInner() {
                                 )}
                                 <Button
                                   type="button"
-                                  variant="ghost"
+                                  variant="ghost-muted"
                                   size="sm"
                                   onClick={() => {
                                     const ops = [
@@ -2531,7 +2513,7 @@ function WorkflowBuilderInner() {
                                       },
                                     });
                                   }}
-                                  className="h-auto gap-1 self-start rounded-lg px-3 py-1.5 text-sm font-medium text-gray-600 dark:text-gray-400"
+                                  className="self-start"
                                 >
                                   <Plus size={14} />
                                   Add
@@ -2541,13 +2523,19 @@ function WorkflowBuilderInner() {
 
                             {selectedNode.type === 'condition' && (
                               <>
-                                <p className="text-xs text-gray-500 dark:text-gray-400">
+                                <p className="text-muted-foreground text-xs">
                                   Create conditions to branch your workflow
                                 </p>
-                                <div className="border-border flex overflow-hidden rounded-lg border">
+                                <div className="border-border bg-card flex gap-1 rounded-xl border p-1">
                                   <Button
                                     type="button"
-                                    variant="ghost"
+                                    variant={
+                                      (selectedNode.data.config?.mode ||
+                                        'simple') === 'simple'
+                                        ? 'outline'
+                                        : 'ghost-muted'
+                                    }
+                                    size="xs"
                                     onClick={() =>
                                       handleUpdateNodeData({
                                         config: {
@@ -2556,18 +2544,19 @@ function WorkflowBuilderInner() {
                                         },
                                       })
                                     }
-                                    className={`h-auto flex-1 rounded-none px-3 py-1.5 text-xs font-medium ${
-                                      (selectedNode.data.config?.mode ||
-                                        'simple') === 'simple'
-                                        ? 'bg-primary hover:bg-primary text-white hover:text-white'
-                                        : 'text-gray-600 dark:text-gray-400'
-                                    }`}
+                                    className="flex-1"
                                   >
                                     Simple
                                   </Button>
                                   <Button
                                     type="button"
-                                    variant="ghost"
+                                    variant={
+                                      selectedNode.data.config?.mode ===
+                                      'advanced'
+                                        ? 'outline'
+                                        : 'ghost-muted'
+                                    }
+                                    size="xs"
                                     onClick={() =>
                                       handleUpdateNodeData({
                                         config: {
@@ -2576,12 +2565,7 @@ function WorkflowBuilderInner() {
                                         },
                                       })
                                     }
-                                    className={`h-auto flex-1 rounded-none px-3 py-1.5 text-xs font-medium ${
-                                      selectedNode.data.config?.mode ===
-                                      'advanced'
-                                        ? 'bg-primary hover:bg-primary text-white hover:text-white'
-                                        : 'text-gray-600 dark:text-gray-400'
-                                    }`}
+                                    className="flex-1"
                                   >
                                     Advanced
                                   </Button>
@@ -2594,15 +2578,15 @@ function WorkflowBuilderInner() {
                                       className="border-border rounded-xl border p-3"
                                     >
                                       <div className="mb-2 flex items-center justify-between">
-                                        <span className="text-sm font-semibold text-orange-600 dark:text-orange-400">
+                                        <span className="text-warning text-sm font-semibold">
                                           {idx === 0 ? 'If' : 'Else if'}
                                         </span>
                                         {(selectedNode.data.config?.cases || [])
                                           .length > 1 && (
                                           <Button
                                             type="button"
-                                            variant="ghost"
-                                            size="icon-sm"
+                                            variant="ghost-destructive"
+                                            size="icon-xs"
                                             onClick={() => {
                                               const cases =
                                                 normalizeConditionCases([
@@ -2633,7 +2617,6 @@ function WorkflowBuilderInner() {
                                                 );
                                               }
                                             }}
-                                            className="size-auto p-0 text-gray-400 hover:bg-transparent hover:text-red-500 dark:hover:bg-transparent"
                                           >
                                             <Trash2 size={14} />
                                           </Button>
@@ -2659,7 +2642,7 @@ function WorkflowBuilderInner() {
                                             },
                                           });
                                         }}
-                                        className="bg-card dark:bg-accent mb-2 h-auto rounded-xl px-3 py-2 text-sm shadow-none"
+                                        className="mb-2"
                                         placeholder="Case name (optional)"
                                       />
                                       {(selectedNode.data.config?.mode ||
@@ -2695,7 +2678,6 @@ function WorkflowBuilderInner() {
                                                 },
                                               });
                                             }}
-                                            className="bg-card dark:bg-accent h-auto rounded-xl px-3 py-2 text-sm shadow-none"
                                             placeholder="Variable"
                                           />
                                           <Select
@@ -2728,7 +2710,10 @@ function WorkflowBuilderInner() {
                                               });
                                             }}
                                           >
-                                            <SelectTrigger className="w-24 shrink-0">
+                                            <SelectTrigger
+                                              size="lg"
+                                              className="w-24 shrink-0"
+                                            >
                                               <SelectValue />
                                             </SelectTrigger>
                                             <SelectContent>
@@ -2787,13 +2772,12 @@ function WorkflowBuilderInner() {
                                                 },
                                               });
                                             }}
-                                            className="bg-card dark:bg-accent h-auto rounded-xl px-3 py-2 text-sm shadow-none"
                                             placeholder="Value"
                                           />
                                         </div>
                                       ) : (
                                         <>
-                                          <textarea
+                                          <Textarea
                                             value={c.expression}
                                             onChange={(e) => {
                                               const cases = [
@@ -2812,7 +2796,6 @@ function WorkflowBuilderInner() {
                                                 },
                                               });
                                             }}
-                                            className="border-border focus-visible:ring-ring/50 focus-visible:border-ring bg-card dark:bg-accent w-full rounded-xl border px-3 py-2 text-sm transition-all outline-none focus-visible:ring-2 dark:text-white"
                                             rows={2}
                                             placeholder='Enter condition, e.g. query.contains("refund")'
                                           />
@@ -2839,7 +2822,7 @@ function WorkflowBuilderInner() {
 
                                 <Button
                                   type="button"
-                                  variant="ghost"
+                                  variant="ghost-muted"
                                   size="sm"
                                   onClick={() => {
                                     const cases = normalizeConditionCases([
@@ -2860,7 +2843,7 @@ function WorkflowBuilderInner() {
                                       },
                                     });
                                   }}
-                                  className="h-auto gap-1 self-start rounded-lg px-3 py-1.5 text-sm font-medium text-gray-600 dark:text-gray-400"
+                                  className="self-start"
                                 >
                                   <Plus size={14} />
                                   Add
@@ -2870,15 +2853,15 @@ function WorkflowBuilderInner() {
 
                             {selectedNode.type === 'code' && (
                               <>
-                                <p className="text-xs text-gray-500 dark:text-gray-400">
+                                <p className="text-muted-foreground text-xs">
                                   Run code in the workflow sandbox. Produced
                                   files are saved as artifacts.
                                 </p>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Code
                                   </label>
-                                  <textarea
+                                  <Textarea
                                     value={selectedNode.data.config?.code ?? ''}
                                     onChange={(e) =>
                                       handleUpdateNodeData({
@@ -2888,7 +2871,7 @@ function WorkflowBuilderInner() {
                                         },
                                       })
                                     }
-                                    className="border-border focus-visible:ring-ring/50 focus-visible:border-ring bg-card w-full rounded-xl border px-3 py-2 font-mono text-xs transition-all outline-none focus-visible:ring-2 dark:text-white"
+                                    className="font-mono"
                                     rows={10}
                                     spellCheck={false}
                                     placeholder={'print("hello world")'}
@@ -2910,7 +2893,7 @@ function WorkflowBuilderInner() {
                                   helpText="Artifacts/upstream refs staged as files in the sandbox (one becomes inputs/<name>)."
                                 />
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Output Variable
                                   </label>
                                   <Input
@@ -2927,12 +2910,11 @@ function WorkflowBuilderInner() {
                                         },
                                       })
                                     }
-                                    className="bg-card h-auto rounded-xl px-3 py-2 text-sm shadow-none"
                                     placeholder="Variable name for output"
                                   />
                                 </div>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Timeout (seconds)
                                   </label>
                                   <Input
@@ -2958,20 +2940,19 @@ function WorkflowBuilderInner() {
                                         },
                                       });
                                     }}
-                                    className="bg-card h-auto rounded-xl px-3 py-2 text-sm shadow-none"
                                     placeholder="Optional"
                                   />
                                 </div>
                                 <div>
-                                  <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+                                  <label className="text-foreground mb-2 block text-sm font-medium">
                                     Structured Output (JSON Schema)
                                   </label>
-                                  <textarea
+                                  <Textarea
                                     value={selectedCodeJsonSchemaText}
                                     onChange={(e) =>
                                       handleCodeJsonSchemaChange(e.target.value)
                                     }
-                                    className="border-border focus-visible:ring-ring/50 focus-visible:border-ring bg-card w-full rounded-xl border px-3 py-2 font-mono text-xs transition-all outline-none focus-visible:ring-2 dark:text-white"
+                                    className="font-mono"
                                     rows={6}
                                     placeholder={`{
   "type": "object",
@@ -2985,8 +2966,8 @@ function WorkflowBuilderInner() {
                                     <p
                                       className={`mt-2 text-xs ${
                                         selectedCodeJsonSchemaError
-                                          ? 'text-red-600 dark:text-red-400'
-                                          : 'text-green-600 dark:text-green-400'
+                                          ? 'text-destructive'
+                                          : 'text-success'
                                       }`}
                                     >
                                       {selectedCodeJsonSchemaError
@@ -3006,7 +2987,8 @@ function WorkflowBuilderInner() {
                       variant="destructive-outline"
                       onClick={handleDeleteNode}
                       disabled={selectedNode?.type === 'start'}
-                      className="w-full rounded-full border-red-200 px-4 py-2 text-sm font-medium text-red-600 hover:bg-red-50 hover:text-red-600 dark:border-red-900/30 dark:text-red-400 dark:hover:bg-red-900/10 dark:hover:text-red-400"
+                      shape="pill"
+                      className="w-full"
                     >
                       <Trash2 size={16} />
                       {selectedNode?.type === 'start'
@@ -3024,7 +3006,7 @@ function WorkflowBuilderInner() {
           <SheetContent
             side="right"
             title="Workflow preview"
-            className="bg-card w-full max-w-none p-0 sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]"
+            className="w-full max-w-none p-0 sm:max-w-[600px] md:max-w-[700px] lg:max-w-[800px]"
           >
             <WorkflowPreview
               workflowId={workflowId}
diff --git a/frontend/src/agents/workflow/WorkflowMiniMap.test.tsx b/frontend/src/agents/workflow/WorkflowMiniMap.test.tsx
new file mode 100644
index 00000000..6451b556
--- /dev/null
+++ b/frontend/src/agents/workflow/WorkflowMiniMap.test.tsx
@@ -0,0 +1,131 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+import type { WorkflowNode } from '../types/workflow';
+import type { WorkflowExecutionStep } from './workflowPreviewSlice';
+import { WorkflowMiniMap } from './WorkflowPreview';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const node = (
+  id: string,
+  type: WorkflowNode['type'],
+  y: number,
+): WorkflowNode => ({
+  id,
+  type,
+  title: id,
+  position: { x: 0, y },
+  data: {},
+});
+
+const nodes = [
+  node('start', 'start', 0),
+  node('done', 'agent', 1),
+  node('broken', 'agent', 2),
+  node('busy', 'agent', 3),
+];
+
+const step = (
+  nodeId: string,
+  status: WorkflowExecutionStep['status'],
+): WorkflowExecutionStep => ({
+  nodeId,
+  nodeType: 'agent',
+  nodeTitle: nodeId,
+  status,
+});
+
+const steps = [
+  step('done', 'completed'),
+  step('broken', 'failed'),
+  step('busy', 'running'),
+];
+
+describe('WorkflowMiniMap', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const rows = (activeNodeId: string | null = null) => {
+    act(() => {
+      root.render(
+        <WorkflowMiniMap
+          nodes={nodes}
+          activeNodeId={activeNodeId}
+          executionSteps={steps}
+        />,
+      );
+    });
+    const byName: Record<string, HTMLButtonElement> = {};
+    container.querySelectorAll<HTMLButtonElement>('button').forEach((b) => {
+      byName[b.textContent ?? ''] = b;
+    });
+    return byName;
+  };
+
+  const tokens = (el: HTMLElement) => el.className.split(/\s+/);
+
+  it('pins the success fill on hover for a completed row', () => {
+    const done = tokens(rows().done);
+    expect(done).toEqual(
+      expect.arrayContaining([
+        'bg-success/10',
+        'hover:bg-success/10',
+        'dark:hover:bg-success/10',
+        'hover:opacity-80',
+      ]),
+    );
+    expect(done).not.toContain('hover:bg-accent');
+    expect(done).not.toContain('dark:hover:bg-input/50');
+  });
+
+  it('pins each status fill on hover', () => {
+    const r = rows();
+    expect(tokens(r.broken)).toEqual(
+      expect.arrayContaining([
+        'hover:bg-destructive/10',
+        'dark:hover:bg-destructive/10',
+      ]),
+    );
+    expect(tokens(r.busy)).toEqual(
+      expect.arrayContaining([
+        'hover:bg-primary/10',
+        'dark:hover:bg-primary/10',
+        'animate-pulse',
+      ]),
+    );
+    expect(tokens(r.Start)).toEqual(
+      expect.arrayContaining([
+        'bg-muted',
+        'hover:bg-muted',
+        'dark:hover:bg-muted',
+      ]),
+    );
+    expect(r.Start.disabled).toBe(true);
+    expect(tokens(r.Start)).not.toContain('hover:opacity-80');
+  });
+
+  it('pins the active fill on hover and keeps the ring', () => {
+    const done = tokens(rows('done').done);
+    expect(done).toEqual(
+      expect.arrayContaining([
+        'ring-2',
+        'ring-primary',
+        'hover:bg-primary/10',
+        'dark:hover:bg-primary/10',
+      ]),
+    );
+    expect(done).not.toContain('hover:bg-accent');
+  });
+});
diff --git a/frontend/src/agents/workflow/WorkflowPreview.tsx b/frontend/src/agents/workflow/WorkflowPreview.tsx
index b400ceb6..924199b8 100644
--- a/frontend/src/agents/workflow/WorkflowPreview.tsx
+++ b/frontend/src/agents/workflow/WorkflowPreview.tsx
@@ -2,6 +2,7 @@ import {
   Bot,
   CheckCircle2,
   Circle,
+  CircleAlert,
   Code2,
   Database,
   FileBox,
@@ -17,6 +18,7 @@ import {
 import { Fragment, useCallback, useEffect, useRef, useState } from 'react';
 import { useDispatch, useSelector } from 'react-redux';
 
+import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Button } from '@/components/ui/button';
 import {
   MessageScroller,
@@ -77,13 +79,13 @@ const NODE_ICONS: Record<string, React.ReactNode> = {
 };
 
 const NODE_COLORS: Record<string, string> = {
-  start: 'text-green-600 dark:text-green-400',
-  agent: 'text-purple-600 dark:text-purple-400',
-  end: 'text-gray-600 dark:text-gray-400',
-  note: 'text-yellow-600 dark:text-yellow-400',
-  state: 'text-blue-600 dark:text-blue-400',
-  condition: 'text-orange-600 dark:text-orange-400',
-  code: 'text-indigo-600 dark:text-indigo-400',
+  start: 'text-success',
+  agent: 'text-primary',
+  end: 'text-destructive',
+  note: 'text-warning',
+  state: 'text-info',
+  condition: 'text-warning',
+  code: 'text-info',
 };
 
 function ExecutionDetails({
@@ -116,17 +118,18 @@ function ExecutionDetails({
     <div className="mb-4 flex w-full flex-col flex-wrap items-start self-start lg:flex-nowrap">
       <div className="my-2 flex flex-row items-center justify-center gap-3">
         <div className="flex h-[26px] w-[30px] items-center justify-center">
-          <Workflow className="h-5 w-5 text-gray-600 dark:text-gray-400" />
+          <Workflow className="text-muted-foreground h-5 w-5" />
         </div>
         <Button
           type="button"
           variant="ghost"
+          size="sm"
           onClick={onToggle}
-          className="h-auto gap-2 px-0 py-0 hover:bg-transparent"
+          className="-ml-2.5"
         >
           <p className="text-base font-semibold">
             Execution Details
-            <span className="ml-1.5 text-sm font-normal text-gray-500 dark:text-gray-400">
+            <span className="text-muted-foreground ml-1.5 text-sm font-normal">
               ({completedSteps.length}{' '}
               {completedSteps.length === 1 ? 'step' : 'steps'})
             </span>
@@ -178,7 +181,7 @@ function ExecutionDetails({
                   className="bg-muted dark:bg-accent rounded-xl p-3"
                 >
                   <div className="flex items-center gap-2 text-sm">
-                    <span className="flex h-5 w-5 shrink-0 items-center justify-center text-xs font-medium text-gray-500 dark:text-gray-400">
+                    <span className="text-muted-foreground flex h-5 w-5 shrink-0 items-center justify-center text-xs font-medium">
                       {stepIndex + 1}.
                     </span>
                     <div
@@ -191,15 +194,15 @@ function ExecutionDetails({
                         <Circle className="h-3 w-3" />
                       )}
                     </div>
-                    <span className="min-w-0 truncate font-medium text-gray-900 dark:text-white">
+                    <span className="text-foreground min-w-0 truncate font-medium">
                       {displayName}
                     </span>
                     <div className="ml-auto shrink-0">
                       {step.status === 'completed' && (
-                        <CheckCircle2 className="h-4 w-4 text-green-600 dark:text-green-400" />
+                        <CheckCircle2 className="text-success h-4 w-4" />
                       )}
                       {step.status === 'failed' && (
-                        <XCircle className="h-4 w-4 text-red-600 dark:text-red-400" />
+                        <XCircle className="text-destructive h-4 w-4" />
                       )}
                     </div>
                   </div>
@@ -207,23 +210,24 @@ function ExecutionDetails({
                     <div className="mt-3 space-y-2 text-sm">
                       {hasOutput && (
                         <div className="bg-muted rounded-lg p-2">
-                          <span className="font-medium text-gray-600 dark:text-gray-400">
+                          <span className="text-muted-foreground font-medium">
                             Output:{' '}
                           </span>
-                          <span className="wrap-break-word whitespace-pre-wrap text-gray-900 dark:text-gray-100">
+                          <span className="text-foreground wrap-break-word whitespace-pre-wrap">
                             {truncateText(formattedOutput, 300)}
                           </span>
                         </div>
                       )}
                       {step.error && (
-                        <div className="rounded-lg bg-red-50 p-2 dark:bg-red-900/30">
-                          <span className="font-medium text-red-700 dark:text-red-300">
-                            Error:{' '}
-                          </span>
-                          <span className="wrap-break-word whitespace-pre-wrap text-red-800 dark:text-red-200">
-                            {step.error}
-                          </span>
-                        </div>
+                        <Alert variant="destructive" role="status">
+                          <CircleAlert />
+                          <AlertDescription>
+                            <span className="font-medium">Error: </span>
+                            <span className="wrap-break-word whitespace-pre-wrap">
+                              {step.error}
+                            </span>
+                          </AlertDescription>
+                        </Alert>
                       )}
                       {stateVars.length > 0 && (
                         <div className="flex flex-wrap gap-2">
@@ -232,11 +236,11 @@ function ExecutionDetails({
                               key={key}
                               className="bg-muted inline-flex items-center rounded-lg px-2 py-1 text-xs"
                             >
-                              <span className="max-w-[100px] truncate font-medium text-gray-600 dark:text-gray-400">
+                              <span className="text-muted-foreground max-w-[100px] truncate font-medium">
                                 {key}:
                               </span>
                               <span
-                                className="ml-1 max-w-[200px] truncate text-gray-900 dark:text-gray-100"
+                                className="text-foreground ml-1 max-w-[200px] truncate"
                                 title={formatValue(value)}
                               >
                                 {truncateText(formatValue(value), 50)}
@@ -272,13 +276,14 @@ function RunArtifactsSection({
     <div className="mb-4 flex w-full flex-col flex-wrap items-start self-start lg:flex-nowrap">
       <div className="my-2 flex flex-row items-center justify-center gap-3">
         <div className="flex h-[26px] w-[30px] items-center justify-center">
-          <FileBox className="h-5 w-5 text-gray-600 dark:text-gray-400" />
+          <FileBox className="text-muted-foreground h-5 w-5" />
         </div>
         <Button
           type="button"
           variant="ghost"
+          size="sm"
           onClick={onToggle}
-          className="h-auto gap-2 px-0 py-0 hover:bg-transparent"
+          className="-ml-2.5"
         >
           <p className="text-base font-semibold">Artifacts</p>
           <img
@@ -312,7 +317,7 @@ function RunArtifactsSection({
   );
 }
 
-function WorkflowMiniMap({
+export function WorkflowMiniMap({
   nodes,
   activeNodeId,
   executionSteps,
@@ -341,26 +346,6 @@ function WorkflowMiniMap({
     return step?.status || 'pending';
   };
 
-  const getStatusColor = (nodeId: string) => {
-    const status = getNodeStatus(nodeId);
-    const isActive = nodeId === activeNodeId;
-
-    if (isActive) {
-      return 'ring-2 ring-purple-500 bg-purple-100 dark:bg-purple-900/50';
-    }
-
-    switch (status) {
-      case 'completed':
-        return 'bg-green-100 dark:bg-green-900/30 border-green-300 dark:border-green-700';
-      case 'running':
-        return 'bg-purple-100 dark:bg-purple-900/30 border-purple-300 dark:border-purple-700 animate-pulse';
-      case 'failed':
-        return 'bg-red-100 dark:bg-red-900/30 border-red-300 dark:border-red-700';
-      default:
-        return 'bg-gray-50 dark:bg-gray-800 border-gray-200 dark:border-gray-700';
-    }
-  };
-
   const executedOrder = new Map(executionSteps.map((s, i) => [s.nodeId, i]));
   const startNode = nodes.find((node) => node.type === 'start');
   const visibleNodeIds = new Set(executionSteps.map((step) => step.nodeId));
@@ -392,55 +377,73 @@ function WorkflowMiniMap({
 
   return (
     <div className="space-y-1">
-      {sortedNodes.map((node, index) => (
-        <div key={node.id} className="relative">
-          {index < sortedNodes.length - 1 && (
-            <div className="absolute top-12 left-4 h-3 w-0.5 bg-gray-200 dark:bg-gray-700" />
-          )}
-
-          <Button
-            type="button"
-            variant="outline"
-            onClick={() => hasStepData(node.id) && onNodeClick?.(node.id)}
-            disabled={!hasStepData(node.id)}
-            className={cn(
-              'h-12 w-full justify-start gap-2 px-3 text-xs disabled:opacity-100',
-              getStatusColor(node.id),
-              hasStepData(node.id) && 'hover:opacity-80',
+      {sortedNodes.map((node, index) => {
+        const status = getNodeStatus(node.id);
+        const isActive = node.id === activeNodeId;
+        return (
+          <div key={node.id} className="relative">
+            {index < sortedNodes.length - 1 && (
+              <div className="bg-border absolute top-12 left-4 h-3 w-0.5" />
             )}
-          >
-            <div
+
+            <Button
+              type="button"
+              variant="outline"
+              size="xs"
+              onClick={() => hasStepData(node.id) && onNodeClick?.(node.id)}
+              disabled={!hasStepData(node.id)}
+              /* eslint-disable shadcn/no-restyle --
+                 Preview minimap status row: the fill, border and ring follow the step status (success, primary running + pulse,
+                 destructive, muted pending), pending and running rows stay unfaded while disabled, and clickable rows dim on hover.
+                 No Button variant is status-tinted. See DESIGN.md, Approved exceptions. */
               className={cn(
-                'flex h-5 w-5 shrink-0 items-center justify-center rounded-full',
-                NODE_COLORS[node.type] || NODE_COLORS.state,
+                'h-12 w-full justify-start disabled:opacity-100',
+                isActive
+                  ? 'bg-primary/10 ring-primary hover:bg-primary/10 dark:bg-primary/10 dark:hover:bg-primary/10 ring-2'
+                  : status === 'completed'
+                    ? 'border-success/50 bg-success/10 hover:bg-success/10 dark:border-success/50 dark:bg-success/10 dark:hover:bg-success/10'
+                    : status === 'running'
+                      ? 'border-primary/50 bg-primary/10 hover:bg-primary/10 dark:border-primary/50 dark:bg-primary/10 dark:hover:bg-primary/10 animate-pulse'
+                      : status === 'failed'
+                        ? 'border-destructive/50 bg-destructive/10 hover:bg-destructive/10 dark:border-destructive/50 dark:bg-destructive/10 dark:hover:bg-destructive/10'
+                        : 'border-border bg-muted hover:bg-muted dark:border-border dark:bg-muted dark:hover:bg-muted',
+                hasStepData(node.id) && 'hover:opacity-80',
               )}
+              /* eslint-enable shadcn/no-restyle */
             >
-              {NODE_ICONS[node.type] || <Circle className="h-3 w-3" />}
-            </div>
-            <div className="min-w-0 flex-1 text-left">
-              <div className="truncate font-medium text-gray-700 dark:text-gray-200">
-                {getNodeDisplayName(node)}
+              <div
+                className={cn(
+                  'flex h-5 w-5 shrink-0 items-center justify-center rounded-full',
+                  NODE_COLORS[node.type] || NODE_COLORS.state,
+                )}
+              >
+                {NODE_ICONS[node.type] || <Circle className="h-3 w-3" />}
               </div>
-              {getNodeSubtitle(node) && (
-                <div className="truncate text-xs text-gray-500 dark:text-gray-400">
-                  {getNodeSubtitle(node)}
+              <div className="min-w-0 flex-1 text-left">
+                <div className="text-foreground truncate font-medium">
+                  {getNodeDisplayName(node)}
                 </div>
-              )}
-            </div>
-            <div className="shrink-0">
-              {getNodeStatus(node.id) === 'running' && (
-                <Loader2 className="h-3 w-3 animate-spin text-purple-500" />
-              )}
-              {getNodeStatus(node.id) === 'completed' && (
-                <CheckCircle2 className="h-3 w-3 text-green-500" />
-              )}
-              {getNodeStatus(node.id) === 'failed' && (
-                <XCircle className="h-3 w-3 text-red-500" />
-              )}
-            </div>
-          </Button>
-        </div>
-      ))}
+                {getNodeSubtitle(node) && (
+                  <div className="text-muted-foreground truncate text-xs">
+                    {getNodeSubtitle(node)}
+                  </div>
+                )}
+              </div>
+              <div className="shrink-0">
+                {status === 'running' && (
+                  <Loader2 className="text-primary h-3 w-3 animate-spin" />
+                )}
+                {status === 'completed' && (
+                  <CheckCircle2 className="text-success h-3 w-3" />
+                )}
+                {status === 'failed' && (
+                  <XCircle className="text-destructive h-3 w-3" />
+                )}
+              </div>
+            </Button>
+          </div>
+        );
+      })}
     </div>
   );
 }
@@ -605,21 +608,19 @@ export default function WorkflowPreview({
     <div className="bg-card flex h-full flex-col">
       <div className="border-border flex h-[77px] items-center justify-between border-b px-6">
         <div className="flex items-center gap-3">
-          <div className="bg-muted flex items-center justify-center rounded-full p-3 text-gray-600 dark:text-gray-300">
+          <div className="bg-muted text-muted-foreground flex items-center justify-center rounded-full p-3">
             <Play className="h-4 w-4" />
           </div>
           <div>
-            <h2 className="text-xl font-bold text-gray-900 dark:text-white">
-              Preview
-            </h2>
-            <p className="max-w-md truncate text-xs text-gray-500 dark:text-gray-400">
+            <h2 className="text-foreground text-xl font-bold">Preview</h2>
+            <p className="text-muted-foreground max-w-md truncate text-xs">
               {workflowData.name}
               {workflowData.description && ` - ${workflowData.description}`}
             </p>
           </div>
         </div>
         {status === 'loading' && (
-          <span className="text-primary dark:text-primary flex items-center gap-1 text-xs">
+          <span className="text-primary flex items-center gap-1 text-xs">
             <Loader2 className="h-3 w-3 animate-spin" />
             Running
           </span>
@@ -629,7 +630,7 @@ export default function WorkflowPreview({
       <div className="flex min-h-0 flex-1">
         <div className="border-border flex w-64 shrink-0 flex-col border-r">
           <div className="flex items-center justify-between px-4 py-3">
-            <h3 className="text-xs font-semibold tracking-wider text-gray-500 uppercase dark:text-gray-400">
+            <h3 className="text-muted-foreground text-xs font-semibold tracking-wider uppercase">
               Workflow
             </h3>
           </div>
@@ -650,16 +651,19 @@ export default function WorkflowPreview({
             {queries.length === 0 ? (
               <div className="flex h-full flex-col items-center justify-center px-4">
                 <div className="bg-muted mb-2 flex size-14 shrink-0 items-center justify-center rounded-xl">
-                  <MessageSquare className="size-6 text-gray-600 dark:text-gray-300" />
+                  <MessageSquare className="text-muted-foreground size-6" />
                 </div>
-                <p className="text-xl font-semibold text-gray-700 dark:text-gray-200">
+                <p className="text-foreground text-xl font-semibold">
                   Test the workflow
                 </p>
               </div>
             ) : (
               <MessageScrollerProvider autoScroll>
                 <MessageScroller>
-                  <MessageScrollerViewport className="scrollbar-thin px-4 pt-4">
+                  <MessageScrollerViewport
+                    /* eslint-disable-next-line shadcn/no-restyle -- MessageScroller padding: the primitive measures Content's padding-block for its scroll math, and the Viewport's top gap must scroll with the messages. See DESIGN.md, Approved exceptions. */
+                    className="scrollbar-thin px-4 pt-4"
+                  >
                     <MessageScrollerContent className="w-full">
                       {queries.map((query, index) => {
                         const querySteps = query.executionSteps || [];
@@ -776,7 +780,7 @@ export default function WorkflowPreview({
           </div>
           <div className="bg-card flex w-full flex-col gap-2 px-4 pt-2 pb-4">
             {sendBlockedMessage && (
-              <p className="text-xs text-red-500" role="alert">
+              <p className="text-destructive text-xs" role="alert">
                 {sendBlockedMessage}
               </p>
             )}
diff --git a/frontend/src/agents/workflow/WorkflowRunArtifacts.tsx b/frontend/src/agents/workflow/WorkflowRunArtifacts.tsx
index f395f9c2..7f7ceb76 100644
--- a/frontend/src/agents/workflow/WorkflowRunArtifacts.tsx
+++ b/frontend/src/agents/workflow/WorkflowRunArtifacts.tsx
@@ -131,7 +131,7 @@ export default function WorkflowRunArtifacts({
 
   if (loading) {
     return (
-      <div className="flex items-center gap-2 px-3 py-4 text-sm text-gray-500 dark:text-gray-400">
+      <div className="text-muted-foreground flex items-center gap-2 px-3 py-4 text-sm">
         <Spinner size="small" /> Loading artifacts...
       </div>
     );
@@ -139,7 +139,7 @@ export default function WorkflowRunArtifacts({
 
   if (error) {
     return (
-      <div className="flex items-center justify-between gap-2 px-3 py-3 text-sm text-red-500">
+      <div className="text-destructive flex items-center justify-between gap-2 px-3 py-3 text-sm">
         <span>{error}</span>
         <Button type="button" variant="outline" size="sm" onClick={loadList}>
           Retry
@@ -150,7 +150,7 @@ export default function WorkflowRunArtifacts({
 
   if (!artifacts || artifacts.length === 0) {
     return (
-      <div className="px-3 py-3 text-sm text-gray-500 dark:text-gray-400">
+      <div className="text-muted-foreground px-3 py-3 text-sm">
         {inProgress
           ? 'Run in progress — artifacts appear here as nodes produce them.'
           : 'No artifacts produced by this run.'}
@@ -166,7 +166,6 @@ export default function WorkflowRunArtifacts({
             type="button"
             variant="ghost"
             size="sm"
-            className="gap-1 px-2"
             onClick={() => setSelectedId(null)}
           >
             <ChevronLeft className="h-4 w-4" />
@@ -180,7 +179,7 @@ export default function WorkflowRunArtifacts({
             </div>
           ) : detailError ? (
             <div className="flex h-full items-center justify-center">
-              <p className="text-sm text-red-500">{detailError}</p>
+              <p className="text-destructive text-sm">{detailError}</p>
             </div>
           ) : detail ? (
             <DocumentArtifactView
@@ -201,14 +200,14 @@ export default function WorkflowRunArtifacts({
             type="button"
             variant="outline"
             onClick={() => setSelectedId(artifact.id)}
-            className="h-auto w-full justify-start gap-3 px-3 py-2 text-left"
+            className="h-auto w-full justify-start text-left"
           >
-            <FileBox className="h-4 w-4 shrink-0 text-gray-500 dark:text-gray-400" />
+            <FileBox className="text-muted-foreground h-4 w-4 shrink-0" />
             <div className="min-w-0 flex-1">
-              <div className="truncate text-sm font-medium text-gray-900 dark:text-white">
+              <div className="text-foreground truncate text-sm font-medium">
                 {artifact.title || `Artifact ${artifact.id.slice(0, 8)}`}
               </div>
-              <div className="truncate text-xs text-gray-500 dark:text-gray-400">
+              <div className="text-muted-foreground truncate text-xs">
                 {artifact.kind || 'file'}
                 {artifact.current_version != null
                   ? ` · v${artifact.current_version}`
diff --git a/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx b/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx
index 17bfced3..50d73793 100644
--- a/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx
+++ b/frontend/src/agents/workflow/components/NodeDocumentsControl.tsx
@@ -60,7 +60,7 @@ export default function NodeDocumentsControl({
 
   return (
     <div>
-      <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+      <label className="text-foreground mb-2 block text-sm font-medium">
         {label}
       </label>
       <div className="border-border bg-card flex gap-1 rounded-xl border p-1">
@@ -68,14 +68,10 @@ export default function NodeDocumentsControl({
           <Button
             key={optionMode}
             type="button"
-            variant="ghost"
-            size="sm"
+            variant={mode === optionMode ? 'outline' : 'ghost-muted'}
+            size="xs"
             onClick={() => selectMode(optionMode)}
-            className={`h-auto flex-1 rounded-lg px-2 py-1.5 text-xs font-medium ${
-              mode === optionMode
-                ? 'bg-primary text-white'
-                : 'text-gray-600 dark:text-gray-300'
-            }`}
+            className="flex-1"
           >
             {modeLabel}
           </Button>
@@ -104,15 +100,13 @@ export default function NodeDocumentsControl({
                   addRef();
                 }
               }}
-              className="bg-card h-auto rounded-xl px-3 py-2 text-sm shadow-none"
               placeholder="Add ref (e.g. A1)"
             />
             <Button
               type="button"
-              variant="ghost"
-              size="sm"
+              variant="ghost-muted"
               onClick={addRef}
-              className="h-auto shrink-0 gap-1 rounded-lg px-3 py-2 text-sm font-medium text-gray-600 dark:text-gray-300"
+              className="shrink-0"
             >
               <Plus size={14} />
               Add
diff --git a/frontend/src/agents/workflow/components/PromptTextArea.tsx b/frontend/src/agents/workflow/components/PromptTextArea.tsx
index ce133990..060ee364 100644
--- a/frontend/src/agents/workflow/components/PromptTextArea.tsx
+++ b/frontend/src/agents/workflow/components/PromptTextArea.tsx
@@ -1,5 +1,12 @@
 import { Braces, Plus, Search } from 'lucide-react';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  type CSSProperties,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { Edge, Node } from 'reactflow';
 
 import { Button } from '@/components/ui/button';
@@ -221,7 +228,7 @@ function HighlightedOverlay({ text }: { text: string }) {
             {part}
           </span>
         ) : (
-          <span key={i} className="text-gray-900 dark:text-white">
+          <span key={i} className="text-foreground">
             {part}
           </span>
         ),
@@ -260,7 +267,7 @@ function VariableListWithSearch({
           value={search}
           onChange={(e) => setSearch(e.target.value)}
           placeholder="Search variables..."
-          className="h-auto rounded-none border-0 px-0 py-0 text-sm text-gray-800 shadow-none focus-visible:ring-0 md:text-sm dark:border-0 dark:text-gray-200"
+          variant="bare"
         />
       </div>
 
@@ -280,15 +287,16 @@ function VariableListWithSearch({
                   key={`${section}-${v.templatePath}`}
                   type="button"
                   variant="ghost"
+                  size="sm"
                   onMouseDown={(e) => {
                     e.preventDefault();
                     e.stopPropagation();
                     onSelect(v.templatePath);
                   }}
-                  className="h-auto w-full justify-start gap-2 rounded-none px-3 py-1.5 text-left text-sm font-normal"
+                  className="w-full justify-start"
                 >
                   <Braces className="text-primary h-3.5 w-3.5 shrink-0" />
-                  <span className="truncate font-medium text-gray-800 dark:text-gray-200">
+                  <span className="text-foreground truncate font-medium">
                     {v.label}
                   </span>
                 </Button>
@@ -439,7 +447,7 @@ export default function PromptTextArea({
   return (
     <div>
       {label && (
-        <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+        <label className="text-foreground mb-2 block text-sm font-medium">
           {label}
         </label>
       )}
@@ -455,9 +463,7 @@ export default function PromptTextArea({
           {value ? (
             <HighlightedOverlay text={value} />
           ) : (
-            <span className="text-gray-400 dark:text-gray-500">
-              {placeholder}
-            </span>
+            <span className="text-muted-foreground">{placeholder}</span>
           )}
         </div>
 
@@ -481,11 +487,7 @@ export default function PromptTextArea({
               overlayRef.current.scrollTop = textareaRef.current.scrollTop;
             }
           }}
-          className="focus-visible:ring-ring/50 focus-visible:border-ring relative w-full rounded-xl bg-transparent px-3 pt-2 pb-8 text-sm caret-black outline-none focus-visible:ring-[3px] dark:caret-white"
-          style={{
-            color: 'transparent',
-            WebkitTextFillColor: 'transparent',
-          }}
+          className="focus-visible:ring-ring/50 focus-visible:border-ring relative w-full rounded-xl bg-transparent px-3 pt-2 pb-8 text-sm text-transparent caret-black outline-none focus-visible:ring-3 dark:caret-white"
           rows={rows}
           placeholder={placeholder}
           spellCheck={false}
@@ -494,11 +496,7 @@ export default function PromptTextArea({
         <div className="absolute right-4 bottom-1.5 z-10">
           <Popover open={contextOpen} onOpenChange={setContextOpen}>
             <PopoverTrigger asChild>
-              <Button
-                type="button"
-                variant="ghost"
-                className="text-primary hover:bg-primary/10 h-auto gap-1 px-2 py-1 text-xs font-medium"
-              >
+              <Button type="button" variant="link" size="xs">
                 <Plus className="h-3 w-3" />
                 Add context
               </Button>
@@ -506,7 +504,7 @@ export default function PromptTextArea({
             <PopoverContent
               align="end"
               side="top"
-              className="border-border bg-card w-60 rounded-xl border p-0 shadow-lg"
+              className="w-60 p-0"
               onOpenAutoFocus={(e) => e.preventDefault()}
             >
               <VariableListWithSearch
@@ -520,8 +518,13 @@ export default function PromptTextArea({
         {showDropdown && filtered.length > 0 && (
           <div
             ref={dropdownRef}
-            className="border-border bg-card absolute z-50 w-64 rounded-xl border shadow-lg"
-            style={{ top: dropdownPos.top, left: dropdownPos.left }}
+            className="border-border bg-card absolute top-(--dropdown-top) left-(--dropdown-left) z-50 w-64 rounded-xl border shadow-lg"
+            style={
+              {
+                '--dropdown-top': `${dropdownPos.top}px`,
+                '--dropdown-left': `${dropdownPos.left}px`,
+              } as CSSProperties
+            }
           >
             <VariableListWithSearch
               variables={filtered}
diff --git a/frontend/src/agents/workflow/nodes/BaseNode.tsx b/frontend/src/agents/workflow/nodes/BaseNode.tsx
index a19346a5..3756ce0a 100644
--- a/frontend/src/agents/workflow/nodes/BaseNode.tsx
+++ b/frontend/src/agents/workflow/nodes/BaseNode.tsx
@@ -23,28 +23,28 @@ export const BaseNode: React.FC<BaseNodeProps> = ({
 }) => {
   let bgColor = 'bg-card';
   let borderColor = 'border-border';
-  let iconBg = 'bg-gray-100 dark:bg-gray-800';
-  let iconColor = 'text-gray-600 dark:text-gray-400';
+  let iconBg = 'bg-muted';
+  let iconColor = 'text-muted-foreground';
 
   if (selected) {
     borderColor = 'border-primary ring-2 ring-primary';
   }
 
   if (type === 'start') {
-    iconBg = 'bg-green-100 dark:bg-green-900/30';
-    iconColor = 'text-green-600 dark:text-green-400';
+    iconBg = 'bg-success/10';
+    iconColor = 'text-success';
   } else if (type === 'end') {
-    iconBg = 'bg-red-100 dark:bg-red-900/30';
-    iconColor = 'text-red-600 dark:text-red-400';
+    iconBg = 'bg-destructive/10';
+    iconColor = 'text-destructive';
   } else if (type === 'state') {
-    iconBg = 'bg-gray-100 dark:bg-gray-800';
-    iconColor = 'text-gray-600 dark:text-gray-400';
+    iconBg = 'bg-muted';
+    iconColor = 'text-muted-foreground';
   } else if (type === 'condition') {
-    iconBg = 'bg-orange-100 dark:bg-orange-900/30';
-    iconColor = 'text-orange-600 dark:text-orange-400';
+    iconBg = 'bg-warning/10';
+    iconColor = 'text-warning';
   } else if (type === 'code') {
-    iconBg = 'bg-indigo-100 dark:bg-indigo-900/30';
-    iconColor = 'text-indigo-600 dark:text-indigo-400';
+    iconBg = 'bg-info/10';
+    iconColor = 'text-info';
   }
 
   return (
@@ -58,7 +58,7 @@ export const BaseNode: React.FC<BaseNodeProps> = ({
           type="target"
           position={Position.Left}
           isConnectable={true}
-          className="hover:bg-primary/90! border-card! -left-1! h-3! w-3! rounded-full! border-2! bg-gray-400! transition-colors!"
+          className="hover:bg-primary/90! border-card! bg-muted-foreground! -left-1! h-3! w-3! rounded-full! border-2! transition-colors!"
         />
       )}
 
@@ -70,13 +70,13 @@ export const BaseNode: React.FC<BaseNodeProps> = ({
         </div>
         <div className="min-w-0 flex-1 pr-3">
           <div
-            className="truncate text-sm font-semibold text-gray-900 dark:text-white"
+            className="text-foreground truncate text-sm font-semibold"
             title={title}
           >
             {title}
           </div>
           {children && (
-            <div className="mt-1 truncate text-xs text-gray-600 dark:text-gray-400">
+            <div className="text-muted-foreground mt-1 truncate text-xs">
               {children}
             </div>
           )}
@@ -88,7 +88,7 @@ export const BaseNode: React.FC<BaseNodeProps> = ({
           type="source"
           position={Position.Right}
           isConnectable={true}
-          className="hover:bg-primary/90! border-card! -right-1! h-3! w-3! rounded-full! border-2! bg-gray-400! transition-colors!"
+          className="hover:bg-primary/90! border-card! bg-muted-foreground! -right-1! h-3! w-3! rounded-full! border-2! transition-colors!"
         />
       )}
     </div>
diff --git a/frontend/src/agents/workflow/nodes/CodeNode.tsx b/frontend/src/agents/workflow/nodes/CodeNode.tsx
index c8559ed9..335a87ba 100644
--- a/frontend/src/agents/workflow/nodes/CodeNode.tsx
+++ b/frontend/src/agents/workflow/nodes/CodeNode.tsx
@@ -30,19 +30,17 @@ const CodeNode = ({ data, selected }: NodeProps<CodeNodeData>) => {
       <div className="flex flex-col gap-1">
         {codeHint ? (
           <div
-            className="truncate font-mono text-xs text-gray-500 dark:text-gray-400"
+            className="text-muted-foreground truncate font-mono text-xs"
             title={code}
           >
             {codeHint}
           </div>
         ) : (
-          <div className="text-xs text-gray-500 dark:text-gray-400">
-            No code yet
-          </div>
+          <div className="text-muted-foreground text-xs">No code yet</div>
         )}
         {config.output_variable && (
           <div
-            className="truncate text-xs text-gray-500 dark:text-gray-400"
+            className="text-muted-foreground truncate text-xs"
             title={`Output: ${config.output_variable}`}
           >
             Output: {config.output_variable}
diff --git a/frontend/src/agents/workflow/nodes/ConditionNode.tsx b/frontend/src/agents/workflow/nodes/ConditionNode.tsx
index e49f33e7..8f5e4b8f 100644
--- a/frontend/src/agents/workflow/nodes/ConditionNode.tsx
+++ b/frontend/src/agents/workflow/nodes/ConditionNode.tsx
@@ -38,7 +38,7 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
     <div
       className={`bg-card relative rounded-2xl border shadow-md transition-all ${
         selected
-          ? 'border-primary dark:ring-primary scale-105 ring-2 ring-purple-300'
+          ? 'border-primary ring-primary scale-105 ring-2'
           : 'border-border hover:shadow-lg'
       }`}
       style={{ minWidth: 180, maxWidth: 220, height }}
@@ -47,21 +47,21 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
         type="target"
         position={Position.Left}
         isConnectable
-        className="hover:bg-primary/90! border-card! top-1/2! -left-1! h-3! w-3! rounded-full! border-2! bg-gray-400! transition-colors!"
+        className="hover:bg-primary/90! border-card! bg-muted-foreground! top-1/2! -left-1! h-3! w-3! rounded-full! border-2! transition-colors!"
       />
 
       <div className="flex items-center gap-3 px-3 py-2">
-        <div className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-orange-100 text-orange-600 dark:bg-orange-900/30 dark:text-orange-400">
+        <div className="bg-warning/10 text-warning flex h-9 w-9 shrink-0 items-center justify-center rounded-full">
           <GitBranch size={14} />
         </div>
         <div className="min-w-0 flex-1 pr-2">
           <div
-            className="truncate text-sm font-semibold text-gray-900 dark:text-white"
+            className="text-foreground truncate text-sm font-semibold"
             title={title}
           >
             {title}
           </div>
-          <div className="text-xs text-gray-500 uppercase">
+          <div className="text-muted-foreground text-xs uppercase">
             {data.config?.mode || 'simple'}
           </div>
         </div>
@@ -74,12 +74,12 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
             className="flex items-center gap-1"
             style={{ height: ROW_HEIGHT }}
           >
-            <span className="shrink-0 text-xs font-medium text-orange-600 dark:text-orange-400">
+            <span className="text-warning shrink-0 text-xs font-medium">
               {i === 0 ? 'If' : 'Else if'}
             </span>
             {c.name && (
               <span
-                className="truncate text-xs text-gray-600 dark:text-gray-400"
+                className="text-muted-foreground truncate text-xs"
                 title={c.name}
               >
                 {c.name}
@@ -88,7 +88,9 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
           </div>
         ))}
         <div className="flex items-center gap-1" style={{ height: ROW_HEIGHT }}>
-          <span className="text-xs font-medium text-gray-500">Else</span>
+          <span className="text-muted-foreground text-xs font-medium">
+            Else
+          </span>
         </div>
       </div>
 
@@ -100,7 +102,7 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
           id={c.sourceHandle}
           isConnectable
           style={{ top: getHandleTop(i, totalOutputs) }}
-          className="hover:bg-primary/90! dark:border-border! -right-1! h-3! w-3! rounded-full! border-2! border-white! bg-orange-400! transition-colors"
+          className="hover:bg-primary/90! border-card! bg-warning! -right-1! h-3! w-3! rounded-full! border-2! transition-colors"
         />
       ))}
       <Handle
@@ -109,7 +111,7 @@ const ConditionNode = ({ data, selected }: NodeProps<ConditionNodeData>) => {
         id="else"
         isConnectable
         style={{ top: getHandleTop(cases.length, totalOutputs) }}
-        className="hover:bg-primary/90! border-card! -right-1! h-3! w-3! rounded-full! border-2! bg-gray-400! transition-colors!"
+        className="hover:bg-primary/90! border-card! bg-muted-foreground! -right-1! h-3! w-3! rounded-full! border-2! transition-colors!"
       />
     </div>
   );
diff --git a/frontend/src/agents/workflow/nodes/SetStateNode.tsx b/frontend/src/agents/workflow/nodes/SetStateNode.tsx
index e9514a92..8416fade 100644
--- a/frontend/src/agents/workflow/nodes/SetStateNode.tsx
+++ b/frontend/src/agents/workflow/nodes/SetStateNode.tsx
@@ -31,7 +31,7 @@ const SetStateNode = ({ data, selected }: NodeProps<SetStateNodeData>) => {
       <div className="flex flex-col gap-1">
         {operations.length > 0 ? (
           <div
-            className="truncate text-xs text-gray-500"
+            className="text-muted-foreground truncate text-xs"
             title={`${operations.length} operation(s)`}
           >
             {operations.length} variable{operations.length !== 1 ? 's' : ''}
@@ -39,14 +39,14 @@ const SetStateNode = ({ data, selected }: NodeProps<SetStateNodeData>) => {
         ) : hasLegacy ? (
           <>
             <div
-              className="truncate text-xs text-gray-500 uppercase"
+              className="text-muted-foreground truncate text-xs uppercase"
               title={`Variable: ${data.variable}`}
             >
               {data.variable}
             </div>
             {data.value && (
               <div
-                className="truncate text-xs text-blue-600 dark:text-blue-400"
+                className="text-info truncate text-xs"
                 title={`Value: ${data.value}`}
               >
                 {data.value}
diff --git a/frontend/src/agents/workflow/nodes/index.tsx b/frontend/src/agents/workflow/nodes/index.tsx
index 4a117350..1b211a3d 100644
--- a/frontend/src/agents/workflow/nodes/index.tsx
+++ b/frontend/src/agents/workflow/nodes/index.tsx
@@ -1,6 +1,8 @@
 import { Bot, Flag, Play, StickyNote } from 'lucide-react';
 import { memo } from 'react';
 
+import { cn } from '@/lib/utils';
+
 import { BaseNode } from './BaseNode';
 import CodeNode from './CodeNode';
 import ConditionNode from './ConditionNode';
@@ -19,7 +21,9 @@ export const StartNode = memo(function StartNode({
       handles={{ target: false, source: true }}
       icon={<Play size={16} />}
     >
-      <div className="text-xs text-gray-500">Entry point of the workflow</div>
+      <div className="text-muted-foreground text-xs">
+        Entry point of the workflow
+      </div>
     </BaseNode>
   );
 });
@@ -37,7 +41,7 @@ export const EndNode = memo(function EndNode({
       handles={{ target: true, source: false }}
       icon={<Flag size={16} />}
     >
-      <div className="text-xs text-gray-500">Workflow completion</div>
+      <div className="text-muted-foreground text-xs">Workflow completion</div>
     </BaseNode>
   );
 });
@@ -70,7 +74,7 @@ export const AgentNode = memo(function AgentNode({
       <div className="flex flex-col gap-1">
         {config.agent_type && (
           <div
-            className="truncate text-xs text-gray-500 uppercase"
+            className="text-muted-foreground truncate text-xs uppercase"
             title={config.agent_type}
           >
             {config.agent_type}
@@ -86,7 +90,7 @@ export const AgentNode = memo(function AgentNode({
         )}
         {config.output_variable && (
           <div
-            className="truncate text-xs text-gray-500 dark:text-gray-400"
+            className="text-muted-foreground truncate text-xs"
             title={`Output: ${config.output_variable}`}
           >
             Output: {config.output_variable}
@@ -113,26 +117,29 @@ export const NoteNode = memo(function NoteNode({
 
   return (
     <div
-      className={`max-w-[250px] rounded-3xl border border-yellow-200 bg-yellow-50 px-5 py-3 shadow-md transition-all dark:border-yellow-800 dark:bg-yellow-900/20 ${
+      className={cn(
+        // Opaque tint: the card colour underneath, the warning wash painted
+        // over it as a flat gradient, so the canvas grid doesn't show through.
+        'bg-card from-warning/10 to-warning/10 max-w-[250px] rounded-3xl border bg-linear-to-b px-5 py-3 shadow-md transition-all',
         selected
-          ? 'scale-105 ring-2 ring-yellow-300 dark:ring-yellow-700'
-          : 'hover:shadow-lg'
-      }`}
+          ? 'border-warning ring-warning scale-105 ring-2'
+          : 'border-warning/50 hover:shadow-lg',
+      )}
     >
       <div className="flex items-start gap-3">
-        <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-yellow-100 text-yellow-700 dark:bg-yellow-800/30 dark:text-yellow-500">
+        <div className="bg-warning/15 text-warning flex h-10 w-10 shrink-0 items-center justify-center rounded-full">
           <StickyNote size={18} />
         </div>
         <div className="min-w-0 flex-1">
           <div
-            className="truncate text-sm font-semibold text-yellow-800 dark:text-yellow-300"
+            className="text-foreground truncate text-sm font-semibold"
             title={title}
           >
             {title}
           </div>
           {displayContent && (
             <div
-              className="mt-1 text-xs wrap-break-word text-yellow-700 italic dark:text-yellow-400"
+              className="text-muted-foreground mt-1 text-xs wrap-break-word italic"
               title={data.content}
             >
               {displayContent}
diff --git a/frontend/src/components/ActionButtons.tsx b/frontend/src/components/ActionButtons.tsx
index cc161017..84f556af 100644
--- a/frontend/src/components/ActionButtons.tsx
+++ b/frontend/src/components/ActionButtons.tsx
@@ -53,11 +53,12 @@ export default function ActionButtons({
         {showNewChat && (
           <Button
             type="button"
-            variant="ghost"
+            variant="ghost-muted"
             size="icon"
+            shape="pill"
             title={t('actionButtons.openNewChat')}
             onClick={newChat}
-            className="text-muted-foreground hover:text-foreground rounded-full lg:hidden"
+            className="lg:hidden"
           >
             <Plus className="size-5" strokeWidth={1.75} aria-label="NewChat" />
           </Button>
@@ -67,11 +68,11 @@ export default function ActionButtons({
           <>
             <Button
               type="button"
-              variant="ghost"
+              variant="ghost-muted"
               size="icon"
+              shape="pill"
               title={t('actionButtons.share')}
               onClick={() => setShareModalState(true)}
-              className="text-muted-foreground hover:text-foreground rounded-full"
             >
               <Share className="size-5" strokeWidth={1.75} aria-label="share" />
             </Button>
diff --git a/frontend/src/components/ArtifactSidebar.tsx b/frontend/src/components/ArtifactSidebar.tsx
index fe3ddaaf..f32ab4bb 100644
--- a/frontend/src/components/ArtifactSidebar.tsx
+++ b/frontend/src/components/ArtifactSidebar.tsx
@@ -9,6 +9,8 @@ import {
 } from 'react-syntax-highlighter/dist/cjs/styles/prism';
 import remarkGfm from 'remark-gfm';
 
+import { cn } from '@/lib/utils';
+
 import userService from '../api/services/userService';
 import { useDarkTheme } from '../hooks';
 import { selectToken } from '../preferences/preferenceSlice';
@@ -16,6 +18,7 @@ import { isDocumentArtifact, type DocumentArtifact } from './artifactViewUtils';
 import CopyButton from './CopyButton';
 import DocumentArtifactView from './DocumentArtifactView';
 import Spinner from './Spinner';
+import { Badge } from './ui/badge';
 import { Button } from './ui/button';
 import { Sheet, SheetContent } from './ui/sheet';
 
@@ -82,17 +85,13 @@ function TodoListView({ data }: { data: TodoArtifactData }) {
     <div className="flex h-full w-full flex-col overflow-hidden">
       <div className="mb-4 flex items-center justify-end">
         <div className="flex gap-2 text-xs">
-          <span className="rounded-full bg-green-100 px-2 py-1 text-green-700 dark:bg-green-900/30 dark:text-green-400">
-            {data.completed_count} done
-          </span>
-          <span className="rounded-full bg-blue-100 px-2 py-1 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400">
-            {data.open_count} open
-          </span>
+          <Badge variant="success">{data.completed_count} done</Badge>
+          <Badge variant="info">{data.open_count} open</Badge>
         </div>
       </div>
       <div className="flex-1 overflow-y-auto">
         {data.items.length === 0 ? (
-          <p className="text-center text-sm text-gray-500 dark:text-gray-400">
+          <p className="text-muted-foreground text-center text-sm">
             No todos yet
           </p>
         ) : (
@@ -100,18 +99,20 @@ function TodoListView({ data }: { data: TodoArtifactData }) {
             {data.items.map((item, index) => (
               <li
                 key={`${item.todo_id}-${index}`}
-                className={`flex items-start gap-3 rounded-lg border p-3 ${
+                className={cn(
+                  'flex items-start gap-3 rounded-lg border p-3',
                   item.status === 'completed'
-                    ? 'border-green-300 dark:border-green-800'
-                    : 'border-gray-200 dark:border-gray-700'
-                }`}
+                    ? 'border-success/50'
+                    : 'border-border',
+                )}
               >
                 <span
-                  className={`mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border-2 ${
+                  className={cn(
+                    'mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border-2',
                     item.status === 'completed'
-                      ? 'border-green-500 bg-green-500 text-white'
-                      : 'border-gray-300 dark:border-gray-600'
-                  }`}
+                      ? 'border-success bg-success text-success-foreground'
+                      : 'border-input',
+                  )}
                 >
                   {item.status === 'completed' && (
                     <svg
@@ -131,15 +132,18 @@ function TodoListView({ data }: { data: TodoArtifactData }) {
                 </span>
                 <div className="flex-1">
                   <p
-                    className={`text-sm ${
+                    className={cn(
+                      'text-sm',
                       item.status === 'completed'
-                        ? 'text-gray-500 line-through dark:text-gray-400'
-                        : 'text-gray-900 dark:text-white'
-                    }`}
+                        ? 'text-muted-foreground line-through'
+                        : 'text-foreground',
+                    )}
                   >
                     {item.title}
                   </p>
-                  <p className="mt-1 text-xs text-gray-400">#{item.todo_id}</p>
+                  <p className="text-muted-foreground mt-1 text-xs">
+                    #{item.todo_id}
+                  </p>
                 </div>
               </li>
             ))}
@@ -157,7 +161,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
     <div className="flex h-full w-full flex-col overflow-hidden">
       <div className="mb-4 flex items-center justify-end">
         <div className="flex items-center gap-2">
-          <span className="text-xs text-gray-500 dark:text-gray-400">
+          <span className="text-muted-foreground text-xs">
             {data.line_count} lines
           </span>
           <CopyButton textToCopy={data.content || ''} />
@@ -165,7 +169,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
       </div>
       <div className="flex-1 overflow-y-auto p-4">
         {data.content ? (
-          <div className="flex flex-col gap-3 text-sm leading-normal wrap-break-word whitespace-pre-wrap text-gray-800 dark:text-gray-200">
+          <div className="text-foreground flex flex-col gap-3 text-sm leading-normal wrap-break-word whitespace-pre-wrap">
             <ReactMarkdown
               remarkPlugins={[remarkGfm]}
               components={{
@@ -185,7 +189,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
                   return match ? (
                     <div className="group border-border relative my-2 overflow-hidden rounded-xl border">
                       <div className="bg-muted flex items-center justify-between px-2 py-1">
-                        <span className="text-foreground dark:text-foreground text-xs font-medium">
+                        <span className="text-foreground text-xs font-medium">
                           {language}
                         </span>
                         <CopyButton
@@ -196,6 +200,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
                         {...rest}
                         PreTag="div"
                         language={language}
+                        /* eslint-disable-next-line shadcn/no-inline-styles -- SyntaxHighlighter's style prop is its Prism theme object (oneLight / vscDarkPlus), picked by theme at runtime; it is not CSS. See DESIGN.md, Approved exceptions. */
                         style={isDarkTheme ? vscDarkPlus : oneLight}
                         customStyle={{
                           margin: 0,
@@ -208,7 +213,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
                     </div>
                   ) : (
                     <code
-                      className="dark:bg-accent dark:text-foreground rounded-md bg-gray-200 px-2 py-1 text-xs font-normal"
+                      className="bg-accent rounded-md px-2 py-1 text-xs font-normal"
                       {...rest}
                     >
                       {children}
@@ -235,7 +240,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
                       href={href}
                       target="_blank"
                       rel="noopener noreferrer"
-                      className="text-blue-600 hover:underline dark:text-blue-400"
+                      className="text-primary hover:underline"
                     >
                       {children}
                     </a>
@@ -255,7 +260,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
                 },
                 blockquote({ children }) {
                   return (
-                    <blockquote className="border-l-4 border-gray-300 pl-4 italic dark:border-gray-600">
+                    <blockquote className="border-border border-l-4 pl-4 italic">
                       {children}
                     </blockquote>
                   );
@@ -266,7 +271,7 @@ function NoteView({ data }: { data: NoteArtifactData }) {
             </ReactMarkdown>
           </div>
         ) : (
-          <p className="text-sm text-gray-500 dark:text-gray-400">Empty note</p>
+          <p className="text-muted-foreground text-sm">Empty note</p>
         )}
       </div>
     </div>
@@ -446,7 +451,7 @@ export default function ArtifactSidebar({
     if (error) {
       return (
         <div className="flex h-full items-center justify-center">
-          <p className="text-sm text-red-500">{error}</p>
+          <p className="text-destructive text-sm">{error}</p>
         </div>
       );
     }
@@ -462,9 +467,7 @@ export default function ArtifactSidebar({
     if (!artifact) {
       return (
         <div className="flex h-full items-center justify-center">
-          <p className="text-sm text-gray-500 dark:text-gray-400">
-            Artifact not found
-          </p>
+          <p className="text-muted-foreground text-sm">Artifact not found</p>
         </div>
       );
     }
@@ -475,7 +478,7 @@ export default function ArtifactSidebar({
         return <NoteView data={artifact.data} />;
       default:
         return (
-          <pre className="text-xs text-gray-600 dark:text-gray-400">
+          <pre className="text-muted-foreground text-xs">
             {JSON.stringify(artifact, null, 2)}
           </pre>
         );
@@ -490,16 +493,16 @@ export default function ArtifactSidebar({
         {/* Space for top bar / actions */}
         <div className="h-14 shrink-0" />
         {/* Artifact panel */}
-        <div className="flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-gray-200 bg-transparent dark:border-gray-700">
+        <div className="border-border flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border bg-transparent">
           <div className="flex w-full items-center justify-between px-4 py-2">
-            <span className="text-sm font-medium text-gray-600 dark:text-gray-300">
+            <span className="text-muted-foreground text-sm font-medium">
               {title}
             </span>
             <Button
               type="button"
               variant="ghost"
               size="icon-sm"
-              className="rounded-full"
+              shape="pill"
               onClick={onClose}
               aria-label="Close"
             >
@@ -523,24 +526,26 @@ export default function ArtifactSidebar({
         side="right"
         showCloseButton={false}
         title={title || 'Artifact preview'}
-        className="dark:bg-card bg-card flex h-full w-80 flex-col gap-0 border-l border-[#9ca3af]/10 p-0 sm:w-96 sm:max-w-none"
+        className="h-full w-80 p-0 sm:w-96 sm:max-w-none"
       >
-        <div className="flex w-full items-center justify-between border-b border-gray-200 px-4 py-3 dark:border-gray-700">
-          <span className="text-sm font-medium text-gray-600 dark:text-gray-300">
-            {title}
-          </span>
-          <Button
-            type="button"
-            variant="ghost"
-            size="icon"
-            className="rounded-full"
-            onClick={onClose}
-            aria-label="Close"
-          >
-            <X className="h-4 w-4" />
-          </Button>
+        <div className="flex min-h-0 flex-1 flex-col">
+          <div className="border-border flex w-full items-center justify-between border-b px-4 py-3">
+            <span className="text-muted-foreground text-sm font-medium">
+              {title}
+            </span>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              shape="pill"
+              onClick={onClose}
+              aria-label="Close"
+            >
+              <X className="h-4 w-4" />
+            </Button>
+          </div>
+          <div className="flex-1 overflow-hidden p-4">{renderContent()}</div>
         </div>
-        <div className="flex-1 overflow-hidden p-4">{renderContent()}</div>
       </SheetContent>
     </Sheet>
   );
diff --git a/frontend/src/components/Chunks.tsx b/frontend/src/components/Chunks.tsx
index 8efa7f64..f0f39b89 100644
--- a/frontend/src/components/Chunks.tsx
+++ b/frontend/src/components/Chunks.tsx
@@ -3,6 +3,8 @@ import React, { useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 
+import { cn } from '@/lib/utils';
+
 import userService from '../api/services/userService';
 import ArrowLeft from '../assets/arrow-left.svg';
 import FileIcon from '../assets/file.svg';
@@ -51,7 +53,7 @@ const LineNumberedTextarea: React.FC<LineNumberedTextareaProps> = ({
     onChange(e.target.value);
   };
 
-  const lineHeight = 19.93;
+  const lineHeight = 20;
   const contentLines = value.split('\n').length;
 
   const heightOffset = isMobile ? 200 : 300;
@@ -62,24 +64,30 @@ const LineNumberedTextarea: React.FC<LineNumberedTextareaProps> = ({
   const totalLines = Math.max(contentLines, minLinesForDisplay);
 
   return (
-    <div className={`relative w-full ${className}`}>
-      <div
-        className="pointer-events-none absolute top-0 left-0 w-8 pr-2 text-right font-mono text-xs leading-[19.93px] text-gray-500 select-none lg:w-12 lg:pr-3 lg:text-sm dark:text-gray-400"
-        style={{
-          height: `${totalLines * lineHeight}px`,
-        }}
-      >
+    <div
+      className={cn('relative w-full', className)}
+      style={
+        {
+          '--numbered-height': `${totalLines * lineHeight}px`,
+        } as React.CSSProperties
+      }
+    >
+      <div className="text-muted-foreground pointer-events-none absolute top-0 left-0 h-(--numbered-height) w-8 pr-2 text-right font-mono text-xs leading-5 select-none lg:w-12 lg:pr-3 lg:text-sm">
         {Array.from({ length: totalLines }, (_, i) => (
           <div
             key={i + 1}
-            className="flex h-[19.93px] items-center justify-end leading-[19.93px]"
+            className="flex h-5 items-center justify-end leading-5"
           >
             {i + 1}
           </div>
         ))}
       </div>
       <textarea
-        className={`text-foreground focus-visible:ring-ring/50 focus-visible:border-ring w-full resize-none overflow-hidden border-none bg-transparent pl-8 font-['Inter'] text-[13.68px] leading-[19.93px] outline-none focus-visible:ring-[3px] lg:pl-12 dark:text-white ${isMobile ? 'min-h-[calc(100vh-200px)]' : 'min-h-[calc(100vh-300px)]'} ${!editable ? 'select-none' : ''}`}
+        className={cn(
+          'text-foreground focus-visible:ring-ring/50 focus-visible:border-ring h-(--numbered-height) w-full resize-none overflow-hidden border-none bg-transparent pl-8 text-sm leading-5 outline-none focus-visible:ring-3 lg:pl-12',
+          isMobile ? 'min-h-[calc(100vh-200px)]' : 'min-h-[calc(100vh-300px)]',
+          !editable && 'select-none',
+        )}
         value={value}
         onChange={editable ? handleChange : undefined}
         onDoubleClick={onDoubleClick}
@@ -87,9 +95,6 @@ const LineNumberedTextarea: React.FC<LineNumberedTextareaProps> = ({
         aria-label={ariaLabel}
         rows={totalLines}
         readOnly={!editable}
-        style={{
-          height: `${totalLines * lineHeight}px`,
-        }}
       />
     </div>
   );
@@ -309,8 +314,10 @@ const Chunks: React.FC<ChunksProps> = ({
           <Button
             type="button"
             variant="outline"
-            size="icon-sm"
-            className="mr-3 h-[29px] w-[29px] rounded-full p-2 text-gray-400 dark:border-0 dark:text-gray-500"
+            size="icon-xs"
+            shape="pill"
+            className="mr-3"
+            aria-label={t('settings.sources.back')}
             onClick={
               editingChunk
                 ? () => setEditingChunk(null)
@@ -330,20 +337,22 @@ const Chunks: React.FC<ChunksProps> = ({
 
             {pathParts.length > 0 && (
               <>
-                <span className="mx-1 shrink-0 text-gray-500">/</span>
+                <span className="text-muted-foreground mx-1 shrink-0">/</span>
                 {pathParts.map((part, index) => (
                   <React.Fragment key={index}>
                     <span
                       className={`wrap-break-word ${
                         index < pathParts.length - 1
                           ? 'text-primary font-medium'
-                          : 'text-gray-700 dark:text-gray-300'
+                          : 'text-foreground'
                       }`}
                     >
                       {part}
                     </span>
                     {index < pathParts.length - 1 && (
-                      <span className="mx-1 shrink-0 text-gray-500">/</span>
+                      <span className="text-muted-foreground mx-1 shrink-0">
+                        /
+                      </span>
                     )}
                   </React.Fragment>
                 ))}
@@ -359,7 +368,8 @@ const Chunks: React.FC<ChunksProps> = ({
               <>
                 <Button
                   type="button"
-                  className="h-[38px] min-w-[108px] rounded-full px-4 text-sm font-medium whitespace-nowrap"
+                  shape="pill"
+                  className="min-w-[108px]"
                   onClick={() => setIsEditing(true)}
                 >
                   {t('modals.chunk.edit')}
@@ -367,7 +377,8 @@ const Chunks: React.FC<ChunksProps> = ({
                 <Button
                   type="button"
                   variant="destructive-outline"
-                  className="h-[38px] min-w-[108px] rounded-full px-4 py-1 text-sm font-medium text-nowrap"
+                  shape="pill"
+                  className="min-w-[108px]"
                   onClick={() => {
                     confirmDeleteChunk(editingChunk);
                   }}
@@ -383,7 +394,8 @@ const Chunks: React.FC<ChunksProps> = ({
                   onClick={() => {
                     setIsEditing(false);
                   }}
-                  className="dark:text-foreground h-[38px] min-w-[108px] cursor-pointer rounded-full px-4 py-1 text-sm font-medium text-nowrap"
+                  shape="pill"
+                  className="min-w-[108px]"
                 >
                   {t('modals.chunk.cancel')}
                 </Button>
@@ -412,13 +424,8 @@ const Chunks: React.FC<ChunksProps> = ({
                     (editingTitle === (editingChunk?.metadata?.title || '') &&
                       editingText === (editingChunk?.text || ''))
                   }
-                  className={`h-[38px] min-w-[108px] rounded-full px-4 py-1 text-sm font-medium text-nowrap transition-all ${
-                    editingText.trim() &&
-                    (editingTitle !== (editingChunk?.metadata?.title || '') ||
-                      editingText !== (editingChunk?.text || ''))
-                      ? 'cursor-pointer'
-                      : 'cursor-not-allowed bg-gray-400 text-white hover:bg-gray-400'
-                  }`}
+                  shape="pill"
+                  className="min-w-[108px]"
                 >
                   {t('modals.chunk.save')}
                 </Button>
@@ -430,7 +437,8 @@ const Chunks: React.FC<ChunksProps> = ({
                 type="button"
                 variant="ghost"
                 onClick={() => setIsAddingChunk(false)}
-                className="dark:text-foreground h-[38px] min-w-[108px] cursor-pointer rounded-full px-4 py-1 text-sm font-medium text-nowrap"
+                shape="pill"
+                className="min-w-[108px]"
               >
                 {t('modals.chunk.cancel')}
               </Button>
@@ -443,11 +451,8 @@ const Chunks: React.FC<ChunksProps> = ({
                   }
                 }}
                 disabled={!editingText.trim()}
-                className={`h-[38px] min-w-[108px] rounded-full px-4 py-1 text-sm font-medium text-nowrap transition-all ${
-                  editingText.trim()
-                    ? 'cursor-pointer'
-                    : 'cursor-not-allowed bg-gray-400 text-white hover:bg-gray-400'
-                }`}
+                shape="pill"
+                className="min-w-[108px]"
               >
                 {t('modals.chunk.add')}
               </Button>
@@ -496,30 +501,26 @@ const Chunks: React.FC<ChunksProps> = ({
   const renderFileSearch = () => {
     return (
       <div className="relative" ref={searchDropdownRef}>
-        <div className="relative flex items-center">
-          <div className="pointer-events-none absolute left-3">
+        <Input
+          type="text"
+          value={fileSearchQuery}
+          onChange={(e) => handleFileSearchChange(e.target.value)}
+          placeholder={t('settings.sources.searchFiles')}
+          className="h-[38px]"
+          leftIcon={
             <SearchIcon
               className="text-muted-foreground size-4"
               strokeWidth={1.75}
               aria-label="Search"
             />
-          </div>
-          <Input
-            type="text"
-            value={fileSearchQuery}
-            onChange={(e) => handleFileSearchChange(e.target.value)}
-            placeholder={t('settings.sources.searchFiles')}
-            className={`h-[38px] py-2 pr-4 pl-10 ${
-              fileSearchQuery ? 'rounded-t-md' : 'rounded-md'
-            } transition-all duration-200`}
-          />
-        </div>
+          }
+        />
 
         {fileSearchQuery && (
-          <div className="border-border bg-card dark:border-border dark:bg-card absolute z-10 max-h-[calc(100vh-200px)] w-full overflow-hidden rounded-b-md border border-t-0 shadow-lg">
+          <div className="border-border bg-popover text-popover-foreground absolute top-full right-0 left-0 z-20 mt-1 max-h-[calc(100vh-200px)] w-full overflow-hidden rounded-xl border shadow-md">
             <div className="max-h-[calc(100vh-200px)] overflow-x-hidden overflow-y-auto">
               {fileSearchResults.length === 0 ? (
-                <div className="py-2 text-center text-sm text-gray-500 dark:text-gray-400">
+                <div className="text-muted-foreground py-2 text-center text-sm">
                   {t('settings.sources.noResults')}
                 </div>
               ) : (
@@ -568,7 +569,7 @@ const Chunks: React.FC<ChunksProps> = ({
             <>
               <div className="mb-3 flex flex-col items-start justify-between gap-3 sm:flex-row sm:items-center">
                 <div className="border-border dark:border-border flex h-[38px] w-full flex-1 items-center overflow-hidden rounded-md border">
-                  <div className="dark:text-foreground flex h-full items-center px-4 font-medium whitespace-nowrap text-gray-700">
+                  <div className="text-foreground flex h-full items-center px-4 font-medium whitespace-nowrap">
                     {totalChunks > 999999
                       ? `${(totalChunks / 1000000).toFixed(2)}M`
                       : totalChunks > 999
@@ -577,19 +578,21 @@ const Chunks: React.FC<ChunksProps> = ({
                     {t('settings.sources.chunks')}
                   </div>
                   <div className="bg-border dark:bg-border h-full w-px"></div>
-                  <div className="h-full flex-1">
+                  <div className="h-full flex-1 px-3 py-2">
                     <Input
                       type="text"
+                      variant="bare"
                       placeholder={t('settings.sources.searchPlaceholder')}
                       value={searchTerm}
                       onChange={(e) => setSearchTerm(e.target.value)}
-                      className="h-full rounded-none border-0 px-3 py-2 text-[13.56px] leading-[100%] font-normal shadow-none focus-visible:ring-0 md:text-[13.56px] dark:border-0"
+                      className="h-full"
                     />
                   </div>
                 </div>
                 <Button
                   type="button"
-                  className="h-[38px] w-full min-w-[108px] shrink-0 rounded-full px-4 text-sm font-medium whitespace-normal sm:w-auto"
+                  shape="pill"
+                  className="w-full min-w-[108px] shrink-0 whitespace-normal sm:w-auto"
                   title={t('settings.sources.addChunk')}
                   onClick={() => {
                     setIsAddingChunk(true);
@@ -607,7 +610,7 @@ const Chunks: React.FC<ChunksProps> = ({
               ) : (
                 <div className="grid w-full grid-cols-1 justify-items-start gap-4 sm:grid-cols-[repeat(auto-fit,minmax(400px,1fr))]">
                   {filteredChunks.length === 0 ? (
-                    <div className="col-span-full flex min-h-[50vh] w-full flex-col items-center justify-center text-center text-gray-500 dark:text-gray-400">
+                    <div className="text-muted-foreground col-span-full flex min-h-[50vh] w-full flex-col items-center justify-center text-center">
                       <img
                         src={isDarkTheme ? NoFilesDarkIcon : NoFilesIcon}
                         alt={t('settings.sources.noChunksAlt')}
@@ -628,13 +631,13 @@ const Chunks: React.FC<ChunksProps> = ({
                       >
                         <div className="w-full">
                           <div className="border-border bg-muted dark:border-border dark:bg-card flex w-full items-center justify-between border-b px-4 py-3">
-                            <div className="dark:text-muted-foreground text-sm text-[#59636E]">
+                            <div className="text-muted-foreground text-sm">
                               {formatChunkTokens(chunk.metadata)}{' '}
                               {t('settings.sources.tokensUnit')}
                             </div>
                           </div>
                           <div className="px-4 pt-3 pb-6">
-                            <p className="text-foreground line-clamp-6 font-['Inter'] text-[13.68px] leading-[19.93px] font-normal">
+                            <p className="text-foreground line-clamp-6 text-sm leading-5 font-normal">
                               {chunk.text}
                             </p>
                           </div>
@@ -661,7 +664,7 @@ const Chunks: React.FC<ChunksProps> = ({
               <div className="w-full">
                 <div className="border-border dark:border-border relative flex w-full flex-col overflow-hidden rounded-md border">
                   <div className="border-border bg-muted dark:border-border dark:bg-card flex w-full items-center justify-between border-b px-4 py-3">
-                    <div className="dark:text-muted-foreground text-sm text-[#59636E]">
+                    <div className="text-muted-foreground text-sm">
                       {formatChunkTokens(editingChunk.metadata)}{' '}
                       {t('settings.sources.tokensUnit')}
                     </div>
diff --git a/frontend/src/components/ConfigFields.tsx b/frontend/src/components/ConfigFields.tsx
index 9e7520c4..27ad8e1a 100644
--- a/frontend/src/components/ConfigFields.tsx
+++ b/frontend/src/components/ConfigFields.tsx
@@ -1,7 +1,5 @@
 import { useMemo } from 'react';
 
-import { cn } from '@/lib/utils';
-
 import { ConfigRequirements } from '../modals/types';
 import { Input } from './ui/input';
 import { Label } from './ui/label';
@@ -68,7 +66,7 @@ export default function ConfigFields({
             <div key={key} className="flex flex-col gap-1.5">
               <Label htmlFor={key}>
                 {spec.label || key}
-                {spec.required && <span className="text-red-500">*</span>}
+                {spec.required && <span className="text-destructive">*</span>}
               </Label>
               <Select
                 value={value || spec.default || ''}
@@ -78,11 +76,8 @@ export default function ConfigFields({
                   id={key}
                   variant="ghost"
                   size="lg"
-                  className={cn(
-                    'w-full rounded-xl',
-                    hasError &&
-                      'border-destructive aria-invalid:ring-destructive/20',
-                  )}
+                  aria-invalid={hasError || undefined}
+                  className="w-full"
                 >
                   <SelectValue placeholder={spec.label || key} />
                 </SelectTrigger>
@@ -106,7 +101,7 @@ export default function ConfigFields({
           <div key={key} className="flex flex-col gap-1.5">
             <Label htmlFor={key}>
               {spec.label || key}
-              {spec.required && <span className="text-red-500">*</span>}
+              {spec.required && <span className="text-destructive">*</span>}
             </Label>
             <Input
               id={key}
@@ -136,7 +131,6 @@ export default function ConfigFields({
                 spec.type === 'number' && key === 'timeout' ? 300 : undefined
               }
               aria-invalid={hasError || undefined}
-              className={cn('rounded-xl', hasError && 'border-destructive')}
             />
             {hasError && (
               <p className="text-destructive text-xs">{errors[key]}</p>
diff --git a/frontend/src/components/ConnectorAuth.test.tsx b/frontend/src/components/ConnectorAuth.test.tsx
new file mode 100644
index 00000000..49939bf4
--- /dev/null
+++ b/frontend/src/components/ConnectorAuth.test.tsx
@@ -0,0 +1,84 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => 'token',
+}));
+
+vi.mock('../hooks', () => ({
+  useDarkTheme: () => [false, () => undefined],
+}));
+
+vi.mock('../api/services/userService', () => ({ default: {} }));
+
+import ConnectorAuth from './ConnectorAuth';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('ConnectorAuth', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = (props: Partial<Parameters<typeof ConnectorAuth>[0]>) =>
+    act(() =>
+      root.render(
+        <ConnectorAuth
+          provider="google_drive"
+          onSuccess={() => undefined}
+          onError={() => undefined}
+          label="Connect"
+          {...props}
+        />,
+      ),
+    );
+
+  it('shows the error as a destructive alert with an icon', () => {
+    render({ errorMessage: 'Session expired' });
+    const alert = container.querySelector('[role="alert"]');
+    expect(alert).not.toBeNull();
+    expect(alert?.className).toContain('text-destructive');
+    expect(alert?.querySelector('svg')).not.toBeNull();
+    expect(alert?.textContent).toContain('Session expired');
+  });
+
+  it('renders the connected banner as a polite success alert', () => {
+    const onDisconnect = vi.fn();
+    render({ isConnected: true, userEmail: 'a@b.c', onDisconnect });
+    const banner = container.querySelector('[role="status"]');
+    expect(banner).not.toBeNull();
+    expect(banner?.className).toContain('text-success');
+    expect(banner?.className).toContain('bg-success/10');
+    expect(banner?.querySelector('svg')).not.toBeNull();
+    const button = banner?.querySelector('button');
+    expect(button?.className).toContain('text-primary');
+    expect(button?.className).not.toContain('text-black');
+    expect(button?.textContent).toBe(
+      'modals.uploadDoc.connectors.auth.disconnect',
+    );
+    act(() => button?.click());
+    expect(onDisconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders the auth button as a default brand button', () => {
+    render({});
+    const button = container.querySelector('button');
+    expect(button?.textContent).toContain('Connect');
+    expect(button?.className).toContain('bg-primary');
+    expect(button?.className).not.toContain('bg-blue-500');
+  });
+});
diff --git a/frontend/src/components/ConnectorAuth.tsx b/frontend/src/components/ConnectorAuth.tsx
index f18c077e..a7fa776c 100644
--- a/frontend/src/components/ConnectorAuth.tsx
+++ b/frontend/src/components/ConnectorAuth.tsx
@@ -1,11 +1,12 @@
+import { CircleCheck, TriangleAlert } from 'lucide-react';
 import React, { useEffect, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 
 import userService from '../api/services/userService';
-import { useDarkTheme } from '../hooks';
 import { selectToken } from '../preferences/preferenceSlice';
 import { isTrustedConnectorMessage } from '../utils/connectorAuthUtils';
+import { Alert, AlertDescription } from './ui/alert';
 import { Button } from './ui/button';
 
 interface ConnectorAuthProps {
@@ -31,7 +32,6 @@ const ConnectorAuth: React.FC<ConnectorAuthProps> = ({
 }) => {
   const { t } = useTranslation();
   const token = useSelector(selectToken);
-  const [isDarkTheme] = useDarkTheme();
   const completedRef = useRef(false);
   const intervalRef = useRef<number | null>(null);
   const authWindowRef = useRef<Window | null>(null);
@@ -208,67 +208,36 @@ const ConnectorAuth: React.FC<ConnectorAuthProps> = ({
   return (
     <>
       {errorMessage && (
-        <div className="mb-4 flex items-center gap-2 rounded-lg border border-[#E60000] bg-transparent p-2 dark:border-[#D42626] dark:bg-[#D426261A]">
-          <svg
-            width="30"
-            height="30"
-            viewBox="0 0 30 30"
-            fill="none"
-            xmlns="http://www.w3.org/2000/svg"
-          >
-            <path
-              d="M7.09974 24.5422H22.9C24.5156 24.5422 25.5228 22.7901 24.715 21.3947L16.8149 7.74526C16.007 6.34989 13.9927 6.34989 13.1848 7.74526L5.28471 21.3947C4.47686 22.7901 5.48405 24.5422 7.09974 24.5422ZM14.9998 17.1981C14.4228 17.1981 13.9507 16.726 13.9507 16.149V14.0507C13.9507 13.4736 14.4228 13.0015 14.9998 13.0015C15.5769 13.0015 16.049 13.4736 16.049 14.0507V16.149C16.049 16.726 15.5769 17.1981 14.9998 17.1981ZM16.049 21.3947H13.9507V19.2964H16.049V21.3947Z"
-              fill={isDarkTheme ? '#EECF56' : '#E60000'}
-            />
-          </svg>
-
-          <span
-            className="text-sm text-[#E60000] dark:text-red-400"
-            style={{
-              fontFamily: 'Inter',
-              lineHeight: '100%',
-            }}
-          >
-            {errorMessage}
-          </span>
-        </div>
+        <Alert variant="destructive" className="mb-4">
+          <TriangleAlert aria-hidden="true" />
+          <AlertDescription>{errorMessage}</AlertDescription>
+        </Alert>
       )}
 
       {isConnected ? (
-        <div className="mb-4">
-          <div className="flex w-full items-center justify-between rounded-lg bg-[#8FDD51] px-4 py-2 text-sm font-medium text-black">
-            <div className="flex max-w-[500px] items-center gap-2">
-              <svg className="h-4 w-4" viewBox="0 0 24 24">
-                <path
-                  fill="currentColor"
-                  d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"
-                />
-              </svg>
-              <span>
-                {t('modals.uploadDoc.connectors.auth.connectedAs', {
-                  email: userEmail,
-                })}
-              </span>
-            </div>
+        <Alert variant="success" className="mb-4">
+          <CircleCheck aria-hidden="true" />
+          <AlertDescription className="flex items-center justify-between">
+            <span className="max-w-[500px]">
+              {t('modals.uploadDoc.connectors.auth.connectedAs', {
+                email: userEmail,
+              })}
+            </span>
             {onDisconnect && (
               <Button
                 type="button"
                 variant="link"
-                size="sm"
+                size="xs"
                 onClick={onDisconnect}
-                className="h-auto p-0 text-xs text-black underline hover:text-gray-700"
+                className="-my-1 ml-2 shrink-0"
               >
                 {t('modals.uploadDoc.connectors.auth.disconnect')}
               </Button>
             )}
-          </div>
-        </div>
+          </AlertDescription>
+        </Alert>
       ) : (
-        <Button
-          type="button"
-          onClick={handleAuth}
-          className="w-full rounded-lg bg-blue-500 px-4 py-3 text-white hover:bg-blue-600"
-        >
+        <Button type="button" onClick={handleAuth} className="w-full">
           <svg className="h-5 w-5" viewBox="0 0 24 24">
             <path
               fill="currentColor"
diff --git a/frontend/src/components/ConnectorTree.tsx b/frontend/src/components/ConnectorTree.tsx
index 99bb30ca..abd655e4 100644
--- a/frontend/src/components/ConnectorTree.tsx
+++ b/frontend/src/components/ConnectorTree.tsx
@@ -111,8 +111,8 @@ const ConnectorTree: React.FC<ConnectorTreeProps> = ({
         disabled={isSyncing}
         className={`flex h-[38px] min-w-[108px] items-center justify-center rounded-full px-4 text-sm font-medium whitespace-nowrap transition-colors ${
           isSyncing
-            ? 'dark:bg-muted dark:text-muted-foreground cursor-not-allowed bg-gray-300 text-gray-600'
-            : 'bg-primary hover:bg-primary/90 text-white'
+            ? 'bg-muted text-muted-foreground cursor-not-allowed'
+            : 'bg-primary hover:bg-primary/90 text-primary-foreground'
         }`}
         title={
           isSyncing
diff --git a/frontend/src/components/CopyButton.test.tsx b/frontend/src/components/CopyButton.test.tsx
new file mode 100644
index 00000000..add10cd6
--- /dev/null
+++ b/frontend/src/components/CopyButton.test.tsx
@@ -0,0 +1,88 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+const copyMock = vi.fn<(text: string) => boolean>(() => true);
+vi.mock('copy-to-clipboard', () => ({
+  default: (text: string) => copyMock(text),
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import CopyButton from './CopyButton';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('CopyButton', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    copyMock.mockClear();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.useRealTimers();
+  });
+
+  function button(): HTMLButtonElement {
+    const el = container.querySelector('button');
+    if (!el) throw new Error('no button');
+    return el;
+  }
+
+  async function click() {
+    await act(async () => {
+      button().click();
+    });
+  }
+
+  it('renders an idle ghost-muted icon button', () => {
+    act(() => root.render(<CopyButton textToCopy="hello" />));
+    expect(button().getAttribute('aria-label')).toBe('conversation.copy');
+    expect(button().dataset.variant).toBe('ghost-muted');
+    expect(button().dataset.size).toBe('icon-sm');
+    expect(button().dataset.shape).toBe('pill');
+  });
+
+  it('uses icon-xs when size is xs and xs with text', () => {
+    act(() => root.render(<CopyButton textToCopy="hello" size="xs" />));
+    expect(button().dataset.size).toBe('icon-xs');
+    act(() => root.render(<CopyButton textToCopy="hello" showText />));
+    expect(button().dataset.size).toBe('xs');
+    expect(button().textContent).toContain('conversation.copy');
+  });
+
+  it('copies the text and shows the copied state without disabling', async () => {
+    act(() => root.render(<CopyButton textToCopy="hello" showText />));
+    await click();
+
+    expect(copyMock).toHaveBeenCalledWith('hello');
+    expect(button().getAttribute('aria-label')).toBe('conversation.copied');
+    expect(button().dataset.variant).toBe('secondary');
+    expect(button().hasAttribute('disabled')).toBe(false);
+    expect(button().textContent).toContain('conversation.copied');
+  });
+
+  it('ignores clicks while copied and resets after the timeout', async () => {
+    act(() =>
+      root.render(<CopyButton textToCopy="hello" copiedDuration={1000} />),
+    );
+    await click();
+    await click();
+    expect(copyMock).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(button().getAttribute('aria-label')).toBe('conversation.copy');
+    expect(button().dataset.variant).toBe('ghost-muted');
+  });
+});
diff --git a/frontend/src/components/CopyButton.tsx b/frontend/src/components/CopyButton.tsx
index 69285193..b6b9a3bc 100644
--- a/frontend/src/components/CopyButton.tsx
+++ b/frontend/src/components/CopyButton.tsx
@@ -1,71 +1,38 @@
-import clsx from 'clsx';
 import copy from 'copy-to-clipboard';
+import { Check, Copy } from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
-import CheckMark from '../assets/checkmark.svg?react';
-import CopyIcon from '../assets/copy.svg?react';
 import { Button } from './ui/button';
 
 type CopyButtonProps = {
   textToCopy: string;
-  iconSize?: string;
-  padding?: string;
+  /** Icon-only button size: `xs` is `icon-xs` (28px), `sm` is `icon-sm` (32px). */
+  size?: 'xs' | 'sm';
+  /** Show a "Copy"/"Copied" label next to the icon (renders at Button `xs`). */
   showText?: boolean;
   copiedDuration?: number;
   className?: string;
-  iconWrapperClassName?: string;
-  textClassName?: string;
 };
 
-const DEFAULT_ICON_SIZE = 'w-4 h-4';
-const DEFAULT_PADDING = 'p-2';
 const DEFAULT_COPIED_DURATION = 2000;
 
 export default function CopyButton({
   textToCopy,
-  iconSize = DEFAULT_ICON_SIZE,
-  padding = DEFAULT_PADDING,
+  size = 'sm',
   showText = false,
   copiedDuration = DEFAULT_COPIED_DURATION,
   className,
-  iconWrapperClassName,
-  textClassName,
 }: CopyButtonProps) {
   const { t } = useTranslation();
   const [isCopied, setIsCopied] = useState(false);
   const timeoutIdRef = useRef<number | null>(null);
-  // `copy` is async, so `isCopied` and the disabled prop only catch up after it
-  // resolves. Guard that window so rapid clicks cannot start a second write.
+  // `copy` is async, so `isCopied` only catches up after it resolves. Guard
+  // that window so rapid clicks cannot start a second write. The button is
+  // never disabled, so the copied confirmation does not fade.
   const copyInFlightRef = useRef(false);
 
-  const iconWrapperClasses = clsx(
-    'flex items-center justify-center rounded-full transition-colors duration-150 ease-in-out',
-    padding,
-    {
-      [`bg-transparent hover:bg-muted`]: !isCopied,
-      'bg-green-100 dark:bg-green-900 hover:bg-green-100 dark:hover:bg-green-900':
-        isCopied,
-    },
-    iconWrapperClassName,
-  );
-
-  const rootButtonClasses = clsx(
-    'group h-auto rounded-full bg-transparent p-0 hover:bg-transparent disabled:opacity-100',
-    className,
-  );
-
-  const textSpanClasses = clsx(
-    'text-xs text-gray-600 dark:text-gray-400 transition-opacity duration-150 ease-in-out',
-    { 'opacity-75': isCopied },
-    textClassName,
-  );
-
-  const IconComponent = isCopied ? CheckMark : CopyIcon;
-  const iconClasses = clsx(iconSize, {
-    'stroke-green-600 dark:stroke-green-400': isCopied,
-    'fill-none text-gray-700 dark:text-gray-300': !isCopied,
-  });
+  const IconComponent = isCopied ? Check : Copy;
 
   const buttonTitle = isCopied
     ? t('conversation.copied')
@@ -111,17 +78,16 @@ export default function CopyButton({
   return (
     <Button
       type="button"
-      variant="ghost"
+      variant={isCopied ? 'secondary' : 'ghost-muted'}
+      size={showText ? 'xs' : size === 'xs' ? 'icon-xs' : 'icon-sm'}
+      shape="pill"
       onClick={handleCopy}
-      className={rootButtonClasses}
+      className={className}
       title={buttonTitle}
       aria-label={buttonTitle}
-      disabled={isCopied}
     >
-      <div className={iconWrapperClasses}>
-        <IconComponent className={iconClasses} aria-hidden="true" />
-      </div>
-      {showText && <span className={textSpanClasses}>{displayedText}</span>}
+      <IconComponent aria-hidden="true" />
+      {showText && <span>{displayedText}</span>}
       <span className="sr-only" aria-live="polite" aria-atomic="true">
         {isCopied ? t('conversation.copied', 'Copied to clipboard') : ''}
       </span>
diff --git a/frontend/src/components/DocumentArtifactView.tsx b/frontend/src/components/DocumentArtifactView.tsx
index 1050c3e2..447dcce2 100644
--- a/frontend/src/components/DocumentArtifactView.tsx
+++ b/frontend/src/components/DocumentArtifactView.tsx
@@ -86,7 +86,7 @@ function FramePreview({
 
   if (renderError) {
     return (
-      <pre className="overflow-auto p-4 text-xs text-gray-600 dark:text-gray-400">
+      <pre className="text-muted-foreground overflow-auto p-4 text-xs">
         {source}
       </pre>
     );
@@ -107,7 +107,7 @@ function FramePreview({
       // No allow-same-origin: content is fully isolated from the app origin.
       sandbox=""
       title="Artifact preview"
-      className="h-full w-full rounded-md border border-gray-200 bg-white dark:border-gray-700"
+      className="border-border h-full w-full rounded-md border bg-white"
       srcDoc={buildPreviewDocument(previewKind, rendered)}
     />
   );
@@ -126,16 +126,14 @@ function DownloadCard({
 }) {
   return (
     <div className="flex h-full flex-col items-center justify-center gap-4">
-      <div className="flex flex-col items-center gap-3 rounded-xl border border-gray-200 p-8 text-center dark:border-gray-700">
-        <FileText className="h-12 w-12 text-gray-400" />
+      <div className="border-border flex flex-col items-center gap-3 rounded-xl border p-8 text-center">
+        <FileText className="text-muted-foreground h-12 w-12" />
         <div>
-          <p className="text-sm font-medium break-all text-gray-800 dark:text-gray-200">
+          <p className="text-foreground text-sm font-medium break-all">
             {filename}
           </p>
           {size != null && (
-            <p className="text-xs text-gray-500 dark:text-gray-400">
-              {formatBytes(size)}
-            </p>
+            <p className="text-muted-foreground text-xs">{formatBytes(size)}</p>
           )}
         </div>
         <Button
@@ -207,7 +205,7 @@ function BytesPreview({
         // No allow-same-origin / no scripts: bytes are isolated from the app origin.
         sandbox=""
         title="Artifact preview"
-        className="h-full w-full rounded-md border border-gray-200 bg-white dark:border-gray-700"
+        className="border-border h-full w-full rounded-md border bg-white"
         srcDoc={buildPreviewDocument(
           mode === 'iframe-svg' ? 'svg' : 'html',
           state.text,
@@ -219,7 +217,7 @@ function BytesPreview({
     return <MarkdownPreview content={state.text} />;
   }
   return (
-    <pre className="h-full overflow-auto p-4 text-xs whitespace-pre-wrap text-gray-700 dark:text-gray-300">
+    <pre className="text-foreground h-full overflow-auto p-4 text-xs whitespace-pre-wrap">
       {state.text}
     </pre>
   );
@@ -340,7 +338,7 @@ export default function DocumentArtifactView({
         : (selectedRow?.preview_text ?? '');
       if (text) {
         return (
-          <pre className="h-full overflow-auto p-4 text-xs whitespace-pre-wrap text-gray-700 dark:text-gray-300">
+          <pre className="text-foreground h-full overflow-auto p-4 text-xs whitespace-pre-wrap">
             {text}
           </pre>
         );
@@ -379,7 +377,7 @@ export default function DocumentArtifactView({
           value={String(selectedVersion)}
           onValueChange={(v) => setSelectedVersion(Number(v))}
         >
-          <SelectTrigger className="h-8 w-auto gap-2 rounded-md px-3 text-xs">
+          <SelectTrigger size="sm" className="w-auto">
             <History className="h-3.5 w-3.5" />
             <SelectValue />
           </SelectTrigger>
@@ -426,7 +424,7 @@ export default function DocumentArtifactView({
         )}
       </div>
 
-      {actionError && <p className="text-xs text-red-500">{actionError}</p>}
+      {actionError && <p className="text-destructive text-xs">{actionError}</p>}
 
       <div className="min-h-0 flex-1 overflow-hidden">{renderPreview()}</div>
     </div>
diff --git a/frontend/src/components/DocumentPagination.test.tsx b/frontend/src/components/DocumentPagination.test.tsx
new file mode 100644
index 00000000..489ab9e2
--- /dev/null
+++ b/frontend/src/components/DocumentPagination.test.tsx
@@ -0,0 +1,76 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import Pagination from './DocumentPagination';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('DocumentPagination rows-per-page', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async (onRowsPerPageChange = vi.fn()) => {
+    await act(async () => {
+      root.render(
+        <Pagination
+          currentPage={1}
+          totalPages={3}
+          rowsPerPage={10}
+          onPageChange={vi.fn()}
+          onRowsPerPageChange={onRowsPerPageChange}
+        />,
+      );
+    });
+    return onRowsPerPageChange;
+  };
+
+  const trigger = () =>
+    document.body.querySelector<HTMLButtonElement>(
+      '[data-slot="select-trigger"]',
+    );
+
+  it('shows the current value in a labelled combobox trigger', async () => {
+    await render();
+    const el = trigger();
+    expect(el).not.toBeNull();
+    expect(el!.getAttribute('role')).toBe('combobox');
+    expect(el!.getAttribute('aria-label')).toBe('pagination.rowsPerPage');
+    expect(el!.getAttribute('data-size')).toBe('sm');
+    expect(el!.textContent).toContain('10');
+  });
+
+  it('calls onRowsPerPageChange with the chosen number', async () => {
+    const onChange = await render();
+    const el = trigger()!;
+    await act(async () => {
+      el.dispatchEvent(
+        new PointerEvent('pointerdown', {
+          bubbles: true,
+          button: 0,
+          pointerType: 'mouse',
+        }),
+      );
+    });
+    const option = Array.from(
+      document.body.querySelectorAll<HTMLElement>('[role="option"]'),
+    ).find((o) => o.textContent === '50');
+    expect(option).toBeDefined();
+    await act(async () => option!.click());
+    expect(onChange).toHaveBeenCalledWith(50);
+  });
+});
diff --git a/frontend/src/components/DocumentPagination.tsx b/frontend/src/components/DocumentPagination.tsx
index 94692bfe..8461a1d5 100644
--- a/frontend/src/components/DocumentPagination.tsx
+++ b/frontend/src/components/DocumentPagination.tsx
@@ -1,10 +1,17 @@
-import React, { useState } from 'react';
+import React from 'react';
 import { useTranslation } from 'react-i18next';
 import SingleArrowLeft from '../assets/single-left-arrow.svg';
 import SingleArrowRight from '../assets/single-right-arrow.svg';
 import DoubleArrowLeft from '../assets/double-arrow-left.svg';
 import DoubleArrowRight from '../assets/double-arrow-right.svg';
 import { Button } from './ui/button';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from './ui/select';
 
 interface PaginationProps {
   currentPage: number;
@@ -22,11 +29,8 @@ const Pagination: React.FC<PaginationProps> = ({
   onRowsPerPageChange,
 }) => {
   const { t } = useTranslation();
-  const [isDropdownOpen, setIsDropdownOpen] = useState(false);
   const rowsPerPageOptions = [5, 10, 20, 50];
 
-  const toggleDropdown = () => setIsDropdownOpen((prev) => !prev);
-
   const handlePreviousPage = () => {
     if (currentPage > 1) {
       onPageChange(currentPage - 1);
@@ -48,63 +52,42 @@ const Pagination: React.FC<PaginationProps> = ({
   };
 
   const handleSelectRowsPerPage = (rows: number) => {
-    setIsDropdownOpen(false);
     onRowsPerPageChange(rows);
   };
 
   return (
-    <div className="mt-2 flex items-center justify-end gap-4 border-gray-200 p-2 text-xs">
+    <div className="mt-2 flex items-center justify-end gap-4 p-2 text-xs">
       {/* Rows per page dropdown */}
       <div className="relative flex items-center gap-2">
-        <span className="text-gray-900 dark:text-gray-50">
-          {t('pagination.rowsPerPage')}:
-        </span>
-        <div className="relative">
-          <Button
-            type="button"
-            variant="outline"
-            size="sm"
-            onClick={toggleDropdown}
-            className="dark:bg-card h-auto rounded px-3 py-1 shadow-none"
-          >
-            {rowsPerPage}
-          </Button>
-          <div
-            className={`ring-opacity-5 dark:bg-card bg-card absolute right-0 z-50 mt-1 w-28 transform shadow-lg ring-1 ring-black transition-all duration-200 ease-in-out ${
-              isDropdownOpen
-                ? 'block scale-100 opacity-100'
-                : 'hidden scale-95 opacity-0'
-            }`}
-          >
+        <span className="text-foreground">{t('pagination.rowsPerPage')}:</span>
+        <Select
+          value={String(rowsPerPage)}
+          onValueChange={(value) => handleSelectRowsPerPage(Number(value))}
+        >
+          <SelectTrigger size="sm" aria-label={t('pagination.rowsPerPage')}>
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
             {rowsPerPageOptions.map((option) => (
-              <div
-                key={option}
-                onClick={() => handleSelectRowsPerPage(option)}
-                className={`hover:bg-accent dark:hover:bg-accent cursor-pointer px-4 py-2 text-xs ${
-                  rowsPerPage === option
-                    ? 'dark:text-foreground bg-gray-100 dark:bg-neutral-700'
-                    : 'bg-card dark:text-foreground'
-                }`}
-              >
+              <SelectItem key={option} value={String(option)}>
                 {option}
-              </div>
+              </SelectItem>
             ))}
-          </div>
-        </div>
+          </SelectContent>
+        </Select>
       </div>
 
       {/* Pagination controls */}
-      <div className="text-gray-900 dark:text-gray-50">
+      <div className="text-foreground">
         {t('pagination.pageOf', { currentPage, totalPages })}
       </div>
-      <div className="flex items-center gap-2 text-gray-900 dark:text-gray-50">
+      <div className="text-foreground flex items-center gap-2">
         <Button
           type="button"
           variant="outline"
-          size="sm"
+          size="icon-xs"
           onClick={handleFirstPage}
           disabled={currentPage === 1}
-          className="h-auto rounded px-2 py-1 shadow-none"
         >
           <img
             src={DoubleArrowLeft}
@@ -115,10 +98,9 @@ const Pagination: React.FC<PaginationProps> = ({
         <Button
           type="button"
           variant="outline"
-          size="sm"
+          size="icon-xs"
           onClick={handlePreviousPage}
           disabled={currentPage === 1}
-          className="h-auto rounded px-2 py-1 shadow-none"
         >
           <img
             src={SingleArrowLeft}
@@ -129,10 +111,9 @@ const Pagination: React.FC<PaginationProps> = ({
         <Button
           type="button"
           variant="outline"
-          size="sm"
+          size="icon-xs"
           onClick={handleNextPage}
           disabled={currentPage === totalPages}
-          className="h-auto rounded px-2 py-1 shadow-none"
         >
           <img
             src={SingleArrowRight}
@@ -143,10 +124,9 @@ const Pagination: React.FC<PaginationProps> = ({
         <Button
           type="button"
           variant="outline"
-          size="sm"
+          size="icon-xs"
           onClick={handleLastPage}
           disabled={currentPage === totalPages}
-          className="h-auto rounded px-2 py-1 shadow-none"
         >
           <img
             src={DoubleArrowRight}
diff --git a/frontend/src/components/FilePicker.test.tsx b/frontend/src/components/FilePicker.test.tsx
new file mode 100644
index 00000000..e6a4772b
--- /dev/null
+++ b/frontend/src/components/FilePicker.test.tsx
@@ -0,0 +1,109 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+const validateConnectorSession = vi.fn();
+const getConnectorFiles = vi.fn();
+vi.mock('../api/services/userService', () => ({
+  default: {
+    validateConnectorSession: (...args: unknown[]) =>
+      validateConnectorSession(...args),
+    getConnectorFiles: (...args: unknown[]) => getConnectorFiles(...args),
+    disconnectConnector: vi.fn(),
+  },
+}));
+
+vi.mock('../utils/providerUtils', () => ({
+  getSessionToken: () => 'session-token',
+  setSessionToken: vi.fn(),
+  removeSessionToken: vi.fn(),
+}));
+
+vi.mock('../components/ConnectorAuth', () => ({ default: () => null }));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { FilePicker } from './FilePicker';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('FilePicker', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    validateConnectorSession.mockReset();
+    getConnectorFiles.mockReset();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it('shows an expired session as a destructive alert', async () => {
+    validateConnectorSession.mockResolvedValue({ ok: false });
+    await act(async () => {
+      root.render(
+        <FilePicker
+          provider="google_drive"
+          token={null}
+          onSelectionChange={() => undefined}
+        />,
+      );
+    });
+    const alert = container.querySelector('[role="alert"]');
+    expect(alert?.textContent).toContain('Session expired');
+    expect(alert?.querySelector('svg')).not.toBeNull();
+  });
+
+  async function renderSharePoint() {
+    validateConnectorSession.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        success: true,
+        user_email: 'lena@meridian.example',
+        allows_shared_content: true,
+      }),
+    });
+    getConnectorFiles.mockResolvedValue({
+      json: async () => ({ success: true, files: [], next_page_token: null }),
+    });
+    await act(async () => {
+      root.render(
+        <FilePicker
+          provider="share_point"
+          token={null}
+          onSelectionChange={() => undefined}
+        />,
+      );
+    });
+  }
+
+  it('renders the drive switch as underline tabs with the active one marked', async () => {
+    await renderSharePoint();
+    const tabs = Array.from(
+      container.querySelectorAll('[data-slot="button"][data-variant="tab"]'),
+    );
+    expect(tabs.map((tab) => tab.textContent)).toEqual([
+      'filePicker.myFiles',
+      'filePicker.sharedWithMe',
+    ]);
+    expect(tabs[0].getAttribute('data-active')).toBe('true');
+    expect(tabs[1].getAttribute('data-active')).not.toBe('true');
+  });
+
+  it('shows the folder trail as a breadcrumb with the current folder as the page', async () => {
+    await renderSharePoint();
+    const trail = container.querySelector('nav[aria-label="breadcrumb"]');
+    expect(trail).not.toBeNull();
+    const page = trail?.querySelector('[data-slot="breadcrumb-page"]');
+    expect(page?.textContent).toBe('My Files');
+    expect(page?.getAttribute('title')).toBe('My Files');
+    expect(trail?.querySelector('button[disabled]')).toBeNull();
+  });
+});
diff --git a/frontend/src/components/FilePicker.tsx b/frontend/src/components/FilePicker.tsx
index d8437d42..ced97c52 100644
--- a/frontend/src/components/FilePicker.tsx
+++ b/frontend/src/components/FilePicker.tsx
@@ -1,5 +1,11 @@
-import { Search as SearchIcon } from 'lucide-react';
-import React, { useState, useEffect, useCallback, useRef } from 'react';
+import { Search as SearchIcon, TriangleAlert } from 'lucide-react';
+import React, {
+  Fragment,
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+} from 'react';
 import { useTranslation } from 'react-i18next';
 import userService from '../api/services/userService';
 import { formatBytes } from '../utils/stringUtils';
@@ -13,6 +19,15 @@ import ConnectorAuth from '../components/ConnectorAuth';
 import FileIcon from '../assets/file.svg';
 import FolderIcon from '../assets/folder.svg';
 import CheckIcon from '../assets/checkmark.svg';
+import { Alert, AlertDescription } from './ui/alert';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from './ui/breadcrumb';
 import { Button } from './ui/button';
 import { Input } from './ui/input';
 import {
@@ -379,7 +394,10 @@ export const FilePicker: React.FC<CloudFilePickerProps> = ({
   return (
     <div className="">
       {authError && (
-        <div className="mb-4 text-center text-sm text-red-500">{authError}</div>
+        <Alert variant="destructive" className="mb-4">
+          <TriangleAlert aria-hidden="true" />
+          <AlertDescription>{authError}</AlertDescription>
+        </Alert>
       )}
 
       <ConnectorAuth
@@ -429,59 +447,61 @@ export const FilePicker: React.FC<CloudFilePickerProps> = ({
       />
 
       {isConnected && (
-        <div className="border-border dark:border-border mt-3 overflow-hidden rounded-lg border">
-          <div className="border-border dark:border-border rounded-t-lg">
+        <div className="border-border mt-3 overflow-hidden rounded-lg border">
+          <div className="border-border rounded-t-lg">
             {provider === 'share_point' && allowsSharedContent && (
-              <div className="border-border dark:border-border flex border-b">
+              <div className="border-border flex border-b">
                 <Button
                   type="button"
-                  variant="ghost"
+                  variant="tab"
+                  data-active={activeTab === 'my_files'}
                   onClick={() => handleTabChange('my_files')}
-                  className={`h-auto rounded-none px-4 py-2 text-sm font-medium ${
-                    activeTab === 'my_files'
-                      ? 'border-b-2 border-[#A076F6] text-[#A076F6] hover:bg-transparent hover:text-[#A076F6]'
-                      : 'text-gray-600 hover:text-gray-800 dark:text-gray-400 dark:hover:text-gray-200'
-                  }`}
                 >
                   {t('filePicker.myFiles')}
                 </Button>
                 <Button
                   type="button"
-                  variant="ghost"
+                  variant="tab"
+                  data-active={activeTab === 'shared'}
                   onClick={() => handleTabChange('shared')}
-                  className={`h-auto rounded-none px-4 py-2 text-sm font-medium ${
-                    activeTab === 'shared'
-                      ? 'border-b-2 border-[#A076F6] text-[#A076F6] hover:bg-transparent hover:text-[#A076F6]'
-                      : 'text-gray-600 hover:text-gray-800 dark:text-gray-400 dark:hover:text-gray-200'
-                  }`}
                 >
                   {t('filePicker.sharedWithMe')}
                 </Button>
               </div>
             )}
-            <div className="dark:bg-muted rounded-t-lg bg-[#EEE6FF78] px-4 pt-4">
-              <div className="mb-2 flex items-center gap-1">
-                {folderPath.map((path, index) => (
-                  <div
-                    key={path.id || 'root'}
-                    className="flex items-center gap-1"
-                  >
-                    {index > 0 && <span className="text-gray-400">/</span>}
-                    <Button
-                      type="button"
-                      variant="link"
-                      size="sm"
-                      onClick={() => navigateBack(index)}
-                      className="h-auto p-0 text-sm text-[#A076F6] underline-offset-2 hover:text-[#8A5FD4]"
-                      disabled={index === folderPath.length - 1}
-                    >
-                      {path.name}
-                    </Button>
-                  </div>
-                ))}
-              </div>
+            <div className="bg-muted rounded-t-lg px-4 pt-4">
+              <Breadcrumb className="mb-2 min-w-0">
+                <BreadcrumbList className="flex-nowrap">
+                  {folderPath.map((path, index) => (
+                    <Fragment key={path.id || 'root'}>
+                      {index > 0 && <BreadcrumbSeparator />}
+                      {index === folderPath.length - 1 ? (
+                        <BreadcrumbItem className="min-w-0">
+                          <BreadcrumbPage
+                            title={path.name}
+                            className="max-w-[32ch]"
+                          >
+                            {path.name}
+                          </BreadcrumbPage>
+                        </BreadcrumbItem>
+                      ) : (
+                        <BreadcrumbItem>
+                          <BreadcrumbLink asChild>
+                            <button
+                              type="button"
+                              onClick={() => navigateBack(index)}
+                            >
+                              {path.name}
+                            </button>
+                          </BreadcrumbLink>
+                        </BreadcrumbItem>
+                      )}
+                    </Fragment>
+                  ))}
+                </BreadcrumbList>
+              </Breadcrumb>
 
-              <div className="mb-3 text-sm text-gray-600 dark:text-gray-400">
+              <div className="text-muted-foreground mb-3 text-sm">
                 Select Files from {getProviderConfig(provider).displayName}
               </div>
 
@@ -491,7 +511,7 @@ export const FilePicker: React.FC<CloudFilePickerProps> = ({
                   label={t('filePicker.searchPlaceholder')}
                   value={searchQuery}
                   onChange={(e) => handleSearchChange(e.target.value)}
-                  labelBgClassName="bg-[#EEE6FF78] dark:bg-muted"
+                  labelSurface="muted"
                   leftIcon={
                     <SearchIcon
                       className="text-muted-foreground size-4"
@@ -502,18 +522,18 @@ export const FilePicker: React.FC<CloudFilePickerProps> = ({
               </div>
 
               {/* Selected Files Message */}
-              <div className="pb-3 text-sm text-gray-600 dark:text-gray-400">
+              <div className="text-muted-foreground pb-3 text-sm">
                 {t('filePicker.itemsSelected', {
                   count: selectedFiles.length + selectedFolders.length,
                 })}
               </div>
             </div>
 
-            <div className="border-border dark:border-border h-72 border-t">
+            <div className="border-border scrollbar-overlay h-72 border-t">
               <TableContainer
                 ref={scrollContainerRef}
                 height="288px"
-                className="scrollbar-overlay md:w-4xl lg:w-5xl"
+                className="md:w-4xl lg:w-5xl"
                 bordered={false}
               >
                 {
@@ -538,16 +558,16 @@ export const FilePicker: React.FC<CloudFilePickerProps> = ({
                           ? Array.from({ length: 5 }).map((_, i) => (
                               <TableRow key={`skeleton-${i}`}>
                                 <TableCell width="40px" align="center">
-                                  <div className="mx-auto h-5 w-5 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                  <div className="bg-muted mx-auto h-5 w-5 animate-pulse rounded" />
                                 </TableCell>
                                 <TableCell>
-                                  <div className="h-4 w-48 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                  <div className="bg-muted h-4 w-48 animate-pulse rounded" />
                                 </TableCell>
                                 <TableCell>
-                                  <div className="h-4 w-24 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                  <div className="bg-muted h-4 w-24 animate-pulse rounded" />
                                 </TableCell>
                                 <TableCell>
-                                  <div className="h-4 w-16 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                  <div className="bg-muted h-4 w-16 animate-pulse rounded" />
                                 </TableCell>
                               </TableRow>
                             ))
@@ -564,7 +584,7 @@ export const FilePicker: React.FC<CloudFilePickerProps> = ({
                               >
                                 <TableCell width="40px" align="center">
                                   <div
-                                    className="border-border dark:border-border mx-auto flex h-5 w-5 shrink-0 cursor-pointer items-center justify-center border p-[0.5px] text-sm"
+                                    className="border-border mx-auto flex h-5 w-5 shrink-0 cursor-pointer items-center justify-center border text-sm"
                                     onClick={(e) => {
                                       e.stopPropagation();
                                       handleFileSelect(file.id, isFolder(file));
@@ -611,16 +631,16 @@ export const FilePicker: React.FC<CloudFilePickerProps> = ({
                           Array.from({ length: 3 }).map((_, i) => (
                             <TableRow key={`load-more-skeleton-${i}`}>
                               <TableCell width="40px" align="center">
-                                <div className="mx-auto h-5 w-5 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                <div className="bg-muted mx-auto h-5 w-5 animate-pulse rounded" />
                               </TableCell>
                               <TableCell>
-                                <div className="h-4 w-48 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                <div className="bg-muted h-4 w-48 animate-pulse rounded" />
                               </TableCell>
                               <TableCell>
-                                <div className="h-4 w-24 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                <div className="bg-muted h-4 w-24 animate-pulse rounded" />
                               </TableCell>
                               <TableCell>
-                                <div className="h-4 w-16 animate-pulse rounded bg-gray-200 dark:bg-gray-700" />
+                                <div className="bg-muted h-4 w-16 animate-pulse rounded" />
                               </TableCell>
                             </TableRow>
                           ))}
diff --git a/frontend/src/components/FileUpload.test.tsx b/frontend/src/components/FileUpload.test.tsx
new file mode 100644
index 00000000..33f3ccc4
--- /dev/null
+++ b/frontend/src/components/FileUpload.test.tsx
@@ -0,0 +1,111 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { FileUpload } from './FileUpload';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+function makeFile(name: string, type: string, bytes = 10): File {
+  return new File([new Uint8Array(bytes)], name, { type });
+}
+
+async function selectFiles(container: HTMLElement, files: File[]) {
+  const input = container.querySelector('input[type="file"]');
+  if (!input) throw new Error('no file input');
+  Object.defineProperty(input, 'files', { value: files, configurable: true });
+  await act(async () => {
+    input.dispatchEvent(new Event('change', { bubbles: true }));
+  });
+  // react-dropzone resolves the selected files asynchronously.
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+describe('FileUpload', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  it('renders on the shared Dropzone with the upload prompt', async () => {
+    await act(async () => {
+      root.render(<FileUpload onUpload={vi.fn()} />);
+    });
+    const zone = container.querySelector('[data-slot="dropzone"]');
+    expect(zone).not.toBeNull();
+    expect(zone?.getAttribute('data-size')).toBe('default');
+    expect(container.textContent).toContain(
+      'components.fileUpload.clickToUpload',
+    );
+    expect(container.textContent).toContain('components.fileUpload.fileTypes');
+  });
+
+  it('passes the compact size through', async () => {
+    await act(async () => {
+      root.render(<FileUpload onUpload={vi.fn()} size="compact" />);
+    });
+    expect(
+      container
+        .querySelector('[data-slot="dropzone"]')
+        ?.getAttribute('data-size'),
+    ).toBe('compact');
+  });
+
+  it('renders highlighted upload text segments', async () => {
+    await act(async () => {
+      root.render(
+        <FileUpload
+          onUpload={vi.fn()}
+          uploadText={[
+            { text: 'Click to upload', highlight: true },
+            { text: ' or drag and drop' },
+          ]}
+        />,
+      );
+    });
+    const highlighted = Array.from(container.querySelectorAll('span')).find(
+      (s) => s.textContent === 'Click to upload',
+    );
+    expect(highlighted?.className).toContain('text-primary');
+  });
+
+  it('calls onUpload with a valid file', async () => {
+    const onUpload = vi.fn();
+    await act(async () => {
+      root.render(<FileUpload onUpload={onUpload} />);
+    });
+    const file = makeFile('logo.png', 'image/png');
+    await selectFiles(container, [file]);
+    expect(onUpload).toHaveBeenCalledWith([file]);
+  });
+
+  it('shows the validator error and does not upload', async () => {
+    const onUpload = vi.fn();
+    await act(async () => {
+      root.render(
+        <FileUpload
+          onUpload={onUpload}
+          validator={() => ({ isValid: false, error: 'Bad image' })}
+        />,
+      );
+    });
+    await selectFiles(container, [makeFile('logo.png', 'image/png')]);
+    expect(onUpload).not.toHaveBeenCalled();
+    const error = container.querySelector('.text-destructive');
+    expect(error?.textContent).toContain('Bad image');
+  });
+});
diff --git a/frontend/src/components/FileUpload.tsx b/frontend/src/components/FileUpload.tsx
index 73aafa73..5369ca2f 100644
--- a/frontend/src/components/FileUpload.tsx
+++ b/frontend/src/components/FileUpload.tsx
@@ -1,10 +1,16 @@
 import React, { useCallback, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import { useDropzone } from 'react-dropzone';
-import { twMerge } from 'tailwind-merge';
+import type { FileRejection } from 'react-dropzone';
+import { ImageUp } from 'lucide-react';
 
+import { Dropzone } from '@/components/ui/dropzone';
 import Cross from '../assets/cross.svg';
-import ImagesIcon from '../assets/images.svg';
+
+type UploadTextSegment = {
+  text: string;
+  /** Renders the segment in the brand colour; others are muted. */
+  highlight?: boolean;
+};
 
 interface FileUploadProps {
   onUpload: (files: File[]) => void;
@@ -15,14 +21,14 @@ interface FileUploadProps {
   accept?: Record<string, string[]>; // e.g. { 'image/*': ['.png', '.jpg'] }
   showPreview?: boolean;
   previewSize?: number;
+  /** `compact` is a one-row target for forms and panels. */
+  size?: 'default' | 'compact';
 
   children?: React.ReactNode;
+  /** Layout classes only; the Dropzone owns colours, border and radius. */
   className?: string;
-  activeClassName?: string;
-  acceptClassName?: string;
-  rejectClassName?: string;
 
-  uploadText?: string | { text: string; colorClass?: string }[];
+  uploadText?: string | UploadTextSegment[];
   dragActiveText?: string;
   fileTypeText?: string;
   sizeLimitText?: string;
@@ -31,6 +37,13 @@ interface FileUploadProps {
   validator?: (file: File) => { isValid: boolean; error?: string };
 }
 
+/**
+ * Image/file picker built on `ui/dropzone`. Adds size and custom validation,
+ * an optional image preview with a remove button, and translated prompts.
+ *
+ * @param props - See `FileUploadProps`.
+ * @returns The dropzone with its preview and validation errors.
+ */
 export const FileUpload = ({
   onUpload,
   onRemove,
@@ -40,11 +53,9 @@ export const FileUpload = ({
   accept = { 'image/*': ['.jpeg', '.png', '.jpg'] },
   showPreview = false,
   previewSize = 80,
+  size = 'default',
   children,
-  className = 'border-2 border-dashed rounded-3xl p-6 text-center cursor-pointer transition-colors border-border dark:border-border',
-  activeClassName = 'border-blue-500 bg-blue-50',
-  acceptClassName = 'border-green-500 dark:border-green-500 bg-green-50 dark:bg-green-50/10',
-  rejectClassName = 'border-red-500 bg-red-50 dark:bg-red-500/10 dark:border-red-500',
+  className,
   uploadText,
   dragActiveText,
   fileTypeText,
@@ -83,12 +94,12 @@ export const FileUpload = ({
   };
 
   const onDrop = useCallback(
-    (acceptedFiles: File[], fileRejections: any[]) => {
+    (acceptedFiles: File[], fileRejections: FileRejection[]) => {
       setErrors([]);
 
       if (fileRejections.length > 0) {
         const newErrors = fileRejections
-          .map(({ errors }) => errors.map((e: any) => e.message))
+          .map(({ errors }) => errors.map((e) => e.message))
           .flat();
         setErrors(newErrors);
         return;
@@ -117,40 +128,22 @@ export const FileUpload = ({
     [onUpload, multiple, maxSize, validator],
   );
 
-  const {
-    getRootProps,
-    getInputProps,
-    isDragActive,
-    isDragAccept,
-    isDragReject,
-  } = useDropzone({
-    onDrop,
-    multiple,
-    maxFiles,
-    maxSize,
-    accept,
-    disabled,
-  });
-
-  const currentClassName = twMerge(
-    'border-2 border-dashed rounded-3xl p-8 text-center cursor-pointer transition-colors border-border dark:border-border',
-    className,
-    isDragActive && activeClassName,
-    isDragAccept && acceptClassName,
-    isDragReject && rejectClassName,
-    disabled && 'opacity-50 cursor-not-allowed',
-  );
-
   const handleRemove = () => {
     setPreview(null);
     setCurrentFile(null);
     if (onRemove && currentFile) onRemove(currentFile);
   };
 
+  // Callers size the preview box at runtime; a custom property keeps the
+  // dimension out of the style's width/height and in the classes.
+  const previewSizeStyle = {
+    '--preview-size': `${previewSize}px`,
+  } as React.CSSProperties;
+
   const renderPreview = () => (
     <div
-      className="relative"
-      style={{ width: previewSize, height: previewSize }}
+      className="relative size-(--preview-size) shrink-0"
+      style={previewSizeStyle}
     >
       <img
         src={preview ?? undefined}
@@ -170,71 +163,75 @@ export const FileUpload = ({
     </div>
   );
 
-  const renderUploadText = () => {
-    if (Array.isArray(uploadText)) {
-      return (
-        <p className="text-sm font-semibold">
-          {uploadText.map((segment, i) => (
-            <span key={i} className={segment.colorClass || ''}>
-              {segment.text}
-            </span>
-          ))}
-        </p>
-      );
-    }
-    return (
-      <p className="text-sm font-semibold">
-        {uploadText || t('components.fileUpload.clickToUpload')}
-      </p>
-    );
-  };
-
-  const defaultContent = (
-    <div className="flex flex-col items-center gap-2">
-      {showPreview && preview ? (
-        renderPreview()
-      ) : (
-        <div
-          style={{ width: previewSize, height: previewSize }}
-          className="flex items-center justify-center"
+  const uploadPrompt = Array.isArray(uploadText)
+    ? uploadText.map((segment, i) => (
+        <span
+          key={i}
+          className={
+            segment.highlight ? 'text-primary' : 'text-muted-foreground'
+          }
         >
-          <img src={ImagesIcon} className="h-10 w-10" />
-        </div>
-      )}
-      <div className="text-center">
-        <div className="text-sm font-medium">
-          {isDragActive ? (
-            <p className="text-sm font-semibold">
-              {dragActiveText || t('components.fileUpload.dropFiles')}
-            </p>
-          ) : (
-            renderUploadText()
-          )}
-        </div>
-        <p className="mt-1 text-xs text-[#A3A3A3]">
-          {fileTypeText || t('components.fileUpload.fileTypes')}{' '}
-          {maxSize / 1024 / 1024}
-          {sizeLimitText || t('components.fileUpload.sizeLimitUnit')}
-        </p>
-      </div>
-    </div>
+          {segment.text}
+        </span>
+      ))
+    : uploadText || t('components.fileUpload.clickToUpload');
+
+  // The Dropzone owns the drag state; its data attribute swaps the prompt.
+  const title = (
+    <>
+      <span className="in-data-[drag-active]:hidden">{uploadPrompt}</span>
+      <span className="hidden in-data-[drag-active]:inline">
+        {dragActiveText || t('components.fileUpload.dropFiles')}
+      </span>
+    </>
   );
 
+  const description = (
+    <>
+      {fileTypeText || t('components.fileUpload.fileTypes')}{' '}
+      {maxSize / 1024 / 1024}
+      {sizeLimitText || t('components.fileUpload.sizeLimitUnit')}
+    </>
+  );
+
+  // With a preview, the image takes the icon's place; the text block mirrors
+  // the Dropzone's own title/description layout.
+  const previewContent =
+    showPreview && preview ? (
+      <>
+        {renderPreview()}
+        <span className="flex min-w-0 flex-col gap-0.5">
+          <span className="text-sm font-medium">{title}</span>
+          <span className="text-muted-foreground text-xs">{description}</span>
+        </span>
+      </>
+    ) : undefined;
+
+  const error =
+    errors.length > 0
+      ? errors.map((message, i) => (
+          <span key={i} className="block truncate">
+            {message}
+          </span>
+        ))
+      : undefined;
+
   return (
-    <div className="relative">
-      <div {...getRootProps({ className: currentClassName })}>
-        <input {...getInputProps()} />
-        {children || defaultContent}
-        {errors.length > 0 && (
-          <div className="absolute right-0 left-0 mt-[2px] px-4 text-xs text-red-600">
-            {errors.map((error, i) => (
-              <p key={i} className="truncate">
-                {error}
-              </p>
-            ))}
-          </div>
-        )}
-      </div>
-    </div>
+    <Dropzone
+      onDrop={onDrop}
+      accept={accept}
+      multiple={multiple}
+      maxFiles={maxFiles}
+      maxSize={maxSize}
+      disabled={disabled}
+      size={size}
+      title={title}
+      description={description}
+      icon={<ImageUp />}
+      error={error}
+      className={className}
+    >
+      {children ?? previewContent}
+    </Dropzone>
   );
 };
diff --git a/frontend/src/components/GoogleDrivePicker.tsx b/frontend/src/components/GoogleDrivePicker.tsx
index 6cdef9b2..ced4391b 100644
--- a/frontend/src/components/GoogleDrivePicker.tsx
+++ b/frontend/src/components/GoogleDrivePicker.tsx
@@ -123,8 +123,7 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
 
     try {
       const clientId: string = envVar('VITE_GOOGLE_CLIENT_ID');
-      const developerKey: string =
-        envVar('VITE_GOOGLE_PICKER_API_KEY') ?? '';
+      const developerKey: string = envVar('VITE_GOOGLE_PICKER_API_KEY') ?? '';
 
       // Derive appId from clientId (extract numeric part before first dash)
       const appId = clientId ? clientId.split('-')[0] : null;
@@ -265,7 +264,7 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
           />
 
           {isConnected && (
-            <div className="border-border dark:border-border rounded-lg border">
+            <div className="border-border rounded-lg border">
               <div className="p-4">
                 <div className="mb-4 flex items-center justify-between">
                   <h3 className="text-sm font-medium">
@@ -275,7 +274,6 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
                     type="button"
                     size="sm"
                     onClick={() => handleOpenPicker()}
-                    className="bg-[#A076F6] hover:bg-[#8A5FD4]"
                     disabled={isLoading}
                   >
                     {isLoading
@@ -287,7 +285,7 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
                 </div>
 
                 {selectedFiles.length === 0 && selectedFolders.length === 0 ? (
-                  <p className="text-sm text-gray-600 dark:text-gray-400">
+                  <p className="text-muted-foreground text-sm">
                     {t(
                       'modals.uploadDoc.connectors.googleDrive.noFilesSelected',
                     )}
@@ -296,13 +294,13 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
                   <div className="max-h-60 overflow-y-auto">
                     {selectedFolders.length > 0 && (
                       <div className="mb-2">
-                        <h4 className="mb-1 text-xs font-medium text-gray-500">
+                        <h4 className="text-muted-foreground mb-1 text-xs font-medium">
                           {t('modals.uploadDoc.connectors.googleDrive.folders')}
                         </h4>
                         {selectedFolders.map((folder) => (
                           <div
                             key={folder.id}
-                            className="flex items-center border-b border-gray-200 p-2 dark:border-gray-700"
+                            className="border-border flex items-center border-b p-2"
                           >
                             <img
                               src={folder.iconUrl}
@@ -316,8 +314,8 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
                             </span>
                             <Button
                               type="button"
-                              variant="link"
-                              size="sm"
+                              variant="ghost-destructive"
+                              size="xs"
                               onClick={() => {
                                 const newSelectedFolders =
                                   selectedFolders.filter(
@@ -329,7 +327,7 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
                                   newSelectedFolders.map((f) => f.id),
                                 );
                               }}
-                              className="ml-2 h-auto p-0 text-sm text-red-500 hover:text-red-700 hover:no-underline"
+                              className="ml-2"
                             >
                               {t(
                                 'modals.uploadDoc.connectors.googleDrive.remove',
@@ -342,13 +340,13 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
 
                     {selectedFiles.length > 0 && (
                       <div>
-                        <h4 className="mb-1 text-xs font-medium text-gray-500">
+                        <h4 className="text-muted-foreground mb-1 text-xs font-medium">
                           {t('modals.uploadDoc.connectors.googleDrive.files')}
                         </h4>
                         {selectedFiles.map((file) => (
                           <div
                             key={file.id}
-                            className="flex items-center border-b border-gray-200 p-2 dark:border-gray-700"
+                            className="border-border flex items-center border-b p-2"
                           >
                             <img
                               src={file.iconUrl}
@@ -362,8 +360,8 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
                             </span>
                             <Button
                               type="button"
-                              variant="link"
-                              size="sm"
+                              variant="ghost-destructive"
+                              size="xs"
                               onClick={() => {
                                 const newSelectedFiles = selectedFiles.filter(
                                   (f) => f.id !== file.id,
@@ -374,7 +372,7 @@ const GoogleDrivePicker: React.FC<GoogleDrivePickerProps> = ({
                                   selectedFolders.map((f) => f.id),
                                 );
                               }}
-                              className="ml-2 h-auto p-0 text-sm text-red-500 hover:text-red-700 hover:no-underline"
+                              className="ml-2"
                             >
                               {t(
                                 'modals.uploadDoc.connectors.googleDrive.remove',
diff --git a/frontend/src/components/GraphView.tsx b/frontend/src/components/GraphView.tsx
index f61b62e1..bb9f6462 100644
--- a/frontend/src/components/GraphView.tsx
+++ b/frontend/src/components/GraphView.tsx
@@ -162,8 +162,9 @@ const GraphView: React.FC<GraphViewProps> = ({
         <Button
           type="button"
           variant="outline"
-          size="icon-sm"
-          className="text-muted-foreground mr-3 h-[29px] w-[29px] rounded-full p-2 dark:border-0"
+          size="icon-xs"
+          shape="pill"
+          className="mr-3"
           onClick={onBackToDocuments}
           aria-label={t('settings.sources.backToAll')}
         >
diff --git a/frontend/src/components/Help.tsx b/frontend/src/components/Help.tsx
index 721ba5ba..7bc92873 100644
--- a/frontend/src/components/Help.tsx
+++ b/frontend/src/components/Help.tsx
@@ -41,10 +41,10 @@ const Help = () => {
     <div className="relative inline-block text-sm" ref={dropdownRef}>
       <Button
         type="button"
-        variant="ghost"
+        variant="sidebar-item"
         ref={buttonRef}
         onClick={toggleDropdown}
-        className="hover:bg-sidebar-accent mx-4 my-auto w-full justify-start gap-2.5 rounded-3xl pr-0 pl-3"
+        className="mx-4 my-auto w-full"
       >
         <img
           src={Info}
diff --git a/frontend/src/components/MarkdownPreview.tsx b/frontend/src/components/MarkdownPreview.tsx
index d671e8e1..97f85983 100644
--- a/frontend/src/components/MarkdownPreview.tsx
+++ b/frontend/src/components/MarkdownPreview.tsx
@@ -9,7 +9,7 @@ import remarkGfm from 'remark-gfm';
 export default function MarkdownPreview({ content }: { content: string }) {
   return (
     <div className="h-full overflow-auto p-4">
-      <div className="flex flex-col gap-3 text-sm leading-normal break-words whitespace-pre-wrap text-gray-800 dark:text-gray-200">
+      <div className="text-foreground flex flex-col gap-3 text-sm leading-normal break-words whitespace-pre-wrap">
         <ReactMarkdown
           remarkPlugins={[remarkGfm]}
           components={{
@@ -19,7 +19,7 @@ export default function MarkdownPreview({ content }: { content: string }) {
                   href={href}
                   target="_blank"
                   rel="noopener noreferrer"
-                  className="text-blue-600 hover:underline dark:text-blue-400"
+                  className="text-primary hover:underline"
                 >
                   {children}
                 </a>
@@ -51,7 +51,7 @@ export default function MarkdownPreview({ content }: { content: string }) {
             code({ children, ...rest }) {
               return (
                 <code
-                  className="dark:bg-accent dark:text-foreground rounded-md bg-gray-200 px-2 py-1 text-xs font-normal"
+                  className="bg-accent rounded-md px-2 py-1 text-xs font-normal"
                   {...rest}
                 >
                   {children}
@@ -60,7 +60,7 @@ export default function MarkdownPreview({ content }: { content: string }) {
             },
             blockquote({ children }) {
               return (
-                <blockquote className="border-l-4 border-gray-300 pl-4 italic dark:border-gray-600">
+                <blockquote className="border-border border-l-4 pl-4 italic">
                   {children}
                 </blockquote>
               );
diff --git a/frontend/src/components/MermaidRenderer.test.tsx b/frontend/src/components/MermaidRenderer.test.tsx
index 409235c0..36cbc863 100644
--- a/frontend/src/components/MermaidRenderer.test.tsx
+++ b/frontend/src/components/MermaidRenderer.test.tsx
@@ -48,7 +48,42 @@ describe('MermaidRenderer', () => {
       );
     });
 
-    expect(container.querySelector('pre.mermaid')).not.toBeNull();
+    // The diagram host is the only <pre> while the code view is closed.
+    expect(container.querySelectorAll('pre')).toHaveLength(1);
+    expect(container.querySelector('pre')?.id).toMatch(/^mermaid-/);
     expect(container.querySelector('svg[data-rendered="true"]')).not.toBeNull();
   });
+
+  it('opens the Download menu with a menu item per format', async () => {
+    renderMermaidDiagramMock.mockResolvedValue({ svg: '<svg></svg>' });
+
+    await act(async () => {
+      root.render(
+        <MermaidRenderer code={'flowchart LR\nA --> B'} isLoading={false} />,
+      );
+    });
+
+    const trigger = container.querySelector<HTMLButtonElement>(
+      'button[title="mermaid.downloadOptions"]',
+    );
+    expect(trigger).not.toBeNull();
+    expect(trigger?.getAttribute('aria-haspopup')).toBe('menu');
+    expect(document.querySelector('[role="menu"]')).toBeNull();
+
+    await act(async () => {
+      trigger?.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }),
+      );
+    });
+
+    expect(trigger?.getAttribute('aria-expanded')).toBe('true');
+    const items = Array.from(
+      document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
+    ).map((item) => item.textContent);
+    expect(items).toEqual([
+      'Download as SVG',
+      'Download as PNG',
+      'Download as MMD',
+    ]);
+  });
 });
diff --git a/frontend/src/components/MermaidRenderer.tsx b/frontend/src/components/MermaidRenderer.tsx
index ff86d882..6a866966 100644
--- a/frontend/src/components/MermaidRenderer.tsx
+++ b/frontend/src/components/MermaidRenderer.tsx
@@ -1,6 +1,7 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
+import { CircleAlert } from 'lucide-react';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import {
   oneLight,
@@ -11,7 +12,14 @@ import { selectStatus } from '../conversation/conversationSlice';
 import { useDarkTheme } from '../hooks';
 import CopyButton from './CopyButton';
 import { renderMermaidDiagram } from './mermaidSecurity';
+import { Alert, AlertDescription } from './ui/alert';
 import { Button } from './ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from './ui/dropdown-menu';
 import { MermaidRendererProps } from './types';
 
 const MermaidRenderer: React.FC<MermaidRendererProps> = ({
@@ -27,8 +35,6 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
   const status = useSelector(selectStatus);
   const [error, setError] = useState<string | null>(null);
   const [showCode, setShowCode] = useState<boolean>(false);
-  const [showDownloadMenu, setShowDownloadMenu] = useState<boolean>(false);
-  const downloadMenuRef = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const diagramRef = useRef<HTMLPreElement>(null);
   const [hoverPosition, setHoverPosition] = useState<{
@@ -126,22 +132,6 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
     };
   }, [code, isDarkTheme, isCurrentlyLoading]);
 
-  useEffect(() => {
-    const handleClickOutside = (event: MouseEvent) => {
-      if (
-        downloadMenuRef.current &&
-        !downloadMenuRef.current.contains(event.target as Node)
-      ) {
-        setShowDownloadMenu(false);
-      }
-    };
-
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => {
-      document.removeEventListener('mousedown', handleClickOutside);
-    };
-  }, [showDownloadMenu]);
-
   const downloadSvg = (): void => {
     const element = document.getElementById(diagramId.current);
     if (!element) return;
@@ -274,61 +264,43 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
   const errorRender = !isCurrentlyLoading && error;
 
   return (
-    <div className="w-inherit group border-border bg-card relative overflow-hidden rounded-xl border">
+    <div className="group border-border bg-card relative overflow-hidden rounded-xl border">
       <div className="bg-muted flex items-center justify-between px-2 py-1">
-        <span className="text-foreground dark:text-foreground text-xs font-medium">
-          mermaid
-        </span>
+        <span className="text-foreground text-xs font-medium">mermaid</span>
         <div className="flex items-center gap-2">
           <CopyButton textToCopy={String(code).replace(/\n$/, '')} />
 
           {showDiagramOptions && (
-            <div className="relative" ref={downloadMenuRef}>
-              <Button
-                type="button"
-                variant="secondary"
-                size="sm"
-                onClick={() => setShowDownloadMenu(!showDownloadMenu)}
-                className="h-auto gap-1 rounded-sm bg-gray-100 px-2 py-1 text-xs dark:bg-gray-700"
-                title={t('mermaid.downloadOptions')}
-              >
-                Download <span className="ml-1">▼</span>
-              </Button>
-              {showDownloadMenu && (
-                <div className="border-border bg-card absolute right-0 z-10 mt-1 w-40 rounded-sm border shadow-lg">
-                  <ul>
-                    {downloadOptions.map((option, index) => (
-                      <li key={index}>
-                        <Button
-                          type="button"
-                          variant="ghost"
-                          onClick={() => {
-                            option.action();
-                            setShowDownloadMenu(false);
-                          }}
-                          className="h-auto w-full justify-start rounded-none px-4 py-2 text-left text-xs font-normal"
-                        >
-                          {option.label}
-                        </Button>
-                      </li>
-                    ))}
-                  </ul>
-                </div>
-              )}
-            </div>
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  type="button"
+                  variant="ghost-muted"
+                  size="xs"
+                  title={t('mermaid.downloadOptions')}
+                >
+                  Download <span className="ml-1">▼</span>
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="w-40">
+                {downloadOptions.map((option) => (
+                  <DropdownMenuItem
+                    key={option.label}
+                    onSelect={() => option.action()}
+                  >
+                    {option.label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
           )}
 
           {showDiagramOptions && (
             <Button
               type="button"
-              variant="secondary"
-              size="sm"
+              variant={showCode ? 'secondary' : 'ghost-muted'}
+              size="xs"
               onClick={() => setShowCode(!showCode)}
-              className={`h-auto rounded px-2 py-1 text-xs ${
-                showCode
-                  ? 'bg-blue-200 hover:bg-blue-200/90 dark:bg-blue-800 dark:hover:bg-blue-800/90'
-                  : 'bg-gray-100 hover:bg-gray-100/90 dark:bg-gray-700 dark:hover:bg-gray-700/90'
-              }`}
               title={t('mermaid.viewCode')}
             >
               Code
@@ -339,16 +311,17 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
 
       {isCurrentlyLoading ? (
         <div className="bg-card flex items-center justify-center p-4">
-          <div className="text-sm text-gray-500 dark:text-gray-400">
+          <div className="text-muted-foreground text-sm">
             Loading diagram...
           </div>
         </div>
       ) : errorRender ? (
-        <div className="m-2 rounded-sm border-2 border-red-400 dark:border-red-700">
-          <div className="overflow-auto bg-red-100 px-4 py-2 text-sm wrap-break-word whitespace-normal text-red-800 dark:bg-red-900/30 dark:text-red-300">
+        <Alert variant="destructive" className="m-2 w-auto">
+          <CircleAlert />
+          <AlertDescription className="overflow-auto wrap-break-word whitespace-normal">
             {error}
-          </div>
-        </div>
+          </AlertDescription>
+        </Alert>
       ) : (
         <>
           <div
@@ -373,11 +346,14 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
                   <Button
                     type="button"
                     variant="ghost"
+                    size="icon-xs"
                     onClick={() =>
                       setZoomFactor((prev) => Math.max(1, prev - 0.5))
                     }
-                    className="h-auto px-1 py-0 text-white hover:bg-gray-600 hover:text-white"
                     title={t('mermaid.decreaseZoom')}
+                    /* eslint-disable-next-line shadcn/no-restyle --
+                       zoom controls sit on the bg-black/70 overlay; ghost's accent hover would paint a light square on it */
+                    className="hover:bg-white/20 hover:text-white dark:hover:bg-white/20"
                   >
                     -
                   </Button>
@@ -393,11 +369,14 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
                   <Button
                     type="button"
                     variant="ghost"
+                    size="icon-xs"
                     onClick={() =>
                       setZoomFactor((prev) => Math.min(6, prev + 0.5))
                     }
-                    className="h-auto px-1 py-0 text-white hover:bg-gray-600 hover:text-white"
                     title={t('mermaid.increaseZoom')}
+                    /* eslint-disable-next-line shadcn/no-restyle --
+                       zoom controls sit on the bg-black/70 overlay; ghost's accent hover would paint a light square on it */
+                    className="hover:bg-white/20 hover:text-white dark:hover:bg-white/20"
                   >
                     +
                   </Button>
@@ -406,7 +385,7 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
             )}
             <pre
               ref={diagramRef}
-              className="mermaid w-full select-none"
+              className="w-full select-none"
               id={diagramId.current}
               key={`mermaid-${diagramId.current}`}
               style={{
@@ -424,7 +403,7 @@ const MermaidRenderer: React.FC<MermaidRendererProps> = ({
           {showCode && (
             <div className="border-border border-t">
               <div className="bg-muted p-2">
-                <span className="text-foreground dark:text-foreground text-xs font-medium">
+                <span className="text-foreground text-xs font-medium">
                   Mermaid Code
                 </span>
               </div>
diff --git a/frontend/src/components/MessageInput.tsx b/frontend/src/components/MessageInput.tsx
index 76751195..3535c757 100644
--- a/frontend/src/components/MessageInput.tsx
+++ b/frontend/src/components/MessageInput.tsx
@@ -1,4 +1,5 @@
 import { envVar } from '@/env';
+import { cn } from '@/lib/utils';
 import {
   useCallback,
   useEffect,
@@ -1712,7 +1713,7 @@ export default function MessageInput({
         )}
         {sendArmed && sendReadiness.state === 'blocked' && (
           <div
-            className="px-2 pb-1 text-xs text-[#B42318] sm:px-3"
+            className="text-destructive px-2 pb-1 text-xs sm:px-3"
             role="alert"
           >
             {t('conversation.attachments.sendBlockedByFailed', {
@@ -1721,7 +1722,7 @@ export default function MessageInput({
           </div>
         )}
         {voiceError && (
-          <div className="px-2 pb-1 text-xs text-[#B42318] sm:px-3">
+          <div className="text-destructive px-2 pb-1 text-xs sm:px-3">
             {voiceError}
           </div>
         )}
@@ -1742,7 +1743,7 @@ export default function MessageInput({
             }
             tabIndex={1}
             placeholder={t('inputPlaceholder')}
-            className="inputbox-style dark:text-foreground dark:placeholder:text-muted-foreground/50 w-full scrollbar-thin overflow-x-hidden overflow-y-auto rounded-t-3xl bg-transparent px-2 text-base leading-tight whitespace-pre-wrap opacity-100 placeholder:text-gray-500 focus:outline-hidden sm:px-3"
+            className="inputbox-style dark:text-foreground placeholder:text-muted-foreground w-full scrollbar-thin overflow-x-hidden overflow-y-auto rounded-t-3xl bg-transparent px-2 text-base leading-tight whitespace-pre-wrap opacity-100 focus:outline-hidden sm:px-3"
             onKeyDown={handleKeyDown}
             onPaste={handlePaste}
             aria-label={t('inputPlaceholder')}
@@ -1791,9 +1792,10 @@ export default function MessageInput({
               type="button"
               variant="default"
               size="icon"
+              shape="pill"
               onClick={handleCancel}
               aria-label={t('cancel')}
-              className="bg-primary ml-auto h-7 w-7 shrink-0 rounded-full text-white sm:h-9 sm:w-9"
+              className="ml-auto h-7 w-7 shrink-0 sm:h-9 sm:w-9"
               disabled={!loading}
             >
               <div className="flex h-3 w-3 items-center justify-center rounded-sm bg-white sm:h-3.5 sm:w-3.5" />
@@ -1803,13 +1805,18 @@ export default function MessageInput({
               type="button"
               variant="default"
               size="icon"
+              shape="pill"
               onClick={handleSubmit}
               aria-label={t('send')}
-              className={`ml-auto h-7 w-7 shrink-0 rounded-full transition-colors duration-300 ease-in-out sm:h-9 sm:w-9 ${
-                canSubmit
-                  ? 'bg-primary text-white'
-                  : 'bg-muted text-muted-foreground dark:bg-accent dark:text-muted-foreground'
-              }`}
+              className={cn(
+                'ml-auto h-7 w-7 shrink-0 sm:h-9 sm:w-9',
+                !canSubmit &&
+                  /* eslint-disable-next-line shadcn/no-restyle --
+                     The empty composer's send button is a grey circle, not a
+                     faded brand one: no variant is neutral while disabled, and
+                     secondary is the brand-tinted pressed state. */
+                  'bg-muted text-muted-foreground dark:bg-accent',
+              )}
               disabled={!canSubmit}
             >
               <SendArrow
@@ -1839,7 +1846,7 @@ export default function MessageInput({
             <span className="text-muted-foreground dark:text-muted-foreground px-2 text-2xl font-bold">
               {t('modals.uploadDoc.drag.title')}
             </span>
-            <span className="text-s text-muted-foreground dark:text-muted-foreground w-48 p-2 text-center">
+            <span className="text-muted-foreground dark:text-muted-foreground w-48 p-2 text-center text-sm">
               {t('modals.uploadDoc.drag.description')}
             </span>
           </div>,
diff --git a/frontend/src/components/MultiSelectPopover.test.tsx b/frontend/src/components/MultiSelectPopover.test.tsx
new file mode 100644
index 00000000..99258411
--- /dev/null
+++ b/frontend/src/components/MultiSelectPopover.test.tsx
@@ -0,0 +1,81 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+const media = { isMobile: false, isTablet: false, isDesktop: true };
+vi.mock('../hooks', () => ({
+  useMediaQuery: () => media,
+  useDarkTheme: () => [false, () => undefined],
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, fallback?: string) => fallback ?? key,
+  }),
+}));
+
+import { MultiSelectPopover } from './MultiSelectPopover';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const items = [
+  { id: 'a', label: 'Alpha' },
+  { id: 'b', label: 'Beta' },
+];
+
+describe('MultiSelectPopover', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    media.isMobile = false;
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const render = () =>
+    act(() => {
+      root.render(
+        <MultiSelectPopover
+          open
+          trigger={<button type="button">Open</button>}
+          items={items}
+          selectedIds={['b']}
+          onToggle={() => undefined}
+          className="max-h-40"
+        />,
+      );
+    });
+
+  it('puts className on the desktop popover', () => {
+    render();
+    const content = document.querySelector('[data-slot="popover-content"]');
+    expect(content?.className).toContain('max-h-40');
+  });
+
+  it('puts className on the mobile sheet', () => {
+    media.isMobile = true;
+    render();
+    const content = document.querySelector('[data-slot="sheet-content"]');
+    expect(content?.className).toContain('max-h-40');
+  });
+
+  it('marks chosen rows with CommandItem checked and a primary tick', () => {
+    render();
+    const rows = document.querySelectorAll('[data-slot="command-item"]');
+    expect(rows).toHaveLength(2);
+    expect(rows[0].hasAttribute('data-checked')).toBe(false);
+    expect(rows[1].getAttribute('data-checked')).toBe('true');
+    rows.forEach((row) => expect(row.querySelector('img')).toBeNull());
+    const tick = rows[1].querySelector('svg');
+    expect(tick).not.toBeNull();
+    expect(tick?.getAttribute('class')).toContain('text-primary');
+    expect(rows[0].querySelector('svg')).toBeNull();
+  });
+});
diff --git a/frontend/src/components/MultiSelectPopover.tsx b/frontend/src/components/MultiSelectPopover.tsx
index fc711c50..2684c9f1 100644
--- a/frontend/src/components/MultiSelectPopover.tsx
+++ b/frontend/src/components/MultiSelectPopover.tsx
@@ -1,7 +1,7 @@
+import { Check } from 'lucide-react';
 import * as React from 'react';
 import { useTranslation } from 'react-i18next';
 
-import CheckmarkIcon from '../assets/checkmark.svg';
 import NoFilesDarkIcon from '../assets/no-files-dark.svg';
 import NoFilesIcon from '../assets/no-files.svg';
 import { useDarkTheme, useMediaQuery } from '../hooks';
@@ -42,7 +42,8 @@ export type MultiSelectPopoverProps = {
   footer?: React.ReactNode;
   align?: 'start' | 'center' | 'end';
   side?: 'top' | 'right' | 'bottom' | 'left';
-  contentClassName?: string;
+  /** Extra layout classes for the popup (the desktop popover or the mobile sheet). */
+  className?: string;
   emptyMessage?: string;
   selectedFirst?: boolean;
   title?: string;
@@ -80,7 +81,7 @@ export function MultiSelectPopover({
   footer,
   align = 'start',
   side = 'bottom',
-  contentClassName,
+  className,
   emptyMessage,
   selectedFirst = false,
   title,
@@ -128,14 +129,15 @@ export function MultiSelectPopover({
         onSelect={() => {
           if (!item.disabled) onToggle(item.id);
         }}
-        className="dark:border-border data-[selected=true]:bg-accent flex cursor-pointer items-center justify-between gap-2 rounded-none border-b border-[#D9D9D9] px-3 py-3 last:border-b-0"
+        checked={isSelected}
+        className="cursor-pointer justify-between"
         aria-selected={isSelected}
       >
         <div className="mr-3 flex grow items-center overflow-hidden">
           {renderIcon(item.icon)}
           <div className="overflow-hidden">
             <p
-              className="overflow-hidden text-sm font-medium text-ellipsis whitespace-nowrap text-gray-900 dark:text-white"
+              className="text-foreground overflow-hidden text-sm font-medium text-ellipsis whitespace-nowrap"
               title={item.label}
             >
               {item.label}
@@ -150,17 +152,11 @@ export function MultiSelectPopover({
           </div>
         </div>
         <div
-          className="border-border bg-card flex h-4 w-4 shrink-0 items-center justify-center rounded-xs border-2 p-[0.5px]"
+          className="border-border bg-card flex h-4 w-4 shrink-0 items-center justify-center rounded-xs border-2"
           aria-hidden="true"
         >
           {isSelected && (
-            <img
-              src={CheckmarkIcon}
-              alt=""
-              width={10}
-              height={10}
-              aria-hidden="true"
-            />
+            <Check className="text-primary size-2.5" aria-hidden="true" />
           )}
         </div>
       </CommandItem>
@@ -175,19 +171,17 @@ export function MultiSelectPopover({
         aria-hidden="true"
         className="mb-3 h-16 w-16"
       />
-      <p className="text-sm text-gray-500 dark:text-gray-400">
+      <p className="text-muted-foreground text-sm">
         {emptyMessage || t('settings.tools.noToolsFound', 'No results found')}
       </p>
     </div>
   );
 
   const commandBody = (
-    <Command shouldFilter={searchable} className="bg-transparent">
+    <Command shouldFilter={searchable}>
       {title && (
         <div className="shrink-0 px-4 pt-4">
-          <h3 className="text-lg font-medium text-gray-900 dark:text-white">
-            {title}
-          </h3>
+          <h3 className="text-foreground text-lg font-medium">{title}</h3>
         </div>
       )}
       {searchable && (
@@ -197,11 +191,11 @@ export function MultiSelectPopover({
       )}
 
       {loading ? (
-        <div className="text-foreground flex items-center justify-center py-8 dark:text-white">
+        <div className="text-foreground flex items-center justify-center py-8">
           <Spinner size="small" />
         </div>
       ) : (
-        <div className="dark:border-border mx-4 my-4 flex min-h-0 flex-1 flex-col overflow-hidden rounded-md border border-[#D9D9D9]">
+        <div className="border-border mx-4 my-4 flex min-h-0 flex-1 flex-col overflow-hidden rounded-md border">
           <CommandList className="max-h-none min-h-0 flex-1 overflow-y-auto">
             <CommandEmpty>{renderEmptyState()}</CommandEmpty>
             {hasGroups ? (
@@ -212,23 +206,20 @@ export function MultiSelectPopover({
                   <CommandGroup
                     key={`group-${groupKey || 'ungrouped'}`}
                     heading={groupKey || undefined}
-                    className="[&_[cmdk-group-heading]]:bg-muted/50 [&_[cmdk-group-heading]]:dark:bg-card [&_[cmdk-group-heading]]:text-muted-foreground p-0 [&_[cmdk-group-heading]]:sticky [&_[cmdk-group-heading]]:top-0 [&_[cmdk-group-heading]]:z-10 [&_[cmdk-group-heading]]:border-b [&_[cmdk-group-heading]]:border-[#D9D9D9] [&_[cmdk-group-heading]]:px-3 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-semibold [&_[cmdk-group-heading]]:uppercase [&_[cmdk-group-heading]]:dark:border-[#2E2E2E]"
                   >
                     {groupItems.map(renderItem)}
                   </CommandGroup>
                 );
               })
             ) : (
-              <CommandGroup className="p-0">
-                {orderedItems.map(renderItem)}
-              </CommandGroup>
+              <CommandGroup>{orderedItems.map(renderItem)}</CommandGroup>
             )}
           </CommandList>
         </div>
       )}
 
       {footer && (
-        <div className="border-border dark:border-border shrink-0 border-t px-4 py-4">
+        <div className="border-border shrink-0 border-t px-4 py-4">
           {footer}
         </div>
       )}
@@ -244,15 +235,18 @@ export function MultiSelectPopover({
           showCloseButton={false}
           onOpenAutoFocus={(e) => e.preventDefault()}
           className={cn(
-            'border-border bg-background dark:border-border dark:bg-card flex max-h-[85vh] flex-col gap-0 overflow-hidden rounded-t-2xl p-0 pb-[env(safe-area-inset-bottom)]',
-            contentClassName,
+            /* eslint-disable-next-line shadcn/no-restyle, shadcn/no-arbitrary-values --
+               bottom-sheet shape: rounded top, no gap, card fill in dark to match Command's
+               bg-popover, and pb-[env(safe-area-inset-bottom)] to clear the iPhone home indicator. */
+            'dark:bg-card flex max-h-[85vh] flex-col gap-0 overflow-hidden rounded-t-2xl p-0 pb-[env(safe-area-inset-bottom)]',
+            className,
           )}
         >
           <SheetTitle className="sr-only">
             {title || effectivePlaceholder}
           </SheetTitle>
           <div
-            className="mx-auto mt-2 mb-1 h-1.5 w-12 shrink-0 rounded-full bg-gray-300 dark:bg-gray-600"
+            className="bg-border mx-auto mt-2 mb-1 h-1.5 w-12 shrink-0 rounded-full"
             aria-hidden="true"
           />
           {commandBody}
@@ -268,8 +262,8 @@ export function MultiSelectPopover({
         align={align}
         side={side}
         className={cn(
-          'border-border bg-background dark:border-border dark:bg-card flex max-h-[min(600px,80vh)] w-[min(462px,calc(100vw-20px))] flex-col overflow-hidden rounded-lg p-0 shadow-md',
-          contentClassName,
+          'flex max-h-[min(600px,80vh)] w-[min(462px,calc(100vw-20px))] flex-col overflow-hidden p-0',
+          className,
         )}
       >
         {commandBody}
diff --git a/frontend/src/components/Notification.tsx b/frontend/src/components/Notification.tsx
index def9f580..8b5f7047 100644
--- a/frontend/src/components/Notification.tsx
+++ b/frontend/src/components/Notification.tsx
@@ -25,114 +25,90 @@ export default function Notification({
 }: NotificationProps) {
   const { t } = useTranslation();
   return (
-    <>
-      <style>{`
-        @keyframes twinkle {
-          0%, 100% {
-            opacity: 0.3;
-            transform: scale(1) translateY(0);
-          }
-          50% {
-            opacity: 1;
-            transform: scale(1.2) translateY(-2px);
-          }
-        }
-
-        .star {
-          animation: twinkle var(--duration) ease-in-out infinite;
-          animation-delay: var(--delay);
-        }
-      `}</style>
-      <a
-        className="group absolute right-2 bottom-24 z-20 flex w-3/4 items-center justify-center gap-2 overflow-hidden rounded-lg px-2 py-4 sm:right-4 sm:bottom-6 md:w-2/5 lg:w-1/3 xl:w-1/4 2xl:w-1/5"
-        style={{
-          background:
-            'linear-gradient(90deg, #390086 0%, #6222B7 100%), linear-gradient(90deg, rgba(57, 0, 134, 0) 0%, #6222B7 53.02%, rgba(57, 0, 134, 0) 100%)',
-        }}
-        href={notificationLink}
-        target="_blank"
-        aria-label={t('notification.ariaLabel')}
-        rel="noreferrer"
-      >
-        {/* Animated stars background */}
-        <div className="pointer-events-none absolute inset-0">
-          {stars.map((star) => (
-            <svg
-              key={star.id}
-              className="star absolute"
-              style={
-                {
-                  width: `${star.size * 4}px`,
-                  height: `${star.size * 4}px`,
-                  left: `${star.left}%`,
-                  top: `${star.top}%`,
-                  opacity: star.opacity,
-                  filter: `drop-shadow(0 0 ${star.size}px rgba(255, 255, 255, 0.5))`,
-                  '--duration': `${star.animationDuration}s`,
-                  '--delay': `${star.animationDelay}s`,
-                } as React.CSSProperties & {
-                  '--duration': string;
-                  '--delay': string;
-                }
-              }
-              viewBox="0 0 24 24"
-              fill="none"
-              xmlns="http://www.w3.org/2000/svg"
-            >
-              {/* 4-pointed Christmas star */}
-              <path
-                d="M12 0L13.5 10.5L24 12L13.5 13.5L12 24L10.5 13.5L0 12L10.5 10.5L12 0Z"
-                fill="white"
-              />
-            </svg>
-          ))}
-        </div>
-
-        <p className="relative z-10 text-xs leading-6 font-semibold text-white xl:text-sm xl:leading-7">
-          {notificationText}
-        </p>
-        <span className="relative z-10 flex items-center">
+    <a
+      className="notification-banner group absolute right-2 bottom-24 z-20 flex w-3/4 items-center justify-center gap-2 overflow-hidden rounded-lg px-2 py-4 sm:right-4 sm:bottom-6 md:w-2/5 lg:w-1/3 xl:w-1/4 2xl:w-1/5"
+      href={notificationLink}
+      target="_blank"
+      aria-label={t('notification.ariaLabel')}
+      rel="noreferrer"
+    >
+      {/* Animated stars background. The banner is always the purple gradient,
+          so its imagery is white in both themes. */}
+      <div className="pointer-events-none absolute inset-0 text-white">
+        {stars.map((star) => (
           <svg
-            width="18"
-            height="13"
-            viewBox="0 0 18 13"
+            key={star.id}
+            className="notification-star absolute"
+            style={
+              {
+                '--star-size': `${star.size * 4}px`,
+                '--star-left': `${star.left}%`,
+                '--star-top': `${star.top}%`,
+                '--star-opacity': String(star.opacity),
+                '--star-glow': `${star.size}px`,
+                '--star-duration': `${star.animationDuration}s`,
+                '--star-delay': `${star.animationDelay}s`,
+              } as React.CSSProperties
+            }
+            viewBox="0 0 24 24"
             fill="none"
             xmlns="http://www.w3.org/2000/svg"
-            className="overflow-visible"
           >
-            {/* Arrow tail - grows leftward from arrow head's back point on hover */}
-            <rect
-              x="4"
-              y="5.75"
-              width="8"
-              height="1.5"
-              fill="white"
-              className="scale-x-0 transition-transform duration-300 ease-out group-hover:scale-x-100"
-              style={{ transformOrigin: '12px 6.5px' }}
-            />
-            {/* Arrow head - pushed forward by the tail on hover */}
+            {/* 4-pointed Christmas star */}
             <path
-              d="M13.0303 7.03033C13.3232 6.73744 13.3232 6.26256 13.0303 5.96967L8.25736 1.1967C7.96447 0.903806 7.48959 0.903806 7.1967 1.1967C6.90381 1.48959 6.90381 1.96447 7.1967 2.25736L11.4393 6.5L7.1967 10.7426C6.90381 11.0355 6.90381 11.5104 7.1967 11.8033C7.48959 12.0962 7.96447 12.0962 8.25736 11.8033L13.0303 7.03033Z"
-              fill="white"
-              className="transition-transform duration-300 ease-out group-hover:translate-x-1"
+              d="M12 0L13.5 10.5L24 12L13.5 13.5L12 24L10.5 13.5L0 12L10.5 10.5L12 0Z"
+              fill="currentColor"
             />
           </svg>
-        </span>
+        ))}
+      </div>
 
-        <Button
-          type="button"
-          variant="ghost"
-          className="absolute top-2 right-2 z-30 h-4 w-4 rounded-none bg-transparent p-0 hover:bg-transparent hover:opacity-70"
-          aria-label={t('notification.closeAriaLabel')}
-          onClick={(e) => {
-            e.stopPropagation();
-            e.preventDefault();
-            handleCloseNotification();
-          }}
+      <p className="relative z-10 text-xs leading-6 font-semibold text-white xl:text-sm xl:leading-7">
+        {notificationText}
+      </p>
+      <span className="relative z-10 flex items-center text-white">
+        <svg
+          width="18"
+          height="13"
+          viewBox="0 0 18 13"
+          fill="none"
+          xmlns="http://www.w3.org/2000/svg"
+          className="overflow-visible"
         >
-          <img className="w-full" src={close} alt="Close notification" />
-        </Button>
-      </a>
-    </>
+          {/* Arrow tail - grows leftward from arrow head's back point on hover */}
+          <rect
+            x="4"
+            y="5.75"
+            width="8"
+            height="1.5"
+            fill="currentColor"
+            className="origin-[12px_6.5px] scale-x-0 transition-transform duration-300 ease-out group-hover:scale-x-100"
+          />
+          {/* Arrow head - pushed forward by the tail on hover */}
+          <path
+            d="M13.0303 7.03033C13.3232 6.73744 13.3232 6.26256 13.0303 5.96967L8.25736 1.1967C7.96447 0.903806 7.48959 0.903806 7.1967 1.1967C6.90381 1.48959 6.90381 1.96447 7.1967 2.25736L11.4393 6.5L7.1967 10.7426C6.90381 11.0355 6.90381 11.5104 7.1967 11.8033C7.48959 12.0962 7.96447 12.0962 8.25736 11.8033L13.0303 7.03033Z"
+            fill="currentColor"
+            className="transition-transform duration-300 ease-out group-hover:translate-x-1"
+          />
+        </svg>
+      </span>
+
+      <Button
+        type="button"
+        variant="ghost"
+        /* eslint-disable-next-line shadcn/no-restyle -- a 16px bare close on
+           the promo gradient: no size fits, and ghost's accent hover fill
+           would paint a grey square on the purple. */
+        className="absolute top-2 right-2 z-30 h-4 w-4 rounded-none bg-transparent p-0 hover:bg-transparent hover:opacity-70"
+        aria-label={t('notification.closeAriaLabel')}
+        onClick={(e) => {
+          e.stopPropagation();
+          e.preventDefault();
+          handleCloseNotification();
+        }}
+      >
+        <img className="w-full" src={close} alt="Close notification" />
+      </Button>
+    </a>
   );
 }
diff --git a/frontend/src/components/ProfileButton.tsx b/frontend/src/components/ProfileButton.tsx
index 790d9a07..ea25dae0 100644
--- a/frontend/src/components/ProfileButton.tsx
+++ b/frontend/src/components/ProfileButton.tsx
@@ -17,19 +17,21 @@ export default function ProfileButton() {
   if (authType !== 'oidc' || (!userName && !userEmail)) return null;
 
   const initial = (userName || userEmail || '?').charAt(0).toUpperCase();
-  const renderAvatar = (size: string, text: string) =>
+  // `default` is size-8/text-sm, `xl` is size-10/text-base; the size variant
+  // also brings the flex centring and the overflow-hidden that clips both the
+  // photo and the initials to the circle.
+  const renderAvatar = (size: 'default' | 'xl') =>
     userPicture ? (
       <Avatar
+        size={size}
+        shape="circle"
         src={userPicture}
         alt={userName || userEmail || 'User avatar'}
-        className={size}
-        imgClassName={`${size} rounded-full object-cover`}
+        imgClassName="size-full object-cover"
       />
     ) : (
-      <Avatar className={size}>
-        <span
-          className={`bg-primary text-primary-foreground flex ${size} items-center justify-center rounded-full ${text} font-medium`}
-        >
+      <Avatar size={size} shape="circle">
+        <span className="bg-primary text-primary-foreground flex size-full items-center justify-center font-medium">
           {initial}
         </span>
       </Avatar>
@@ -43,15 +45,15 @@ export default function ProfileButton() {
           aria-label={t('auth.account')}
           className="ring-offset-background focus-visible:ring-ring hover:ring-primary/40 rounded-full transition outline-none hover:ring-2 hover:ring-offset-2 focus-visible:ring-2 focus-visible:ring-offset-2"
         >
-          {renderAvatar('size-8', 'text-sm')}
+          {renderAvatar('default')}
         </button>
       </PopoverTrigger>
       <PopoverContent align="end" sideOffset={8} className="w-64 p-0">
         <div className="flex items-center gap-3 p-4">
-          {renderAvatar('size-10', 'text-base')}
+          {renderAvatar('xl')}
           <span className="flex min-w-0 flex-col">
             {userName && (
-              <p className="text-foreground truncate text-sm font-medium dark:text-white">
+              <p className="text-foreground truncate text-sm font-medium">
                 {userName}
               </p>
             )}
@@ -68,7 +70,7 @@ export default function ProfileButton() {
             type="button"
             onClick={logout}
             data-testid="oidc-signout"
-            className="text-foreground hover:bg-sidebar-accent flex w-full items-center gap-2.5 rounded-lg px-3 py-2 text-sm dark:text-white"
+            className="text-foreground hover:bg-sidebar-accent flex w-full items-center gap-2.5 rounded-lg px-3 py-2 text-sm"
           >
             <LogOut
               className="text-muted-foreground size-4 shrink-0"
diff --git a/frontend/src/components/SourcesPopoverFooter.tsx b/frontend/src/components/SourcesPopoverFooter.tsx
index 056d47fc..31a2732e 100644
--- a/frontend/src/components/SourcesPopoverFooter.tsx
+++ b/frontend/src/components/SourcesPopoverFooter.tsx
@@ -29,9 +29,10 @@ export default function SourcesPopoverFooter({
       </Link>
       <Button
         type="button"
-        variant="outline"
+        variant="outline-primary"
+        shape="pill"
         onClick={onUploadClick}
-        className="border-primary text-primary hover:bg-primary/90 h-auto w-auto self-start rounded-full border bg-transparent px-4 py-2 text-sm font-medium shadow-none transition-colors duration-200 hover:text-white"
+        className="w-auto self-start"
       >
         {t('settings.sources.uploadNew')}
       </Button>
diff --git a/frontend/src/components/Spinner.tsx b/frontend/src/components/Spinner.tsx
index dda8b8c3..df908d2a 100644
--- a/frontend/src/components/Spinner.tsx
+++ b/frontend/src/components/Spinner.tsx
@@ -1,33 +1,15 @@
-import React from 'react';
+import { Spinner as UiSpinner } from './ui/spinner';
 
 type SpinnerProps = {
   size?: 'small' | 'medium' | 'large';
 };
 
-const SIZE_MAP: Record<NonNullable<SpinnerProps['size']>, string> = {
-  small: '20px',
-  medium: '30px',
-  large: '40px',
-};
+const SIZE_MAP = { small: 'sm', medium: 'default', large: 'lg' } as const;
 
+/**
+ * Compatibility wrapper over `ui/spinner`. New code should import
+ * `Spinner` from `@/components/ui/spinner` and use `sm | default | lg`.
+ */
 export default function Spinner({ size = 'medium' }: SpinnerProps) {
-  const spinnerSize = SIZE_MAP[size];
-
-  const spinnerStyle: React.CSSProperties = {
-    width: spinnerSize,
-    height: spinnerSize,
-    aspectRatio: '1',
-    borderRadius: '50%',
-    background: `
-      radial-gradient(farthest-side, currentColor 94%, transparent) top/8px 8px no-repeat,
-      conic-gradient(transparent 30%, currentColor)
-    `,
-    WebkitMask:
-      'radial-gradient(farthest-side, transparent calc(100% - 8px), #000 0)',
-    mask: 'radial-gradient(farthest-side, transparent calc(100% - 8px), #000 0)',
-    animation: 'spinner-rotate 1s infinite linear',
-    color: 'currentColor',
-  };
-
-  return <div className="loader" role="status" style={spinnerStyle} />;
+  return <UiSpinner size={SIZE_MAP[size]} />;
 }
diff --git a/frontend/src/components/TextToSpeechButton.tsx b/frontend/src/components/TextToSpeechButton.tsx
index 028a4bed..8cd16c30 100644
--- a/frontend/src/components/TextToSpeechButton.tsx
+++ b/frontend/src/components/TextToSpeechButton.tsx
@@ -174,11 +174,10 @@ export default function SpeakButton({ text }: { text: string }) {
   return (
     <Button
       type="button"
-      variant="ghost"
+      variant={isSpeaking || isLoading ? 'secondary' : 'ghost'}
       size="icon"
-      className={`cursor-pointer rounded-full ${
-        isSpeaking || isLoading ? 'bg-accent' : ''
-      }`}
+      shape="pill"
+      className="cursor-pointer"
       onClick={handleSpeakClick}
       aria-label={
         isLoading
@@ -192,9 +191,9 @@ export default function SpeakButton({ text }: { text: string }) {
       {isLoading ? (
         <Spinner size="small" />
       ) : isSpeaking ? (
-        <Stopspeech className="fill-none" />
+        <Stopspeech />
       ) : (
-        <Speaker className="fill-none" />
+        <Speaker />
       )}
     </Button>
   );
diff --git a/frontend/src/components/ToolIcon.tsx b/frontend/src/components/ToolIcon.tsx
index bd9edab3..8034a7a6 100644
--- a/frontend/src/components/ToolIcon.tsx
+++ b/frontend/src/components/ToolIcon.tsx
@@ -37,12 +37,6 @@ export default function ToolIcon({ name, className, title }: ToolIconProps) {
     ? { role: 'img' as const, 'aria-label': title }
     : { 'aria-hidden': true as const };
   return (
-    <Icon
-      className={cn(
-        'h-6 w-6 text-neutral-700 dark:text-neutral-200',
-        className,
-      )}
-      {...a11y}
-    />
+    <Icon className={cn('text-foreground h-6 w-6', className)} {...a11y} />
   );
 }
diff --git a/frontend/src/components/UploadToast.test.tsx b/frontend/src/components/UploadToast.test.tsx
new file mode 100644
index 00000000..efed2d77
--- /dev/null
+++ b/frontend/src/components/UploadToast.test.tsx
@@ -0,0 +1,121 @@
+import { configureStore } from '@reduxjs/toolkit';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { Provider } from 'react-redux';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import uploadReducer, {
+  addUploadTask,
+  type UploadTask,
+} from '../upload/uploadSlice';
+import UploadToast from './UploadToast';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const makeStore = () => configureStore({ reducer: { upload: uploadReducer } });
+
+const task = (over: Partial<UploadTask>): UploadTask => ({
+  id: 't1',
+  fileName: 'a.pdf',
+  progress: 40,
+  status: 'training',
+  ...over,
+});
+
+describe('UploadToast', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let store: ReturnType<typeof makeStore>;
+
+  beforeEach(() => {
+    localStorage.clear();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    store = makeStore();
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async () => {
+    await act(async () => {
+      root.render(
+        <Provider store={store}>
+          <UploadToast />
+        </Provider>,
+      );
+    });
+  };
+
+  it('renders nothing without tasks', async () => {
+    await render();
+    expect(container.innerHTML).toBe('');
+  });
+
+  it('renders one card of rows with no rail of its own', async () => {
+    store.dispatch(
+      addUploadTask(task({ id: 't1', fileName: 'a.pdf', stage: 'embedding' })),
+    );
+    store.dispatch(
+      addUploadTask(task({ id: 't2', fileName: 'b.md', status: 'completed' })),
+    );
+    await render();
+    expect(container.querySelectorAll('[data-slot="toast"]')).toHaveLength(1);
+    expect(container.querySelector('[data-slot="toast-viewport"]')).toBeNull();
+    expect(container.querySelector('[role="status"]')).toBeNull();
+    expect(container.querySelector('.fixed')).toBeNull();
+    const rows = container.querySelectorAll('[data-slot="toast-item"]');
+    expect(rows).toHaveLength(2);
+    expect(rows[0].textContent).toContain('b.md');
+    expect(rows[0].querySelector('[data-status="success"]')).not.toBeNull();
+    expect(rows[1].textContent).toContain(
+      'modals.uploadDoc.progress.embedding',
+    );
+    expect(rows[1].querySelector('[role="progressbar"]')).not.toBeNull();
+    expect(
+      container.querySelector('[data-slot="toast-title"]')?.textContent,
+    ).toBe('modals.uploadDoc.progress.upload');
+  });
+
+  it('tints the header and explains a failure', async () => {
+    store.dispatch(
+      addUploadTask(task({ status: 'failed', errorMessage: 'Too big' })),
+    );
+    await render();
+    expect(
+      container
+        .querySelector('[data-slot="toast-header"]')
+        ?.getAttribute('data-variant'),
+    ).toBe('destructive');
+    const row = container.querySelector('[data-slot="toast-item"]');
+    expect(row?.querySelector('[data-status="destructive"]')).not.toBeNull();
+    const message = container.querySelector('[data-slot="toast-message"]');
+    expect(message?.textContent).toBe('Too big');
+    expect(message?.className).toContain('text-destructive');
+  });
+
+  it('collapses the rows and dismisses every task', async () => {
+    store.dispatch(addUploadTask(task({})));
+    await render();
+    const collapse = container.querySelector(
+      'button[aria-label="modals.uploadDoc.progress.collapseDetails"]',
+    ) as HTMLButtonElement;
+    await act(async () => collapse.click());
+    expect(
+      container.querySelector(
+        'button[aria-label="modals.uploadDoc.progress.expandDetails"]',
+      ),
+    ).not.toBeNull();
+    const close = container.querySelector(
+      'button[aria-label="modals.uploadDoc.progress.dismiss"]',
+    ) as HTMLButtonElement;
+    await act(async () => close.click());
+    expect(container.innerHTML).toBe('');
+  });
+});
diff --git a/frontend/src/components/UploadToast.tsx b/frontend/src/components/UploadToast.tsx
index 3c132c29..24b41e29 100644
--- a/frontend/src/components/UploadToast.tsx
+++ b/frontend/src/components/UploadToast.tsx
@@ -1,18 +1,26 @@
-import { X } from 'lucide-react';
+import { ChevronDown, X } from 'lucide-react';
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 
-import { selectWorkflowPreviewOpen } from '../agents/workflow/workflowPreviewSlice';
-import CheckCircleFilled from '../assets/check-circle-filled.svg';
-import ChevronDown from '../assets/chevron-down.svg';
-import WarnIcon from '../assets/warn.svg';
+import { cn } from '@/lib/utils';
+
 import {
   dismissUploadTask,
   selectUploadTasks,
   type UploadTask,
 } from '../upload/uploadSlice';
 import { Button } from './ui/button';
+import {
+  Toast,
+  ToastActions,
+  ToastContent,
+  ToastHeader,
+  ToastItem,
+  ToastMessage,
+  ToastStatus,
+  ToastTitle,
+} from './ui/toast';
 
 const PROGRESS_RADIUS = 10;
 const PROGRESS_CIRCUMFERENCE = 2 * Math.PI * PROGRESS_RADIUS;
@@ -30,6 +38,11 @@ const IN_PROGRESS_STATUSES = new Set<UploadTask['status']>([
  * newest task overall if all are terminal). Per-task progress lives
  * on each row.
  *
+ * Renders only its ``Toast`` card: App.tsx mounts the shared
+ * ``ToastViewport`` and places this card at the bottom of the stack
+ * (and moves the whole stack left while the workflow Preview drawer is
+ * open).
+ *
  * Dismissal: the header X dismisses every visible task at once
  * (mirrors the GDrive panel close — keeps the surface tidy without
  * per-row controls). The chevron collapses the row list.
@@ -40,10 +53,6 @@ export default function UploadToast() {
   const { t } = useTranslation();
   const dispatch = useDispatch();
   const uploadTasks = useSelector(selectUploadTasks);
-  // The workflow Preview drawer occupies the right edge; shift the toast to
-  // the bottom-left while it's open so it stays visible without covering the
-  // drawer's attach/send controls.
-  const previewOpen = useSelector(selectWorkflowPreviewOpen);
 
   const visibleTasks = uploadTasks.filter((task) => !task.dismissed);
   if (visibleTasks.length === 0) return null;
@@ -64,80 +73,62 @@ export default function UploadToast() {
   };
 
   return (
-    <div
-      className={`fixed bottom-4 z-50 flex max-w-md flex-col gap-2 ${
-        previewOpen ? 'left-4' : 'right-4'
-      }`}
-      onMouseDown={(e) => e.stopPropagation()}
-      role="status"
-      aria-live="polite"
-      aria-atomic="false"
-    >
+    <Toast>
+      <ToastHeader
+        variant={primaryTask.status === 'failed' ? 'destructive' : 'default'}
+      >
+        <ToastTitle>{headerLabel}</ToastTitle>
+        <ToastActions>
+          <Button
+            type="button"
+            variant="ghost-muted"
+            size="icon-sm"
+            onClick={() => setCollapsed((prev) => !prev)}
+            aria-label={
+              collapsed
+                ? t('modals.uploadDoc.progress.expandDetails')
+                : t('modals.uploadDoc.progress.collapseDetails')
+            }
+          >
+            <ChevronDown
+              className={cn(
+                'h-4 w-4 transition-transform duration-200',
+                collapsed && 'rotate-180',
+              )}
+            />
+          </Button>
+          <Button
+            type="button"
+            variant="ghost-muted"
+            size="icon-sm"
+            onClick={dismissAll}
+            aria-label={t('modals.uploadDoc.progress.dismiss')}
+          >
+            <X className="h-4 w-4" />
+          </Button>
+        </ToastActions>
+      </ToastHeader>
+
       <div
-        className={`border-border bg-card shadow-toast w-[271px] overflow-hidden rounded-2xl border transition-all duration-300`}
+        className={cn(
+          'grid overflow-hidden transition-[grid-template-rows] duration-300 ease-out',
+          collapsed ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]',
+        )}
       >
         <div
-          className={`flex items-center justify-between px-4 py-3 ${
-            primaryTask.status !== 'failed'
-              ? 'bg-accent/50 dark:bg-muted'
-              : 'bg-destructive/10 dark:bg-destructive/10'
-          }`}
+          className={cn(
+            'min-h-0 overflow-hidden transition-opacity duration-300',
+            collapsed ? 'opacity-0' : 'opacity-100',
+          )}
         >
-          <h3 className="dark:text-foreground text-sm leading-[16.5px] font-medium text-black">
-            {headerLabel}
-          </h3>
-          <div className="flex items-center gap-1">
-            <Button
-              type="button"
-              variant="ghost"
-              size="icon-sm"
-              onClick={() => setCollapsed((prev) => !prev)}
-              aria-label={
-                collapsed
-                  ? t('modals.uploadDoc.progress.expandDetails')
-                  : t('modals.uploadDoc.progress.collapseDetails')
-              }
-              className="text-black opacity-70 hover:bg-transparent hover:opacity-100 dark:text-white dark:hover:bg-transparent"
-            >
-              <img
-                src={ChevronDown}
-                alt=""
-                className={`h-4 w-4 transform transition-transform duration-200 dark:invert ${
-                  collapsed ? 'rotate-180' : ''
-                }`}
-              />
-            </Button>
-            <Button
-              type="button"
-              variant="ghost"
-              size="icon-sm"
-              onClick={dismissAll}
-              className="text-black opacity-70 hover:bg-transparent hover:opacity-100 dark:text-white dark:hover:bg-transparent"
-              aria-label={t('modals.uploadDoc.progress.dismiss')}
-            >
-              <X className="h-4 w-4" />
-            </Button>
-          </div>
-        </div>
-
-        <div
-          className="grid overflow-hidden transition-[grid-template-rows] duration-300 ease-out"
-          style={{ gridTemplateRows: collapsed ? '0fr' : '1fr' }}
-        >
-          <div
-            className={`min-h-0 overflow-hidden transition-opacity duration-300 ${
-              collapsed ? 'opacity-0' : 'opacity-100'
-            }`}
-          >
-            <ul className="max-h-72 overflow-y-auto">
-              {visibleTasks.map((task) => (
-                <UploadRow key={task.id} task={task} t={t} />
-              ))}
-            </ul>
-          </div>
+          <ToastContent scrollable>
+            {visibleTasks.map((task) => (
+              <UploadRow key={task.id} task={task} t={t} />
+            ))}
+          </ToastContent>
         </div>
       </div>
-    </div>
+    </Toast>
   );
 }
 
@@ -154,91 +145,80 @@ function UploadRow({
   const progressOffset = PROGRESS_CIRCUMFERENCE * (1 - rawProgress / 100);
 
   return (
-    <li className="border-border/50 border-b last:border-b-0">
-      <div className="flex items-center justify-between px-5 py-3">
-        <div className="flex min-w-0 flex-col">
-          <p
-            className="dark:text-muted-foreground max-w-[200px] truncate text-sm leading-[16.5px] font-normal text-black"
-            title={task.fileName}
+    <>
+      <ToastItem
+        label={<span title={task.fileName}>{task.fileName}</span>}
+        meta={
+          task.status === 'training' && task.stage
+            ? t(`modals.uploadDoc.progress.${task.stage}`)
+            : undefined
+        }
+      >
+        {showProgress && (
+          // Determinate ring: ToastStatus "pending" is an indeterminate
+          // spinner, and each row reports its own percentage.
+          <svg
+            width="24"
+            height="24"
+            viewBox="0 0 24 24"
+            className="text-primary h-6 w-6 shrink-0"
+            role="progressbar"
+            aria-valuemin={0}
+            aria-valuemax={100}
+            aria-valuenow={formattedProgress}
+            aria-label={t('modals.uploadDoc.progress.uploadProgress', {
+              progress: formattedProgress,
+            })}
           >
-            {task.fileName}
-          </p>
-          {task.status === 'training' && task.stage && (
-            <span className="text-muted-foreground mt-0.5 text-xs leading-[14px]">
-              {t(`modals.uploadDoc.progress.${task.stage}`)}
-            </span>
-          )}
-        </div>
-
-        <div className="flex items-center gap-2">
-          {showProgress && (
-            <svg
-              width="24"
-              height="24"
-              viewBox="0 0 24 24"
-              className="text-primary h-6 w-6 shrink-0"
-              role="progressbar"
-              aria-valuemin={0}
-              aria-valuemax={100}
-              aria-valuenow={formattedProgress}
-              aria-label={t('modals.uploadDoc.progress.uploadProgress', {
-                progress: formattedProgress,
-              })}
-            >
-              <circle
-                className="text-muted dark:text-muted-foreground/30"
-                stroke="currentColor"
-                strokeWidth="2"
-                cx="12"
-                cy="12"
-                r={PROGRESS_RADIUS}
-                fill="none"
-              />
-              <circle
-                className="text-primary"
-                stroke="currentColor"
-                strokeWidth="2"
-                strokeLinecap="round"
-                strokeDasharray={PROGRESS_CIRCUMFERENCE}
-                strokeDashoffset={progressOffset}
-                cx="12"
-                cy="12"
-                r={PROGRESS_RADIUS}
-                fill="none"
-                transform="rotate(-90 12 12)"
-              />
-            </svg>
-          )}
-
-          {task.status === 'completed' && (
-            <img
-              src={CheckCircleFilled}
-              alt=""
-              className="h-6 w-6 shrink-0"
-              aria-hidden="true"
+            <circle
+              className="text-muted dark:text-muted-foreground/30"
+              stroke="currentColor"
+              strokeWidth="2"
+              cx="12"
+              cy="12"
+              r={PROGRESS_RADIUS}
+              fill="none"
             />
-          )}
-
-          {task.status === 'failed' && (
-            <img
-              src={WarnIcon}
-              alt=""
-              className="h-6 w-6 shrink-0"
-              aria-hidden="true"
+            <circle
+              className="text-primary"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeDasharray={PROGRESS_CIRCUMFERENCE}
+              strokeDashoffset={progressOffset}
+              cx="12"
+              cy="12"
+              r={PROGRESS_RADIUS}
+              fill="none"
+              transform="rotate(-90 12 12)"
             />
-          )}
-        </div>
-      </div>
+          </svg>
+        )}
+
+        {task.status === 'completed' && (
+          <ToastStatus
+            status="success"
+            label={t('modals.uploadDoc.progress.completed')}
+          />
+        )}
+
+        {task.status === 'failed' && (
+          <ToastStatus
+            status="destructive"
+            label={t('modals.uploadDoc.progress.failed')}
+          />
+        )}
+      </ToastItem>
 
       {task.status === 'failed' &&
         (task.tokenLimitReached || task.errorMessage) && (
-          <span className="block px-5 pb-3 text-xs text-red-500">
+          <ToastMessage variant="destructive">
             {task.tokenLimitReached
               ? t('modals.uploadDoc.progress.tokenLimit')
               : task.errorMessage}
-          </span>
+          </ToastMessage>
         )}
-    </li>
+    </>
   );
 }
 
diff --git a/frontend/src/components/WikiViewer.tsx b/frontend/src/components/WikiViewer.tsx
index 6ef4181d..7fd5cfbe 100644
--- a/frontend/src/components/WikiViewer.tsx
+++ b/frontend/src/components/WikiViewer.tsx
@@ -57,7 +57,7 @@ const markdownComponents = {
     </a>
   ),
   code: ({ children }: { children?: React.ReactNode }) => (
-    <code className="dark:bg-accent rounded-md bg-gray-200 px-1.5 py-0.5 text-xs">
+    <code className="bg-accent rounded-md px-1.5 py-0.5 text-xs">
       {children}
     </code>
   ),
@@ -213,8 +213,9 @@ const WikiViewer: React.FC<WikiViewerProps> = ({
         <Button
           type="button"
           variant="outline"
-          size="icon-sm"
-          className="text-muted-foreground mr-3 h-[29px] w-[29px] rounded-full p-2 dark:border-0"
+          size="icon-xs"
+          shape="pill"
+          className="mr-3"
           onClick={onBackToDocuments}
           aria-label={t('settings.sources.backToAll')}
         >
diff --git a/frontend/src/components/message-input/AttachFileButton.tsx b/frontend/src/components/message-input/AttachFileButton.tsx
index a0b95403..8a96032f 100644
--- a/frontend/src/components/message-input/AttachFileButton.tsx
+++ b/frontend/src/components/message-input/AttachFileButton.tsx
@@ -2,6 +2,7 @@ import { useTranslation } from 'react-i18next';
 
 import ClipIcon from '../../assets/clip.svg';
 import { ATTACHMENT_FILE_ACCEPT_ATTR } from '../../constants/fileUpload';
+import { Button } from '../ui/button';
 
 type AttachFileButtonProps = {
   onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
@@ -11,29 +12,28 @@ export default function AttachFileButton({ onChange }: AttachFileButtonProps) {
   const { t } = useTranslation();
 
   return (
-    // translate="no": Chrome's page translator rewrites text nodes inside
-    // this label into <font> wrappers and React then loses the control — a
-    // user with auto-translate on rage-clicked a dead Attach button until
-    // they reloaded. Keep the composer's controls out of the translator.
-    <label
-      translate="no"
-      className="xs:px-3 xs:py-1.5 dark:border-border border-border hover:bg-muted dark:hover:bg-muted flex cursor-pointer items-center rounded-full border px-2 py-1 transition-colors"
-    >
-      <img
-        src={ClipIcon}
-        alt="Attach"
-        className="mr-1 h-3.5 w-3.5 sm:mr-1.5 sm:h-4 sm:w-4 dark:invert"
-      />
-      <span className="xs:text-xs dark:text-foreground text-muted-foreground text-xs font-medium sm:text-sm">
-        {t('conversation.attachments.attach')}
-      </span>
-      <input
-        type="file"
-        className="hidden"
-        multiple
-        accept={ATTACHMENT_FILE_ACCEPT_ATTR}
-        onChange={onChange}
-      />
-    </label>
+    <Button asChild variant="outline" size="sm" shape="pill">
+      {/* translate="no": Chrome's page translator rewrites text nodes inside
+          this label into <font> wrappers and React then loses the control — a
+          user with auto-translate on rage-clicked a dead Attach button until
+          they reloaded. Keep the composer's controls out of the translator. */}
+      <label translate="no" className="cursor-pointer justify-start">
+        <img
+          src={ClipIcon}
+          alt="Attach"
+          className="h-3.5 w-3.5 shrink-0 sm:h-4 sm:w-4 dark:invert"
+        />
+        <span className="dark:text-foreground text-muted-foreground text-xs sm:text-sm">
+          {t('conversation.attachments.attach')}
+        </span>
+        <input
+          type="file"
+          className="hidden"
+          multiple
+          accept={ATTACHMENT_FILE_ACCEPT_ATTR}
+          onChange={onChange}
+        />
+      </label>
+    </Button>
   );
 }
diff --git a/frontend/src/components/message-input/AttachmentChipList.tsx b/frontend/src/components/message-input/AttachmentChipList.tsx
index 4d1a9b3e..5eea1bce 100644
--- a/frontend/src/components/message-input/AttachmentChipList.tsx
+++ b/frontend/src/components/message-input/AttachmentChipList.tsx
@@ -58,7 +58,7 @@ export default function AttachmentChipList({
                 attachment.status !== 'completed' ? 'opacity-70' : 'opacity-100'
               } ${
                 draggingId === attachment.id
-                  ? 'ring-dashed opacity-60 ring-2 ring-purple-200'
+                  ? 'ring-primary/30 opacity-60 ring-2'
                   : ''
               }`}
               title={
@@ -98,7 +98,7 @@ export default function AttachmentChipList({
                         fill="none"
                       />
                       <circle
-                        className="text-[#ECECF1]"
+                        className="text-primary-foreground"
                         cx="12"
                         cy="12"
                         r="10"
@@ -123,8 +123,9 @@ export default function AttachmentChipList({
               <Button
                 type="button"
                 variant="ghost"
-                size="icon-sm"
-                className="ml-1.5 h-auto w-auto rounded-full p-1"
+                size="icon-xs"
+                shape="pill"
+                className="ml-1.5"
                 onClick={() => {
                   onRemove(attachment.id);
                 }}
@@ -142,7 +143,7 @@ export default function AttachmentChipList({
 
       {failures.length > 0 && (
         <div
-          className="flex flex-col gap-0.5 px-2 pb-1 text-xs text-[#B42318] sm:px-3"
+          className="text-destructive flex flex-col gap-0.5 px-2 pb-1 text-xs sm:px-3"
           role="alert"
         >
           {failures.map((attachment) => (
@@ -155,7 +156,7 @@ export default function AttachmentChipList({
 
       {unreadable.length > 0 && (
         <div
-          className="flex flex-col gap-0.5 px-2 pb-1 text-xs text-[#B54708] sm:px-3 dark:text-[#FDB022]"
+          className="text-warning flex flex-col gap-0.5 px-2 pb-1 text-xs sm:px-3"
           role="status"
         >
           {unreadable.map((attachment) => (
diff --git a/frontend/src/components/message-input/MicButton.tsx b/frontend/src/components/message-input/MicButton.tsx
index 23dc1590..13ffdd63 100644
--- a/frontend/src/components/message-input/MicButton.tsx
+++ b/frontend/src/components/message-input/MicButton.tsx
@@ -29,39 +29,33 @@ export default function MicButton({
 }: MicButtonProps) {
   const voiceButtonLabel = getVoiceButtonLabel(recordingState);
   const voiceButtonText = getVoiceButtonText(recordingState);
+  const isRecording = recordingState === 'recording';
 
   return (
     <Button
       type="button"
-      variant="outline"
+      variant={isRecording ? 'destructive-outline' : 'outline'}
       size="sm"
+      shape="pill"
       onClick={onClick}
       aria-label={voiceButtonLabel}
       title={voiceButtonLabel}
       disabled={loading || recordingState === 'transcribing'}
-      className={`xs:px-3 xs:py-1.5 dark:border-border flex h-auto items-center justify-start rounded-full border bg-transparent px-2 py-1 shadow-none transition-colors ${
-        recordingState === 'recording'
-          ? 'border-[#B42318] bg-[#FEE4E2] text-[#B42318] dark:bg-[#4A2323]'
-          : 'border-border dark:hover:bg-accent hover:bg-gray-100'
-      } ${
-        loading || recordingState === 'transcribing'
-          ? 'cursor-not-allowed opacity-60'
-          : ''
-      }`}
+      className="justify-start"
     >
       {recordingState === 'transcribing' ? (
-        <LoaderCircle className="mr-1 h-3.5 w-3.5 animate-spin sm:mr-1.5 sm:h-4 sm:w-4" />
-      ) : recordingState === 'recording' ? (
-        <Square className="mr-1 h-3.5 w-3.5 fill-current sm:mr-1.5 sm:h-4 sm:w-4" />
+        <LoaderCircle className="size-3.5 animate-spin sm:size-4" />
+      ) : isRecording ? (
+        <Square className="size-3.5 fill-current sm:size-4" />
       ) : (
-        <Mic className="mr-1 h-3.5 w-3.5 sm:mr-1.5 sm:h-4 sm:w-4" />
+        <Mic className="size-3.5 sm:size-4" />
       )}
       <span
-        className={`xs:text-xs dark:text-foreground text-xs font-medium sm:text-sm ${
-          recordingState === 'recording'
-            ? 'text-[#B42318]'
-            : 'text-muted-foreground'
-        }`}
+        className={
+          isRecording
+            ? 'text-xs sm:text-sm'
+            : 'text-muted-foreground dark:text-foreground text-xs sm:text-sm'
+        }
       >
         {voiceButtonText}
       </span>
diff --git a/frontend/src/components/message-input/SourcesTrigger.tsx b/frontend/src/components/message-input/SourcesTrigger.tsx
index f8edb1fc..f6b5f6aa 100644
--- a/frontend/src/components/message-input/SourcesTrigger.tsx
+++ b/frontend/src/components/message-input/SourcesTrigger.tsx
@@ -51,7 +51,8 @@ export default function SourcesTrigger({
           type="button"
           variant="outline"
           size="sm"
-          className="xs:px-3 xs:py-1.5 dark:border-border border-border hover:bg-accent dark:hover:bg-muted flex h-auto max-w-[130px] items-center justify-start rounded-full border bg-transparent px-2 py-1 shadow-none transition-colors sm:max-w-[150px]"
+          shape="pill"
+          className="max-w-[130px] justify-start sm:max-w-[150px]"
           title={
             selectedDocs && selectedDocs.length > 0
               ? selectedDocs.map((doc) => doc.name).join(', ')
@@ -61,9 +62,9 @@ export default function SourcesTrigger({
           <img
             src={SourceIcon}
             alt="Sources"
-            className="mr-1 h-3.5 w-3.5 shrink-0 sm:mr-1.5 sm:h-4 sm:w-4 dark:invert"
+            className="h-3.5 w-3.5 shrink-0 sm:h-4 sm:w-4 dark:invert"
           />
-          <span className="xs:text-xs dark:text-foreground text-muted-foreground truncate overflow-hidden text-xs font-medium sm:text-sm">
+          <span className="dark:text-foreground text-muted-foreground truncate overflow-hidden text-xs sm:text-sm">
             {selectedDocs && selectedDocs.length > 0
               ? selectedDocs.length === 1
                 ? selectedDocs[0].name
diff --git a/frontend/src/components/message-input/ToolsTrigger.tsx b/frontend/src/components/message-input/ToolsTrigger.tsx
index 6fb2a49a..bed3389d 100644
--- a/frontend/src/components/message-input/ToolsTrigger.tsx
+++ b/frontend/src/components/message-input/ToolsTrigger.tsx
@@ -57,14 +57,15 @@ export default function ToolsTrigger({
           type="button"
           variant="outline"
           size="sm"
-          className="xs:px-3 xs:py-1.5 xs:max-w-[150px] dark:border-border border-border hover:bg-muted dark:hover:bg-muted flex h-auto max-w-[130px] items-center justify-start rounded-full border bg-transparent px-2 py-1 shadow-none transition-colors"
+          shape="pill"
+          className="max-w-[130px] justify-start"
         >
           <img
             src={ToolIcon}
             alt="Tools"
-            className="mr-1 h-3.5 w-3.5 shrink-0 sm:mr-1.5 sm:h-4 sm:w-4 dark:invert"
+            className="h-3.5 w-3.5 shrink-0 sm:h-4 sm:w-4 dark:invert"
           />
-          <span className="xs:text-xs dark:text-foreground text-muted-foreground truncate overflow-hidden text-xs font-medium sm:text-sm">
+          <span className="dark:text-foreground text-muted-foreground truncate overflow-hidden text-xs sm:text-sm">
             {t('settings.tools.label')}
           </span>
         </Button>
diff --git a/frontend/src/components/tree/TreeBrowser.tsx b/frontend/src/components/tree/TreeBrowser.tsx
index 64ce9e3f..cf32bb7c 100644
--- a/frontend/src/components/tree/TreeBrowser.tsx
+++ b/frontend/src/components/tree/TreeBrowser.tsx
@@ -443,8 +443,9 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
         <Button
           type="button"
           variant="ghost"
+          size="icon"
           onClick={(e) => e.stopPropagation()}
-          className="dark:hover:bg-muted h-[35px] w-6 shrink-0 p-0 hover:bg-[#EBEBEB]"
+          className="h-[35px] w-6 shrink-0"
           aria-label={t('settings.sources.menuAlt')}
         >
           <img
@@ -629,11 +630,12 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
           }
         }}
         placeholder={t('settings.sources.searchFiles')}
-        className={`h-[38px] px-4 py-2 ${searchQuery ? 'rounded-t-3xl' : 'rounded-3xl'}`}
+        shape="pill"
+        className="h-[38px]"
       />
 
       {searchQuery && (
-        <div className="border-border bg-card dark:border-border dark:bg-card absolute top-full right-0 left-0 z-20 max-h-[calc(100vh-200px)] w-full overflow-hidden rounded-b-xl border border-t-0 shadow-lg transition-all duration-200">
+        <div className="border-border bg-popover text-popover-foreground absolute top-full right-0 left-0 z-20 mt-1 max-h-[calc(100vh-200px)] w-full overflow-hidden rounded-xl border shadow-md transition-all duration-200">
           <div className="max-h-[calc(100vh-200px)] overflow-x-hidden overflow-y-auto overscroll-contain">
             {searchResults.length === 0 ? (
               <div className="text-muted-foreground py-2 text-center text-sm">
@@ -676,8 +678,9 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
         <Button
           type="button"
           variant="outline"
-          size="icon-sm"
-          className="text-muted-foreground mr-3 h-[29px] w-[29px] rounded-full p-2 dark:border-0"
+          size="icon-xs"
+          shape="pill"
+          className="mr-3"
           onClick={handleBackNavigation}
         >
           <img src={ArrowLeft} alt="left-arrow" className="h-3 w-3" />
@@ -692,9 +695,7 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
               <span className="text-muted-foreground mx-1 shrink-0">/</span>
               {currentPath.map((dir, index) => (
                 <React.Fragment key={index}>
-                  <span className="dark:text-foreground wrap-break-word text-gray-700">
-                    {dir}
-                  </span>
+                  <span className="text-foreground wrap-break-word">{dir}</span>
                   {index < currentPath.length - 1 && (
                     <span className="text-muted-foreground mx-1 shrink-0">
                       /
@@ -707,7 +708,7 @@ const TreeBrowser: React.FC<TreeBrowserProps> = ({
           {selectedFile && (
             <>
               <span className="text-muted-foreground mx-1 shrink-0">/</span>
-              <span className="dark:text-foreground wrap-break-word text-gray-700">
+              <span className="text-foreground wrap-break-word">
                 {selectedFile.name}
               </span>
             </>
diff --git a/frontend/src/components/ui/accordion.test.tsx b/frontend/src/components/ui/accordion.test.tsx
new file mode 100644
index 00000000..eb46b580
--- /dev/null
+++ b/frontend/src/components/ui/accordion.test.tsx
@@ -0,0 +1,49 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from './accordion';
+
+function renderAccordion(): string {
+  return renderToStaticMarkup(
+    <Accordion type="single" collapsible>
+      <AccordionItem value="audit">
+        <AccordionTrigger>Recent activity</AccordionTrigger>
+        <AccordionContent>Rows</AccordionContent>
+      </AccordionItem>
+    </Accordion>,
+  );
+}
+
+/** The class attribute of the element carrying the given data-slot. */
+function slotClasses(html: string, slot: string): string {
+  const tag = new RegExp(`<[^>]*data-slot="${slot}"[^>]*>`).exec(html)?.[0];
+  return /class="([^"]*)"/.exec(tag ?? '')?.[1] ?? '';
+}
+
+describe('AccordionTrigger', () => {
+  it('carries its own inset and section-heading type', () => {
+    const classes = slotClasses(renderAccordion(), 'accordion-trigger');
+    expect(classes).toContain('px-4');
+    expect(classes).toContain('py-3');
+    expect(classes).toContain('text-sm');
+    expect(classes).toContain('font-medium');
+  });
+
+  it('draws the focus ring inside the item, which clips outside it', () => {
+    const classes = slotClasses(renderAccordion(), 'accordion-trigger');
+    expect(classes).toContain('focus-visible:ring-3');
+    expect(classes).toContain('focus-visible:ring-inset');
+    expect(classes).not.toContain('focus-visible:ring-2');
+  });
+
+  it('keeps the chevron in muted-foreground in dark mode', () => {
+    const html = renderAccordion();
+    expect(html).toContain('text-muted-foreground');
+    expect(html).not.toContain('dark:invert');
+  });
+});
diff --git a/frontend/src/components/ui/accordion.tsx b/frontend/src/components/ui/accordion.tsx
index 85d9a075..81332698 100644
--- a/frontend/src/components/ui/accordion.tsx
+++ b/frontend/src/components/ui/accordion.tsx
@@ -33,14 +33,14 @@ function AccordionTrigger({
       <AccordionPrimitive.Trigger
         data-slot="accordion-trigger"
         className={cn(
-          'focus-visible:ring-ring/50 flex flex-1 items-center justify-between gap-4 text-left transition-all outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180',
+          'focus-visible:ring-ring/50 flex flex-1 items-center justify-between gap-4 px-4 py-3 text-left text-sm font-medium transition-all outline-none focus-visible:ring-3 focus-visible:ring-inset disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180',
           className,
         )}
         {...props}
       >
         {children}
         <ChevronDownIcon
-          className="text-muted-foreground h-5 w-5 shrink-0 transition-transform duration-200 dark:invert"
+          className="text-muted-foreground h-5 w-5 shrink-0 transition-transform duration-200"
           aria-hidden="true"
         />
       </AccordionPrimitive.Trigger>
diff --git a/frontend/src/components/ui/alert.test.tsx b/frontend/src/components/ui/alert.test.tsx
new file mode 100644
index 00000000..de7e6ad1
--- /dev/null
+++ b/frontend/src/components/ui/alert.test.tsx
@@ -0,0 +1,55 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { Alert, AlertDescription } from './alert';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  container.remove();
+});
+
+const render = async (element: React.ReactElement) => {
+  await act(async () => root.render(element));
+};
+
+const alertRole = () => container.firstElementChild!.getAttribute('role');
+
+describe('Alert', () => {
+  it.each(['default', 'destructive', 'warning', 'info'] as const)(
+    'announces %s assertively',
+    async (variant) => {
+      await render(
+        <Alert variant={variant}>
+          <AlertDescription>Notice</AlertDescription>
+        </Alert>,
+      );
+      expect(alertRole()).toBe('alert');
+    },
+  );
+
+  it('announces success politely', async () => {
+    await render(
+      <Alert variant="success">
+        <AlertDescription>Done</AlertDescription>
+      </Alert>,
+    );
+    expect(alertRole()).toBe('status');
+  });
+
+  it('lets the caller override the role', async () => {
+    await render(<Alert variant="destructive" role="status" />);
+    expect(alertRole()).toBe('status');
+  });
+});
diff --git a/frontend/src/components/ui/alert.tsx b/frontend/src/components/ui/alert.tsx
index 4def013a..4d411f56 100644
--- a/frontend/src/components/ui/alert.tsx
+++ b/frontend/src/components/ui/alert.tsx
@@ -10,7 +10,12 @@ const alertVariants = cva(
       variant: {
         default: 'bg-background text-foreground',
         destructive:
-          'border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive',
+          'border-destructive/50 bg-destructive/10 text-destructive [&>svg]:text-destructive',
+        success:
+          'border-success/50 bg-success/10 text-success [&>svg]:text-success',
+        warning:
+          'border-warning/50 bg-warning/10 text-warning [&>svg]:text-warning',
+        info: 'border-info/50 bg-info/10 text-info [&>svg]:text-info',
       },
     },
     defaultVariants: {
@@ -25,7 +30,8 @@ const Alert = React.forwardRef<
 >(({ className, variant, ...props }, ref) => (
   <div
     ref={ref}
-    role="alert"
+    // A success notice confirms rather than interrupts, so it is polite.
+    role={variant === 'success' ? 'status' : 'alert'}
     className={cn(alertVariants({ variant }), className)}
     {...props}
   />
diff --git a/frontend/src/components/ui/avatar.test.tsx b/frontend/src/components/ui/avatar.test.tsx
new file mode 100644
index 00000000..15d5e58b
--- /dev/null
+++ b/frontend/src/components/ui/avatar.test.tsx
@@ -0,0 +1,34 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Avatar, avatarVariants } from './avatar';
+
+describe('Avatar variants', () => {
+  it('adds no sizing or radius unless asked, so image avatars are unchanged', () => {
+    const html = renderToStaticMarkup(<Avatar src="/a.png" />);
+    expect(html).toContain('class="shrink-0"');
+  });
+
+  it('sizes and shapes the initials box', () => {
+    const classes = avatarVariants({
+      size: 'lg',
+      shape: 'circle',
+      variant: 'primary',
+    });
+    expect(classes).toContain('size-9');
+    expect(classes).toContain('rounded-full');
+    expect(classes).toContain('bg-primary/10');
+    expect(classes).toContain('items-center');
+  });
+
+  it('renders children instead of the image when given', () => {
+    const html = renderToStaticMarkup(
+      <Avatar size="sm" shape="square" variant="muted">
+        LK
+      </Avatar>,
+    );
+    expect(html).toContain('LK');
+    expect(html).not.toContain('<img');
+    expect(html).toContain('rounded-md');
+  });
+});
diff --git a/frontend/src/components/ui/avatar.tsx b/frontend/src/components/ui/avatar.tsx
index fcf22994..3808252b 100644
--- a/frontend/src/components/ui/avatar.tsx
+++ b/frontend/src/components/ui/avatar.tsx
@@ -1,10 +1,41 @@
 import * as React from 'react';
 import { useEffect, useState } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
 
 import Robot from '../../assets/robot.svg';
 import { cn } from '@/lib/utils';
 
-type AvatarProps = {
+const avatarVariants = cva('shrink-0', {
+  variants: {
+    // `none` keeps the historical behaviour where the image sets the size.
+    size: {
+      none: '',
+      sm: 'flex size-7 items-center justify-center overflow-hidden text-xs',
+      default:
+        'flex size-8 items-center justify-center overflow-hidden text-sm',
+      lg: 'flex size-9 items-center justify-center overflow-hidden text-sm',
+      xl: 'flex size-10 items-center justify-center overflow-hidden text-base',
+    },
+    shape: {
+      none: '',
+      circle: 'rounded-full',
+      square: 'rounded-md',
+    },
+    // Background for initials or icon fallbacks rendered via `children`.
+    variant: {
+      default: '',
+      primary: 'bg-primary/10 text-primary font-medium dark:bg-primary/20',
+      muted: 'bg-muted-foreground/15 text-foreground font-medium',
+    },
+  },
+  defaultVariants: {
+    size: 'none',
+    shape: 'none',
+    variant: 'default',
+  },
+});
+
+type AvatarProps = VariantProps<typeof avatarVariants> & {
   src?: string | null;
   alt?: string;
   fallbackSrc?: string;
@@ -20,6 +51,9 @@ function Avatar({
   className,
   imgClassName,
   children,
+  size = 'none',
+  shape = 'none',
+  variant = 'default',
 }: AvatarProps) {
   const resolvedSrc = src && src.trim() !== '' ? src : fallbackSrc;
   const [currentSrc, setCurrentSrc] = useState(resolvedSrc);
@@ -32,7 +66,13 @@ function Avatar({
   }, [src, fallbackSrc]);
 
   return (
-    <div data-slot="avatar" className={cn('shrink-0', className)}>
+    <div
+      data-slot="avatar"
+      data-size={size}
+      data-shape={shape}
+      data-variant={variant}
+      className={cn(avatarVariants({ size, shape, variant }), className)}
+    >
       {children ?? (
         <img
           src={currentSrc}
@@ -49,4 +89,4 @@ function Avatar({
   );
 }
 
-export { Avatar };
+export { Avatar, avatarVariants };
diff --git a/frontend/src/components/ui/badge.test.tsx b/frontend/src/components/ui/badge.test.tsx
new file mode 100644
index 00000000..0e7264a3
--- /dev/null
+++ b/frontend/src/components/ui/badge.test.tsx
@@ -0,0 +1,39 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Badge, badgeVariants } from './badge';
+
+describe('Badge', () => {
+  it('is a soft brand pill by default', () => {
+    const html = renderToStaticMarkup(<Badge>Beta</Badge>);
+    expect(html).toContain('rounded-full');
+    expect(html).toContain('bg-primary/10');
+    expect(html).toContain('data-variant="default"');
+  });
+
+  it.each([
+    ['success', 'text-success'],
+    ['warning', 'text-warning'],
+    ['destructive', 'text-destructive'],
+    ['info', 'text-info'],
+    ['neutral', 'text-muted-foreground'],
+  ] as const)('variant %s uses its semantic token', (variant, cls) => {
+    expect(badgeVariants({ variant })).toContain(cls);
+  });
+
+  it('never uses raw palette colours', () => {
+    for (const variant of [
+      'default',
+      'neutral',
+      'success',
+      'warning',
+      'destructive',
+      'info',
+      'outline',
+    ] as const) {
+      expect(badgeVariants({ variant })).not.toMatch(
+        /\b(bg|text|border)-(red|green|amber|yellow|blue|gray|purple)-\d+/,
+      );
+    }
+  });
+});
diff --git a/frontend/src/components/ui/badge.tsx b/frontend/src/components/ui/badge.tsx
new file mode 100644
index 00000000..0fa86c7f
--- /dev/null
+++ b/frontend/src/components/ui/badge.tsx
@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+const badgeVariants = cva(
+  'inline-flex w-fit shrink-0 items-center justify-center gap-1 rounded-full border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap [&>svg]:pointer-events-none [&>svg]:size-3',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary/10 text-primary dark:bg-primary/20',
+        neutral: 'bg-muted-foreground/15 text-muted-foreground',
+        success: 'bg-success/10 text-success dark:bg-success/15',
+        warning: 'bg-warning/10 text-warning dark:bg-warning/15',
+        destructive:
+          'bg-destructive/10 text-destructive dark:bg-destructive/15',
+        info: 'bg-info/10 text-info dark:bg-info/15',
+        outline: 'border-border text-foreground',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+/**
+ * Small status or category pill. Use the `variant` for meaning (success,
+ * warning, destructive, info, neutral) instead of raw palette classes.
+ */
+function Badge({
+  className,
+  variant = 'default',
+  asChild = false,
+  ...props
+}: React.ComponentProps<'span'> &
+  VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : 'span';
+
+  return (
+    <Comp
+      data-slot="badge"
+      data-variant={variant}
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+export { Badge, badgeVariants };
diff --git a/frontend/src/components/ui/breadcrumb.test.tsx b/frontend/src/components/ui/breadcrumb.test.tsx
new file mode 100644
index 00000000..5f6d9b9c
--- /dev/null
+++ b/frontend/src/components/ui/breadcrumb.test.tsx
@@ -0,0 +1,24 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { BreadcrumbLink } from './breadcrumb';
+
+describe('BreadcrumbLink', () => {
+  it('shows the standard focus ring on an anchor', () => {
+    const html = renderToStaticMarkup(
+      <BreadcrumbLink href="/agents">Agents</BreadcrumbLink>,
+    );
+    expect(html).toContain('focus-visible:ring-3');
+    expect(html).toContain('focus-visible:ring-ring/50');
+    expect(html).toContain('outline-none');
+  });
+
+  it('passes the focus ring through asChild to a button crumb', () => {
+    const html = renderToStaticMarkup(
+      <BreadcrumbLink asChild>
+        <button type="button">My Drive</button>
+      </BreadcrumbLink>,
+    );
+    expect(html).toMatch(/<button[^>]*focus-visible:ring-3/);
+  });
+});
diff --git a/frontend/src/components/ui/breadcrumb.tsx b/frontend/src/components/ui/breadcrumb.tsx
index 54a4076e..2c992a26 100644
--- a/frontend/src/components/ui/breadcrumb.tsx
+++ b/frontend/src/components/ui/breadcrumb.tsx
@@ -43,7 +43,10 @@ function BreadcrumbLink({
   return (
     <Comp
       data-slot="breadcrumb-link"
-      className={cn('hover:text-foreground transition-colors', className)}
+      className={cn(
+        'hover:text-foreground focus-visible:ring-ring/50 rounded-sm transition-colors outline-none focus-visible:ring-3',
+        className,
+      )}
       {...props}
     />
   );
@@ -56,7 +59,7 @@ function BreadcrumbPage({ className, ...props }: React.ComponentProps<'span'>) {
       role="link"
       aria-disabled="true"
       aria-current="page"
-      className={cn('text-foreground font-normal', className)}
+      className={cn('text-foreground truncate font-normal', className)}
       {...props}
     />
   );
diff --git a/frontend/src/components/ui/button.test.tsx b/frontend/src/components/ui/button.test.tsx
new file mode 100644
index 00000000..4dbefcab
--- /dev/null
+++ b/frontend/src/components/ui/button.test.tsx
@@ -0,0 +1,166 @@
+import type React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Button, buttonVariants } from './button';
+
+/** The class attribute of the rendered root element. */
+function renderedClasses(element: React.ReactElement): string {
+  const html = renderToStaticMarkup(element);
+  return /class="([^"]*)"/.exec(html)?.[1] ?? '';
+}
+
+describe('Button variants', () => {
+  it('renders a rectangular medium button by default', () => {
+    const html = renderToStaticMarkup(<Button>Save</Button>);
+    expect(html).toContain('rounded-md');
+    expect(html).toContain('h-9');
+    expect(html).toContain('data-shape="default"');
+  });
+
+  it('shape="pill" swaps the radius and widens the padding', () => {
+    // Rendered classes go through cn(), which resolves the compound
+    // variant's px-5 against the default size's px-4.
+    const classes = renderedClasses(<Button shape="pill">Save</Button>);
+    expect(classes).toContain('rounded-full');
+    expect(classes).not.toContain('rounded-md');
+    expect(classes).toContain('px-5');
+    expect(classes).not.toMatch(/(^|\s)px-4(\s|$)/);
+  });
+
+  it('large pills get the widest padding', () => {
+    const classes = buttonVariants({ shape: 'pill', size: 'lg' });
+    expect(classes).toContain('px-6');
+    expect(classes).toContain('h-10');
+  });
+
+  it('size="xs" is a compact text-xs button', () => {
+    const classes = renderedClasses(<Button size="xs">Save</Button>);
+    expect(classes).toContain('h-7');
+    expect(classes).toContain('text-xs');
+    expect(classes).not.toMatch(/(^|\s)text-sm(\s|$)/);
+  });
+
+  it('exposes muted and brand-outline variants', () => {
+    expect(buttonVariants({ variant: 'ghost-muted' })).toContain(
+      'text-muted-foreground',
+    );
+    expect(buttonVariants({ variant: 'outline-primary' })).toContain(
+      'border-primary',
+    );
+  });
+
+  it('variant="ghost-destructive" is a muted icon that warns red on hover', () => {
+    const classes = buttonVariants({ variant: 'ghost-destructive' }).split(' ');
+    expect(classes).toContain('text-muted-foreground');
+    expect(classes).toContain('hover:text-destructive');
+    expect(classes).toContain('hover:bg-accent');
+    expect(classes).toContain('dark:hover:bg-accent/50');
+  });
+
+  it('size="inline" adds no height or padding, so a link sits mid-sentence', () => {
+    const classes = buttonVariants({ variant: 'link', size: 'inline' }).split(
+      ' ',
+    );
+    expect(classes).toContain('h-auto');
+    expect(classes).toContain('p-0');
+    expect(classes.some((c) => /^h-\d/.test(c))).toBe(false);
+    expect(classes.some((c) => /^px-\d/.test(c))).toBe(false);
+  });
+
+  it('lets callers pass layout classes through', () => {
+    const html = renderToStaticMarkup(
+      <Button className="mt-4 w-full">Save</Button>,
+    );
+    expect(html).toContain('mt-4');
+    expect(html).toContain('w-full');
+  });
+
+  it('variant="sidebar-item" is a full-width nav row, not a centred button', () => {
+    const classes = renderedClasses(
+      <Button variant="sidebar-item" aria-current="page">
+        Settings
+      </Button>,
+    ).split(' ');
+    for (const cls of [
+      'hover:bg-sidebar-accent',
+      'aria-[current=page]:bg-sidebar-accent',
+      'justify-start',
+      'gap-2.5',
+      'pl-3',
+      'pr-0',
+      'rounded-full',
+      'font-normal',
+    ]) {
+      expect(classes).toContain(cls);
+    }
+    // The default radius, centring and weight must not survive the merge.
+    // (The size's px-4 may remain; pl-3/pr-0 are emitted after padding-inline
+    // in Tailwind v4, so they win in CSS.)
+    for (const cls of ['rounded-md', 'justify-center', 'font-medium']) {
+      expect(classes).not.toContain(cls);
+    }
+  });
+
+  it('variant="tab" is an underline tab: square, muted, with the active state on data-active', () => {
+    const classes = renderedClasses(<Button variant="tab">My Files</Button>);
+    expect(classes).toContain('rounded-none');
+    expect(classes).not.toContain('rounded-md');
+    expect(classes).toContain('border-b-2');
+    expect(classes).toContain('border-transparent');
+    expect(classes).toContain('text-muted-foreground');
+    expect(classes).toContain('data-[active=true]:border-primary');
+    expect(classes).toContain('data-[active=true]:text-foreground');
+    expect(classes).not.toContain('hover:bg-accent');
+  });
+
+  it('variant="tab" size="inline" keeps a 4px gap above the underline', () => {
+    const classes = renderedClasses(
+      <Button variant="tab" size="inline">
+        Logs
+      </Button>,
+    );
+    expect(classes).toContain('h-auto');
+    expect(classes).toContain('pb-1');
+  });
+
+  it('size="field" is the 42px form-row height shared with Input and SelectTrigger lg', () => {
+    const classes = renderedClasses(<Button size="field">Add</Button>).split(
+      ' ',
+    );
+    expect(classes).toContain('h-10.5');
+    expect(classes).toContain('px-4');
+    expect(classes).not.toContain('h-9');
+  });
+
+  it('a field pill starts its text 20px in, like the Input and Select pills', () => {
+    const classes = renderedClasses(
+      <Button variant="combobox" size="field" shape="pill">
+        Select sources
+      </Button>,
+    ).split(' ');
+    expect(classes).toContain('h-10.5');
+    expect(classes).toContain('rounded-full');
+    expect(classes).toContain('px-5');
+    expect(classes).not.toContain('px-4');
+  });
+
+  it('variant="section-toggle" is a foreground title with a primary chevron and no ring of its own', () => {
+    const classes = renderedClasses(
+      <Button variant="section-toggle" size="sm">
+        Advanced
+      </Button>,
+    ).split(' ');
+    expect(classes).toContain('text-foreground');
+    expect(classes).toContain('decoration-primary');
+    expect(classes).toContain('hover:underline');
+    // Rendered HTML escapes `&>`, so read this one off the variant string.
+    expect(buttonVariants({ variant: 'section-toggle' }).split(' ')).toContain(
+      '[&>svg]:text-primary',
+    );
+    // The host panel draws the focus ring, so the button's own is off.
+    expect(classes).toContain('focus-visible:ring-0');
+    expect(classes).not.toContain('focus-visible:ring-3');
+    expect(classes).not.toContain('text-primary');
+  });
+});
diff --git a/frontend/src/components/ui/button.tsx b/frontend/src/components/ui/button.tsx
index 6bac0ae2..3041e75d 100644
--- a/frontend/src/components/ui/button.tsx
+++ b/frontend/src/components/ui/button.tsx
@@ -5,35 +5,90 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '@/lib/utils';
 
 const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
   {
     variants: {
       variant: {
         default: 'bg-primary text-primary-foreground hover:bg-primary/90',
         destructive:
-          'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+          'bg-destructive text-destructive-foreground hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
         'destructive-outline':
-          'border border-destructive text-destructive bg-transparent hover:bg-destructive hover:text-white focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40',
+          'border border-destructive text-destructive bg-transparent hover:bg-destructive hover:text-destructive-foreground focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40',
         outline:
           'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',
+        'outline-primary':
+          'border border-primary text-primary bg-transparent hover:bg-primary hover:text-primary-foreground',
         secondary:
           'bg-secondary text-secondary-foreground hover:bg-secondary/80',
         ghost:
           'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+        'ghost-muted':
+          'text-muted-foreground hover:bg-accent hover:text-foreground dark:hover:bg-accent/50',
+        // Icon actions that remove something: muted at rest, red on hover.
+        'ghost-destructive':
+          'text-muted-foreground hover:bg-accent hover:text-destructive dark:hover:bg-accent/50',
         link: 'text-primary underline-offset-4 hover:underline',
+        // Popover combobox triggers: mirrors SelectTrigger so the two sit
+        // side by side. Set data-placeholder while empty to mute the text.
+        // Rows in the navigation sidebar (Help, Settings, section links).
+        // Pair with aria-current="page" for the active row; the compound
+        // variant below sets the row's own padding and radius.
+        'sidebar-item':
+          'text-foreground hover:bg-sidebar-accent aria-[current=page]:bg-sidebar-accent',
+        combobox:
+          'border border-border bg-card font-normal shadow-xs hover:bg-accent data-placeholder:text-muted-foreground',
+        // Underline tabs (FilePicker's drives, the agent page sub-nav). Mark the
+        // current tab with data-active; the 2px border is always there so the
+        // row height doesn't move. The compound variant squares the corners.
+        tab: 'border-b-2 border-transparent text-muted-foreground hover:text-foreground hover:border-border data-[active=true]:border-primary data-[active=true]:text-foreground',
+        // A section panel's disclosure header (NewAgent's Advanced,
+        // Guardrails): a foreground title with a primary chevron and a primary
+        // underline on hover. It draws no ring of its own; the panel around it
+        // shows focus with has-[[data-variant=section-toggle]:focus-visible].
+        'section-toggle':
+          'text-foreground underline-offset-4 decoration-primary hover:underline focus-visible:ring-0 [&>svg]:text-primary',
       },
       size: {
         default: 'h-9 px-4 py-2 has-[>svg]:px-3',
-        sm: 'h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5',
-        lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+        xs: "h-7 gap-1 px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+        sm: 'h-8 gap-1.5 px-3 has-[>svg]:px-2.5',
+        lg: 'h-10 px-6 has-[>svg]:px-4',
+        // The form-row height (42px), shared with Input default and
+        // SelectTrigger lg, for pickers and buttons that sit among fields.
+        field: 'h-10.5 px-4 has-[>svg]:px-3',
         icon: 'size-9',
+        'icon-xs': 'size-7',
         'icon-sm': 'size-8',
         'icon-lg': 'size-10',
+        // A link mid-sentence: no height or padding, so it wraps with the text.
+        inline: 'h-auto p-0',
+      },
+      shape: {
+        default: 'rounded-md',
+        pill: 'rounded-full',
       },
     },
+    compoundVariants: [
+      // Pills read as cramped at the rectangular paddings, so widen them.
+      { shape: 'pill', size: 'default', class: 'px-5 has-[>svg]:px-4' },
+      { shape: 'pill', size: 'lg', class: 'px-6 has-[>svg]:px-5' },
+      // Text starts 21px in, like the Input and SelectTrigger pills beside it.
+      { shape: 'pill', size: 'field', class: 'px-5 has-[>svg]:px-4' },
+      // Tabs sit on a baseline rule, so they never round off.
+      { variant: 'tab', class: 'rounded-none' },
+      // A padding-free tab (the agent sub-nav) keeps 4px above its underline.
+      { variant: 'tab', size: 'inline', class: 'pb-1' },
+      // Nav rows line their icons up on the left edge at every size/shape.
+      {
+        variant: 'sidebar-item',
+        class:
+          'justify-start gap-2.5 rounded-full pr-0 pl-3 font-normal has-[>svg]:pr-0 has-[>svg]:pl-3',
+      },
+    ],
     defaultVariants: {
       variant: 'default',
       size: 'default',
+      shape: 'default',
     },
   },
 );
@@ -42,6 +97,7 @@ function Button({
   className,
   variant = 'default',
   size = 'default',
+  shape = 'default',
   asChild = false,
   ...props
 }: React.ComponentProps<'button'> &
@@ -55,7 +111,8 @@ function Button({
       data-slot="button"
       data-variant={variant}
       data-size={size}
-      className={cn(buttonVariants({ variant, size, className }))}
+      data-shape={shape}
+      className={cn(buttonVariants({ variant, size, shape, className }))}
       {...props}
     />
   );
diff --git a/frontend/src/components/ui/calendar.tsx b/frontend/src/components/ui/calendar.tsx
index 318da8a3..e36e4606 100644
--- a/frontend/src/components/ui/calendar.tsx
+++ b/frontend/src/components/ui/calendar.tsx
@@ -72,7 +72,7 @@ function Calendar({
           defaultClassNames.dropdowns,
         ),
         dropdown_root: cn(
-          'relative rounded-md border border-input shadow-xs has-focus:border-ring has-focus:ring-[3px] has-focus:ring-ring/50',
+          'relative rounded-md border border-input shadow-xs has-focus:border-ring has-focus:ring-3 has-focus:ring-ring/50',
           defaultClassNames.dropdown_root,
         ),
         dropdown: cn(
@@ -89,7 +89,7 @@ function Calendar({
         month_grid: 'w-full border-collapse',
         weekdays: cn('flex', defaultClassNames.weekdays),
         weekday: cn(
-          'flex-1 rounded-md text-[0.8rem] font-normal text-muted-foreground select-none',
+          'flex-1 rounded-md text-xs font-normal text-muted-foreground select-none',
           defaultClassNames.weekday,
         ),
         week: cn('mt-2 flex w-full', defaultClassNames.week),
@@ -98,7 +98,7 @@ function Calendar({
           defaultClassNames.week_number_header,
         ),
         week_number: cn(
-          'text-[0.8rem] text-muted-foreground select-none',
+          'text-xs text-muted-foreground select-none',
           defaultClassNames.week_number,
         ),
         day: cn(
@@ -209,7 +209,9 @@ function CalendarDayButton({
       data-range-end={modifiers.range_end}
       data-range-middle={modifiers.range_middle}
       className={cn(
-        'group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-accent-foreground flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-[3px] data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md [&>span]:text-xs [&>span]:opacity-70',
+        'group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-accent-foreground flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:ring-3 data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-middle=true]:rounded-none data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md [&>span]:text-xs [&>span]:opacity-70',
+        /* eslint-disable-next-line shadcn/require-static-classes -- react-day-picker
+           hands these names back from getDefaultClassNames() at runtime. */
         defaultClassNames.day,
         className,
       )}
diff --git a/frontend/src/components/ui/card.test.tsx b/frontend/src/components/ui/card.test.tsx
new file mode 100644
index 00000000..43f87bee
--- /dev/null
+++ b/frontend/src/components/ui/card.test.tsx
@@ -0,0 +1,43 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Card, CardAction, CardHeader, CardTitle, cardVariants } from './card';
+
+describe('Card', () => {
+  it('is a bordered card surface by default', () => {
+    const html = renderToStaticMarkup(<Card>Body</Card>);
+    expect(html).toContain('rounded-2xl');
+    expect(html).toContain('bg-card');
+    expect(html).toContain('p-4');
+    expect(html).toContain('data-variant="outline"');
+  });
+
+  it('filled variant drops the border', () => {
+    const classes = cardVariants({ variant: 'filled' });
+    expect(classes).toContain('bg-muted');
+    expect(classes).not.toMatch(/(^|\s)border(\s|$)/);
+  });
+
+  it('interactive cards get hover, focus and selected styles', () => {
+    const html = renderToStaticMarkup(
+      <Card interactive selected asChild>
+        <button type="button">Pick me</button>
+      </Card>,
+    );
+    expect(html).toContain('<button');
+    expect(html).toContain('cursor-pointer');
+    expect(html).toContain('data-selected="true"');
+    expect(html).toContain('focus-visible:ring-3');
+  });
+
+  it('header places the action in the trailing column', () => {
+    const html = renderToStaticMarkup(
+      <CardHeader>
+        <CardTitle>Arc53</CardTitle>
+        <CardAction>menu</CardAction>
+      </CardHeader>,
+    );
+    expect(html).toContain('grid-cols-[1fr_auto]');
+    expect(html).toContain('col-start-2');
+  });
+});
diff --git a/frontend/src/components/ui/card.tsx b/frontend/src/components/ui/card.tsx
new file mode 100644
index 00000000..aa1eb091
--- /dev/null
+++ b/frontend/src/components/ui/card.tsx
@@ -0,0 +1,141 @@
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+const cardVariants = cva(
+  'text-card-foreground flex flex-col gap-3 rounded-2xl text-sm transition-colors',
+  {
+    variants: {
+      variant: {
+        // Bordered surface: lists of entities, panels, headers.
+        outline: 'border-border bg-card border',
+        // Filled, no border: tiles on a card-coloured page (sources, tools).
+        filled: 'bg-muted',
+        // Bordered on a muted page background.
+        subtle: 'border-border bg-background border',
+      },
+      padding: {
+        none: 'p-0',
+        sm: 'p-3',
+        default: 'p-4',
+        lg: 'p-6',
+      },
+      interactive: {
+        false: '',
+        // Whole card is a target: picker tiles, navigable list items.
+        true: 'hover:border-primary/40 hover:bg-accent focus-visible:border-ring focus-visible:ring-ring/50 cursor-pointer text-left outline-none focus-visible:ring-3 data-[selected=true]:border-primary data-[selected=true]:bg-primary/5',
+      },
+    },
+    defaultVariants: {
+      variant: 'outline',
+      padding: 'default',
+      interactive: false,
+    },
+  },
+);
+
+type CardProps = React.ComponentProps<'div'> &
+  VariantProps<typeof cardVariants> & {
+    /** Render the card as its child, e.g. a `<button>` or `<Link>`. */
+    asChild?: boolean;
+    /** Highlights an interactive card as the current choice. */
+    selected?: boolean;
+  };
+
+function Card({
+  className,
+  variant = 'outline',
+  padding = 'default',
+  interactive = false,
+  selected,
+  asChild = false,
+  ...props
+}: CardProps) {
+  const Comp = asChild ? Slot : 'div';
+  return (
+    <Comp
+      data-slot="card"
+      data-variant={variant}
+      data-selected={selected || undefined}
+      className={cn(cardVariants({ variant, padding, interactive }), className)}
+      {...props}
+    />
+  );
+}
+
+/** Title row with an optional trailing action (menu, chevron, button). */
+function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        'grid auto-rows-min grid-cols-[1fr_auto] items-start gap-x-3 gap-y-1',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn('text-foreground leading-snug font-semibold', className)}
+      {...props}
+    />
+  );
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn('text-muted-foreground text-sm', className)}
+      {...props}
+    />
+  );
+}
+
+/** Slot in the header's top-right corner. */
+function CardAction({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn('col-start-2 row-span-2 row-start-1 self-start', className)}
+      {...props}
+    />
+  );
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<'div'>) {
+  return <div data-slot="card-content" className={cn(className)} {...props} />;
+}
+
+/** Meta row or controls at the bottom; pushes to the end of tall cards. */
+function CardFooter({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        'text-muted-foreground mt-auto flex items-center gap-2 text-xs',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardAction,
+  CardContent,
+  CardFooter,
+  cardVariants,
+};
+export type { CardProps };
diff --git a/frontend/src/components/ui/command.test.tsx b/frontend/src/components/ui/command.test.tsx
new file mode 100644
index 00000000..082f7db0
--- /dev/null
+++ b/frontend/src/components/ui/command.test.tsx
@@ -0,0 +1,123 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from './command';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  container.remove();
+});
+
+const render = async (element: React.ReactElement) => {
+  await act(async () => root.render(element));
+};
+
+describe('Command', () => {
+  it('is a plain command surface by default', async () => {
+    await render(<Command />);
+    const cmd = document.querySelector('[data-slot="command"]')!;
+    expect(cmd.getAttribute('data-variant')).toBe('default');
+    expect(cmd.className).not.toContain('[[cmdk-item]]:py-3');
+  });
+
+  it('variant="palette" carries the palette spacing for input and rows', async () => {
+    await render(<Command variant="palette" />);
+    const cmd = document.querySelector('[data-slot="command"]')!;
+    expect(cmd.getAttribute('data-variant')).toBe('palette');
+    expect(cmd.className).toContain(
+      '**:data-[slot=command-input-wrapper]:h-12',
+    );
+    expect(cmd.className).toContain('**:[[cmdk-item]]:py-3');
+    expect(cmd.className).toContain('**:[[cmdk-item]]:px-2');
+  });
+});
+
+describe('CommandDialog', () => {
+  it('renders one palette Command and forwards commandProps to it', async () => {
+    await render(
+      <CommandDialog
+        open
+        showCloseButton={false}
+        commandProps={{ shouldFilter: false, label: 'Search' }}
+      >
+        <CommandInput
+          placeholder="Search"
+          value="zzz"
+          onValueChange={() => {}}
+        />
+        <CommandList>
+          <CommandItem value="a">Fuel surcharge policy</CommandItem>
+        </CommandList>
+      </CommandDialog>,
+    );
+    const commands = document.querySelectorAll('[data-slot="command"]');
+    expect(commands).toHaveLength(1);
+    expect(commands[0].getAttribute('data-variant')).toBe('palette');
+    // shouldFilter={false} reached cmdk: an item that doesn't match the query
+    // stays rendered.
+    expect(document.body.textContent).toContain('Fuel surcharge policy');
+  });
+
+  it('CommandItem checked marks the chosen item apart from the hover highlight', async () => {
+    await render(
+      <Command>
+        <CommandList>
+          <CommandItem value="a" checked>
+            Default
+          </CommandItem>
+          <CommandItem value="b">Strict</CommandItem>
+        </CommandList>
+      </Command>,
+    );
+    const items = document.querySelectorAll('[data-slot="command-item"]');
+    expect(items[0].getAttribute('data-checked')).toBe('true');
+    expect(items[0].className).toContain('data-[checked=true]:bg-secondary');
+    expect(items[1].hasAttribute('data-checked')).toBe(false);
+    expect(items[1].hasAttribute('checked')).toBe(false);
+  });
+
+  it('keeps the checked tint while highlighted and rings it in primary', async () => {
+    await render(
+      <Command>
+        <CommandList>
+          <CommandItem value="a" checked>
+            Default
+          </CommandItem>
+        </CommandList>
+      </Command>,
+    );
+    const classes = document
+      .querySelector('[data-slot="command-item"]')!
+      .className.split(' ');
+    // Stacked data attributes out-rank the plain data-[selected=true] accent.
+    for (const cls of [
+      'data-[checked=true]:data-[selected=true]:bg-secondary',
+      'data-[checked=true]:data-[selected=true]:text-secondary-foreground',
+      'data-[checked=true]:data-[selected=true]:ring-1',
+      'data-[checked=true]:data-[selected=true]:ring-inset',
+      'data-[checked=true]:data-[selected=true]:ring-primary',
+    ]) {
+      expect(classes).toContain(cls);
+    }
+    // The ordinary highlight is still there for unchecked rows.
+    expect(classes).toContain('data-[selected=true]:bg-accent');
+  });
+});
diff --git a/frontend/src/components/ui/command.tsx b/frontend/src/components/ui/command.tsx
index 6bff16e4..3717747b 100644
--- a/frontend/src/components/ui/command.tsx
+++ b/frontend/src/components/ui/command.tsx
@@ -11,15 +11,25 @@ import {
 } from '@/components/ui/dialog';
 import { cn } from '@/lib/utils';
 
-function Command({
-  className,
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive>) {
+// The search-palette spacing: a 48px input row and roomier rows. Shared by
+// CommandDialog and any palette rendered elsewhere (e.g. in a bottom sheet),
+// so both look the same.
+const PALETTE_CLASSES =
+  '**:[[cmdk-group-heading]]:text-muted-foreground **:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5 **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:font-medium **:[[cmdk-group]]:px-2 **:[[cmdk-input]]:h-12 **:[[cmdk-item]]:px-2 **:[[cmdk-item]]:py-3';
+
+type CommandProps = React.ComponentProps<typeof CommandPrimitive> & {
+  /** `palette` is the search-palette spacing CommandDialog uses. */
+  variant?: 'default' | 'palette';
+};
+
+function Command({ className, variant = 'default', ...props }: CommandProps) {
   return (
     <CommandPrimitive
       data-slot="command"
+      data-variant={variant}
       className={cn(
         'bg-popover text-popover-foreground flex h-full w-full flex-col overflow-hidden rounded-xl',
+        variant === 'palette' && PALETTE_CLASSES,
         className,
       )}
       {...props}
@@ -33,12 +43,18 @@ function CommandDialog({
   children,
   className,
   showCloseButton = true,
+  commandProps,
   ...props
 }: React.ComponentProps<typeof Dialog> & {
   title?: string;
   description?: string;
   className?: string;
   showCloseButton?: boolean;
+  /**
+   * Props for the palette's Command, e.g. `shouldFilter={false}` when the
+   * results come from a server search, or a controlled `value`.
+   */
+  commandProps?: Omit<CommandProps, 'variant' | 'children' | 'className'>;
 }) {
   return (
     <Dialog {...props}>
@@ -50,7 +66,7 @@ function CommandDialog({
         className={cn('overflow-hidden p-0', className)}
         showCloseButton={showCloseButton}
       >
-        <Command className="**:[[cmdk-group-heading]]:text-muted-foreground **:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5 **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:font-medium **:[[cmdk-group]]:px-2 **:[[cmdk-input]]:h-12 **:[[cmdk-item]]:px-2 **:[[cmdk-item]]:py-3">
+        <Command variant="palette" {...commandProps}>
           {children}
         </Command>
       </DialogContent>
@@ -137,15 +153,26 @@ function CommandSeparator({
   );
 }
 
+/**
+ * A row in a Command list. `checked` marks the item that is currently chosen
+ * (the active prompt in a picker) with a brand tint, apart from the
+ * `data-selected` highlight cmdk moves with the pointer and arrow keys. A
+ * checked row that is also highlighted keeps its tint and gains a 1px
+ * primary ring (the stacked data attributes out-rank the plain accent).
+ */
 function CommandItem({
   className,
+  checked,
   ...props
-}: React.ComponentProps<typeof CommandPrimitive.Item>) {
+}: React.ComponentProps<typeof CommandPrimitive.Item> & {
+  checked?: boolean;
+}) {
   return (
     <CommandPrimitive.Item
       data-slot="command-item"
+      data-checked={checked ? 'true' : undefined}
       className={cn(
-        "data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "data-[checked=true]:bg-secondary data-[checked=true]:text-secondary-foreground data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[checked=true]:data-[selected=true]:bg-secondary data-[checked=true]:data-[selected=true]:text-secondary-foreground data-[checked=true]:data-[selected=true]:ring-primary [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[checked=true]:data-[selected=true]:ring-1 data-[checked=true]:data-[selected=true]:ring-inset [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       {...props}
diff --git a/frontend/src/components/ui/dropzone.test.tsx b/frontend/src/components/ui/dropzone.test.tsx
new file mode 100644
index 00000000..568ca74a
--- /dev/null
+++ b/frontend/src/components/ui/dropzone.test.tsx
@@ -0,0 +1,42 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Dropzone } from './dropzone';
+
+describe('Dropzone', () => {
+  it('renders the default prompt as a dashed card target', () => {
+    const html = renderToStaticMarkup(<Dropzone onDrop={vi.fn()} />);
+    expect(html).toContain('Click to upload or drag and drop');
+    expect(html).toContain('border-dashed');
+    expect(html).toContain('data-slot="dropzone"');
+    expect(html).toContain('<input');
+  });
+
+  it('shows description, error and custom title', () => {
+    const html = renderToStaticMarkup(
+      <Dropzone
+        onDrop={vi.fn()}
+        title="Drop your agent"
+        description=".yaml or .yml"
+        error="Only .yaml files are supported"
+      />,
+    );
+    expect(html).toContain('Drop your agent');
+    expect(html).toContain('.yaml or .yml');
+    expect(html).toContain('Only .yaml files are supported');
+    expect(html).toContain('text-destructive');
+  });
+
+  it('marks the disabled and compact states with data attributes', () => {
+    const html = renderToStaticMarkup(
+      <Dropzone onDrop={vi.fn()} disabled size="compact" />,
+    );
+    expect(html).toContain('data-disabled="true"');
+    expect(html).toContain('data-size="compact"');
+  });
+
+  it('never uses raw palette colours', () => {
+    const html = renderToStaticMarkup(<Dropzone onDrop={vi.fn()} />);
+    expect(html).not.toMatch(/\b(bg|text|border)-(gray|red|green|blue)-\d+/);
+  });
+});
diff --git a/frontend/src/components/ui/dropzone.tsx b/frontend/src/components/ui/dropzone.tsx
new file mode 100644
index 00000000..7ed9c0ba
--- /dev/null
+++ b/frontend/src/components/ui/dropzone.tsx
@@ -0,0 +1,117 @@
+import * as React from 'react';
+import { CloudUpload } from 'lucide-react';
+import {
+  useDropzone,
+  type Accept,
+  type DropzoneOptions,
+  type FileRejection,
+} from 'react-dropzone';
+
+import { cn } from '@/lib/utils';
+
+type DropzoneProps = {
+  /** Receives accepted files and, when `accept`/`maxSize` reject some, the rejections. */
+  onDrop: (accepted: File[], rejections: FileRejection[]) => void;
+  /** MIME-type map, e.g. `{ 'application/x-yaml': ['.yaml', '.yml'] }`. */
+  accept?: Accept;
+  multiple?: boolean;
+  maxFiles?: number;
+  maxSize?: number;
+  disabled?: boolean;
+  /** Compact fits inside forms and modals; default is the full-height target. */
+  size?: 'default' | 'compact';
+  /** Main line. Defaults to the generic upload prompt. */
+  title?: React.ReactNode;
+  /** Secondary line for accepted types and limits, e.g. ".yaml, up to 5 MB". */
+  description?: React.ReactNode;
+  /** Replaces the cloud icon. */
+  icon?: React.ReactNode;
+  /** Shown under the target in the destructive colour. */
+  error?: React.ReactNode;
+  /** Replaces the icon/title/description block entirely. */
+  children?: React.ReactNode;
+  className?: string;
+  validator?: DropzoneOptions['validator'];
+};
+
+/**
+ * Click-or-drag file target. Layout classes may be passed through
+ * `className`; colours, border and radius are owned by the component and
+ * follow the drag state (`data-drag-active`, `data-drag-reject`).
+ */
+function Dropzone({
+  onDrop,
+  accept,
+  multiple = false,
+  maxFiles,
+  maxSize,
+  disabled = false,
+  size = 'default',
+  title = 'Click to upload or drag and drop',
+  description,
+  icon,
+  error,
+  children,
+  className,
+  validator,
+}: DropzoneProps) {
+  const { getRootProps, getInputProps, isDragActive, isDragReject } =
+    useDropzone({
+      onDrop,
+      accept,
+      multiple,
+      maxFiles,
+      maxSize,
+      disabled,
+      validator,
+    });
+
+  return (
+    <div className={cn('flex flex-col gap-2', className)}>
+      <div
+        {...getRootProps()}
+        data-slot="dropzone"
+        data-size={size}
+        data-disabled={disabled || undefined}
+        data-drag-active={isDragActive || undefined}
+        data-drag-reject={isDragReject || undefined}
+        className={cn(
+          'border-border bg-card text-foreground hover:bg-accent/40 focus-visible:ring-ring/50 flex w-full cursor-pointer flex-col items-center justify-center gap-3 rounded-xl border-2 border-dashed text-center transition-colors outline-none focus-visible:ring-3',
+          'data-[drag-active]:border-primary data-[drag-active]:bg-primary/5',
+          'data-[drag-reject]:border-destructive data-[drag-reject]:bg-destructive/5',
+          'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+          size === 'default' && 'px-6 py-10',
+          size === 'compact' && 'flex-row justify-start px-4 py-3 text-left',
+        )}
+      >
+        <input {...getInputProps()} />
+        {children ?? (
+          <>
+            <span
+              className={cn(
+                'bg-muted text-muted-foreground flex shrink-0 items-center justify-center rounded-full',
+                size === 'default'
+                  ? 'size-12 [&>svg]:size-6'
+                  : 'size-8 [&>svg]:size-4',
+              )}
+            >
+              {icon ?? <CloudUpload />}
+            </span>
+            <span className="flex min-w-0 flex-col gap-0.5">
+              <span className="text-sm font-medium">{title}</span>
+              {description ? (
+                <span className="text-muted-foreground text-xs">
+                  {description}
+                </span>
+              ) : null}
+            </span>
+          </>
+        )}
+      </div>
+      {error ? <p className="text-destructive text-xs">{error}</p> : null}
+    </div>
+  );
+}
+
+export { Dropzone };
+export type { DropzoneProps };
diff --git a/frontend/src/components/ui/feedback.test.tsx b/frontend/src/components/ui/feedback.test.tsx
new file mode 100644
index 00000000..c3487b6f
--- /dev/null
+++ b/frontend/src/components/ui/feedback.test.tsx
@@ -0,0 +1,88 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Progress } from './progress';
+import { Skeleton } from './skeleton';
+import { Spinner } from './spinner';
+import { Textarea, textareaVariants } from './textarea';
+import { Tooltip, TooltipContent, TooltipTrigger } from './tooltip';
+
+describe('Textarea', () => {
+  it('shares the Input field styling and resizes vertically by default', () => {
+    const classes = textareaVariants();
+    expect(classes).toContain('border-border');
+    expect(classes).toContain('focus-visible:ring-3');
+    expect(classes).toContain('resize-y');
+    expect(classes).toContain('min-h-16');
+  });
+
+  it('renders size and resize as data attributes and classes', () => {
+    const html = renderToStaticMarkup(<Textarea size="lg" resize="none" />);
+    expect(html).toContain('data-size="lg"');
+    expect(html).toContain('resize-none');
+    expect(html).toContain('rounded-2xl');
+  });
+});
+
+describe('Spinner', () => {
+  it('is an accessible status element drawn by the ring utility', () => {
+    const html = renderToStaticMarkup(<Spinner size="sm" />);
+    expect(html).toContain('role="status"');
+    expect(html).toContain('aria-label="Loading"');
+    expect(html).toContain('spinner-ring');
+    expect(html).toContain('size-5');
+    expect(html).toContain('data-size="sm"');
+  });
+});
+
+describe('Skeleton', () => {
+  it('is a pulsing muted block hidden from assistive tech', () => {
+    const html = renderToStaticMarkup(<Skeleton className="h-4 w-32" />);
+    expect(html).toContain('animate-pulse');
+    expect(html).toContain('bg-muted');
+    expect(html).toContain('aria-hidden="true"');
+    expect(html).toContain('w-32');
+  });
+});
+
+describe('Progress', () => {
+  it('clamps the value and exposes it as a custom property', () => {
+    const html = renderToStaticMarkup(
+      <Progress value={140} variant="warning" />,
+    );
+    expect(html).toContain('--progress:100%');
+    expect(html).toContain('bg-warning');
+    expect(html).toContain('aria-valuenow="100"');
+  });
+
+  it('never uses raw palette colours', () => {
+    for (const variant of [
+      'default',
+      'success',
+      'warning',
+      'destructive',
+      'info',
+    ] as const) {
+      expect(
+        renderToStaticMarkup(<Progress value={50} variant={variant} />),
+      ).not.toMatch(
+        /\b(bg|text)-(red|green|amber|yellow|blue|gray|purple)-\d+/,
+      );
+    }
+  });
+});
+
+describe('Tooltip', () => {
+  it('renders its trigger without needing an app-level provider', () => {
+    const html = renderToStaticMarkup(
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <button type="button">Delete</button>
+        </TooltipTrigger>
+        <TooltipContent>Delete this source</TooltipContent>
+      </Tooltip>,
+    );
+    expect(html).toContain('data-slot="tooltip-trigger"');
+    expect(html).toContain('Delete');
+  });
+});
diff --git a/frontend/src/components/ui/input.test.tsx b/frontend/src/components/ui/input.test.tsx
new file mode 100644
index 00000000..049a20e7
--- /dev/null
+++ b/frontend/src/components/ui/input.test.tsx
@@ -0,0 +1,129 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Input, inputVariants } from './input';
+
+describe('Input variants', () => {
+  it('keeps the historical 42px rectangular field by default', () => {
+    const classes = inputVariants();
+    expect(classes).toContain('h-10.5');
+    expect(classes).toContain('rounded-md');
+  });
+
+  it('size="sm" is a compact field', () => {
+    const classes = inputVariants({ size: 'sm' });
+    expect(classes).toContain('h-8');
+    expect(classes).toContain('px-2');
+    expect(classes).not.toMatch(/\bh-10\.5\b/);
+  });
+
+  it('shape="pill" with size="lg" is the chat-style field', () => {
+    const classes = inputVariants({ size: 'lg', shape: 'pill' });
+    expect(classes).toContain('rounded-full');
+    expect(classes).toContain('h-12');
+    expect(classes).toContain('px-5');
+  });
+
+  it('a default-size pill starts its text 20px in, like the Select pill', () => {
+    const html = renderToStaticMarkup(<Input shape="pill" />);
+    const classes = (/class="([^"]*)"/.exec(html)?.[1] ?? '').split(' ');
+    expect(classes).toContain('h-10.5');
+    expect(classes).toContain('px-5');
+    expect(classes).not.toContain('px-3');
+  });
+
+  it('an inset icon still pads the left of a default pill', () => {
+    const html = renderToStaticMarkup(
+      <Input shape="pill" leftIcon={<svg />} placeholder="Search" />,
+    );
+    const classes = (/<input[^>]*class="([^"]*)"/.exec(html)?.[1] ?? '').split(
+      ' ',
+    );
+    expect(classes).toContain('pl-10');
+    expect(classes).toContain('px-5');
+  });
+
+  it('moves the floating label to match the field height', () => {
+    const small = renderToStaticMarkup(<Input size="sm" label="Name" />);
+    expect(small).toContain('peer-placeholder-shown:top-1.5');
+    const large = renderToStaticMarkup(<Input size="lg" label="Name" />);
+    expect(large).toContain('peer-placeholder-shown:top-3.5');
+  });
+
+  it('does not leak the variant props onto the DOM element', () => {
+    const html = renderToStaticMarkup(<Input size="sm" shape="pill" />);
+    expect(html).toContain('data-size="sm"');
+    expect(html).not.toMatch(/\ssize="sm"/);
+    expect(html).not.toMatch(/\sshape="pill"/);
+  });
+
+  it('paints the floating label notch on the card surface by default', () => {
+    const html = renderToStaticMarkup(<Input label="Name" />);
+    expect(html).toMatch(/<label[^>]*class="[^"]*\bbg-card\b/);
+  });
+
+  it('labelSurface matches the notch to the surface behind the field', () => {
+    const page = renderToStaticMarkup(
+      <Input label="Search" labelSurface="background" />,
+    );
+    expect(page).toMatch(/<label[^>]*class="[^"]*\bbg-background\b/);
+    expect(page).not.toMatch(/<label[^>]*class="[^"]*\bbg-card\b/);
+    const muted = renderToStaticMarkup(
+      <Input label="Search" labelSurface="muted" />,
+    );
+    expect(muted).toMatch(/<label[^>]*class="[^"]*\bbg-muted\b/);
+    expect(muted).not.toMatch(/\slabelSurface=/i);
+  });
+
+  it('variant="filled" gives the field a card fill on a muted panel', () => {
+    const html = renderToStaticMarkup(<Input variant="filled" />);
+    const classes = (html.match(/class="([^"]*)"/)?.[1] ?? '').split(' ');
+    expect(classes).toContain('bg-card');
+    expect(classes).not.toContain('bg-transparent');
+    expect(html).toContain('data-variant="filled"');
+  });
+
+  it('variant="bare" drops the field chrome so the host frames it', () => {
+    const html = renderToStaticMarkup(<Input variant="bare" />);
+    const classes = /class="([^"]*)"/.exec(html)?.[1].split(' ') ?? [];
+    for (const cls of [
+      'border-0',
+      'rounded-none',
+      'p-0',
+      'h-auto',
+      'shadow-none',
+      'bg-transparent',
+      'text-sm',
+      'focus-visible:ring-0',
+    ]) {
+      expect(classes).toContain(cls);
+    }
+    for (const cls of ['h-10.5', 'px-3', 'shadow-xs', 'rounded-md', 'border']) {
+      expect(classes).not.toContain(cls);
+    }
+    expect(html).toContain('data-variant="bare"');
+  });
+
+  it('renders leftIcon inside the field without a floating label', () => {
+    const html = renderToStaticMarkup(
+      <Input leftIcon={<svg data-testid="icon" />} placeholder="Search" />,
+    );
+    expect(html).toContain('data-testid="icon"');
+    expect(html).toMatch(/<input[^>]*class="[^"]*\bpl-10\b/);
+    expect(html).not.toContain('<label');
+    // No label, so the real placeholder stays visible.
+    expect(html).toContain('placeholder="Search"');
+    expect(html).not.toContain('placeholder:text-transparent');
+  });
+
+  it('keeps the bare input when there is neither a label nor an icon', () => {
+    const html = renderToStaticMarkup(<Input />);
+    expect(html.startsWith('<input')).toBe(true);
+  });
+
+  it('keeps the bordered field by default', () => {
+    const html = renderToStaticMarkup(<Input />);
+    expect(html).toContain('data-variant="default"');
+    expect(html).toContain('shadow-xs');
+  });
+});
diff --git a/frontend/src/components/ui/input.tsx b/frontend/src/components/ui/input.tsx
index 58d4a4ac..b46cc05c 100644
--- a/frontend/src/components/ui/input.tsx
+++ b/frontend/src/components/ui/input.tsx
@@ -1,45 +1,124 @@
 import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
 
 import { cn } from '@/lib/utils';
 
-type InputProps = React.ComponentProps<'input'> & {
-  label?: React.ReactNode;
-  leftIcon?: React.ReactNode;
-  labelBgClassName?: string;
+const inputVariants = cva(
+  'text-foreground file:text-foreground placeholder:text-muted-foreground border-border w-full min-w-0 border bg-transparent shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 selection:bg-primary selection:text-primary-foreground focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive',
+  {
+    variants: {
+      size: {
+        default: 'h-10.5 px-3 py-2 text-base md:text-sm',
+        sm: 'h-8 px-2 py-1 text-sm',
+        lg: 'h-12 px-5 py-3 text-base md:text-sm',
+      },
+      shape: {
+        default: 'rounded-md',
+        pill: 'rounded-full',
+      },
+      // Declared after size and shape so cn() lets it win over them.
+      variant: {
+        default: '',
+        // A field inside a host that already draws the frame (a renaming
+        // sidebar row, a search strip in a bordered panel): no border,
+        // padding, radius, shadow or ring of its own.
+        bare: 'h-auto rounded-none border-0 bg-transparent p-0 text-sm shadow-none focus-visible:ring-0',
+        // A field on a muted panel: keeps the card fill so it still reads
+        // as a field against the panel.
+        filled: 'bg-card',
+      },
+    },
+    compoundVariants: [
+      // A default-size pill would start its text 12px from a 21px round end;
+      // pad it like the lg pill and SelectTrigger's pills (text 21px in).
+      // Not on `bare`, which has no padding of its own.
+      {
+        shape: 'pill',
+        size: 'default',
+        variant: ['default', 'filled'],
+        class: 'px-5',
+      },
+    ],
+    defaultVariants: {
+      size: 'default',
+      shape: 'default',
+      variant: 'default',
+    },
+  },
+);
+
+// Where the floating label sits while the field is empty, per input height.
+const LABEL_RESTING_CLASSES: Record<
+  NonNullable<VariantProps<typeof inputVariants>['size']>,
+  string
+> = {
+  default: 'peer-placeholder-shown:top-2.5 peer-placeholder-shown:text-base',
+  sm: 'peer-placeholder-shown:top-1.5 peer-placeholder-shown:text-sm',
+  lg: 'peer-placeholder-shown:top-3.5 peer-placeholder-shown:text-base',
 };
 
-const baseInputClasses =
-  'text-foreground file:text-foreground placeholder:text-muted-foreground border-border h-[42px] w-full min-w-0 rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm';
+// The floating label sits on the field's border, so its background has to
+// match whatever surface the field is placed on to hide the line behind it.
+const LABEL_SURFACE_CLASSES = {
+  card: 'bg-card',
+  background: 'bg-background',
+  muted: 'bg-muted',
+} as const;
 
-const themeInputClasses =
-  'dark:border-border dark:text-white dark:placeholder:text-gray-400 selection:bg-primary selection:text-primary-foreground focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive';
+type InputProps = Omit<React.ComponentProps<'input'>, 'size'> &
+  VariantProps<typeof inputVariants> & {
+    label?: React.ReactNode;
+    leftIcon?: React.ReactNode;
+    /** Surface behind the field, so the floating label's notch blends in. */
+    labelSurface?: keyof typeof LABEL_SURFACE_CLASSES;
+  };
 
 function Input({
   className,
   type,
   label,
   leftIcon,
-  labelBgClassName = 'bg-card',
+  labelSurface = 'card',
   id,
   placeholder,
   required,
+  size = 'default',
+  shape = 'default',
+  variant = 'default',
   ...props
 }: InputProps) {
   const generatedId = React.useId();
   const inputId = id ?? (label ? generatedId : undefined);
 
   if (!label) {
-    return (
+    const field = (
       <input
         type={type}
         id={id}
         placeholder={placeholder}
         required={required}
         data-slot="input"
-        className={cn(baseInputClasses, themeInputClasses, className)}
+        data-size={size}
+        data-shape={shape}
+        data-variant={variant}
+        className={cn(
+          inputVariants({ size, shape, variant }),
+          leftIcon && 'pl-10',
+          className,
+        )}
         {...props}
       />
     );
+    if (!leftIcon) return field;
+    // An inset icon with no floating label (a search field).
+    return (
+      <div className="relative">
+        {field}
+        <div className="pointer-events-none absolute top-1/2 left-3 flex -translate-y-1/2 items-center justify-center">
+          {leftIcon}
+        </div>
+      </div>
+    );
   }
 
   return (
@@ -48,14 +127,16 @@ function Input({
         type={type}
         id={inputId}
         data-slot="input"
+        data-size={size}
+        data-shape={shape}
+        data-variant={variant}
         // Use a single-space placeholder so :placeholder-shown drives the
         // floating-label peer-trick even when the caller didn't pass one.
         placeholder={placeholder ?? ' '}
         required={required}
         className={cn(
-          baseInputClasses,
-          themeInputClasses,
-          'peer placeholder:text-transparent dark:placeholder:text-transparent',
+          inputVariants({ size, shape, variant }),
+          'peer placeholder:text-transparent',
           leftIcon && 'pl-10',
           className,
         )}
@@ -70,12 +151,12 @@ function Input({
         htmlFor={inputId}
         className={cn(
           'text-muted-foreground pointer-events-none absolute -top-2.5 left-3 max-w-[calc(100%-24px)] cursor-none overflow-hidden px-2 text-xs text-ellipsis whitespace-nowrap transition-all select-none',
-          'peer-placeholder-shown:top-2.5 peer-placeholder-shown:text-base',
+          LABEL_RESTING_CLASSES[size ?? 'default'],
           leftIcon
             ? 'peer-placeholder-shown:left-7'
             : 'peer-placeholder-shown:left-3',
           'peer-focus:-top-2.5 peer-focus:left-3 peer-focus:text-xs',
-          labelBgClassName,
+          LABEL_SURFACE_CLASSES[labelSurface],
         )}
       >
         {label}
@@ -85,5 +166,5 @@ function Input({
   );
 }
 
-export { Input };
+export { Input, inputVariants };
 export type { InputProps };
diff --git a/frontend/src/components/ui/modal.tsx b/frontend/src/components/ui/modal.tsx
index e5a22142..bc2efc6b 100644
--- a/frontend/src/components/ui/modal.tsx
+++ b/frontend/src/components/ui/modal.tsx
@@ -114,7 +114,12 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(function Modal(
           className={cn(
             'bg-card text-foreground data-[state=open]:animate-in data-[state=closed]:animate-out shadow-modal fixed z-50 duration-200 outline-none',
             isMobileSheet
-              ? 'data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom inset-x-0 bottom-0 flex max-h-[90vh] w-full flex-col gap-3 rounded-t-2xl px-4 pt-2 pb-[max(env(safe-area-inset-bottom),1rem)]'
+              ? /* eslint-disable-next-line shadcn/no-arbitrary-values -- the
+                   sheet's bottom padding must clear the iPhone home indicator
+                   (env(safe-area-inset-bottom), about 34px) and fall back to
+                   1rem elsewhere; no scale step can express env() (DESIGN.md
+                   Approved exceptions). */
+                'data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom inset-x-0 bottom-0 flex max-h-[90vh] w-full flex-col gap-3 rounded-t-2xl px-4 pt-2 pb-[max(env(safe-area-inset-bottom),1rem)]'
               : cn(
                   'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 top-[50%] left-[50%] grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-2xl p-8',
                   SIZE_CLASSES[size],
@@ -124,7 +129,7 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(function Modal(
         >
           {isMobileSheet && (
             <div
-              className="mx-auto h-1.5 w-12 shrink-0 rounded-full bg-gray-300 dark:bg-gray-600"
+              className="bg-border mx-auto h-1.5 w-12 shrink-0 rounded-full"
               aria-hidden="true"
             />
           )}
diff --git a/frontend/src/components/ui/multi-select.tsx b/frontend/src/components/ui/multi-select.tsx
index e436dd8f..c0c234f7 100644
--- a/frontend/src/components/ui/multi-select.tsx
+++ b/frontend/src/components/ui/multi-select.tsx
@@ -81,7 +81,7 @@ export function MultiSelect({
           aria-expanded={open}
           className={cn(
             'border-border bg-card hover:bg-accent h-auto min-h-10 w-full justify-between py-1.5',
-            !selected.length && 'text-gray-500 dark:text-gray-400',
+            !selected.length && 'text-muted-foreground',
             className,
           )}
         >
@@ -99,13 +99,13 @@ export function MultiSelect({
                   return (
                     <span
                       key={option?.value || label}
-                      className="bg-primary/20 dark:bg-primary/30 inline-flex max-w-[calc(100%-1rem)] min-w-0 items-center gap-1 rounded-md px-2 py-0.5 text-xs font-medium text-purple-700 dark:text-purple-300"
+                      className="bg-primary/20 dark:bg-primary/30 text-primary inline-flex max-w-[calc(100%-1rem)] min-w-0 items-center gap-1 rounded-md px-2 py-0.5 text-xs font-medium"
                     >
                       <span className="truncate">{label}</span>
                       <span
                         role="button"
                         tabIndex={0}
-                        className="flex h-3 w-3 cursor-pointer items-center justify-center hover:text-purple-900 dark:hover:text-purple-200"
+                        className="hover:text-primary/70 flex h-3 w-3 cursor-pointer items-center justify-center"
                         onMouseDown={(e) => {
                           e.preventDefault();
                           e.stopPropagation();
@@ -127,7 +127,7 @@ export function MultiSelect({
                   );
                 })}
                 {selected.length > 2 && (
-                  <span className="text-xs text-gray-600 dark:text-gray-400">
+                  <span className="text-muted-foreground text-xs">
                     +{selected.length - 2} more
                   </span>
                 )}
@@ -161,8 +161,8 @@ export function MultiSelect({
                       className={cn(
                         'mr-2 flex h-4 w-4 items-center justify-center rounded-sm border-2',
                         isSelected
-                          ? 'border-primary bg-primary text-white'
-                          : 'border-gray-400 dark:border-gray-500',
+                          ? 'border-primary bg-primary text-primary-foreground'
+                          : 'border-input',
                       )}
                     >
                       {isSelected && <Check className="h-3 w-3 stroke-white" />}
diff --git a/frontend/src/components/ui/option-card.test.tsx b/frontend/src/components/ui/option-card.test.tsx
new file mode 100644
index 00000000..df6091b0
--- /dev/null
+++ b/frontend/src/components/ui/option-card.test.tsx
@@ -0,0 +1,54 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { OptionCard } from './option-card';
+
+describe('OptionCard', () => {
+  it('renders a whole-card button with icon and title', () => {
+    const html = renderToStaticMarkup(
+      <OptionCard icon={<svg />} title="Crawler" />,
+    );
+    expect(html).toMatch(/^<button/);
+    expect(html).toContain('Crawler');
+    expect(html).toContain('cursor-pointer');
+    expect(html).toContain('data-slot="option-card-icon"');
+  });
+
+  it('omits the description line when none is given', () => {
+    const html = renderToStaticMarkup(
+      <OptionCard icon={<svg />} title="GitHub" />,
+    );
+    expect(html).not.toContain('data-slot="card-description"');
+  });
+
+  it('marks the selected tile and fills its icon', () => {
+    const html = renderToStaticMarkup(
+      <OptionCard
+        icon={<svg />}
+        title="Classic Agent"
+        description="One model, tools and sources."
+        selected
+      />,
+    );
+    expect(html).toContain('data-selected="true"');
+    expect(html).toContain('aria-checked="true"');
+    expect(html).toContain('bg-primary text-primary-foreground');
+    expect(html).toContain('One model, tools and sources.');
+  });
+
+  it('is a plain button when it is not part of a single-select picker', () => {
+    const html = renderToStaticMarkup(
+      <OptionCard icon={<svg />} title="Upload File" />,
+    );
+    expect(html).not.toContain('role="radio"');
+    expect(html).not.toContain('aria-checked');
+  });
+
+  it('is an unchecked radio when selected={false} is passed', () => {
+    const html = renderToStaticMarkup(
+      <OptionCard icon={<svg />} title="Workflow Agent" selected={false} />,
+    );
+    expect(html).toContain('role="radio"');
+    expect(html).toContain('aria-checked="false"');
+  });
+});
diff --git a/frontend/src/components/ui/option-card.tsx b/frontend/src/components/ui/option-card.tsx
new file mode 100644
index 00000000..7e9025bf
--- /dev/null
+++ b/frontend/src/components/ui/option-card.tsx
@@ -0,0 +1,69 @@
+import * as React from 'react';
+
+import { Card, CardDescription, CardTitle } from '@/components/ui/card';
+import { cn } from '@/lib/utils';
+
+type OptionCardProps = Omit<
+  React.ComponentProps<'button'>,
+  'title' | 'children'
+> & {
+  /** Icon shown in the tinted square; sized by the component. */
+  icon: React.ReactNode;
+  title: React.ReactNode;
+  /** Optional second line. The tile stays the same height without it. */
+  description?: React.ReactNode;
+  /**
+   * Marks the current choice in a single-select picker. Pass it (true or
+   * false) only in a picker: the tile then becomes a radio. Left out, the
+   * tile is a plain button (it advances a step or navigates).
+   */
+  selected?: boolean;
+};
+
+/**
+ * Picker tile: a whole-card button with an icon, a title and an optional
+ * description. Used wherever the user chooses one of several ways to
+ * proceed (agent type, source type). Title-only tiles are fine.
+ */
+function OptionCard({
+  icon,
+  title,
+  description,
+  selected,
+  className,
+  type = 'button',
+  ...props
+}: OptionCardProps) {
+  return (
+    <Card interactive selected={selected} asChild className={className}>
+      <button
+        type={type}
+        role={props.role ?? (selected !== undefined ? 'radio' : undefined)}
+        aria-checked={selected}
+        data-slot="option-card"
+        {...props}
+      >
+        <span className="flex items-center gap-4">
+          <span
+            data-slot="option-card-icon"
+            className={cn(
+              'bg-primary/10 text-primary flex size-12 shrink-0 items-center justify-center rounded-xl transition-colors [&>svg]:size-6',
+              selected && 'bg-primary text-primary-foreground',
+            )}
+          >
+            {icon}
+          </span>
+          <span className="flex min-w-0 flex-col gap-1">
+            <CardTitle className="text-base">{title}</CardTitle>
+            {description ? (
+              <CardDescription>{description}</CardDescription>
+            ) : null}
+          </span>
+        </span>
+      </button>
+    </Card>
+  );
+}
+
+export { OptionCard };
+export type { OptionCardProps };
diff --git a/frontend/src/components/ui/progress.tsx b/frontend/src/components/ui/progress.tsx
new file mode 100644
index 00000000..8871fe15
--- /dev/null
+++ b/frontend/src/components/ui/progress.tsx
@@ -0,0 +1,73 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Progress as ProgressPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+const progressVariants = cva(
+  'bg-muted relative w-full overflow-hidden rounded-full',
+  {
+    variants: {
+      size: {
+        sm: 'h-1.5',
+        default: 'h-2',
+        lg: 'h-3',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+const indicatorVariants = cva(
+  'h-full w-(--progress) rounded-full transition-[width] duration-300',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary',
+        success: 'bg-success',
+        warning: 'bg-warning',
+        destructive: 'bg-destructive',
+        info: 'bg-info',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+);
+
+type ProgressProps = React.ComponentProps<typeof ProgressPrimitive.Root> &
+  VariantProps<typeof progressVariants> &
+  VariantProps<typeof indicatorVariants> & {
+    /** 0 to 100. */
+    value?: number;
+  };
+
+/** Determinate bar for quotas, indexing and run progress. */
+function Progress({
+  className,
+  value = 0,
+  size = 'default',
+  variant = 'default',
+  ...props
+}: ProgressProps) {
+  const clamped = Math.max(0, Math.min(100, value));
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      data-variant={variant}
+      value={clamped}
+      className={cn(progressVariants({ size }), className)}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className={indicatorVariants({ variant })}
+        // The only dynamic value; exposed as a custom property so the width
+        // itself stays a class (w-(--progress)), which the lint accepts.
+        style={{ '--progress': `${clamped}%` } as React.CSSProperties}
+      />
+    </ProgressPrimitive.Root>
+  );
+}
+
+export { Progress, progressVariants };
+export type { ProgressProps };
diff --git a/frontend/src/components/ui/select.test.tsx b/frontend/src/components/ui/select.test.tsx
new file mode 100644
index 00000000..0d311e53
--- /dev/null
+++ b/frontend/src/components/ui/select.test.tsx
@@ -0,0 +1,41 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Select, SelectContent, SelectItem, SelectTrigger } from './select';
+
+(
+  globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: Root | null = null;
+let host: HTMLDivElement | null = null;
+
+afterEach(() => {
+  act(() => root?.unmount());
+  host?.remove();
+  root = null;
+  host = null;
+});
+
+describe('SelectItem', () => {
+  it('fills the highlighted item, so keyboard navigation is visible', () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+    act(() => {
+      root!.render(
+        <Select open value="a">
+          <SelectTrigger aria-label="Rows">a</SelectTrigger>
+          <SelectContent>
+            <SelectItem value="a">A</SelectItem>
+          </SelectContent>
+        </Select>,
+      );
+    });
+    const item = document.querySelector('[data-slot="select-item"]');
+    expect(item).not.toBeNull();
+    // Radix sets data-highlighted on pointer hover and on arrow-key focus alike.
+    expect(item!.className).toContain('data-highlighted:bg-muted');
+  });
+});
diff --git a/frontend/src/components/ui/select.tsx b/frontend/src/components/ui/select.tsx
index e643031b..5ad1409a 100644
--- a/frontend/src/components/ui/select.tsx
+++ b/frontend/src/components/ui/select.tsx
@@ -26,22 +26,28 @@ function SelectTrigger({
   className,
   size = 'default',
   variant = 'default',
+  shape = 'default',
   children,
   ...props
 }: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
   size?: 'sm' | 'default' | 'lg';
   variant?: 'default' | 'ghost';
+  shape?: 'default' | 'pill';
 }) {
   return (
     <SelectPrimitive.Trigger
       data-slot="select-trigger"
       data-size={size}
+      data-shape={shape}
       className={cn(
-        "group aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive flex w-fit items-center justify-between gap-2 rounded-md border px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=lg]:h-[42px] data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-gray-600 dark:[&_svg:not([class*='text-'])]:text-gray-400",
+        "group aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive [&_svg:not([class*='text-'])]:text-muted-foreground flex w-fit items-center justify-between gap-2 border px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=lg]:h-10.5 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         variant === 'default' &&
           'border-border bg-card focus-visible:ring-ring/50 hover:bg-accent data-placeholder:text-muted-foreground',
         variant === 'ghost' &&
           'border-border focus-visible:ring-ring/50 hover:bg-accent data-[state=open]:bg-muted data-placeholder:text-muted-foreground dark:border-border dark:hover:bg-accent dark:data-[state=open]:bg-muted bg-transparent',
+        shape === 'default' && 'rounded-md',
+        shape === 'pill' &&
+          'rounded-full px-4 data-[size=lg]:px-5 data-[size=sm]:px-3',
         className,
       )}
       {...props}
@@ -66,7 +72,7 @@ function SelectContent({
       <SelectPrimitive.Content
         data-slot="select-content"
         className={cn(
-          'border-border bg-card data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-200 max-h-(--radix-select-content-available-height) w-(--radix-select-trigger-width) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-xl border text-gray-900 shadow-md dark:text-white',
+          'border-border bg-card data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 text-foreground relative z-200 max-h-(--radix-select-content-available-height) w-(--radix-select-trigger-width) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-xl border shadow-md',
           position === 'popper' &&
             'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
           className,
@@ -113,7 +119,7 @@ function SelectItem({
     <SelectPrimitive.Item
       data-slot="select-item"
       className={cn(
-        "[&_svg:not([class*='text-'])]:text-muted-foreground hover:bg-muted 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 data-disabled:pointer-events-none 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",
+        "[&_svg:not([class*='text-'])]:text-muted-foreground data-highlighted:bg-muted 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 data-disabled:pointer-events-none 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",
         className,
       )}
       {...props}
diff --git a/frontend/src/components/ui/skeleton.tsx b/frontend/src/components/ui/skeleton.tsx
new file mode 100644
index 00000000..1dbe1936
--- /dev/null
+++ b/frontend/src/components/ui/skeleton.tsx
@@ -0,0 +1,17 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+/** Placeholder block; size it with width/height classes, round it as needed. */
+function Skeleton({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="skeleton"
+      aria-hidden="true"
+      className={cn('bg-muted animate-pulse rounded-md', className)}
+      {...props}
+    />
+  );
+}
+
+export { Skeleton };
diff --git a/frontend/src/components/ui/spinner.tsx b/frontend/src/components/ui/spinner.tsx
new file mode 100644
index 00000000..682228b7
--- /dev/null
+++ b/frontend/src/components/ui/spinner.tsx
@@ -0,0 +1,41 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+type SpinnerProps = React.ComponentProps<'div'> & {
+  size?: 'sm' | 'default' | 'lg';
+  /** Announced to screen readers. */
+  label?: string;
+};
+
+const SIZE_CLASSES: Record<NonNullable<SpinnerProps['size']>, string> = {
+  sm: 'size-5',
+  default: 'size-7',
+  lg: 'size-10',
+};
+
+/**
+ * Ring spinner drawn in `currentColor`, so it takes the text colour of its
+ * parent (or a `text-*` class). The ring itself is the `spinner-ring`
+ * utility in src/index.css.
+ */
+function Spinner({
+  className,
+  size = 'default',
+  label = 'Loading',
+  ...props
+}: SpinnerProps) {
+  return (
+    <div
+      role="status"
+      aria-label={label}
+      data-slot="spinner"
+      data-size={size}
+      className={cn('spinner-ring shrink-0', SIZE_CLASSES[size], className)}
+      {...props}
+    />
+  );
+}
+
+export { Spinner };
+export type { SpinnerProps };
diff --git a/frontend/src/components/ui/switch.tsx b/frontend/src/components/ui/switch.tsx
index b42e7e23..69b990ac 100644
--- a/frontend/src/components/ui/switch.tsx
+++ b/frontend/src/components/ui/switch.tsx
@@ -11,7 +11,7 @@ function Switch({
     <SwitchPrimitive.Root
       data-slot="switch"
       className={cn(
-        'peer focus-visible:ring-ring/50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-muted-foreground/35 dark:data-[state=unchecked]:bg-muted-foreground/45 inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-xs transition-colors outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
+        'peer focus-visible:ring-ring/50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-muted-foreground/35 dark:data-[state=unchecked]:bg-muted-foreground/45 inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-xs transition-colors outline-none focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50',
         className,
       )}
       {...props}
diff --git a/frontend/src/components/ui/table.tsx b/frontend/src/components/ui/table.tsx
index b15cfb6e..d3f79dd4 100644
--- a/frontend/src/components/ui/table.tsx
+++ b/frontend/src/components/ui/table.tsx
@@ -56,11 +56,17 @@ const TableContainer = React.forwardRef<HTMLDivElement, TableContainerProps>(
           className={cn(
             'w-full overflow-x-auto rounded-md bg-transparent',
             bordered && 'border-border border',
+            height === 'auto'
+              ? 'overflow-y-hidden'
+              : 'max-h-(--table-max-height) overflow-y-auto',
           )}
-          style={{
-            maxHeight: height === 'auto' ? undefined : height,
-            overflowY: height === 'auto' ? 'hidden' : 'auto',
-          }}
+          // The height is a runtime prop; exposed as a custom property so
+          // max-height itself stays a class.
+          style={
+            height === 'auto'
+              ? undefined
+              : ({ '--table-max-height': height } as React.CSSProperties)
+          }
         >
           {children}
         </div>
@@ -153,9 +159,12 @@ const TableHeader: React.FC<TableCellProps> = ({
         'border-border text-muted-foreground relative box-border border-b px-2 py-3 text-sm font-medium lg:px-3',
         alignmentClass,
         minWidth,
+        width && 'w-(--cell-width) max-w-(--cell-width) min-w-(--cell-width)',
         className,
       )}
-      style={width ? { width, minWidth: width, maxWidth: width } : {}}
+      style={
+        width ? ({ '--cell-width': width } as React.CSSProperties) : undefined
+      }
     >
       {children}
     </th>
@@ -185,9 +194,12 @@ const TableCell: React.FC<TableCellProps> = ({
         'box-border px-2 py-2 text-sm lg:px-3',
         alignmentClass,
         minWidth,
+        width && 'w-(--cell-width) max-w-(--cell-width) min-w-(--cell-width)',
         className,
       )}
-      style={width ? { width, minWidth: width, maxWidth: width } : {}}
+      style={
+        width ? ({ '--cell-width': width } as React.CSSProperties) : undefined
+      }
     >
       {children}
     </td>
diff --git a/frontend/src/components/ui/tabs.tsx b/frontend/src/components/ui/tabs.tsx
index f72d0b1a..cfa5bbf2 100644
--- a/frontend/src/components/ui/tabs.tsx
+++ b/frontend/src/components/ui/tabs.tsx
@@ -40,7 +40,7 @@ function TabsTrigger({
     <TabsPrimitive.Trigger
       data-slot="tabs-trigger"
       className={cn(
-        'focus-visible:ring-ring/50 data-[state=active]:bg-muted data-[state=active]:text-foreground dark:data-[state=active]:bg-accent text-muted-foreground hover:text-foreground snap-start rounded-3xl px-4 py-2 text-sm font-bold whitespace-nowrap transition-colors outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50 dark:text-neutral-400 dark:hover:text-white dark:data-[state=active]:text-white',
+        'focus-visible:ring-ring/50 data-[state=active]:bg-muted data-[state=active]:text-foreground dark:data-[state=active]:bg-accent text-muted-foreground hover:text-foreground snap-start rounded-3xl px-4 py-2 text-sm font-bold whitespace-nowrap transition-colors outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
         className,
       )}
       {...props}
diff --git a/frontend/src/components/ui/textarea.test.tsx b/frontend/src/components/ui/textarea.test.tsx
new file mode 100644
index 00000000..56ccd467
--- /dev/null
+++ b/frontend/src/components/ui/textarea.test.tsx
@@ -0,0 +1,33 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Textarea } from './textarea';
+
+function classesOf(html: string): string[] {
+  return (/class="([^"]*)"/.exec(html)?.[1] ?? '').split(' ');
+}
+
+describe('Textarea variants', () => {
+  it('is transparent by default, so it shows the surface behind it', () => {
+    const html = renderToStaticMarkup(<Textarea />);
+    expect(classesOf(html)).toContain('bg-transparent');
+    expect(html).toContain('data-variant="default"');
+  });
+
+  it('variant="filled" gives the field a card fill on a muted panel', () => {
+    const html = renderToStaticMarkup(<Textarea variant="filled" size="sm" />);
+    const classes = classesOf(html);
+    expect(classes).toContain('bg-card');
+    expect(classes).not.toContain('bg-transparent');
+    expect(html).toContain('data-variant="filled"');
+    expect(html).toContain('data-size="sm"');
+  });
+
+  it('does not leak the variant props onto the DOM element', () => {
+    const html = renderToStaticMarkup(
+      <Textarea variant="filled" resize="none" />,
+    );
+    expect(html).not.toMatch(/\svariant="filled"/);
+    expect(html).not.toMatch(/\sresize="none"/);
+  });
+});
diff --git a/frontend/src/components/ui/textarea.tsx b/frontend/src/components/ui/textarea.tsx
new file mode 100644
index 00000000..9363ea87
--- /dev/null
+++ b/frontend/src/components/ui/textarea.tsx
@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+const textareaVariants = cva(
+  'text-foreground placeholder:text-muted-foreground border-border selection:bg-primary selection:text-primary-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive flex w-full min-w-0 border bg-transparent shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50',
+  {
+    variants: {
+      size: {
+        default: 'min-h-16 rounded-md px-3 py-2 text-base md:text-sm',
+        sm: 'min-h-8 rounded-md px-2 py-1 text-sm',
+        lg: 'min-h-24 rounded-2xl px-4 py-3 text-base md:text-sm',
+      },
+      resize: {
+        none: 'resize-none',
+        vertical: 'resize-y',
+        both: 'resize',
+      },
+      // Declared after size so cn() lets it win.
+      variant: {
+        default: '',
+        // A field on a muted panel: keeps the card fill so it still reads
+        // as a field against the panel (the same as Input's `filled`).
+        filled: 'bg-card',
+      },
+    },
+    defaultVariants: {
+      size: 'default',
+      resize: 'vertical',
+      variant: 'default',
+    },
+  },
+);
+
+type TextareaProps = React.ComponentProps<'textarea'> &
+  VariantProps<typeof textareaVariants>;
+
+/** Multi-line sibling of Input; shares its border, ring and error styling. */
+function Textarea({
+  className,
+  size = 'default',
+  resize = 'vertical',
+  variant = 'default',
+  ...props
+}: TextareaProps) {
+  return (
+    <textarea
+      data-slot="textarea"
+      data-size={size}
+      data-variant={variant}
+      className={cn(textareaVariants({ size, resize, variant }), className)}
+      {...props}
+    />
+  );
+}
+
+export { Textarea, textareaVariants };
+export type { TextareaProps };
diff --git a/frontend/src/components/ui/toast.test.tsx b/frontend/src/components/ui/toast.test.tsx
new file mode 100644
index 00000000..b1510772
--- /dev/null
+++ b/frontend/src/components/ui/toast.test.tsx
@@ -0,0 +1,128 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import {
+  Toast,
+  ToastContent,
+  ToastHeader,
+  ToastItem,
+  ToastMessage,
+  ToastStatus,
+  ToastTitle,
+  ToastViewport,
+} from './toast';
+
+describe('Toast', () => {
+  it('is a bordered card with the toast shadow', () => {
+    const html = renderToStaticMarkup(<Toast>x</Toast>);
+    expect(html).toContain('shadow-toast');
+    expect(html).toContain('rounded-2xl');
+  });
+
+  it('leaves the live region to the viewport', () => {
+    const html = renderToStaticMarkup(
+      <ToastViewport>
+        <Toast>a</Toast>
+        <Toast>b</Toast>
+      </ToastViewport>,
+    );
+    // Exactly one live region: the viewport. Cards must not nest another.
+    expect(html.match(/role="status"/g)).toHaveLength(1);
+    expect(html).toMatch(
+      /^<div role="status" aria-live="polite" data-slot="toast-viewport"/,
+    );
+    expect(renderToStaticMarkup(<Toast>x</Toast>)).not.toContain('role=');
+  });
+
+  it('lets a caller override the viewport politeness', () => {
+    const html = renderToStaticMarkup(<ToastViewport aria-live="assertive" />);
+    expect(html).toContain('aria-live="assertive"');
+    expect(html).not.toContain('aria-live="polite"');
+  });
+
+  it('truncates the title unless it wraps', () => {
+    const truncated = renderToStaticMarkup(<ToastTitle>t</ToastTitle>);
+    expect(truncated).toContain('truncate');
+    const wrapped = renderToStaticMarkup(<ToastTitle wrap>t</ToastTitle>);
+    expect(wrapped).not.toContain('truncate');
+    expect(wrapped).not.toContain('wrap=');
+  });
+
+  it('sizes the message xs by default and sm on request', () => {
+    const xs = renderToStaticMarkup(<ToastMessage>m</ToastMessage>);
+    expect(xs).toContain('text-xs');
+    expect(xs).not.toContain('text-sm');
+    const sm = renderToStaticMarkup(<ToastMessage size="sm">m</ToastMessage>);
+    expect(sm).toContain('text-sm');
+    expect(sm).toContain('leading-4.5');
+    expect(sm).not.toContain('text-xs');
+  });
+
+  it('pads a message that is the only content under the header', () => {
+    const html = renderToStaticMarkup(<ToastMessage>m</ToastMessage>);
+    // pb-3 always; pt-3 only when nothing sits above it in ToastContent.
+    expect(html).toContain('pb-3');
+    expect(html).toContain('first:pt-3');
+  });
+
+  it('keeps a message under its row instead of below a divider', () => {
+    const html = renderToStaticMarkup(
+      <ToastItem label="1.png">
+        <ToastStatus status="destructive" />
+      </ToastItem>,
+    );
+    expect(html).toContain(
+      '[&amp;:has(+[data-slot=toast-message])]:border-b-0',
+    );
+  });
+
+  it('renders an optional icon before the label', () => {
+    const html = renderToStaticMarkup(
+      <ToastItem label="Conversation" icon={<ToastStatus status="warning" />}>
+        <button>Review</button>
+      </ToastItem>,
+    );
+    expect(html.indexOf('data-status="warning"')).toBeLessThan(
+      html.indexOf('Conversation'),
+    );
+    expect(html).not.toContain('icon=');
+  });
+
+  it('tints the header by variant and colours the message', () => {
+    const html = renderToStaticMarkup(
+      <Toast>
+        <ToastHeader variant="destructive">
+          <ToastTitle>Upload failed</ToastTitle>
+        </ToastHeader>
+        <ToastContent>
+          <ToastItem label="1.png">
+            <ToastStatus status="destructive" />
+          </ToastItem>
+          <ToastMessage variant="destructive">
+            No text could be extracted.
+          </ToastMessage>
+        </ToastContent>
+      </Toast>,
+    );
+    expect(html).toContain('bg-destructive/10');
+    expect(html).toContain('data-status="destructive"');
+    expect(html).toContain('text-destructive');
+    expect(html).toContain('No text could be extracted.');
+  });
+
+  it('never uses raw palette colours', () => {
+    const html = renderToStaticMarkup(
+      <Toast>
+        <ToastHeader variant="success">
+          <ToastTitle>Done</ToastTitle>
+        </ToastHeader>
+        <ToastItem label="a.md" meta="1.2k tokens">
+          <ToastStatus status="success" />
+        </ToastItem>
+      </Toast>,
+    );
+    expect(html).not.toMatch(
+      /\b(bg|text)-(red|green|amber|gray|black|white)\b/,
+    );
+  });
+});
diff --git a/frontend/src/components/ui/toast.tsx b/frontend/src/components/ui/toast.tsx
new file mode 100644
index 00000000..d8542046
--- /dev/null
+++ b/frontend/src/components/ui/toast.tsx
@@ -0,0 +1,280 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { AlertCircle, Check, Info, TriangleAlert } from 'lucide-react';
+
+import { Spinner } from '@/components/ui/spinner';
+import { cn } from '@/lib/utils';
+
+/**
+ * Bottom-right message card: the app's messaging surface for uploads, tool
+ * approvals and team notifications. Compose:
+ * ToastViewport > Toast > ToastHeader(variant) [ToastTitle, ToastActions]
+ *                       > ToastContent > ToastItem(s) / ToastMessage
+ */
+
+/**
+ * Fixed stack in the bottom-right corner. One per app, mounted in App.tsx;
+ * every toast renders only its `Toast` cards into it. It is the single live
+ * region (`role="status"`, `aria-live="polite"`), so cards carry no role.
+ */
+function ToastViewport({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      data-slot="toast-viewport"
+      className={cn(
+        'fixed right-4 bottom-6 z-50 flex max-w-md flex-col gap-2',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function Toast({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="toast"
+      className={cn(
+        'border-border bg-card text-card-foreground shadow-toast w-68 overflow-hidden rounded-2xl border',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+const toastHeaderVariants = cva(
+  'flex items-center justify-between gap-2 px-4 py-3',
+  {
+    variants: {
+      variant: {
+        default: 'bg-accent/50 dark:bg-muted',
+        success: 'bg-success/10',
+        warning: 'bg-warning/10',
+        destructive: 'bg-destructive/10',
+        info: 'bg-info/10',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+);
+
+function ToastHeader({
+  className,
+  variant = 'default',
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof toastHeaderVariants>) {
+  return (
+    <div
+      data-slot="toast-header"
+      data-variant={variant}
+      className={cn(toastHeaderVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+/** One line with an ellipsis by default; `wrap` lets a long title wrap. */
+function ToastTitle({
+  className,
+  wrap = false,
+  ...props
+}: React.ComponentProps<'h3'> & { wrap?: boolean }) {
+  return (
+    <h3
+      data-slot="toast-title"
+      className={cn(
+        'text-foreground text-sm font-medium',
+        wrap ? 'min-w-0 break-words' : 'truncate',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** Collapse and close buttons; use `Button variant="ghost-muted" size="icon-sm"`. */
+function ToastActions({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="toast-actions"
+      className={cn('flex shrink-0 items-center gap-1', className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Rows and messages. Pass `scrollable` only for long lists (uploads); a
+ * plain block sizes reliably in every engine, a max-height scroll box does
+ * not always inside a flex item in WebKit.
+ */
+function ToastContent({
+  className,
+  scrollable = false,
+  ...props
+}: React.ComponentProps<'div'> & { scrollable?: boolean }) {
+  return (
+    <div
+      data-slot="toast-content"
+      className={cn(scrollable && 'max-h-72 overflow-y-auto', className)}
+      {...props}
+    />
+  );
+}
+
+/** Action buttons under the rows, right-aligned. */
+function ToastFooter({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="toast-footer"
+      className={cn('flex justify-end gap-2 px-5 pt-1 pb-3', className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * One row: optional icon, label and optional meta on the left, status or
+ * actions on the right. A `ToastMessage` right after it belongs to the row,
+ * so the divider moves below the message.
+ */
+function ToastItem({
+  className,
+  label,
+  meta,
+  icon,
+  children,
+  ...props
+}: React.ComponentProps<'div'> & {
+  label: React.ReactNode;
+  meta?: React.ReactNode;
+  icon?: React.ReactNode;
+}) {
+  return (
+    <div
+      data-slot="toast-item"
+      className={cn(
+        'border-border/50 flex items-center justify-between gap-3 border-b px-5 py-3 last:border-b-0 [&:has(+[data-slot=toast-message])]:border-b-0',
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex min-w-0 items-center gap-2">
+        {icon}
+        <div className="flex min-w-0 flex-col">
+          <span className="text-foreground truncate text-sm">{label}</span>
+          {meta ? (
+            <span className="text-muted-foreground mt-0.5 text-xs">{meta}</span>
+          ) : null}
+        </div>
+      </div>
+      {children ? (
+        <div className="flex shrink-0 items-center gap-2">{children}</div>
+      ) : null}
+    </div>
+  );
+}
+
+const toastStatusVariants = cva(
+  'flex size-6 shrink-0 items-center justify-center rounded-full [&>svg]:size-3.5',
+  {
+    variants: {
+      status: {
+        pending: 'text-primary',
+        success: 'bg-success text-success-foreground',
+        warning: 'bg-warning text-warning-foreground',
+        destructive: 'bg-destructive text-destructive-foreground',
+        info: 'bg-info text-info-foreground',
+      },
+    },
+    defaultVariants: { status: 'pending' },
+  },
+);
+
+const STATUS_ICON = {
+  pending: <Spinner size="sm" className="size-6" />,
+  success: <Check strokeWidth={3} />,
+  warning: <TriangleAlert strokeWidth={3} />,
+  destructive: <AlertCircle strokeWidth={3} />,
+  info: <Info strokeWidth={3} />,
+} as const;
+
+/** Filled status circle for a ToastItem. */
+function ToastStatus({
+  className,
+  status = 'pending',
+  label,
+  ...props
+}: React.ComponentProps<'span'> &
+  VariantProps<typeof toastStatusVariants> & { label?: string }) {
+  return (
+    <span
+      data-slot="toast-status"
+      data-status={status}
+      role="img"
+      aria-label={label ?? status ?? undefined}
+      className={cn(toastStatusVariants({ status }), className)}
+      {...props}
+    >
+      {STATUS_ICON[status ?? 'pending']}
+    </span>
+  );
+}
+
+// `first:pt-3` pads a message that is the only content under the header;
+// under a ToastItem the row's own padding already spaces it.
+const toastMessageVariants = cva(
+  'border-border/50 block border-b px-5 pb-3 last:border-b-0 first:pt-3',
+  {
+    variants: {
+      variant: {
+        default: 'text-muted-foreground',
+        success: 'text-success',
+        warning: 'text-warning',
+        destructive: 'text-destructive',
+        info: 'text-info',
+      },
+      size: {
+        xs: 'text-xs',
+        sm: 'text-sm leading-4.5',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'xs' },
+  },
+);
+
+/**
+ * Explanation under a row (why a file failed), or the whole body of a
+ * notice when it is the only content (`size="sm"`).
+ */
+function ToastMessage({
+  className,
+  variant = 'default',
+  size = 'xs',
+  ...props
+}: React.ComponentProps<'span'> & VariantProps<typeof toastMessageVariants>) {
+  return (
+    <span
+      data-slot="toast-message"
+      className={cn(toastMessageVariants({ variant, size }), className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  ToastViewport,
+  Toast,
+  ToastHeader,
+  ToastTitle,
+  ToastActions,
+  ToastContent,
+  ToastFooter,
+  ToastItem,
+  ToastStatus,
+  ToastMessage,
+  toastHeaderVariants,
+};
diff --git a/frontend/src/components/ui/tooltip.tsx b/frontend/src/components/ui/tooltip.tsx
new file mode 100644
index 00000000..45edb5af
--- /dev/null
+++ b/frontend/src/components/ui/tooltip.tsx
@@ -0,0 +1,60 @@
+import * as React from 'react';
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+function TooltipProvider({
+  delayDuration = 200,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  );
+}
+
+/** Each Tooltip carries its own provider, so no app-level wrapper is needed. */
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return (
+    <TooltipProvider>
+      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+    </TooltipProvider>
+  );
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 4,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          'bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-xs" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };
diff --git a/frontend/src/conversation/AnswerFlow.tsx b/frontend/src/conversation/AnswerFlow.tsx
index c9f32892..1abe5de6 100644
--- a/frontend/src/conversation/AnswerFlow.tsx
+++ b/frontend/src/conversation/AnswerFlow.tsx
@@ -180,11 +180,10 @@ function InlineThoughtChip({
         variant="ghost"
         onClick={() => setIsOpen(!isOpen)}
         aria-expanded={isOpen}
-        // ml-4 plus the button's own px-2 puts the icon on the answer's ml-6
-        // text column. has-[>svg]:px-2 restates that padding under the same
-        // variant the button's own has-[>svg]:px-3 uses; a plain px-2 does not
-        // override it, and the chevron makes it match.
-        className="hover:bg-muted/60 ml-4 flex h-auto w-fit max-w-full items-center justify-start gap-2 rounded-lg bg-transparent px-2 py-1.5 text-sm font-normal has-[>svg]:px-2"
+        size="sm"
+        // ml-3.5 plus size sm's own has-[>svg]:px-2.5 (the chevron is a direct
+        // svg child) puts the icon on the answer's ml-6 text column.
+        className="ml-3.5 w-fit max-w-full justify-start"
       >
         <img src={Cloud} alt="" aria-hidden className="h-4 w-4 shrink-0" />
         <span
@@ -204,7 +203,7 @@ function InlineThoughtChip({
       {showLiveWindow && (
         <div
           ref={liveRef}
-          className="text-muted-foreground mt-1 ml-6 h-24 overflow-hidden scroll-smooth mask-[linear-gradient(to_bottom,transparent,black_40%)] text-sm leading-normal motion-reduce:scroll-auto"
+          className="text-muted-foreground mt-1 ml-6 h-24 overflow-hidden scroll-smooth mask-t-from-60% text-sm leading-normal motion-reduce:scroll-auto"
         >
           <div className="flex min-h-full flex-col justify-end wrap-break-word whitespace-pre-wrap">
             {pacedThought}
@@ -246,11 +245,10 @@ function InlineToolCallChip({
         variant="ghost"
         onClick={() => setIsOpen(!isOpen)}
         aria-expanded={isOpen}
-        // ml-4 plus the button's own px-2 puts the icon on the answer's ml-6
-        // text column. has-[>svg]:px-2 restates that padding under the same
-        // variant the button's own has-[>svg]:px-3 uses; a plain px-2 does not
-        // override it, and the chevron makes it match.
-        className="hover:bg-muted/60 ml-4 flex h-auto w-fit max-w-full items-center justify-start gap-2 rounded-lg bg-transparent px-2 py-1.5 text-sm font-normal has-[>svg]:px-2"
+        size="sm"
+        // ml-3.5 plus size sm's own has-[>svg]:px-2.5 (the chevron is a direct
+        // svg child) puts the icon on the answer's ml-6 text column.
+        className="ml-3.5 w-fit max-w-full justify-start"
       >
         {/* ToolIcon renders nothing for a tool with no bundled icon, so the
             dot below stands in via ``only:block`` to keep the row aligned. */}
diff --git a/frontend/src/conversation/Conversation.tsx b/frontend/src/conversation/Conversation.tsx
index 592509f8..5ae43619 100644
--- a/frontend/src/conversation/Conversation.tsx
+++ b/frontend/src/conversation/Conversation.tsx
@@ -419,7 +419,7 @@ export default function Conversation() {
         {/* One notch narrower than the message column above it, which keeps its
             own width. */}
         <div
-          className={`bg-opacity-0 z-3 flex h-auto w-full flex-col items-end self-center rounded-2xl py-1 ${
+          className={`z-3 flex h-auto w-full flex-col items-end self-center rounded-2xl py-1 ${
             isSplitArtifactOpen
               ? 'max-w-290'
               : 'max-w-290 md:w-10/12 lg:w-9/12 xl:w-8/12 2xl:w-7/12'
diff --git a/frontend/src/conversation/ConversationBubble.test.tsx b/frontend/src/conversation/ConversationBubble.test.tsx
new file mode 100644
index 00000000..1c375f65
--- /dev/null
+++ b/frontend/src/conversation/ConversationBubble.test.tsx
@@ -0,0 +1,189 @@
+import { configureStore } from '@reduxjs/toolkit';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { Provider } from 'react-redux';
+
+import en from '../locale/en.json';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string) =>
+      key
+        .split('.')
+        .reduce<unknown>(
+          (node, part) => (node as Record<string, unknown>)?.[part],
+          en,
+        ) ?? key,
+  }),
+}));
+
+import ConversationBubble from './ConversationBubble';
+import { ToolCallsType } from './types';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const makeStore = () =>
+  configureStore({
+    reducer: {
+      preference: () => ({
+        chunks: '2',
+        selectedDocs: [],
+        token: null,
+        ttsAvailable: false,
+      }),
+    },
+  });
+
+const pendingCall: ToolCallsType = {
+  tool_name: 'crm',
+  action_name: 'crm_update',
+  call_id: 'call-1',
+  arguments: { id: 7 },
+  status: 'awaiting_approval',
+};
+
+describe('ConversationBubble', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async (ui: React.ReactElement) => {
+    await act(async () => {
+      root.render(<Provider store={makeStore()}>{ui}</Provider>);
+    });
+  };
+
+  const buttonByText = (text: string) =>
+    Array.from(container.querySelectorAll('button')).find(
+      (b) => b.textContent?.trim() === text,
+    ) as HTMLButtonElement;
+
+  it('renders the approval bar on Button variants and disables Approve while a deny reason is typed', async () => {
+    await render(
+      <ConversationBubble
+        type="ANSWER"
+        toolCalls={[pendingCall]}
+        onToolAction={() => {}}
+      />,
+    );
+
+    const approve = buttonByText('Approve');
+    const deny = buttonByText('Deny');
+    expect(approve.dataset.variant).toBe('default');
+    expect(approve.dataset.size).toBe('xs');
+    expect(approve.dataset.shape).toBe('pill');
+    expect(approve.disabled).toBe(false);
+    expect(deny.dataset.variant).toBe('outline');
+    expect(deny.dataset.size).toBe('xs');
+
+    const details = container.querySelector(
+      'button[title="Details"]',
+    ) as HTMLButtonElement;
+    expect(details.dataset.variant).toBe('ghost-muted');
+    expect(details.dataset.size).toBe('icon-xs');
+
+    await act(async () => deny.click());
+    const input = container.querySelector('input') as HTMLInputElement;
+    expect(input.dataset.size).toBe('sm');
+    await act(async () => {
+      const setter = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        'value',
+      )!.set!;
+      setter.call(input, 'wrong record');
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+
+    expect(buttonByText('Approve').disabled).toBe(true);
+    expect(buttonByText('Deny').dataset.variant).toBe('destructive-outline');
+  });
+
+  it('renders artifact chips as secondary pills and feedback as muted icon buttons', async () => {
+    await render(
+      <ConversationBubble
+        type="ANSWER"
+        message="Done."
+        feedback="LIKE"
+        handleFeedback={() => {}}
+        onOpenArtifact={() => {}}
+        toolCalls={[
+          {
+            tool_name: 'code_executor',
+            action_name: 'code_executor_run',
+            call_id: 'call-2',
+            arguments: {},
+            status: 'completed',
+            artifact_id: 'art-1',
+          } as ToolCallsType,
+        ]}
+      />,
+    );
+
+    const chips = container.querySelectorAll(
+      'button[aria-label="View artifact"]',
+    );
+    expect(chips.length).toBe(1);
+    chips.forEach((chip) => {
+      expect((chip as HTMLElement).dataset.variant).toBe('secondary');
+      expect((chip as HTMLElement).dataset.shape).toBe('pill');
+    });
+
+    const like = container.querySelector(
+      'button[aria-label="Remove like"]',
+    ) as HTMLButtonElement;
+    expect(like.dataset.variant).toBe('ghost-muted');
+    expect(like.dataset.size).toBe('icon-sm');
+    expect(like.dataset.shape).toBe('pill');
+  });
+
+  it('renders the question edit actions as pill buttons', async () => {
+    await render(<ConversationBubble type="QUESTION" message="Hello" />);
+
+    const edit = container.querySelector('img[alt="Edit"]')!
+      .parentElement as HTMLButtonElement;
+    expect(edit.dataset.size).toBe('icon-xs');
+    expect(edit.dataset.shape).toBe('pill');
+    await act(async () => edit.click());
+
+    const cancel = buttonByText(en.conversation.edit.cancel);
+    const update = buttonByText(en.conversation.edit.update);
+    expect(cancel.dataset.variant).toBe('ghost');
+    expect(cancel.dataset.shape).toBe('pill');
+    expect(update.dataset.variant).toBe('default');
+    expect(update.dataset.shape).toBe('pill');
+    expect(update.disabled).toBe(true);
+  });
+
+  it('renders the question on the secondary tint with a foreground chevron', async () => {
+    const scrollHeight = vi
+      .spyOn(HTMLElement.prototype, 'scrollHeight', 'get')
+      .mockReturnValue(200);
+    await render(<ConversationBubble type="QUESTION" message="Hello" />);
+    scrollHeight.mockRestore();
+
+    const bubble = Array.from(
+      container.querySelectorAll<HTMLElement>('div'),
+    ).find((el) => el.className.includes('rounded-3xl'))!;
+    expect(bubble.className).toContain('bg-secondary');
+    expect(bubble.className).toContain('text-foreground');
+    expect(bubble.className).not.toMatch(/bg-primary|text-primary-foreground/);
+
+    const toggle = bubble.querySelector<HTMLButtonElement>(
+      'button[aria-label="Toggle"]',
+    )!;
+    expect(toggle.dataset.variant).toBe('ghost');
+    expect(toggle.className).not.toContain('white/20');
+    expect(toggle.querySelector('img')).toBeNull();
+    expect(toggle.querySelector('svg')).not.toBeNull();
+  });
+});
diff --git a/frontend/src/conversation/ConversationBubble.tsx b/frontend/src/conversation/ConversationBubble.tsx
index 557ec121..ff42b736 100644
--- a/frontend/src/conversation/ConversationBubble.tsx
+++ b/frontend/src/conversation/ConversationBubble.tsx
@@ -1,7 +1,8 @@
 import { envVar } from '@/env';
+import { cn } from '@/lib/utils';
 import 'katex/dist/katex.min.css';
 
-import { Pencil } from 'lucide-react';
+import { ChevronDown as ChevronDownIcon, Pencil } from 'lucide-react';
 import { forwardRef, Fragment, useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
@@ -152,7 +153,7 @@ const ConversationBubble = forwardRef<
                   title={file.fileName}
                   className="dark:text-foreground dark:bg-accent text-muted-foreground bg-muted flex items-center rounded-xl p-2 text-sm"
                 >
-                  <div className="bg-primary mr-2 items-center justify-center rounded-lg p-[5.5px]">
+                  <div className="bg-primary mr-2 items-center justify-center rounded-lg p-1.5">
                     <img
                       src={DocumentationDark}
                       alt="Attachment"
@@ -175,7 +176,7 @@ const ConversationBubble = forwardRef<
                 {/* ``mr-3`` plus the pill's own ``mr-2`` puts the question's
                     right edge on the answer's ``mr-5`` gutter. */}
                 <div className="relative mr-3 flex w-full min-w-0 flex-col">
-                  <div className="mr-2 ml-2 flex max-w-full min-w-0 items-start gap-2 rounded-3xl bg-linear-to-b from-violet-500 to-violet-600 px-5 py-4 text-sm leading-normal wrap-anywhere whitespace-pre-wrap text-white sm:text-base">
+                  <div className="bg-secondary text-foreground mr-2 ml-2 flex max-w-full min-w-0 items-start gap-2 rounded-3xl px-5 py-4 text-sm leading-normal wrap-anywhere whitespace-pre-wrap sm:text-base">
                     <div
                       ref={messageRef}
                       className={`${isQuestionCollapsed ? 'line-clamp-4' : ''} w-full min-w-0`}
@@ -186,19 +187,21 @@ const ConversationBubble = forwardRef<
                       <Button
                         type="button"
                         variant="ghost"
-                        size="icon-sm"
+                        size="icon-lg"
+                        shape="pill"
                         onClick={(e) => {
                           e.stopPropagation();
                           setIsQuestionCollapsed(!isQuestionCollapsed);
                         }}
-                        className="ml-1 h-auto w-auto rounded-full bg-transparent p-2 hover:bg-[#D9D9D933]"
+                        aria-label="Toggle"
+                        className="ml-1"
                       >
-                        <img
-                          src={ChevronDown}
-                          alt="Toggle"
-                          width={24}
-                          height={24}
-                          className={`transform invert transition-transform duration-200 ${isQuestionCollapsed ? '' : 'rotate-180'}`}
+                        <ChevronDownIcon
+                          aria-hidden
+                          className={cn(
+                            'size-6 transition-transform duration-200',
+                            !isQuestionCollapsed && 'rotate-180',
+                          )}
                         />
                       </Button>
                     )}
@@ -207,12 +210,13 @@ const ConversationBubble = forwardRef<
                 <Button
                   type="button"
                   variant="ghost"
-                  size="icon-sm"
+                  size="icon-xs"
+                  shape="pill"
                   onClick={() => {
                     setIsEditClicked(true);
                     setEditInputBox(message ?? '');
                   }}
-                  className="invisible mt-3 h-fit w-auto shrink-0 cursor-pointer rounded-full p-2 pt-1.5 pl-1.5 group-hover:visible"
+                  className="invisible mt-3 shrink-0 cursor-pointer group-hover:visible"
                 >
                   <img src={Edit} alt="Edit" className="cursor-pointer" />
                 </Button>
@@ -237,20 +241,20 @@ const ConversationBubble = forwardRef<
                 }}
                 rows={5}
                 value={editInputBox}
-                className="border-border text-foreground dark:border-border dark:text-foreground focus-visible:ring-ring/50 focus-visible:border-ring w-full resize-none rounded-3xl border px-4 py-3 text-base leading-relaxed focus:outline-hidden focus-visible:ring-[3px]"
+                className="border-border text-foreground dark:border-border dark:text-foreground focus-visible:ring-ring/50 focus-visible:border-ring w-full resize-none rounded-3xl border px-4 py-3 text-base leading-relaxed focus:outline-hidden focus-visible:ring-3"
               />
               <div className="flex items-center justify-end gap-2">
                 <Button
                   type="button"
                   variant="ghost"
-                  className="text-primary hover:bg-muted hover:text-foreground dark:hover:bg-accent dark:hover:text-foreground h-auto rounded-full px-4 py-2 text-sm font-semibold"
+                  shape="pill"
                   onClick={() => setIsEditClicked(false)}
                 >
                   {t('conversation.edit.cancel')}
                 </Button>
                 <Button
                   type="button"
-                  className="bg-primary not-disabled:hover:bg-primary/90 not-disabled:dark:hover:bg-primary/90 disabled:bg-primary/30 h-auto rounded-full px-4 py-2 text-sm font-medium text-white disabled:cursor-not-allowed disabled:opacity-100"
+                  shape="pill"
                   onClick={handleEditClick}
                   disabled={
                     !editInputBox.trim() ||
@@ -284,7 +288,7 @@ const ConversationBubble = forwardRef<
                   <Avatar
                     src={Sources}
                     alt={t('conversation.sources.title')}
-                    className="h-6.5 w-7.5 text-xl"
+                    className="h-6.5 w-7.5"
                     imgClassName="h-full w-full object-fill"
                   />
                   <p className="text-base font-semibold">
@@ -312,7 +316,7 @@ const ConversationBubble = forwardRef<
                           <div
                             className={`mt-3.5 flex flex-row items-center gap-1.5 underline-offset-2 ${
                               source.link && source.link !== 'local'
-                                ? 'hover:text-[#007DFF] hover:underline dark:hover:text-blue-400'
+                                ? 'hover:text-primary hover:underline'
                                 : ''
                             }`}
                             onClick={() =>
@@ -346,7 +350,7 @@ const ConversationBubble = forwardRef<
                         </div>
                         {activeTooltip === index && (
                           <div
-                            className={`dark:bg-card dark:text-foreground absolute left-1/2 z-50 max-h-48 w-40 translate-x-[-50%] translate-y-0.75 rounded-xl bg-[#FBFBFB] p-4 text-black shadow-xl sm:w-56`}
+                            className="bg-popover text-popover-foreground absolute left-1/2 z-50 max-h-48 w-40 translate-x-[-50%] translate-y-0.75 rounded-xl p-4 shadow-md sm:w-56"
                             onMouseOver={() => setActiveTooltip(index)}
                             onMouseOut={() => setActiveTooltip(null)}
                           >
@@ -386,7 +390,8 @@ const ConversationBubble = forwardRef<
                     toolName: artifact.toolName,
                   })
                 }
-                className="h-auto rounded-full bg-purple-100 px-3 py-2 text-sm font-medium text-purple-700 hover:bg-purple-200 dark:bg-purple-900/30 dark:text-purple-300 dark:hover:bg-purple-900/50"
+                variant="secondary"
+                shape="pill"
               >
                 <svg
                   className="h-4 w-4"
@@ -425,7 +430,7 @@ const ConversationBubble = forwardRef<
         {type === 'ERROR' ? (
           message && (
             <div className="flex max-w-full flex-col flex-wrap items-start self-start lg:flex-nowrap">
-              <div className="fade-in-bubble text-destructive/80 dark:border-destructive dark:bg-destructive/15 relative mr-5 flex max-w-full flex-row items-center rounded-full border border-transparent bg-[#FFE7E7] p-2 px-6 py-5 text-sm font-normal dark:text-white">
+              <div className="fade-in-bubble text-destructive/80 dark:border-destructive bg-destructive/10 relative mr-5 flex max-w-full flex-row items-center rounded-full border border-transparent p-2 px-6 py-5 text-sm font-normal dark:text-white">
                 <MarkdownAnswer content={message} isStreaming={isStreaming} />
               </div>
             </div>
@@ -484,7 +489,8 @@ const ConversationBubble = forwardRef<
                             toolName: artifact.toolName,
                           })
                         }
-                        className="h-auto rounded-full bg-purple-100 px-3 py-2 text-sm font-medium text-purple-700 hover:bg-purple-200 dark:bg-purple-900/30 dark:text-purple-300 dark:hover:bg-purple-900/50"
+                        variant="secondary"
+                        shape="pill"
                         aria-label="View artifact"
                       >
                         <svg
@@ -524,8 +530,9 @@ const ConversationBubble = forwardRef<
                       <div className="relative block items-center justify-center">
                         <Button
                           type="button"
-                          variant="ghost"
+                          variant="ghost-muted"
                           size="icon-sm"
+                          shape="pill"
                           onClick={() => {
                             const blob = new Blob([message], {
                               type: 'text/markdown',
@@ -537,7 +544,7 @@ const ConversationBubble = forwardRef<
                             link.click();
                             URL.revokeObjectURL(url);
                           }}
-                          className="bg-card hover:bg-muted dark:hover:bg-accent h-auto w-auto cursor-pointer rounded-full p-2 dark:bg-transparent"
+                          className="cursor-pointer"
                           aria-label="Export as Markdown"
                           title="Export as Markdown"
                         >
@@ -566,9 +573,10 @@ const ConversationBubble = forwardRef<
                         <div className="relative flex items-center justify-center">
                           <Button
                             type="button"
-                            variant="ghost"
+                            variant="ghost-muted"
                             size="icon-sm"
-                            className="h-auto w-auto cursor-pointer rounded-full bg-transparent p-2"
+                            shape="pill"
+                            className="cursor-pointer"
                             onClick={() => {
                               if (feedback === 'LIKE') {
                                 handleFeedback?.(null);
@@ -581,7 +589,7 @@ const ConversationBubble = forwardRef<
                             }
                           >
                             <Like
-                              className={`${feedback === 'LIKE' ? 'stroke-primary fill-white dark:fill-transparent' : 'stroke-muted-foreground fill-none'}`}
+                              className={`${feedback === 'LIKE' ? 'stroke-primary fill-white dark:fill-transparent' : 'stroke-muted-foreground fill-transparent'}`}
                             ></Like>
                           </Button>
                         </div>
@@ -589,9 +597,10 @@ const ConversationBubble = forwardRef<
                         <div className="relative flex items-center justify-center">
                           <Button
                             type="button"
-                            variant="ghost"
+                            variant="ghost-muted"
                             size="icon-sm"
-                            className="h-auto w-auto cursor-pointer rounded-full bg-transparent p-2"
+                            shape="pill"
+                            className="cursor-pointer"
                             onClick={() => {
                               if (feedback === 'DISLIKE') {
                                 handleFeedback?.(null);
@@ -606,7 +615,7 @@ const ConversationBubble = forwardRef<
                             }
                           >
                             <Dislike
-                              className={`${feedback === 'DISLIKE' ? 'stroke-destructive fill-white dark:fill-transparent' : 'stroke-muted-foreground fill-none'}`}
+                              className={`${feedback === 'DISLIKE' ? 'stroke-destructive fill-white dark:fill-transparent' : 'stroke-muted-foreground fill-transparent'}`}
                             ></Dislike>
                           </Button>
                         </div>
@@ -623,7 +632,7 @@ const ConversationBubble = forwardRef<
             <SheetContent
               side="right"
               title="Sources"
-              className="bg-card w-64 border-l border-[#9ca3af]/10 sm:w-80 sm:max-w-none"
+              className="w-64 sm:w-80 sm:max-w-none"
             >
               <div className="flex h-full flex-col items-center gap-2 px-6 py-4 text-center">
                 <AllSources sources={sources} />
@@ -654,7 +663,7 @@ function AllSources(sources: AllSourcesProps) {
     <div className="h-full w-full">
       <div className="w-full">
         <p className="text-left text-xl">{`${sources.sources.length} ${t('conversation.sources.title')}`}</p>
-        <div className="mx-1 mt-2 h-[0.8px] w-full rounded-full bg-[#C4C4C4]/40 lg:w-[95%]"></div>
+        <div className="bg-border mx-1 mt-2 h-[0.8px] w-full rounded-full lg:w-[95%]"></div>
       </div>
       <div className="mt-6 flex h-[90%] w-52 flex-col gap-4 overflow-y-auto pr-3 sm:w-64">
         {sources.sources.map((source, index) => {
@@ -688,7 +697,7 @@ function AllSources(sources: AllSourcesProps) {
                   />
                 )}
               </p>
-              <p className="dark:text-foreground mt-3 line-clamp-4 rounded-md text-left text-xs wrap-break-word text-black">
+              <p className="text-foreground mt-3 line-clamp-4 rounded-md text-left text-xs wrap-break-word">
                 {source.text}
               </p>
             </div>
@@ -762,11 +771,9 @@ function ToolCallApprovalBar({
         <div className="flex items-center gap-2">
           <Button
             type="button"
-            className={`h-auto rounded-full px-4 py-1 text-xs font-medium ${
-              comment
-                ? 'bg-muted text-muted-foreground hover:bg-muted cursor-default opacity-50'
-                : 'bg-primary hover:bg-primary/90 text-white'
-            }`}
+            size="xs"
+            shape="pill"
+            disabled={Boolean(comment)}
             onClick={() => {
               if (!comment) onToolAction?.(toolCall.call_id, 'approved');
             }}
@@ -777,7 +784,8 @@ function ToolCallApprovalBar({
             <Button
               type="button"
               variant="outline"
-              className="h-auto rounded-full border bg-transparent px-4 py-1 text-xs font-medium shadow-none"
+              size="xs"
+              shape="pill"
               onClick={() => {
                 void handleApproveSticky();
               }}
@@ -788,12 +796,9 @@ function ToolCallApprovalBar({
           )}
           <Button
             type="button"
-            variant="outline"
-            className={`h-auto rounded-full border bg-transparent px-4 py-1 text-xs font-medium shadow-none ${
-              comment
-                ? 'border-destructive bg-destructive/10 text-destructive hover:bg-destructive/10 font-semibold'
-                : 'hover:bg-accent text-muted-foreground dark:bg-transparent'
-            }`}
+            variant={comment ? 'destructive-outline' : 'outline'}
+            size="xs"
+            shape="pill"
             onClick={() => {
               if (expanded && comment) {
                 onToolAction?.(toolCall.call_id, 'denied', comment);
@@ -808,9 +813,9 @@ function ToolCallApprovalBar({
           </Button>
           <Button
             type="button"
-            variant="ghost"
-            size="icon-sm"
-            className="text-muted-foreground hover:text-foreground h-6 w-6 rounded-full"
+            variant="ghost-muted"
+            size="icon-xs"
+            shape="pill"
             onClick={() => setExpanded(!expanded)}
             title="Details"
           >
@@ -833,7 +838,8 @@ function ToolCallApprovalBar({
           <Input
             type="text"
             placeholder="Optional reason for denying..."
-            className="bg-background h-8 rounded-lg px-3 py-1.5 text-sm md:text-sm"
+            size="sm"
+            variant="filled"
             value={comment}
             onChange={(e) => setComment(e.target.value)}
             onKeyDown={(e) => {
diff --git a/frontend/src/conversation/ConversationMessages.test.tsx b/frontend/src/conversation/ConversationMessages.test.tsx
new file mode 100644
index 00000000..ad431b99
--- /dev/null
+++ b/frontend/src/conversation/ConversationMessages.test.tsx
@@ -0,0 +1,80 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('./ConversationBubble', () => ({
+  default: ({ message }: { message?: string }) => <div>{message}</div>,
+}));
+
+vi.mock('../Hero', () => ({ default: () => null }));
+
+vi.mock('./StreamingStatusLine', () => ({ default: () => null }));
+
+import ConversationMessages from './ConversationMessages';
+import type { Query } from './conversationModels';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('ConversationMessages', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = (queries: Query[]) =>
+    act(() => {
+      root.render(
+        <ConversationMessages
+          handleQuestion={() => undefined}
+          handleQuestionSubmission={() => undefined}
+          queries={queries}
+          status="idle"
+        />,
+      );
+    });
+
+  it('shows a non-fatal notice as a polite warning alert with an icon', () => {
+    render([
+      { prompt: 'hi', response: 'hello', notice: 'Some tools were skipped.' },
+    ]);
+
+    const notice = container.querySelector('[role="status"]');
+    expect(notice?.textContent).toBe('Some tools were skipped.');
+    expect(notice?.className).toContain('bg-warning/10');
+    expect(notice?.querySelector('svg')).not.toBeNull();
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+  });
+
+  it('collapses the pin spacer once it has scrolled below the fold', () => {
+    render([{ prompt: 'hi', response: 'hello' }]);
+
+    const viewport = container.querySelector<HTMLElement>(
+      '[data-slot="message-scroller-viewport"]',
+    )!;
+    const spacer = container.querySelector<HTMLElement>(
+      '[data-message-scroller-spacer]',
+    )!;
+    expect(spacer.className).not.toContain('max-h-0');
+
+    spacer.style.height = '200px';
+    Object.defineProperty(viewport, 'scrollHeight', { value: 1000 });
+    Object.defineProperty(viewport, 'clientHeight', { value: 500 });
+    act(() => {
+      viewport.dispatchEvent(new Event('scroll'));
+    });
+
+    expect(spacer.className).toContain('max-h-0');
+  });
+});
diff --git a/frontend/src/conversation/ConversationMessages.tsx b/frontend/src/conversation/ConversationMessages.tsx
index 41befb2f..89735118 100644
--- a/frontend/src/conversation/ConversationMessages.tsx
+++ b/frontend/src/conversation/ConversationMessages.tsx
@@ -7,9 +7,11 @@ import {
   useRef,
   useState,
 } from 'react';
+import { TriangleAlert } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 
 import Retry from '../assets/retry.svg?react';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import {
   MessageScroller,
@@ -24,6 +26,7 @@ import { deriveArtifactChips } from './artifactChips';
 import ConversationBubble from './ConversationBubble';
 import { FEEDBACK, Query, Status } from './conversationModels';
 import StreamingStatusLine from './StreamingStatusLine';
+import { cn } from '@/lib/utils';
 
 type ConversationMessagesProps = {
   handleQuestion: (params: {
@@ -116,7 +119,9 @@ export default function ConversationMessages({
       // (dist >= its height) so removing it never shifts the visible content.
       // Reading style.height (the primitive's inline value) avoids a reflow.
       if (!spacerCollapsedRef.current) {
-        const spacer = vp.querySelector<HTMLElement>('.msc-spacer');
+        const spacer = vp.querySelector<HTMLElement>(
+          '[data-message-scroller-spacer]',
+        );
         const spacerH = spacer ? parseFloat(spacer.style.height) || 0 : 0;
         if (spacerH > STICK_THRESHOLD_PX && dist >= spacerH) {
           spacerCollapsedRef.current = true;
@@ -138,8 +143,10 @@ export default function ConversationMessages({
   }, [status, lastTurnContentLength, hasMessages]);
 
   const columnClass = isSplitView
-    ? 'w-full max-w-325 px-2'
-    : 'w-full max-w-325 px-2 md:w-11/12 lg:w-10/12 xl:w-9/12 2xl:w-8/12';
+    ? // eslint-disable-next-line shadcn/no-restyle -- MessageScroller padding: the primitive measures Content's padding-block for its scroll math, and the Viewport's top gap must scroll with the messages. See DESIGN.md, Approved exceptions.
+      'w-full max-w-325 px-2'
+    : // eslint-disable-next-line shadcn/no-restyle -- MessageScroller padding: the primitive measures Content's padding-block for its scroll math, and the Viewport's top gap must scroll with the messages. See DESIGN.md, Approved exceptions.
+      'w-full max-w-325 px-2 md:w-11/12 lg:w-10/12 xl:w-9/12 2xl:w-8/12';
 
   // The empty state sits directly on top of the composer with nothing between
   // them, so it takes the composer's width rather than the wider message column.
@@ -157,8 +164,10 @@ export default function ConversationMessages({
       const retryButton = (
         <Button
           type="button"
-          variant="ghost"
-          className="dark:text-foreground h-auto self-center rounded-full px-5 py-3 text-lg text-gray-500 delay-100 hover:border-gray-500"
+          variant="ghost-muted"
+          size="icon"
+          shape="pill"
+          className="self-center"
           disabled={status === 'loading'}
           onClick={() => {
             const questionToRetry = queries[index].prompt;
@@ -170,11 +179,7 @@ export default function ConversationMessages({
           }}
           aria-label={t('conversation.retry')}
         >
-          <Retry
-            width={12}
-            height={12}
-            className="text-gray-500 dark:text-[#ECECF1]"
-          />
+          <Retry width={12} height={12} />
         </Button>
       );
       return (
@@ -206,12 +211,14 @@ export default function ConversationMessages({
       return (
         <Fragment key={`${index}-ANSWER`}>
           {query.notice ? (
-            <div
+            <Alert
+              variant="warning"
               role="status"
-              className={`${bubbleMargin} mr-5 self-start rounded-2xl border border-amber-300 bg-amber-50 px-4 py-2 text-sm text-amber-800 dark:border-amber-500/40 dark:bg-amber-500/10 dark:text-amber-200`}
+              className={cn(bubbleMargin, 'mr-5 w-auto')}
             >
-              {query.notice}
-            </div>
+              <TriangleAlert className="size-4" aria-hidden="true" />
+              <AlertDescription>{query.notice}</AlertDescription>
+            </Alert>
           ) : null}
           <ConversationBubble
             className={bubbleMargin}
@@ -268,11 +275,13 @@ export default function ConversationMessages({
   return (
     <MessageScrollerProvider autoScroll>
       <MessageScroller>
-        <MessageScrollerViewport className="sm:pt-6 lg:pt-12">
+        <MessageScrollerViewport
+          /* eslint-disable-next-line shadcn/no-restyle -- MessageScroller padding: the primitive measures Content's padding-block for its scroll math, and the Viewport's top gap must scroll with the messages. See DESIGN.md, Approved exceptions. */
+          className="sm:pt-6 lg:pt-12"
+        >
           <MessageScrollerContent
-            spacerClassName={
-              spacerCollapsed ? 'msc-spacer max-h-0' : 'msc-spacer'
-            }
+            spacerClassName={spacerCollapsed ? 'max-h-0' : undefined}
+            /* eslint-disable-next-line shadcn/no-restyle -- MessageScroller padding: the primitive measures Content's padding-block for its scroll math, and the Viewport's top gap must scroll with the messages. See DESIGN.md, Approved exceptions. */
             className={`mx-auto pb-7 ${columnClass}`}
           >
             {headerContent}
diff --git a/frontend/src/conversation/ConversationTile.tsx b/frontend/src/conversation/ConversationTile.tsx
index cfc5d87d..f289ab5f 100644
--- a/frontend/src/conversation/ConversationTile.tsx
+++ b/frontend/src/conversation/ConversationTile.tsx
@@ -20,6 +20,7 @@ import { ShareConversationModal } from '../modals/ShareConversationModal';
 import { useTranslation } from 'react-i18next';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
+import { cn } from '../lib/utils';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -196,12 +197,13 @@ export default function ConversationTile({
             : ''
         }`}
       >
-        <div className={`flex w-10/12 gap-4`}>
+        <div className={cn('flex w-10/12 gap-4', isEdit && 'px-1')}>
           {isEdit ? (
             <Input
               autoFocus
               type="text"
-              className="h-6 w-full rounded-2xl border-0 px-1 text-sm leading-6 font-normal shadow-none focus-visible:ring-0 md:text-sm dark:border-0"
+              variant="bare"
+              className="w-full"
               value={conversationName}
               onChange={(e) => setConversationsName(e.target.value)}
               onKeyDown={handleRenameKeyDown}
@@ -218,11 +220,11 @@ export default function ConversationTile({
               <div className="flex gap-1">
                 <Button
                   type="button"
-                  variant="ghost"
-                  size="icon-sm"
+                  variant="ghost-muted"
+                  size="icon-xs"
                   aria-label={t('convTile.save')}
                   title={t('convTile.save')}
-                  className="mr-2 h-auto w-auto bg-transparent p-0 hover:bg-transparent hover:opacity-50"
+                  className="mr-2"
                   onClick={(event: SyntheticEvent) => {
                     event.stopPropagation();
                     handleSaveConversation({
@@ -235,12 +237,12 @@ export default function ConversationTile({
                 </Button>
                 <Button
                   type="button"
-                  variant="ghost"
-                  size="icon-sm"
+                  variant="ghost-muted"
+                  size="icon-xs"
                   aria-label={t('cancel')}
                   title={t('cancel')}
                   id={`img-${conversation.id}`}
-                  className="mt-px mr-4 h-auto w-auto bg-transparent p-0 hover:bg-transparent hover:opacity-50"
+                  className="mt-px mr-4"
                   onClick={(event: SyntheticEvent) => {
                     event.stopPropagation();
                     onClear();
@@ -256,10 +258,11 @@ export default function ConversationTile({
                     type="button"
                     variant="ghost"
                     size="icon-sm"
+                    shape="pill"
                     onClick={(event: SyntheticEvent) => {
                       event.stopPropagation();
                     }}
-                    className="mr-2 h-6 w-6 rounded-full"
+                    className="mr-2 h-6 w-6"
                   >
                     <img src={threeDots} width={8} alt="menu" />
                   </Button>
diff --git a/frontend/src/conversation/MarkdownAnswer.tsx b/frontend/src/conversation/MarkdownAnswer.tsx
index 9d41dcd0..946f654a 100644
--- a/frontend/src/conversation/MarkdownAnswer.tsx
+++ b/frontend/src/conversation/MarkdownAnswer.tsx
@@ -163,15 +163,15 @@ export default function MarkdownAnswer({
       <Button
         type="button"
         variant="link"
+        size="inline"
         onClick={() =>
           onOpenArtifact({
             id: artifact.id,
             toolName: artifact.toolName ?? '',
           })
         }
-        /* Sits mid-sentence: no pill background, no fixed height, and it must
-           wrap with the surrounding text. */
-        className="text-primary h-auto w-auto bg-transparent p-0 whitespace-normal underline underline-offset-2"
+        /* Sits mid-sentence, so it must wrap with the surrounding text. */
+        className="whitespace-normal"
         title={artifact.label}
       >
         {content}
@@ -215,6 +215,9 @@ export default function MarkdownAnswer({
                       return (
                         <Button
                           type="button"
+                          variant="secondary"
+                          size="xs"
+                          shape="pill"
                           onClick={() => {
                             const el = document.getElementById(
                               `source-${sourceIdx}`,
@@ -224,18 +227,15 @@ export default function MarkdownAnswer({
                                 behavior: 'smooth',
                                 block: 'center',
                               });
-                              el.classList.add('ring-2', 'ring-purple-500');
+                              el.classList.add('ring-3', 'ring-primary');
                               setTimeout(
                                 () =>
-                                  el.classList.remove(
-                                    'ring-2',
-                                    'ring-purple-500',
-                                  ),
+                                  el.classList.remove('ring-3', 'ring-primary'),
                                 2000,
                               );
                             }
                           }}
-                          className="mx-0.5 h-5 min-w-5 rounded-full bg-purple-100 px-1.5 text-xs font-semibold text-purple-700 hover:bg-purple-200 dark:bg-purple-900/40 dark:text-purple-300 dark:hover:bg-purple-900/60"
+                          className="mx-0.5 h-5 min-w-5"
                           title={`Jump to source ${num}`}
                         >
                           {num}
@@ -293,6 +293,7 @@ export default function MarkdownAnswer({
                           {...rest}
                           PreTag="div"
                           language={language}
+                          /* eslint-disable-next-line shadcn/no-inline-styles -- SyntaxHighlighter's style prop is its Prism theme object (oneLight / vscDarkPlus), picked by theme at runtime; it is not CSS. See DESIGN.md, Approved exceptions. */
                           style={isDarkTheme ? vscDarkPlus : oneLight}
                           className="mt-0!"
                           customStyle={{ margin: 0, borderRadius: 0 }}
@@ -301,7 +302,7 @@ export default function MarkdownAnswer({
                         </SyntaxHighlighter>
                       </div>
                     ) : (
-                      <code className="dark:bg-accent dark:text-foreground rounded-md bg-gray-200 px-2 py-1 text-xs font-normal whitespace-pre-line">
+                      <code className="bg-accent dark:text-foreground rounded-md px-2 py-1 text-xs font-normal whitespace-pre-line">
                         {children}
                       </code>
                     );
@@ -327,7 +328,7 @@ export default function MarkdownAnswer({
                   table({ children }) {
                     return (
                       <div className="border-border relative overflow-x-auto rounded-lg border">
-                        <table className="dark:text-foreground w-full text-left text-gray-700">
+                        <table className="text-foreground w-full text-left">
                           {children}
                         </table>
                       </div>
@@ -359,7 +360,7 @@ export default function MarkdownAnswer({
               </ReactMarkdown>
             </div>
           ) : (
-            <div className="my-4 w-full" style={{ minWidth: '100%' }}>
+            <div className="my-4 w-full min-w-full">
               <MermaidRenderer code={segment.content} isLoading={isStreaming} />
             </div>
           )}
diff --git a/frontend/src/conversation/ResearchProgress.tsx b/frontend/src/conversation/ResearchProgress.tsx
index 1d86832d..298678e0 100644
--- a/frontend/src/conversation/ResearchProgress.tsx
+++ b/frontend/src/conversation/ResearchProgress.tsx
@@ -3,10 +3,11 @@ import ResearchIcon from '../assets/research.svg';
 import { Avatar } from '../components/ui/avatar';
 import { Button } from '../components/ui/button';
 import { ResearchState } from './conversationModels';
+import { cn } from '@/lib/utils';
 
 const SmallCheck = () => (
   <svg
-    className="h-3 w-3 text-green-500"
+    className="text-success h-3 w-3"
     fill="none"
     viewBox="0 0 24 24"
     stroke="currentColor"
@@ -18,7 +19,7 @@ const SmallCheck = () => (
 
 const SmallSpinner = () => (
   <svg
-    className="h-3 w-3 animate-spin text-purple-500"
+    className="text-primary h-3 w-3 animate-spin"
     fill="none"
     viewBox="0 0 24 24"
   >
@@ -39,7 +40,7 @@ const SmallSpinner = () => (
 );
 
 const SmallPending = () => (
-  <div className="h-2.5 w-2.5 rounded-full border-[1.5px] border-gray-400 dark:border-gray-500" />
+  <div className="border-muted-foreground h-2.5 w-2.5 rounded-full border" />
 );
 
 function StatusText({ status, elapsed }: { status: string; elapsed?: number }) {
@@ -51,12 +52,10 @@ function StatusText({ status, elapsed }: { status: string; elapsed?: number }) {
   };
   const elapsed_str = elapsed ? ` \u00B7 ${Math.round(elapsed)}s` : '';
   return (
-    <span className="text-xs text-gray-500 dark:text-gray-400">
+    <span className="text-muted-foreground text-xs">
       {status === 'complete' ? (
         <>
-          <span className="text-green-600 dark:text-green-400">
-            {labels.complete}
-          </span>
+          <span className="text-success">{labels.complete}</span>
           {elapsed_str}
         </>
       ) : (
@@ -103,21 +102,24 @@ export default function ResearchProgress({
         <Avatar
           src={ResearchIcon}
           alt="Research"
-          className="h-[26px] w-[30px] text-xl"
+          className="h-[26px] w-[30px]"
           imgClassName="h-full w-full object-fill"
         />
         <Button
           type="button"
           variant="ghost"
           size="sm"
-          className="h-auto bg-transparent px-0 py-0 font-normal hover:bg-transparent dark:hover:bg-transparent"
+          className="-ml-2.5"
           onClick={() => setIsExpanded(!isExpanded)}
         >
           <p className="text-sm font-semibold">
             {isExpanded ? 'Research' : summaryText}
           </p>
           <svg
-            className={`h-4 w-4 text-gray-500 transition-transform duration-200 dark:text-gray-400 ${isExpanded ? 'rotate-180' : ''}`}
+            className={cn(
+              'text-muted-foreground h-4 w-4 transition-transform duration-200',
+              isExpanded && 'rotate-180',
+            )}
             fill="none"
             viewBox="0 0 24 24"
             stroke="currentColor"
@@ -152,20 +154,19 @@ export default function ResearchProgress({
                         <SmallPending />
                       )}
                     </div>
-                    {!isLast && (
-                      <div className="mt-1 w-px flex-1 bg-gray-300 dark:bg-gray-600" />
-                    )}
+                    {!isLast && <div className="bg-border mt-1 w-px flex-1" />}
                   </div>
                   {/* Step content */}
                   <div className={`pb-3 ${isLast ? '' : ''}`}>
                     <p
-                      className={`text-sm ${
+                      className={cn(
+                        'text-sm',
                         step.status === 'complete'
-                          ? 'text-gray-700 dark:text-gray-300'
+                          ? 'text-foreground'
                           : step.status === 'researching'
-                            ? 'font-medium text-purple-700 dark:text-purple-300'
-                            : 'text-gray-500 dark:text-gray-500'
-                      }`}
+                            ? 'text-primary font-medium'
+                            : 'text-muted-foreground',
+                      )}
                     >
                       {step.query}
                     </p>
diff --git a/frontend/src/conversation/SharedConversation.tsx b/frontend/src/conversation/SharedConversation.tsx
index 3a45a4fe..5271c63a 100644
--- a/frontend/src/conversation/SharedConversation.tsx
+++ b/frontend/src/conversation/SharedConversation.tsx
@@ -146,7 +146,7 @@ export const SharedConversation = () => {
           </h1>
           <h2 className="text-foreground dark:text-foreground text-base font-semibold">
             {t('sharedConv.subtitle')}{' '}
-            <a href="/" className="text-[#007DFF]">
+            <a href="/" className="text-info">
               DocsGPT
             </a>
           </h2>
@@ -176,7 +176,9 @@ export const SharedConversation = () => {
             <Button
               type="button"
               onClick={() => navigate('/')}
-              className="mb-14 h-auto w-fit rounded-full px-5 py-3 text-white shadow-xl sm:mb-0"
+              size="lg"
+              shape="pill"
+              className="mb-14 w-fit sm:mb-0"
             >
               {t('sharedConv.button')}
             </Button>
diff --git a/frontend/src/design/DesignSystem.tsx b/frontend/src/design/DesignSystem.tsx
new file mode 100644
index 00000000..db49d528
--- /dev/null
+++ b/frontend/src/design/DesignSystem.tsx
@@ -0,0 +1,1932 @@
+import {
+  Check,
+  Clock,
+  Copy,
+  Mail,
+  Mic,
+  Moon,
+  MoreHorizontal,
+  Pencil,
+  Plus,
+  Search,
+  Settings,
+  Bot,
+  ChevronDown,
+  ChevronRight,
+  ChevronsUpDown,
+  X,
+  Calendar as CalendarIcon,
+  Database,
+  FileText,
+  Globe,
+  Link2,
+  Cloud,
+  Book,
+  GitBranch,
+  MessageSquare,
+  Users,
+  Workflow,
+  Sun,
+  Trash2,
+} from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@/components/ui/accordion';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { Avatar } from '@/components/ui/avatar';
+import { Badge } from '@/components/ui/badge';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/components/ui/breadcrumb';
+import { Button } from '@/components/ui/button';
+import { Dropzone } from '@/components/ui/dropzone';
+import { Calendar } from '@/components/ui/calendar';
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandShortcut,
+} from '@/components/ui/command';
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Modal } from '@/components/ui/modal';
+import { MultiSelect } from '@/components/ui/multi-select';
+import { OptionCard } from '@/components/ui/option-card';
+import { Progress } from '@/components/ui/progress';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Spinner } from '@/components/ui/spinner';
+import { Textarea } from '@/components/ui/textarea';
+import {
+  Toast,
+  ToastActions,
+  ToastContent,
+  ToastFooter,
+  ToastHeader,
+  ToastItem,
+  ToastMessage,
+  ToastStatus,
+  ToastTitle,
+} from '@/components/ui/toast';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@/components/ui/tooltip';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+} from '@/components/ui/sheet';
+import { Switch } from '@/components/ui/switch';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { TimePicker } from '@/components/ui/time-picker';
+import { useDarkTheme } from '../hooks';
+
+/**
+ * Dev-only style guide, served at /design. It renders every component in
+ * src/components/ui with the variants DESIGN.md documents as the defaults,
+ * so the page doubles as a visual test of the theme tokens in both modes.
+ * Nothing here is translated: the route is not registered in production.
+ */
+
+const SECTIONS = [
+  ['tokens', 'Colour tokens'],
+  ['typography', 'Typography'],
+  ['buttons', 'Buttons'],
+  ['badges', 'Badges & toasts'],
+  ['cards', 'Cards'],
+  ['forms', 'Forms'],
+  ['dropzone', 'Dropzone'],
+  ['feedback', 'Feedback & loading'],
+  ['avatars', 'Avatars'],
+  ['navigation', 'Navigation'],
+  ['tables', 'Tables'],
+  ['overlays', 'Overlays'],
+  ['pickers', 'Pickers'],
+] as const;
+
+const SURFACE_TOKENS = [
+  { name: 'background', bg: 'bg-background', fg: 'text-foreground' },
+  { name: 'card', bg: 'bg-card', fg: 'text-card-foreground' },
+  { name: 'popover', bg: 'bg-popover', fg: 'text-popover-foreground' },
+  { name: 'muted', bg: 'bg-muted', fg: 'text-muted-foreground' },
+  { name: 'accent', bg: 'bg-accent', fg: 'text-accent-foreground' },
+  { name: 'sidebar', bg: 'bg-sidebar', fg: 'text-sidebar-foreground' },
+  { name: 'answer-bubble', bg: 'bg-answer-bubble', fg: 'text-foreground' },
+] as const;
+
+const BRAND_TOKENS = [
+  { name: 'primary', bg: 'bg-primary', fg: 'text-primary-foreground' },
+  { name: 'secondary', bg: 'bg-secondary', fg: 'text-secondary-foreground' },
+  {
+    name: 'destructive',
+    bg: 'bg-destructive',
+    fg: 'text-destructive-foreground',
+  },
+  { name: 'success', bg: 'bg-success', fg: 'text-success-foreground' },
+  { name: 'warning', bg: 'bg-warning', fg: 'text-warning-foreground' },
+  { name: 'info', bg: 'bg-info', fg: 'text-info-foreground' },
+] as const;
+
+const LINE_TOKENS = [
+  { name: 'border', cls: 'border-border' },
+  { name: 'input', cls: 'border-input' },
+  { name: 'ring', cls: 'border-ring' },
+] as const;
+
+const CHART_TOKENS = [
+  'bg-chart-1',
+  'bg-chart-2',
+  'bg-chart-3',
+  'bg-chart-4',
+  'bg-chart-5',
+] as const;
+
+const BUTTON_VARIANTS = [
+  'default',
+  'secondary',
+  'outline',
+  'outline-primary',
+  'ghost',
+  'ghost-muted',
+  'ghost-destructive',
+  'link',
+  'destructive',
+  'destructive-outline',
+] as const;
+
+const BUTTON_SIZES = ['xs', 'sm', 'default', 'lg'] as const;
+const ICON_SIZES = ['icon-xs', 'icon-sm', 'icon', 'icon-lg'] as const;
+
+const BADGE_VARIANTS = [
+  'default',
+  'neutral',
+  'success',
+  'warning',
+  'destructive',
+  'info',
+  'outline',
+] as const;
+
+const AVATAR_SIZES = ['sm', 'default', 'lg', 'xl'] as const;
+
+const MULTI_OPTIONS = [
+  { value: 'pdf', label: 'PDF' },
+  { value: 'docx', label: 'Word' },
+  { value: 'md', label: 'Markdown' },
+  { value: 'html', label: 'HTML' },
+  { value: 'csv', label: 'CSV' },
+];
+
+const SOURCE_TYPES = [
+  ['Upload file', FileText],
+  ['Crawler', Globe],
+  ['Link', Link2],
+  ['GitHub', GitBranch],
+  ['Reddit', MessageSquare],
+  ['Google Drive', Cloud],
+  ['Amazon S3', Database],
+  ['New wiki', Book],
+] as const;
+
+const TABLE_ROWS = [
+  { name: 'Contracts & Policy Assistant', status: 'success', runs: 128 },
+  { name: 'Customer Renewal Desk', status: 'info', runs: 42 },
+  { name: 'Vendor Due Diligence', status: 'warning', runs: 9 },
+  { name: 'Legacy importer', status: 'destructive', runs: 0 },
+] as const;
+
+/** Reads a CSS custom property after the theme class has been applied. */
+function useCssVar(name: string, isDark: boolean): string {
+  const [value, setValue] = useState('');
+  useEffect(() => {
+    const frame = requestAnimationFrame(() => {
+      setValue(
+        getComputedStyle(document.documentElement)
+          .getPropertyValue(name)
+          .trim(),
+      );
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [name, isDark]);
+  return value;
+}
+
+function Section({
+  id,
+  title,
+  intro,
+  children,
+}: {
+  id: string;
+  title: string;
+  intro: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <section id={id} className="scroll-mt-24">
+      <h2 className="text-foreground text-xl font-semibold">{title}</h2>
+      <p className="text-muted-foreground mt-1 max-w-2xl text-sm">{intro}</p>
+      <div className="mt-6 flex flex-col gap-8">{children}</div>
+    </section>
+  );
+}
+
+function Example({
+  title,
+  code,
+  children,
+}: {
+  title: string;
+  code?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-wrap items-baseline justify-between gap-2">
+        <h3 className="text-foreground text-sm font-medium">{title}</h3>
+        {code ? (
+          <code className="text-muted-foreground font-mono text-xs">
+            {code}
+          </code>
+        ) : null}
+      </div>
+      <div className="border-border bg-card rounded-xl border p-6">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+function Swatch({
+  name,
+  bg,
+  fg,
+  isDark,
+}: {
+  name: string;
+  bg: string;
+  fg: string;
+  isDark: boolean;
+}) {
+  const value = useCssVar(`--${name}`, isDark);
+  return (
+    <div className="border-border flex flex-col overflow-hidden rounded-lg border">
+      <div className={`${bg} ${fg} flex h-16 items-end px-3 pb-2 text-xs`}>
+        Aa
+      </div>
+      <div className="bg-card px-3 py-2">
+        <div className="text-foreground text-xs font-medium">{name}</div>
+        <div className="text-muted-foreground font-mono text-xs">{value}</div>
+      </div>
+    </div>
+  );
+}
+
+export default function DesignSystem() {
+  const [isDark, toggleTheme] = useDarkTheme();
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const jumpTo = (id: string) => (event: React.MouseEvent) => {
+    event.preventDefault();
+    const container = scrollRef.current;
+    const target = document.getElementById(id);
+    if (!container || !target) return;
+    // Sections are offset from the scroll container; leave room for the
+    // sticky header.
+    container.scrollTo({ top: target.offsetTop - 88, behavior: 'smooth' });
+    window.history.replaceState(null, '', `#${id}`);
+  };
+  const [switchOn, setSwitchOn] = useState(true);
+  const [formats, setFormats] = useState<string[]>(['pdf', 'md']);
+  const [time, setTime] = useState('09:30');
+  const [date, setDate] = useState<Date | undefined>(new Date());
+  const [modalOpen, setModalOpen] = useState(false);
+  const [showArchived, setShowArchived] = useState(true);
+  const [dropped, setDropped] = useState<string[]>([]);
+  const [agentType, setAgentType] = useState<'classic' | 'workflow'>('classic');
+  const [toolOn, setToolOn] = useState(false);
+  const [sectionOpen, setSectionOpen] = useState(false);
+  const [sourceType, setSourceType] = useState<string>('Upload file');
+
+  return (
+    <div
+      ref={scrollRef}
+      className="bg-background text-foreground relative h-full overflow-y-auto"
+    >
+      <header className="border-border bg-background/95 sticky top-0 z-20 border-b backdrop-blur">
+        <div className="mx-auto flex max-w-6xl flex-wrap items-center gap-4 px-6 py-3">
+          <div className="mr-auto">
+            <h1 className="text-base font-semibold">DocsGPT design system</h1>
+            <p className="text-muted-foreground text-xs">
+              Defaults from frontend/DESIGN.md, rendered with the real
+              components. Dev route only.
+            </p>
+          </div>
+          <nav className="hidden flex-wrap gap-1 lg:flex">
+            {SECTIONS.map(([id, label]) => (
+              <Button key={id} asChild variant="ghost-muted" size="xs">
+                <a href={`#${id}`} onClick={jumpTo(id)}>
+                  {label}
+                </a>
+              </Button>
+            ))}
+          </nav>
+          <Button
+            variant="outline"
+            size="sm"
+            shape="pill"
+            onClick={toggleTheme}
+            aria-label="Toggle theme"
+          >
+            {isDark ? <Sun /> : <Moon />}
+            {isDark ? 'Light' : 'Dark'}
+          </Button>
+        </div>
+      </header>
+
+      <main className="mx-auto flex max-w-6xl flex-col gap-16 px-6 py-10">
+        <Section
+          id="tokens"
+          title="Colour tokens"
+          intro="Every colour in the UI resolves to one of these variables from src/index.css. The value shown is the one currently applied, so toggle the theme to compare."
+        >
+          <Example title="Surfaces" code="bg-card text-card-foreground">
+            <div className="grid grid-cols-2 gap-3 sm:grid-cols-4 lg:grid-cols-7">
+              {SURFACE_TOKENS.map((t) => (
+                <Swatch key={t.name} {...t} isDark={isDark} />
+              ))}
+            </div>
+          </Example>
+          <Example
+            title="Brand and status"
+            code="bg-success text-success-foreground"
+          >
+            <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-6">
+              {BRAND_TOKENS.map((t) => (
+                <Swatch key={t.name} {...t} isDark={isDark} />
+              ))}
+            </div>
+          </Example>
+          <Example title="Lines and charts" code="border-border · bg-chart-1">
+            <div className="flex flex-wrap items-center gap-6">
+              {LINE_TOKENS.map((t) => (
+                <div key={t.name} className="flex items-center gap-2">
+                  <div className={`${t.cls} size-10 rounded-md border-2`} />
+                  <span className="text-muted-foreground text-xs">
+                    {t.name}
+                  </span>
+                </div>
+              ))}
+              <div className="flex items-center gap-1">
+                {CHART_TOKENS.map((cls) => (
+                  <div key={cls} className={`${cls} h-10 w-6 rounded-sm`} />
+                ))}
+                <span className="text-muted-foreground ml-2 text-xs">
+                  chart-1 to chart-5: primary, info, success, warning,
+                  destructive
+                </span>
+              </div>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="typography"
+          title="Typography"
+          intro="Two text tones cover the app: foreground for content and muted-foreground for everything secondary. Lighter tiers use an opacity modifier, not a lighter grey."
+        >
+          <Example
+            title="Tones"
+            code="text-foreground · text-muted-foreground · text-muted-foreground/70"
+          >
+            <div className="flex flex-col gap-2 text-sm">
+              <p className="text-foreground">
+                Foreground: titles, body copy, values in tables.
+              </p>
+              <p className="text-muted-foreground">
+                Muted foreground: descriptions, labels, timestamps, icons.
+              </p>
+              <p className="text-muted-foreground/70">
+                Muted at 70%: placeholders and de-emphasised metadata.
+              </p>
+              <p className="text-primary">
+                Primary: links and the selected state.
+              </p>
+              <p className="text-destructive">Destructive: errors.</p>
+            </div>
+          </Example>
+          <Example
+            title="Scale"
+            code="text-xs · text-sm · text-base · text-lg · text-xl · font-mono"
+          >
+            <div className="flex flex-col gap-2">
+              <p className="text-xs">Extra small, 12px, badges and hints</p>
+              <p className="text-sm">Small, 14px, the default UI size</p>
+              <p className="text-base">
+                Base, 16px, inputs on mobile and prose
+              </p>
+              <p className="text-lg font-semibold">
+                Large, 18px, dialog titles
+              </p>
+              <p className="text-xl font-semibold">
+                Extra large, 20px, page titles
+              </p>
+              <p className="font-mono text-sm">Mono: ids, code, token values</p>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="buttons"
+          title="Buttons"
+          intro="Pick a variant for meaning, a size for density and a shape for the surface it sits on. className is for placement only."
+        >
+          <Example
+            title="Variants × sizes"
+            code='<Button variant="…" size="…">'
+          >
+            <div className="overflow-x-auto">
+              <div className="grid min-w-2xl grid-cols-[8rem_repeat(4,auto)] items-center gap-x-6 gap-y-3">
+                <span />
+                {BUTTON_SIZES.map((size) => (
+                  <span
+                    key={size}
+                    className="text-muted-foreground font-mono text-xs"
+                  >
+                    {size}
+                  </span>
+                ))}
+                {BUTTON_VARIANTS.map((variant) => (
+                  <div key={variant} className="contents">
+                    <span className="text-muted-foreground font-mono text-xs">
+                      {variant}
+                    </span>
+                    {BUTTON_SIZES.map((size) => (
+                      <div key={size}>
+                        <Button variant={variant} size={size}>
+                          <Plus />
+                          Add source
+                        </Button>
+                      </div>
+                    ))}
+                  </div>
+                ))}
+              </div>
+            </div>
+          </Example>
+          <Example
+            title="Shapes"
+            code='shape="pill" replaces rounded-3xl / rounded-full overrides'
+          >
+            <div className="flex flex-wrap items-center gap-3">
+              <Button shape="pill">Send</Button>
+              <Button shape="pill" size="lg">
+                Get started
+              </Button>
+              <Button shape="pill" variant="outline-primary">
+                Upgrade
+              </Button>
+              <Button shape="pill" variant="outline">
+                <Settings />
+                Configure
+              </Button>
+              <Button shape="pill" variant="secondary" size="sm">
+                Filter
+              </Button>
+              <Button shape="pill" variant="ghost-muted" size="xs">
+                Clear
+              </Button>
+              <Button shape="pill" variant="outline" size="sm">
+                <Mic />
+                Voice
+              </Button>
+            </div>
+          </Example>
+          <Example
+            title="Sidebar rows"
+            code='<Button variant="sidebar-item" aria-current={active ? "page" : undefined}>'
+          >
+            <div className="bg-sidebar flex w-64 flex-col gap-1 rounded-lg border py-2">
+              <Button variant="sidebar-item" className="mx-4 w-auto">
+                <Book className="text-muted-foreground size-5" />
+                Sources
+              </Button>
+              <Button
+                variant="sidebar-item"
+                aria-current="page"
+                className="mx-4 w-auto"
+              >
+                <Settings className="text-muted-foreground size-5" />
+                Settings
+              </Button>
+              <Button variant="sidebar-item" className="mx-4 w-auto">
+                <MessageSquare className="text-muted-foreground size-5" />
+                Help
+              </Button>
+            </div>
+          </Example>
+          <Example
+            title="Combobox trigger"
+            code='<Button variant="combobox" role="combobox" data-placeholder={value ? undefined : ""}>'
+          >
+            <div className="flex max-w-md flex-col gap-3">
+              <Button
+                variant="combobox"
+                role="combobox"
+                aria-expanded={false}
+                data-placeholder=""
+                className="w-full justify-between"
+              >
+                <span className="truncate">Select a timezone…</span>
+                <ChevronsUpDown className="size-4 shrink-0 opacity-50" />
+              </Button>
+              <Button
+                variant="combobox"
+                role="combobox"
+                aria-expanded={false}
+                className="w-full justify-between"
+              >
+                <span className="flex min-w-0 flex-1 items-center justify-between gap-3">
+                  <span className="truncate">Europe/Berlin</span>
+                  <span className="text-muted-foreground shrink-0 text-xs">
+                    UTC+02:00
+                  </span>
+                </span>
+                <ChevronsUpDown className="size-4 shrink-0 opacity-50" />
+              </Button>
+            </div>
+          </Example>
+          <Example
+            title="Form row (field height)"
+            code='<Input shape="pill"> · <SelectTrigger size="lg" shape="pill"> · <Button variant="combobox" size="field" shape="pill">'
+          >
+            <div className="flex max-w-md flex-col gap-3">
+              <Input shape="pill" placeholder="Agent name" />
+              <div className="flex gap-2">
+                <Select defaultValue="default">
+                  <SelectTrigger size="lg" shape="pill" className="flex-1">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="default">default</SelectItem>
+                    <SelectItem value="strict">strict</SelectItem>
+                  </SelectContent>
+                </Select>
+                <Button variant="outline-primary" size="field" shape="pill">
+                  Add
+                </Button>
+              </div>
+              <Button
+                variant="combobox"
+                size="field"
+                shape="pill"
+                data-placeholder=""
+                className="w-full justify-start text-left"
+              >
+                <span className="truncate">Select sources</span>
+              </Button>
+            </div>
+          </Example>
+          <Example
+            title="Link inside running text"
+            code='<Button variant="link" size="inline">'
+          >
+            <p className="text-foreground max-w-md text-base">
+              The quarterly review for Halvorsen Logistics is ready. Open{' '}
+              <Button variant="link" size="inline">
+                QBR report.html
+              </Button>{' '}
+              to see lane costs and the renewal summary.
+            </p>
+          </Example>
+          <Example
+            title="Underline tabs"
+            code='<Button variant="tab" data-active={active}>  ·  size="inline" for padding-free tabs'
+          >
+            <div className="flex flex-col gap-6">
+              <div className="border-border flex border-b">
+                <Button variant="tab" data-active>
+                  My Files
+                </Button>
+                <Button variant="tab">Shared with Me</Button>
+              </div>
+              <div className="border-border flex items-center gap-6 border-b">
+                <Button
+                  variant="tab"
+                  size="inline"
+                  data-active
+                  className="-mb-px"
+                >
+                  Overview
+                </Button>
+                <Button variant="tab" size="inline" className="-mb-px">
+                  Logs
+                </Button>
+                <Button variant="tab" size="inline" className="-mb-px">
+                  Schedules
+                </Button>
+              </div>
+            </div>
+          </Example>
+          <Example
+            title="Section panel toggle"
+            code='<div className="has-[[data-variant=section-toggle]:focus-visible]:ring-3 …"><Button variant="section-toggle" size="sm" aria-expanded>'
+          >
+            <div className="bg-muted max-w-md rounded-2xl p-4">
+              <div className="bg-card has-[[data-variant=section-toggle]:focus-visible]:ring-ring/50 rounded-2xl px-6 py-3 has-[[data-variant=section-toggle]:focus-visible]:ring-3 has-[[data-variant=section-toggle]:focus-visible]:ring-inset">
+                <div className="flex flex-wrap items-center gap-2">
+                  <Button
+                    variant="section-toggle"
+                    size="sm"
+                    aria-expanded={sectionOpen}
+                    onClick={() => setSectionOpen(!sectionOpen)}
+                    className="-ml-3 w-fit justify-start"
+                  >
+                    <ChevronRight
+                      aria-hidden="true"
+                      className={sectionOpen ? 'rotate-90' : undefined}
+                    />
+                    <span className="text-lg font-semibold">Guardrails</span>
+                  </Button>
+                  <Badge variant="success">3 active</Badge>
+                  <Badge variant="destructive">1 needs setup</Badge>
+                </div>
+                {sectionOpen && (
+                  <p className="text-muted-foreground mt-2 text-sm">
+                    Run the selected checks on this agent&apos;s runs.
+                  </p>
+                )}
+              </div>
+            </div>
+          </Example>
+          <Example
+            title="Pressed toggles"
+            code='variant={active ? "secondary" : "ghost-muted"}'
+          >
+            <div className="grid gap-4 md:grid-cols-3">
+              {(['card', 'background', 'muted'] as const).map((surface) => (
+                <div
+                  key={surface}
+                  className={
+                    surface === 'card'
+                      ? 'bg-card flex items-center gap-2 rounded-lg border p-4'
+                      : surface === 'background'
+                        ? 'bg-background flex items-center gap-2 rounded-lg border p-4'
+                        : 'bg-muted flex items-center gap-2 rounded-lg border p-4'
+                  }
+                >
+                  <Button
+                    variant="ghost-muted"
+                    size="icon-sm"
+                    shape="pill"
+                    aria-label="Copy"
+                  >
+                    <Copy />
+                  </Button>
+                  <Button
+                    variant="secondary"
+                    size="icon-sm"
+                    shape="pill"
+                    aria-label="Copied"
+                  >
+                    <Check />
+                  </Button>
+                  <Button variant="secondary" size="xs" shape="pill">
+                    <Check />
+                    Copied
+                  </Button>
+                  <span className="text-muted-foreground text-xs">
+                    on {surface}
+                  </span>
+                </div>
+              ))}
+            </div>
+          </Example>
+          <Example title="Icon buttons" code='size="icon-xs" … "icon-lg"'>
+            <div className="flex flex-wrap items-center gap-6">
+              {ICON_SIZES.map((size) => (
+                <div key={size} className="flex flex-col items-center gap-2">
+                  <div className="flex items-center gap-2">
+                    <Button size={size} variant="default" aria-label="Add">
+                      <Plus />
+                    </Button>
+                    <Button size={size} variant="outline" aria-label="Edit">
+                      <Pencil />
+                    </Button>
+                    <Button size={size} variant="ghost-muted" aria-label="More">
+                      <MoreHorizontal />
+                    </Button>
+                    <Button
+                      size={size}
+                      variant="ghost-destructive"
+                      shape="pill"
+                      aria-label="Delete"
+                    >
+                      <Trash2 />
+                    </Button>
+                  </div>
+                  <span className="text-muted-foreground font-mono text-xs">
+                    {size}
+                  </span>
+                </div>
+              ))}
+            </div>
+          </Example>
+          <Example title="States" code="disabled · asChild">
+            <div className="flex flex-wrap items-center gap-3">
+              <Button disabled>Saving…</Button>
+              <Button variant="outline" disabled>
+                Disabled outline
+              </Button>
+              <Button variant="destructive">
+                <Trash2 />
+                Delete
+              </Button>
+              <Button variant="destructive-outline" size="sm">
+                Remove
+              </Button>
+              <Button asChild variant="link">
+                <a href="#buttons">Rendered as a link</a>
+              </Button>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="badges"
+          title="Badges, toasts & notices"
+          intro="Status meaning comes from the four status tokens. Pills are Badge. Messages to the user are toasts in the bottom-right corner. Alert is only for an inline notice inside a form or modal, never for feedback on an action."
+        >
+          <Example title="Badge variants" code='<Badge variant="success">'>
+            <div className="flex flex-wrap items-center gap-2">
+              {BADGE_VARIANTS.map((variant) => (
+                <Badge key={variant} variant={variant}>
+                  {variant}
+                </Badge>
+              ))}
+              <Badge variant="success">
+                <Check />
+                With icon
+              </Badge>
+            </div>
+          </Example>
+          <Example
+            title="Toasts"
+            code="<ToastViewport> (one, in App.tsx) > <Toast><ToastHeader variant><ToastTitle wrap?> · <ToastItem icon? label meta><ToastStatus status/> · <ToastMessage variant size>"
+          >
+            <div className="bg-muted/40 flex flex-wrap items-start gap-4 rounded-xl p-6">
+              <Toast>
+                <ToastHeader variant="destructive">
+                  <ToastTitle>Upload failed</ToastTitle>
+                  <ToastActions>
+                    <Button
+                      size="icon-sm"
+                      variant="ghost-muted"
+                      aria-label="Collapse"
+                    >
+                      <ChevronDown />
+                    </Button>
+                    <Button
+                      size="icon-sm"
+                      variant="ghost-muted"
+                      aria-label="Dismiss"
+                    >
+                      <X />
+                    </Button>
+                  </ToastActions>
+                </ToastHeader>
+                <ToastContent>
+                  <ToastItem label="🦖1.png">
+                    <ToastStatus status="destructive" />
+                  </ToastItem>
+                  <ToastMessage variant="destructive">
+                    No text could be extracted from this file. It may be empty,
+                    image-only, or in an unsupported format.
+                  </ToastMessage>
+                </ToastContent>
+              </Toast>
+              <Toast>
+                <ToastHeader>
+                  <ToastTitle>Upload completed</ToastTitle>
+                  <ToastActions>
+                    <Button
+                      size="icon-sm"
+                      variant="ghost-muted"
+                      aria-label="Collapse"
+                    >
+                      <ChevronDown />
+                    </Button>
+                    <Button
+                      size="icon-sm"
+                      variant="ghost-muted"
+                      aria-label="Dismiss"
+                    >
+                      <X />
+                    </Button>
+                  </ToastActions>
+                </ToastHeader>
+                <ToastContent scrollable>
+                  <ToastItem label="Audit.md" meta="1.8k tokens">
+                    <ToastStatus status="success" />
+                  </ToastItem>
+                  <ToastItem label="Tender checklist.docx" meta="Indexing…">
+                    <ToastStatus status="pending" />
+                  </ToastItem>
+                </ToastContent>
+              </Toast>
+              <Toast>
+                <ToastHeader variant="warning">
+                  <ToastTitle>Tool approval needed</ToastTitle>
+                  <ToastActions>
+                    <Button
+                      size="icon-sm"
+                      variant="ghost-muted"
+                      aria-label="Dismiss"
+                    >
+                      <X />
+                    </Button>
+                  </ToastActions>
+                </ToastHeader>
+                <ToastContent>
+                  <ToastItem
+                    icon={<ToastStatus status="warning" />}
+                    label="Vendor Due Diligence"
+                    meta="wants to run web_search"
+                  />
+                  <ToastFooter>
+                    <Button size="sm" variant="outline">
+                      Deny
+                    </Button>
+                    <Button size="sm">Approve</Button>
+                  </ToastFooter>
+                </ToastContent>
+              </Toast>
+              <Toast>
+                <ToastHeader>
+                  <ToastTitle wrap>
+                    Zu einem Team hinzugefügt: Meridian Freight Operations
+                  </ToastTitle>
+                  <ToastActions>
+                    <Button
+                      size="icon-sm"
+                      variant="ghost-muted"
+                      aria-label="Dismiss"
+                    >
+                      <X />
+                    </Button>
+                  </ToastActions>
+                </ToastHeader>
+                <ToastContent>
+                  <ToastMessage size="sm">
+                    You were added to Meridian Freight Operations as member
+                  </ToastMessage>
+                </ToastContent>
+              </Toast>
+            </div>
+          </Example>
+          <Example
+            title="Inline notices (forms and modals only)"
+            code='<Alert variant="default | success | warning | info | destructive">'
+          >
+            <div className="flex flex-col gap-3">
+              <Alert>
+                <Mail />
+                <AlertTitle>Index rebuilt</AlertTitle>
+                <AlertDescription>
+                  All 1,204 chunks were re-embedded with the new model.
+                </AlertDescription>
+              </Alert>
+              <Alert variant="success">
+                <Check />
+                <AlertTitle>Connector synced</AlertTitle>
+                <AlertDescription>
+                  SharePoint finished 12 minutes ago with no changes.
+                </AlertDescription>
+              </Alert>
+              <Alert variant="warning">
+                <Clock />
+                <AlertTitle>Token expires in 3 days</AlertTitle>
+                <AlertDescription>
+                  Reconnect before Friday to keep the nightly sync running.
+                </AlertDescription>
+              </Alert>
+              <Alert variant="info">
+                <Search />
+                <AlertTitle>Indexing in progress</AlertTitle>
+                <AlertDescription>
+                  Answers may miss the newest documents until it finishes.
+                </AlertDescription>
+              </Alert>
+              <Alert variant="destructive">
+                <Trash2 />
+                <AlertTitle>Connector unreachable</AlertTitle>
+                <AlertDescription>
+                  The SharePoint token expired. Reconnect to resume syncing.
+                </AlertDescription>
+              </Alert>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="cards"
+          title="Cards"
+          intro="One card, three surfaces. outline is the bordered default; filled is for tiles on a card-coloured page; subtle is a bordered box on a muted page. Interactive cards are the whole target."
+        >
+          <Example
+            title="Entity cards"
+            code='<Card variant="outline | filled"> + CardHeader / CardTitle / CardAction / CardFooter'
+          >
+            <div className="grid gap-4 md:grid-cols-3">
+              <Card variant="filled">
+                <CardHeader>
+                  <CardTitle>
+                    Doc 1 - Tender Guidance and Checklist.docx
+                  </CardTitle>
+                  <CardAction>
+                    <Button
+                      size="icon-xs"
+                      variant="ghost-muted"
+                      aria-label="More"
+                    >
+                      <MoreHorizontal />
+                    </Button>
+                  </CardAction>
+                </CardHeader>
+                <CardFooter className="flex-col items-start gap-1">
+                  <span className="flex items-center gap-1">
+                    <CalendarIcon className="size-3" /> 11/08/2026, 16:44
+                  </span>
+                  <span className="flex items-center gap-1">
+                    <Database className="size-3" /> 1.8k tokens
+                  </span>
+                </CardFooter>
+              </Card>
+              <Card variant="filled">
+                <CardHeader>
+                  <div className="flex flex-col gap-1">
+                    <CardTitle>Arc53</CardTitle>
+                    <Badge variant="neutral">GraphRAG</Badge>
+                  </div>
+                  <CardAction>
+                    <Button
+                      size="icon-xs"
+                      variant="ghost-muted"
+                      aria-label="More"
+                    >
+                      <MoreHorizontal />
+                    </Button>
+                  </CardAction>
+                </CardHeader>
+                <CardFooter className="flex-col items-start gap-1">
+                  <span className="flex items-center gap-1">
+                    <CalendarIcon className="size-3" /> 29/06/2026, 05:22
+                  </span>
+                  <span className="flex items-center gap-1">
+                    <Database className="size-3" /> 20.19k tokens
+                  </span>
+                </CardFooter>
+              </Card>
+              <Card variant="filled">
+                <CardHeader>
+                  <span className="bg-muted-foreground/15 text-foreground flex size-8 items-center justify-center rounded-md">
+                    <FileText className="size-4" />
+                  </span>
+                  <CardAction>
+                    <Button
+                      size="icon-xs"
+                      variant="ghost-muted"
+                      aria-label="More"
+                    >
+                      <MoreHorizontal />
+                    </Button>
+                  </CardAction>
+                </CardHeader>
+                <CardContent className="flex flex-col gap-1">
+                  <CardTitle>Notepad</CardTitle>
+                  <CardDescription>
+                    Single note. Supports viewing, overwriting, string
+                    replacement.
+                  </CardDescription>
+                </CardContent>
+                <CardFooter className="justify-end">
+                  <Switch
+                    checked={toolOn}
+                    onCheckedChange={setToolOn}
+                    aria-label="Enable tool"
+                  />
+                </CardFooter>
+              </Card>
+            </div>
+          </Example>
+          <Example
+            title="Bordered surfaces"
+            code='<Card> (outline) · <Card interactive asChild><Link/></Card> · <Card padding="sm">'
+          >
+            <div className="grid gap-4 md:grid-cols-2">
+              <Card interactive asChild>
+                <a href="#cards">
+                  <CardHeader>
+                    <div className="flex items-center gap-3">
+                      <Avatar size="lg" shape="square" variant="muted">
+                        A
+                      </Avatar>
+                      <CardTitle>Arc</CardTitle>
+                    </div>
+                    <CardAction className="flex items-center gap-2">
+                      <Badge variant="neutral">admin</Badge>
+                      <span className="text-muted-foreground">›</span>
+                    </CardAction>
+                  </CardHeader>
+                  <CardDescription className="italic">
+                    No description
+                  </CardDescription>
+                  <CardFooter>
+                    <Users className="size-3" /> 3 members · 3 shared
+                  </CardFooter>
+                </a>
+              </Card>
+              <Card>
+                <CardHeader>
+                  <div className="flex items-start gap-3">
+                    <Avatar size="xl" shape="circle" imgClassName="size-full" />
+                    <div className="flex flex-col gap-1">
+                      <CardTitle>DocsGPT New Contact Responder</CardTitle>
+                      <CardDescription className="line-clamp-2">
+                        This agent processes notifications about new contact
+                        form submissions, extracts the name and email address,
+                        then drafts a personalised welcome.
+                      </CardDescription>
+                    </div>
+                  </div>
+                  <CardAction>
+                    <Button size="sm" variant="outline" shape="pill">
+                      <Pencil />
+                      Edit
+                    </Button>
+                  </CardAction>
+                </CardHeader>
+              </Card>
+              <div className="grid grid-cols-2 items-start gap-3">
+                <Card padding="sm" className="gap-1">
+                  <CardDescription>Run success</CardDescription>
+                  <span className="text-xl font-semibold">—</span>
+                </Card>
+                <Card padding="sm" className="gap-1">
+                  <CardDescription>Feedback</CardDescription>
+                  <span className="text-xl font-semibold">+0 / -0</span>
+                </Card>
+              </div>
+              <Card padding="sm">
+                <CardHeader className="items-center">
+                  <CardTitle>Token usage</CardTitle>
+                  <CardAction className="flex items-center gap-2">
+                    <span className="text-muted-foreground text-xs">
+                      Background tokens
+                    </span>
+                    <Switch aria-label="Background tokens" />
+                  </CardAction>
+                </CardHeader>
+                <CardContent>
+                  <div className="bg-muted/40 flex h-24 items-end justify-around rounded-lg px-4 pb-2">
+                    <span className="bg-chart-1 h-6 w-3 rounded-sm" />
+                    <span className="bg-chart-1 h-16 w-3 rounded-sm" />
+                    <span className="bg-chart-2 h-10 w-3 rounded-sm" />
+                    <span className="bg-chart-1 h-3 w-3 rounded-sm" />
+                  </div>
+                </CardContent>
+              </Card>
+            </div>
+          </Example>
+          <Example
+            title="Picker tiles"
+            code="<OptionCard icon title description? selected onClick>"
+          >
+            <div className="flex flex-col gap-6">
+              <div className="grid gap-3 sm:grid-cols-2" role="radiogroup">
+                <OptionCard
+                  icon={<Bot />}
+                  title="Classic Agent"
+                  description="A standard AI agent with a single model, tools and knowledge sources."
+                  selected={agentType === 'classic'}
+                  onClick={() => setAgentType('classic')}
+                />
+                <OptionCard
+                  icon={<Workflow />}
+                  title="Workflow Agent"
+                  description="Multi-step workflows with different models, conditions and state."
+                  selected={agentType === 'workflow'}
+                  onClick={() => setAgentType('workflow')}
+                />
+              </div>
+              <div
+                className="grid gap-3 sm:grid-cols-2 md:grid-cols-3"
+                role="radiogroup"
+              >
+                {SOURCE_TYPES.map(([label, Icon]) => (
+                  <OptionCard
+                    key={label}
+                    icon={<Icon />}
+                    title={label}
+                    selected={sourceType === label}
+                    onClick={() => setSourceType(label)}
+                  />
+                ))}
+              </div>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="forms"
+          title="Forms"
+          intro="Inputs and selects share the 42px default height, the sm and lg densities and the pill shape. Labels float inside the field when passed as a prop."
+        >
+          <Example
+            title="Input sizes"
+            code='<Input size="sm" | "default" | "lg">'
+          >
+            <div className="grid gap-4 md:grid-cols-3">
+              <div className="flex flex-col gap-2">
+                <Label htmlFor="in-sm">Small</Label>
+                <Input id="in-sm" size="sm" placeholder="Filter rows…" />
+              </div>
+              <div className="flex flex-col gap-2">
+                <Label htmlFor="in-md">Default</Label>
+                <Input id="in-md" placeholder="Agent name" />
+              </div>
+              <div className="flex flex-col gap-2">
+                <Label htmlFor="in-lg">Large</Label>
+                <Input id="in-lg" size="lg" placeholder="Ask anything…" />
+              </div>
+            </div>
+          </Example>
+          <Example
+            title="Input shapes and states"
+            code='shape="pill" · label · leftIcon · aria-invalid · disabled'
+          >
+            <div className="grid gap-6 md:grid-cols-2">
+              <Input size="lg" shape="pill" placeholder="Search the docs" />
+              <Input
+                shape="pill"
+                leftIcon={<Search className="text-muted-foreground size-4" />}
+                label="With icon"
+              />
+              <Input
+                leftIcon={<Search className="text-muted-foreground size-4" />}
+                placeholder="Search files (icon, no label)"
+              />
+              <Input label="Floating label" defaultValue="Renewal desk" />
+              <Input label="Required" required />
+              <Input label="Invalid" aria-invalid defaultValue="not-an-email" />
+              <Input label="Disabled" disabled defaultValue="Read only" />
+            </div>
+          </Example>
+          <Example
+            title="Floating label on other surfaces"
+            code='<Input label="…" labelSurface="card" | "background" | "muted">'
+          >
+            <div className="grid gap-4 md:grid-cols-3">
+              {(['card', 'background', 'muted'] as const).map((surface) => (
+                <div
+                  key={surface}
+                  className={
+                    surface === 'card'
+                      ? 'bg-card rounded-lg border p-4'
+                      : surface === 'background'
+                        ? 'bg-background rounded-lg border p-4'
+                        : 'bg-muted rounded-lg border p-4'
+                  }
+                >
+                  <Input
+                    label={`On ${surface}`}
+                    labelSurface={surface}
+                    defaultValue="Renewal desk"
+                  />
+                </div>
+              ))}
+            </div>
+          </Example>
+          <Example
+            title="Bare field inside a host"
+            code='<Input variant="bare">'
+          >
+            <div className="bg-sidebar w-64 rounded-lg border py-2">
+              <div className="bg-sidebar-accent mx-2 flex h-9 items-center gap-1 rounded-3xl pr-1 pl-3">
+                <Input
+                  variant="bare"
+                  aria-label="Conversation name"
+                  defaultValue="Q3 carrier renewals"
+                  className="flex-1"
+                />
+                <Button variant="ghost-muted" size="icon-xs" aria-label="Save">
+                  <Check />
+                </Button>
+                <Button
+                  variant="ghost-muted"
+                  size="icon-xs"
+                  aria-label="Cancel"
+                >
+                  <X />
+                </Button>
+              </div>
+            </div>
+          </Example>
+          <Example
+            title="Field on a muted panel"
+            code='<Input variant="filled"> · <Textarea variant="filled">'
+          >
+            <div className="bg-muted flex max-w-sm flex-col gap-2 rounded-lg p-4">
+              <Input
+                variant="filled"
+                aria-label="Base URL"
+                defaultValue="https://api.meridianfreight.example/v2"
+              />
+              <Textarea
+                variant="filled"
+                size="sm"
+                rows={3}
+                aria-label="Banned terms"
+                defaultValue={'competitor name\ninternal codename'}
+              />
+            </div>
+          </Example>
+          <Example
+            title="Select"
+            code='<SelectTrigger size="…" variant="…" shape="…">'
+          >
+            <div className="flex flex-wrap items-center gap-4">
+              <Select defaultValue="finance">
+                <SelectTrigger size="sm">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="finance">Small</SelectItem>
+                  <SelectItem value="legal">Legal</SelectItem>
+                </SelectContent>
+              </Select>
+              <Select defaultValue="finance">
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="finance">Default</SelectItem>
+                  <SelectItem value="legal">Legal</SelectItem>
+                </SelectContent>
+              </Select>
+              <Select defaultValue="finance">
+                <SelectTrigger size="lg">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="finance">Large</SelectItem>
+                  <SelectItem value="legal">Legal</SelectItem>
+                </SelectContent>
+              </Select>
+              <Select defaultValue="finance">
+                <SelectTrigger size="lg" shape="pill">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="finance">Large pill</SelectItem>
+                  <SelectItem value="legal">Legal</SelectItem>
+                </SelectContent>
+              </Select>
+              <Select defaultValue="finance">
+                <SelectTrigger variant="ghost">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="finance">Ghost</SelectItem>
+                  <SelectItem value="legal">Legal</SelectItem>
+                </SelectContent>
+              </Select>
+              <Select>
+                <SelectTrigger>
+                  <SelectValue placeholder="Placeholder" />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="a">Option A</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+          </Example>
+          <Example
+            title="Textarea"
+            code='<Textarea size="sm | default | lg" resize="none | vertical | both" variant="default | filled">'
+          >
+            <div className="grid items-start gap-4 md:grid-cols-3">
+              <Textarea size="sm" placeholder="Short note…" />
+              <Textarea placeholder="Describe what this agent does…" />
+              <Textarea
+                size="lg"
+                resize="none"
+                placeholder="System prompt…"
+                defaultValue="You are a helpful assistant for Meridian Freight Group."
+              />
+            </div>
+          </Example>
+          <Example
+            title="Switch and multi-select"
+            code="<Switch> · <MultiSelect>"
+          >
+            <div className="grid items-start gap-6 md:grid-cols-2">
+              <div className="flex flex-col gap-4">
+                <div className="flex items-center gap-3">
+                  <Switch
+                    id="sw-1"
+                    checked={switchOn}
+                    onCheckedChange={setSwitchOn}
+                  />
+                  <Label htmlFor="sw-1">
+                    Notify on failed runs{' '}
+                    <span className="text-muted-foreground">
+                      ({switchOn ? 'on' : 'off'})
+                    </span>
+                  </Label>
+                </div>
+                <div className="flex items-center gap-3">
+                  <Switch id="sw-2" disabled />
+                  <Label htmlFor="sw-2">Disabled</Label>
+                </div>
+              </div>
+              <MultiSelect
+                options={MULTI_OPTIONS}
+                selected={formats}
+                onChange={setFormats}
+                placeholder="Allowed formats"
+              />
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="dropzone"
+          title="Dropzone"
+          intro="Click-or-drag file target used by imports and uploads. Colours follow the drag state; pass accept and limits and describe them in the second line."
+        >
+          <Example
+            title="Default and compact"
+            code='<Dropzone accept={…} description="…" size="compact">'
+          >
+            <div className="grid gap-6 md:grid-cols-2">
+              <Dropzone
+                onDrop={(files) => setDropped(files.map((f) => f.name))}
+                accept={{ 'application/x-yaml': ['.yaml', '.yml'] }}
+                title="Click to upload or drag and drop a .yaml file"
+                description="Agent definitions exported from DocsGPT"
+              />
+              <div className="flex flex-col gap-4">
+                <Dropzone
+                  size="compact"
+                  multiple
+                  onDrop={(files) => setDropped(files.map((f) => f.name))}
+                  title="Attach files"
+                  description="PDF, Word, Markdown, up to 25 MB each"
+                  icon={<FileText />}
+                />
+                <Dropzone
+                  size="compact"
+                  disabled
+                  onDrop={() => undefined}
+                  title="Uploads paused"
+                  description="Indexing in progress"
+                />
+                <Dropzone
+                  size="compact"
+                  onDrop={() => undefined}
+                  title="With an error"
+                  error="Only .yaml or .yml files are supported"
+                />
+                <p className="text-muted-foreground text-xs">
+                  Last drop:{' '}
+                  {dropped.length ? dropped.join(', ') : 'nothing yet'}
+                </p>
+              </div>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="feedback"
+          title="Feedback & loading"
+          intro="Tooltip replaces title attributes; Spinner and Skeleton replace the hand-drawn loaders; Progress replaces width-percent divs."
+        >
+          <Example
+            title="Tooltip"
+            code="<Tooltip><TooltipTrigger asChild>…<TooltipContent>"
+          >
+            <div className="flex flex-wrap items-center gap-3">
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button size="icon" variant="ghost-muted" aria-label="Delete">
+                    <Trash2 />
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent>Delete source</TooltipContent>
+              </Tooltip>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button size="icon" variant="ghost-muted" aria-label="Copy">
+                    <Copy />
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent side="bottom">
+                  Copy conversation link
+                </TooltipContent>
+              </Tooltip>
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Badge variant="neutral">GraphRAG</Badge>
+                </TooltipTrigger>
+                <TooltipContent>
+                  Indexed as a knowledge graph; answers can follow relations
+                  between entities.
+                </TooltipContent>
+              </Tooltip>
+              <span className="text-muted-foreground text-xs">
+                hover or focus the controls
+              </span>
+            </div>
+          </Example>
+          <Example
+            title="Spinner and skeleton"
+            code='<Spinner size="sm | default | lg"> · <Skeleton className="h-4 w-40">'
+          >
+            <div className="grid items-start gap-8 md:grid-cols-2">
+              <div className="flex items-center gap-6">
+                <Spinner size="sm" />
+                <Spinner />
+                <Spinner size="lg" />
+                <span className="text-primary flex items-center gap-2 text-sm">
+                  <Spinner size="sm" /> inherits text colour
+                </span>
+              </div>
+              <div className="flex items-center gap-4">
+                <Skeleton className="size-10 rounded-full" />
+                <div className="flex flex-1 flex-col gap-2">
+                  <Skeleton className="h-4 w-3/5" />
+                  <Skeleton className="h-3 w-4/5" />
+                  <Skeleton className="h-3 w-2/5" />
+                </div>
+              </div>
+            </div>
+          </Example>
+          <Example
+            title="Progress"
+            code='<Progress value={62} variant="success" size="sm">'
+          >
+            <div className="grid gap-5 md:grid-cols-2">
+              <div className="flex flex-col gap-2">
+                <div className="text-muted-foreground flex justify-between text-xs">
+                  <span>Indexing 1,204 chunks</span>
+                  <span>62%</span>
+                </div>
+                <Progress value={62} />
+              </div>
+              <div className="flex flex-col gap-2">
+                <div className="text-muted-foreground flex justify-between text-xs">
+                  <span>Monthly quota</span>
+                  <span>91%</span>
+                </div>
+                <Progress value={91} variant="warning" />
+              </div>
+              <div className="flex flex-col gap-2">
+                <div className="text-muted-foreground flex justify-between text-xs">
+                  <span>Run success</span>
+                  <span>100%</span>
+                </div>
+                <Progress value={100} variant="success" size="sm" />
+              </div>
+              <div className="flex flex-col gap-2">
+                <div className="text-muted-foreground flex justify-between text-xs">
+                  <span>Guardrail blocks</span>
+                  <span>18%</span>
+                </div>
+                <Progress value={18} variant="destructive" size="lg" />
+              </div>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="avatars"
+          title="Avatars"
+          intro="Image avatars keep their own size. Initials boxes take size, shape and a tone."
+        >
+          <Example
+            title="Sizes, shapes, tones"
+            code='<Avatar size="lg" shape="circle" variant="primary">LK</Avatar>'
+          >
+            <div className="flex flex-wrap items-end gap-8">
+              <div className="flex items-end gap-3">
+                {AVATAR_SIZES.map((size) => (
+                  <Avatar
+                    key={size}
+                    size={size}
+                    shape="circle"
+                    variant="primary"
+                  >
+                    LK
+                  </Avatar>
+                ))}
+              </div>
+              <div className="flex items-end gap-3">
+                {AVATAR_SIZES.map((size) => (
+                  <Avatar key={size} size={size} shape="square" variant="muted">
+                    MF
+                  </Avatar>
+                ))}
+              </div>
+              <div className="flex items-end gap-3">
+                <Avatar size="xl" shape="circle" imgClassName="size-full" />
+                <Avatar size="lg" shape="square" imgClassName="size-full" />
+                <span className="text-muted-foreground self-center text-xs">
+                  image, robot fallback
+                </span>
+              </div>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="navigation"
+          title="Navigation"
+          intro="Tabs, accordions and breadcrumbs as shipped."
+        >
+          <Example title="Tabs" code="<Tabs>">
+            <Tabs defaultValue="sources">
+              <TabsList>
+                <TabsTrigger value="sources">Sources</TabsTrigger>
+                <TabsTrigger value="tools">Tools</TabsTrigger>
+                <TabsTrigger value="guardrails">Guardrails</TabsTrigger>
+              </TabsList>
+              <TabsContent value="sources">
+                <p className="text-muted-foreground pt-4 text-sm">
+                  Connected sources and their indexing status.
+                </p>
+              </TabsContent>
+              <TabsContent value="tools">
+                <p className="text-muted-foreground pt-4 text-sm">
+                  Tools the agent may call.
+                </p>
+              </TabsContent>
+              <TabsContent value="guardrails">
+                <p className="text-muted-foreground pt-4 text-sm">
+                  Controls applied before and after each turn.
+                </p>
+              </TabsContent>
+            </Tabs>
+          </Example>
+          <Example
+            title="Accordion and breadcrumb"
+            code="<Accordion> · <Breadcrumb>"
+          >
+            <div className="grid gap-8 md:grid-cols-2">
+              <Accordion type="single" collapsible defaultValue="a">
+                <AccordionItem value="a">
+                  <AccordionTrigger>
+                    What does re-embedding do?
+                  </AccordionTrigger>
+                  <AccordionContent>
+                    Recomputes vectors for every chunk with the current model.
+                  </AccordionContent>
+                </AccordionItem>
+                <AccordionItem value="b">
+                  <AccordionTrigger>Can I pause a schedule?</AccordionTrigger>
+                  <AccordionContent>
+                    Yes, paused schedules keep their history.
+                  </AccordionContent>
+                </AccordionItem>
+              </Accordion>
+              <Breadcrumb>
+                <BreadcrumbList>
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#navigation">Agents</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#navigation">
+                      Renewal desk
+                    </BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbPage>Schedules</BreadcrumbPage>
+                  </BreadcrumbItem>
+                </BreadcrumbList>
+              </Breadcrumb>
+              <Breadcrumb>
+                <BreadcrumbList>
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#navigation">Agents</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbPage
+                      title="Quarterly renewal desk for key logistics accounts"
+                      className="max-w-[16ch]"
+                    >
+                      Quarterly renewal desk for key logistics accounts
+                    </BreadcrumbPage>
+                  </BreadcrumbItem>
+                </BreadcrumbList>
+              </Breadcrumb>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="tables"
+          title="Tables"
+          intro="Cells accept alignment and typography classes plus text-muted-foreground; everything else is layout."
+        >
+          <Example
+            title="Table with status badges"
+            code='<TableCell align="right" className="tabular-nums">'
+          >
+            <TableContainer>
+              <Table>
+                <TableHead>
+                  <TableRow>
+                    <TableHeader>Agent</TableHeader>
+                    <TableHeader>Status</TableHeader>
+                    <TableHeader align="right">Runs</TableHeader>
+                    <TableHeader align="right">Actions</TableHeader>
+                  </TableRow>
+                </TableHead>
+                <TableBody>
+                  {TABLE_ROWS.map((row) => (
+                    <TableRow key={row.name}>
+                      <TableCell className="font-medium">{row.name}</TableCell>
+                      <TableCell>
+                        <Badge variant={row.status}>{row.status}</Badge>
+                      </TableCell>
+                      <TableCell align="right" className="tabular-nums">
+                        {row.runs}
+                      </TableCell>
+                      <TableCell align="right">
+                        <Button
+                          size="icon-sm"
+                          variant="ghost-muted"
+                          aria-label="Copy"
+                        >
+                          <Copy />
+                        </Button>
+                        <Button
+                          size="icon-sm"
+                          variant="ghost-muted"
+                          aria-label="Edit"
+                        >
+                          <Pencil />
+                        </Button>
+                      </TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            </TableContainer>
+          </Example>
+        </Section>
+
+        <Section
+          id="overlays"
+          title="Overlays"
+          intro="Modal is the only dialog API for app code; the Radix Dialog underneath is private to ui/. Sheet is for side panels. Popovers and menus share the popover surface."
+        >
+          <Example
+            title="Modal and sheet"
+            code='<Modal size="md"> · <SheetContent side="right">'
+          >
+            <div className="flex flex-wrap items-center gap-3">
+              <Button variant="outline" onClick={() => setModalOpen(true)}>
+                Open modal
+              </Button>
+              <Modal
+                open={modalOpen}
+                onOpenChange={setModalOpen}
+                title="Move to folder"
+                description="Pick where this agent should live."
+                footer={
+                  <>
+                    <Button
+                      variant="outline"
+                      onClick={() => setModalOpen(false)}
+                    >
+                      Cancel
+                    </Button>
+                    <Button onClick={() => setModalOpen(false)}>Move</Button>
+                  </>
+                }
+              >
+                <div className="flex flex-col gap-4">
+                  <Input label="Folder name" defaultValue="Finance" />
+                  <Select defaultValue="team">
+                    <SelectTrigger className="w-full">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value="team">Shared with team</SelectItem>
+                      <SelectItem value="me">Only me</SelectItem>
+                    </SelectContent>
+                  </Select>
+                </div>
+              </Modal>
+              <Sheet>
+                <SheetTrigger asChild>
+                  <Button variant="outline">Open sheet</Button>
+                </SheetTrigger>
+                <SheetContent side="right">
+                  <SheetHeader>
+                    <SheetTitle>Run details</SheetTitle>
+                    <SheetDescription>
+                      Started 09:30, finished 09:31, 3 tools called.
+                    </SheetDescription>
+                  </SheetHeader>
+                </SheetContent>
+              </Sheet>
+            </div>
+          </Example>
+          <Example
+            title="Popover and dropdown menu"
+            code="<Popover> · <DropdownMenu>"
+          >
+            <div className="flex flex-wrap items-center gap-3">
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button variant="outline">Open popover</Button>
+                </PopoverTrigger>
+                <PopoverContent>
+                  <div className="flex flex-col gap-2">
+                    <p className="text-sm font-medium">Retrieval settings</p>
+                    <p className="text-muted-foreground text-sm">
+                      Chunks per query and the reranker threshold.
+                    </p>
+                    <Input size="sm" defaultValue="8" label="Chunks" />
+                  </div>
+                </PopoverContent>
+              </Popover>
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <Button variant="outline">
+                    Actions
+                    <MoreHorizontal />
+                  </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="start">
+                  <DropdownMenuLabel>Conversation</DropdownMenuLabel>
+                  <DropdownMenuItem>
+                    <Pencil />
+                    Rename
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <Copy />
+                    Duplicate
+                  </DropdownMenuItem>
+                  <DropdownMenuCheckboxItem
+                    checked={showArchived}
+                    onCheckedChange={(v) => setShowArchived(Boolean(v))}
+                  >
+                    Show archived
+                  </DropdownMenuCheckboxItem>
+                  <DropdownMenuSeparator />
+                  <DropdownMenuItem variant="destructive">
+                    <Trash2 />
+                    Delete
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </div>
+          </Example>
+          <Example
+            title="Command palette"
+            code='<Command variant="palette">, the spacing CommandDialog uses'
+          >
+            <div className="border-border max-w-md overflow-hidden rounded-lg border">
+              <Command variant="palette">
+                <CommandInput placeholder="Search agents, sources, settings…" />
+                <CommandList>
+                  <CommandEmpty>No results.</CommandEmpty>
+                  <CommandGroup heading="Agents">
+                    <CommandItem>
+                      <Settings />
+                      Contracts & Policy Assistant
+                      <CommandShortcut>⌘1</CommandShortcut>
+                    </CommandItem>
+                    <CommandItem>
+                      <Settings />
+                      Customer Renewal Desk
+                      <CommandShortcut>⌘2</CommandShortcut>
+                    </CommandItem>
+                  </CommandGroup>
+                  <CommandGroup heading="Actions">
+                    <CommandItem>
+                      <Plus />
+                      New conversation
+                    </CommandItem>
+                  </CommandGroup>
+                </CommandList>
+              </Command>
+            </div>
+          </Example>
+          <Example
+            title="Chosen item in a picker"
+            code="<CommandItem checked={item.id === selectedId}>"
+          >
+            <div className="border-border max-w-xs overflow-hidden rounded-lg border">
+              <Command>
+                <CommandList>
+                  <CommandItem value="default">default</CommandItem>
+                  <CommandItem value="creative" checked>
+                    creative
+                  </CommandItem>
+                  <CommandItem value="strict">strict</CommandItem>
+                </CommandList>
+              </Command>
+            </div>
+          </Example>
+        </Section>
+
+        <Section
+          id="pickers"
+          title="Pickers"
+          intro="Calendar wraps react-day-picker with the Button ghost variant; TimePicker is two Selects."
+        >
+          <Example
+            title="Calendar and time"
+            code='<Calendar mode="single"> · <TimePicker>'
+          >
+            <div className="flex flex-wrap items-start gap-8">
+              <div className="border-border rounded-lg border">
+                <Calendar mode="single" selected={date} onSelect={setDate} />
+              </div>
+              <div className="flex flex-col gap-3">
+                <Label>Run at</Label>
+                <TimePicker value={time} onChange={setTime} minuteStep={5} />
+                <p className="text-muted-foreground flex items-center gap-1 text-xs">
+                  <Clock className="size-3" />
+                  {date ? date.toLocaleDateString() : 'No date'} at {time}
+                </p>
+              </div>
+            </div>
+          </Example>
+        </Section>
+      </main>
+    </div>
+  );
+}
diff --git a/frontend/src/index.css b/frontend/src/index.css
index a9e6438d..c664c481 100644
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -130,6 +130,34 @@
   }
 }
 
+/* Ring spinner used by ui/spinner. Colour comes from currentColor. */
+@utility spinner-ring {
+  --spinner-thickness: 4px;
+  aspect-ratio: 1;
+  border-radius: 50%;
+  background:
+    radial-gradient(farthest-side, currentColor 94%, transparent) top /
+      var(--spinner-thickness) var(--spinner-thickness) no-repeat,
+    conic-gradient(transparent 30%, currentColor);
+  -webkit-mask: radial-gradient(
+    farthest-side,
+    transparent calc(100% - var(--spinner-thickness)),
+    #000 0
+  );
+  mask: radial-gradient(
+    farthest-side,
+    transparent calc(100% - var(--spinner-thickness)),
+    #000 0
+  );
+  animation: spinner-rotate 1s infinite linear;
+  &[data-size='sm'] {
+    --spinner-thickness: 3px;
+  }
+  &[data-size='lg'] {
+    --spinner-thickness: 5px;
+  }
+}
+
 @utility table-default {
   @apply border-border text-foreground block w-full table-auto justify-center overflow-auto rounded-xl border text-center;
 
@@ -179,6 +207,41 @@
   }
 }
 
+/* The promo banner in components/Notification.tsx. Its purples are a one-off
+   decorative gradient rather than UI chrome, so they stay literal here
+   instead of becoming theme tokens. */
+@utility notification-banner {
+  background:
+    linear-gradient(90deg, #390086 0%, #6222b7 100%),
+    linear-gradient(
+      90deg,
+      rgba(57, 0, 134, 0) 0%,
+      #6222b7 53.02%,
+      rgba(57, 0, 134, 0) 100%
+    );
+}
+
+/* One twinkling star on the promo banner. Every value is randomised per star
+   at render, so the component passes them in as custom properties. */
+@utility notification-star {
+  width: var(--star-size);
+  height: var(--star-size);
+  left: var(--star-left);
+  top: var(--star-top);
+  opacity: var(--star-opacity);
+  filter: drop-shadow(0 0 var(--star-glow) rgba(255, 255, 255, 0.5));
+  animation: twinkle var(--star-duration) ease-in-out infinite;
+  animation-delay: var(--star-delay);
+
+  /* Nested rather than grouped with the other resets in @layer base: the
+     utility is emitted after that layer, so an outside reset of equal
+     specificity would lose and the stars would twinkle anyway. They rest at
+     the opacity the component randomised for them. */
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
 @layer utilities {
   :root {
     --viewport-height: 100vh;
@@ -784,6 +847,18 @@ Avoid over-scrolling in mobile browsers
       transform: rotate(1turn);
     }
   }
+
+  @keyframes twinkle {
+    0%,
+    100% {
+      opacity: 0.3;
+      transform: scale(1) translateY(0);
+    }
+    50% {
+      opacity: 1;
+      transform: scale(1.2) translateY(-2px);
+    }
+  }
 }
 
 /*
@@ -813,6 +888,13 @@ Avoid over-scrolling in mobile browsers
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
   --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
@@ -846,21 +928,34 @@ Avoid over-scrolling in mobile browsers
   --popover-foreground: #171717;
   --primary: #7d54d1;
   --primary-foreground: #ffffff;
-  --secondary: #f4f4f4;
-  --secondary-foreground: #7d54d1;
+  /* Pressed/active toggle fill: a brand tint, so it shows on any surface
+     (card, background, muted) and never reads as the neutral ghost hover. */
+  --secondary: #7d54d11a; /* primary at 10%; static, so no color-mix fallback */
+  --secondary-foreground: var(--primary);
   --muted: #f6f6f6;
   --muted-foreground: #737373;
   --accent: #ececec;
   --accent-foreground: #171717;
   --destructive: #ef4444;
+  --destructive-foreground: #ffffff;
+  /* Status colours. Pair `text-<token>` with `bg-<token>/10` for soft badges
+     and alerts; use `bg-<token> text-<token>-foreground` for solid fills. */
+  --success: #079455;
+  --success-foreground: #ffffff;
+  --warning: #ca8a04;
+  --warning-foreground: #ffffff;
+  --info: #2563eb;
+  --info-foreground: #ffffff;
   --border: #d9d9d9;
   --input: #d9d9d9;
   --ring: #7d54d1;
-  --chart-1: oklch(0.646 0.222 41.116);
-  --chart-2: oklch(0.6 0.118 184.704);
-  --chart-3: oklch(0.398 0.07 227.392);
-  --chart-4: oklch(0.828 0.189 84.429);
-  --chart-5: oklch(0.769 0.188 70.08);
+  /* Data series reuse brand and status colours: chart-1 is the brand, and a
+     series with a meaning takes the matching token (failed = chart-5). */
+  --chart-1: var(--primary);
+  --chart-2: var(--info);
+  --chart-3: var(--success);
+  --chart-4: var(--warning);
+  --chart-5: var(--destructive);
   --sidebar: #fbfbfb;
   --sidebar-foreground: #171717;
   --sidebar-primary: #7d54d1;
@@ -885,21 +980,30 @@ Avoid over-scrolling in mobile browsers
   --popover-foreground: #fafafa;
   --primary: #976af3;
   --primary-foreground: #ffffff;
-  --secondary: #2b2c31;
-  --secondary-foreground: #e0e0e0;
+  --secondary: #976af326; /* primary at 15% */
+  /* A lighter primary: #976af3 on the tint is about 3:1, this is 4.4-5.6:1. */
+  --secondary-foreground: #b89cf8;
   --muted: #35363b;
   --muted-foreground: #a1a1a1;
   --accent: #3e3f45;
   --accent-foreground: #fafafa;
   --destructive: #dc2626;
+  --destructive-foreground: #ffffff;
+  --success: #4ade80;
+  --success-foreground: #052e16;
+  --warning: #fbbf24;
+  --warning-foreground: #451a03;
+  --info: #60a5fa;
+  --info-foreground: #172554;
   --border: #44454c;
   --input: #44454c;
   --ring: #976af3;
-  --chart-1: oklch(0.488 0.243 264.376);
-  --chart-2: oklch(0.696 0.17 162.48);
-  --chart-3: oklch(0.769 0.188 70.08);
-  --chart-4: oklch(0.627 0.265 303.9);
-  --chart-5: oklch(0.645 0.246 16.439);
+  /* Same aliases as :root, re-declared so they resolve to the dark values. */
+  --chart-1: var(--primary);
+  --chart-2: var(--info);
+  --chart-3: var(--success);
+  --chart-4: var(--warning);
+  --chart-5: var(--destructive);
   --sidebar: #161616;
   --sidebar-foreground: #fafafa;
   --sidebar-primary: #976af3;
diff --git a/frontend/src/locale/de.json b/frontend/src/locale/de.json
index 061b5480..c5239f7e 100644
--- a/frontend/src/locale/de.json
+++ b/frontend/src/locale/de.json
@@ -23,7 +23,10 @@
     "sharedTitle": "Mit dir geteilt",
     "sharedBody": "{{type}} mit deinem Team geteilt: {{name}} ({{access}})",
     "sharedBodyNoName": "{{type}} wurde mit deinem Team geteilt ({{access}})",
-    "dismiss": "Schließen"
+    "dismiss": "Schließen",
+    "toolApprovalTitle": "Tool-Freigabe erforderlich",
+    "toolApprovalReview": "Prüfen",
+    "toolApprovalFallbackName": "Unterhaltung"
   },
   "demo": [
     {
@@ -221,6 +224,7 @@
       "deleteWarning": "Bist du sicher, dass du \"{{name}}\" löschen möchtest?",
       "confirmDelete": "Bist du sicher, dass du diese Datei löschen möchtest? Diese Aktion kann nicht rückgängig gemacht werden.",
       "backToAll": "Zurück zu allen Quellen",
+      "back": "Zurück",
       "chunks": "Chunks",
       "noChunks": "Keine Chunks gefunden",
       "noChunksAlt": "Keine Chunks gefunden",
@@ -371,6 +375,7 @@
       "failed": "Fehlgeschlagen",
       "skipped": "Übersprungen",
       "successful": "Erfolgreich",
+      "otherSeries": "Andere",
       "stats": {
         "messages": "Nachrichten",
         "tokens": "Tokens",
@@ -1594,6 +1599,7 @@
       "backToRoot": "Zurück",
       "currentFolder": "Dieser Ordner",
       "noSubfolders": "Keine Unterordner",
+      "openFolder": "Ordner öffnen",
       "noFolders": "Noch keine Ordner"
     },
     "guardrailEvents": {
diff --git a/frontend/src/locale/en.json b/frontend/src/locale/en.json
index 665e746c..e92dc526 100644
--- a/frontend/src/locale/en.json
+++ b/frontend/src/locale/en.json
@@ -27,7 +27,10 @@
     "sharedTitle": "Shared with you",
     "sharedBody": "{{type}} shared with your team: {{name}} ({{access}})",
     "sharedBodyNoName": "{{type}} shared with your team ({{access}})",
-    "dismiss": "Dismiss"
+    "dismiss": "Dismiss",
+    "toolApprovalTitle": "Tool approval needed",
+    "toolApprovalReview": "Review",
+    "toolApprovalFallbackName": "Conversation"
   },
   "demo": [
     {
@@ -225,6 +228,7 @@
       "deleteWarning": "Are you sure you want to delete \"{{name}}\"?",
       "confirmDelete": "Are you sure you want to delete this file? This action cannot be undone.",
       "backToAll": "Back to all sources",
+      "back": "Back",
       "chunks": "Chunks",
       "noChunks": "No chunks found",
       "noChunksAlt": "No chunks found",
@@ -375,6 +379,7 @@
       "failed": "Failed",
       "skipped": "Skipped",
       "successful": "Successful",
+      "otherSeries": "Other",
       "stats": {
         "messages": "Messages",
         "tokens": "Tokens",
@@ -1605,6 +1610,7 @@
       "backToRoot": "Back",
       "currentFolder": "This folder",
       "noSubfolders": "No subfolders",
+      "openFolder": "Open folder",
       "noFolders": "No folders yet"
     },
     "guardrailEvents": {
diff --git a/frontend/src/locale/es.json b/frontend/src/locale/es.json
index 1c27a945..fcb8d33f 100644
--- a/frontend/src/locale/es.json
+++ b/frontend/src/locale/es.json
@@ -23,7 +23,10 @@
     "sharedTitle": "Compartido contigo",
     "sharedBody": "Se compartió con tu equipo: {{type}} «{{name}}» ({{access}})",
     "sharedBodyNoName": "Se compartió con tu equipo: {{type}} ({{access}})",
-    "dismiss": "Descartar"
+    "dismiss": "Descartar",
+    "toolApprovalTitle": "Se requiere aprobar una herramienta",
+    "toolApprovalReview": "Revisar",
+    "toolApprovalFallbackName": "Conversación"
   },
   "demo": [
     {
@@ -221,6 +224,7 @@
       "deleteWarning": "¿Estás seguro de que deseas eliminar \"{{name}}\"?",
       "confirmDelete": "¿Estás seguro de que deseas eliminar este archivo? Esta acción no se puede deshacer.",
       "backToAll": "Volver a todas las fuentes",
+      "back": "Volver",
       "chunks": "Fragmentos",
       "noChunks": "No se encontraron fragmentos",
       "noChunksAlt": "No se encontraron fragmentos",
@@ -371,6 +375,7 @@
       "failed": "Fallidas",
       "skipped": "Omitidas",
       "successful": "Exitosas",
+      "otherSeries": "Otros",
       "stats": {
         "messages": "Mensajes",
         "tokens": "Tokens",
@@ -1594,6 +1599,7 @@
       "backToRoot": "Volver",
       "currentFolder": "Esta carpeta",
       "noSubfolders": "Sin subcarpetas",
+      "openFolder": "Abrir carpeta",
       "noFolders": "No hay carpetas todavía"
     },
     "guardrailEvents": {
diff --git a/frontend/src/locale/jp.json b/frontend/src/locale/jp.json
index 537a6373..7eca77f1 100644
--- a/frontend/src/locale/jp.json
+++ b/frontend/src/locale/jp.json
@@ -23,7 +23,10 @@
     "sharedTitle": "あなたに共有されました",
     "sharedBody": "チームに{{type}}が共有されました: {{name}}（{{access}}）",
     "sharedBodyNoName": "チームに{{type}}が共有されました（{{access}}）",
-    "dismiss": "閉じる"
+    "dismiss": "閉じる",
+    "toolApprovalTitle": "ツールの承認が必要です",
+    "toolApprovalReview": "確認",
+    "toolApprovalFallbackName": "会話"
   },
   "demo": [
     {
@@ -220,6 +223,7 @@
       "deleteWarning": "\"{{name}}\"を削除してもよろしいですか？",
       "confirmDelete": "このファイルを削除してもよろしいですか？この操作は元に戻せません。",
       "backToAll": "すべてのソースに戻る",
+      "back": "戻る",
       "chunks": "チャンク",
       "noChunks": "チャンクが見つかりません",
       "noChunksAlt": "チャンクが見つかりません",
@@ -370,6 +374,7 @@
       "failed": "失敗",
       "skipped": "スキップ",
       "successful": "成功",
+      "otherSeries": "その他",
       "stats": {
         "messages": "メッセージ",
         "tokens": "トークン",
@@ -1590,6 +1595,7 @@
       "backToRoot": "戻る",
       "currentFolder": "このフォルダ",
       "noSubfolders": "サブフォルダなし",
+      "openFolder": "フォルダーを開く",
       "noFolders": "フォルダがありません"
     },
     "guardrailEvents": {
diff --git a/frontend/src/locale/ru.json b/frontend/src/locale/ru.json
index 243954cb..62696e0c 100644
--- a/frontend/src/locale/ru.json
+++ b/frontend/src/locale/ru.json
@@ -23,7 +23,10 @@
     "sharedTitle": "Поделились с вами",
     "sharedBody": "С вашей командой поделились: {{type}} «{{name}}» ({{access}})",
     "sharedBodyNoName": "С вашей командой поделились: {{type}} ({{access}})",
-    "dismiss": "Закрыть"
+    "dismiss": "Закрыть",
+    "toolApprovalTitle": "Требуется одобрение инструмента",
+    "toolApprovalReview": "Проверить",
+    "toolApprovalFallbackName": "Диалог"
   },
   "demo": [
     {
@@ -233,6 +236,7 @@
       "deleteWarning": "Вы уверены, что хотите удалить \"{{name}}\"?",
       "confirmDelete": "Вы уверены, что хотите удалить этот файл? Это действие нельзя отменить.",
       "backToAll": "Вернуться ко всем источникам",
+      "back": "Назад",
       "chunks": "Фрагменты",
       "noChunks": "Фрагменты не найдены",
       "noChunksAlt": "Фрагменты не найдены",
@@ -383,6 +387,7 @@
       "failed": "Не удалось",
       "skipped": "Пропущено",
       "successful": "Успешно",
+      "otherSeries": "Другие",
       "stats": {
         "messages": "Сообщения",
         "tokens": "Токены",
@@ -1632,6 +1637,7 @@
       "backToRoot": "Назад",
       "currentFolder": "Эта папка",
       "noSubfolders": "Нет подпапок",
+      "openFolder": "Открыть папку",
       "noFolders": "Пока нет папок"
     },
     "guardrailEvents": {
diff --git a/frontend/src/locale/zh-TW.json b/frontend/src/locale/zh-TW.json
index 3e10c564..813a11a2 100644
--- a/frontend/src/locale/zh-TW.json
+++ b/frontend/src/locale/zh-TW.json
@@ -23,7 +23,10 @@
     "sharedTitle": "已與您分享",
     "sharedBody": "已與您的團隊分享{{type}}：{{name}}（{{access}}）",
     "sharedBodyNoName": "已與您的團隊分享一個{{type}}（{{access}}）",
-    "dismiss": "關閉"
+    "dismiss": "關閉",
+    "toolApprovalTitle": "需要核准工具",
+    "toolApprovalReview": "檢視",
+    "toolApprovalFallbackName": "對話"
   },
   "demo": [
     {
@@ -220,6 +223,7 @@
       "deleteWarning": "您確定要刪除 \"{{name}}\" 嗎？",
       "confirmDelete": "您確定要刪除此檔案嗎？此操作無法復原。",
       "backToAll": "返回所有來源",
+      "back": "返回",
       "chunks": "文本塊",
       "noChunks": "未找到文本塊",
       "noChunksAlt": "未找到文本塊",
@@ -370,6 +374,7 @@
       "failed": "失敗",
       "skipped": "已略過",
       "successful": "成功",
+      "otherSeries": "其他",
       "stats": {
         "messages": "訊息",
         "tokens": "Token",
@@ -1590,6 +1595,7 @@
       "backToRoot": "返回",
       "currentFolder": "此資料夾",
       "noSubfolders": "沒有子資料夾",
+      "openFolder": "開啟資料夾",
       "noFolders": "暫無資料夾"
     },
     "guardrailEvents": {
diff --git a/frontend/src/locale/zh.json b/frontend/src/locale/zh.json
index 201b6c4c..733fae99 100644
--- a/frontend/src/locale/zh.json
+++ b/frontend/src/locale/zh.json
@@ -23,7 +23,10 @@
     "sharedTitle": "与您共享",
     "sharedBody": "{{type}}已共享给您的团队：{{name}}（{{access}}）",
     "sharedBodyNoName": "已与您的团队共享一个{{type}}（{{access}}）",
-    "dismiss": "忽略"
+    "dismiss": "忽略",
+    "toolApprovalTitle": "需要批准工具",
+    "toolApprovalReview": "查看",
+    "toolApprovalFallbackName": "对话"
   },
   "demo": [
     {
@@ -220,6 +223,7 @@
       "deleteWarning": "您确定要删除 \"{{name}}\" 吗？",
       "confirmDelete": "您确定要删除此文件吗？此操作无法撤销。",
       "backToAll": "返回所有来源",
+      "back": "返回",
       "chunks": "文本块",
       "noChunks": "未找到文本块",
       "noChunksAlt": "未找到文本块",
@@ -370,6 +374,7 @@
       "failed": "失败",
       "skipped": "已跳过",
       "successful": "成功",
+      "otherSeries": "其他",
       "stats": {
         "messages": "消息",
         "tokens": "令牌",
@@ -1590,6 +1595,7 @@
       "backToRoot": "返回",
       "currentFolder": "此文件夹",
       "noSubfolders": "没有子文件夹",
+      "openFolder": "打开文件夹",
       "noFolders": "暂无文件夹"
     },
     "guardrailEvents": {
diff --git a/frontend/src/modals/AccessTokenCreatedModal.tsx b/frontend/src/modals/AccessTokenCreatedModal.tsx
index 2004d3b5..49deb962 100644
--- a/frontend/src/modals/AccessTokenCreatedModal.tsx
+++ b/frontend/src/modals/AccessTokenCreatedModal.tsx
@@ -41,18 +41,14 @@ export default function AccessTokenCreatedModal({
       // dismiss it; closing takes the explicit button (or Esc).
       isPerformingTask
       footer={
-        <Button
-          type="button"
-          onClick={onClose}
-          className="rounded-3xl px-6 text-white"
-        >
+        <Button type="button" onClick={onClose} shape="pill" size="lg">
           {t('settings.accessTokens.created.done')}
         </Button>
       }
     >
       <div className="flex flex-col gap-5 px-1">
         <div>
-          <h2 className="text-foreground dark:text-foreground text-xl font-semibold">
+          <h2 className="text-foreground text-xl font-semibold">
             {t(`${copy}.title`)}
           </h2>
           <p className="text-muted-foreground mt-2 text-sm break-words">
@@ -65,23 +61,23 @@ export default function AccessTokenCreatedModal({
 
         <div
           role="alert"
-          className="flex items-start gap-3 rounded-lg bg-amber-50 px-4 py-3 text-sm text-amber-800 dark:bg-amber-900/20 dark:text-amber-300"
+          className="bg-warning/10 text-foreground flex items-start gap-3 rounded-lg px-4 py-3 text-sm"
         >
           <TriangleAlert
-            className="mt-0.5 size-4 shrink-0"
+            className="text-warning mt-0.5 size-4 shrink-0"
             aria-hidden="true"
           />
           <p>{t('settings.accessTokens.created.warning')}</p>
         </div>
 
         <div className="flex flex-col gap-1.5">
-          <p className="text-foreground dark:text-foreground text-sm font-semibold">
+          <p className="text-foreground text-sm font-semibold">
             {t('settings.accessTokens.created.tokenLabel')}
           </p>
           <div className="bg-muted flex items-center gap-2 rounded-xl py-2 pr-2 pl-4">
             <code
               data-testid="pat-plaintext"
-              className="text-foreground dark:text-foreground min-w-0 flex-1 font-mono text-xs break-all select-all sm:text-sm"
+              className="text-foreground min-w-0 flex-1 font-mono text-xs break-all select-all sm:text-sm"
             >
               {token}
             </code>
@@ -90,7 +86,7 @@ export default function AccessTokenCreatedModal({
         </div>
 
         <div className="flex flex-col gap-2">
-          <p className="text-foreground dark:text-foreground text-sm font-semibold">
+          <p className="text-foreground text-sm font-semibold">
             {t('settings.accessTokens.created.usageTitle')}
           </p>
           <p className="text-muted-foreground text-xs">
@@ -101,7 +97,7 @@ export default function AccessTokenCreatedModal({
               key={index}
               className="bg-muted flex items-start gap-2 rounded-xl py-2 pr-2 pl-4"
             >
-              <pre className="text-foreground dark:text-foreground min-w-0 flex-1 font-mono text-xs leading-relaxed break-all whitespace-pre-wrap">
+              <pre className="text-foreground min-w-0 flex-1 font-mono text-xs leading-relaxed break-all whitespace-pre-wrap">
                 {snippet}
               </pre>
               <CopyButton textToCopy={snippet} />
diff --git a/frontend/src/modals/AddActionModal.tsx b/frontend/src/modals/AddActionModal.tsx
index 4f19191b..49db61d7 100644
--- a/frontend/src/modals/AddActionModal.tsx
+++ b/frontend/src/modals/AddActionModal.tsx
@@ -55,16 +55,12 @@ export default function AddActionModal({
           <Button
             type="button"
             variant="ghost"
+            shape="pill"
             onClick={handleCancel}
-            className="rounded-3xl px-5"
           >
             {t('modals.configTool.closeButton')}
           </Button>
-          <Button
-            type="button"
-            onClick={handleAddAction}
-            className="rounded-3xl px-5"
-          >
+          <Button type="button" shape="pill" onClick={handleAddAction}>
             {t('modals.addAction.addButton')}
           </Button>
         </>
@@ -79,13 +75,12 @@ export default function AddActionModal({
             setActionName(value);
             setFunctionNameError(!isValidFunctionName(value));
           }}
-          labelBgClassName="bg-card"
           label={t('modals.addAction.actionNamePlaceholder')}
           required={true}
         />
         <p
           className={`mt-2 ml-1 text-xs italic ${
-            functionNameError ? 'text-red-500' : 'text-muted-foreground'
+            functionNameError ? 'text-destructive' : 'text-muted-foreground'
           }`}
         >
           {functionNameError
diff --git a/frontend/src/modals/AgentDetailsModal.tsx b/frontend/src/modals/AgentDetailsModal.tsx
index 78b70c48..ab133388 100644
--- a/frontend/src/modals/AgentDetailsModal.tsx
+++ b/frontend/src/modals/AgentDetailsModal.tsx
@@ -104,185 +104,198 @@ export default function AgentDetailsModal({
 
   return (
     <>
-    <Modal
-      open={modalState === 'ACTIVE'}
-      onOpenChange={(o) => !o && setModalState('INACTIVE')}
-      title={t('modals.agentDetails.title')}
-      size="md"
-    >
-      <div>
-        <div className="mt-8 flex flex-col gap-6">
-          <div className="flex flex-col gap-3">
-            <div className="flex items-center gap-2">
-              <h2 className="text-foreground dark:text-foreground text-base font-semibold">
-                {t('modals.agentDetails.publicLink')}
-              </h2>
-            </div>
-            {sharedToken ? (
-              <div className="flex flex-col gap-2">
-                <p className="dark:text-foreground inline text-sm leading-normal font-medium break-all text-gray-700">
-                  <a
-                    href={`${baseURL}/shared/agent/${sharedToken}`}
-                    target="_blank"
-                    rel="noreferrer"
-                  >
-                    {`${baseURL}/shared/agent/${sharedToken}`}
-                  </a>
-                  <CopyButton
-                    textToCopy={`${baseURL}/shared/agent/${sharedToken}`}
-                    padding="p-1"
-                    className="absolute -mt-0.5 ml-1 inline-flex"
-                  />
-                </p>
-                <a
-                  href="https://docs.docsgpt.cloud/Agents/basics#core-components-of-an-agent"
-                  className="text-primary flex w-fit items-center gap-1 hover:underline"
-                  target="_blank"
-                  rel="noopener noreferrer"
-                >
-                  <span className="text-sm">
-                    {t('modals.agentDetails.learnMore')}
-                  </span>
-                  <img
-                    src={ExternalLinkIcon}
-                    alt="External link"
-                    className="h-3 w-3"
-                  />
-                </a>
+      <Modal
+        open={modalState === 'ACTIVE'}
+        onOpenChange={(o) => !o && setModalState('INACTIVE')}
+        title={t('modals.agentDetails.title')}
+        size="md"
+      >
+        <div>
+          <div className="mt-8 flex flex-col gap-6">
+            <div className="flex flex-col gap-3">
+              <div className="flex items-center gap-2">
+                <h2 className="text-foreground dark:text-foreground text-base font-semibold">
+                  {t('modals.agentDetails.publicLink')}
+                </h2>
               </div>
-            ) : (
-              <Button
-                type="button"
-                variant="outline"
-                onClick={handleGeneratePublicLink}
-                className="border-primary text-primary hover:bg-primary/90 w-28 rounded-3xl border-solid px-5 hover:text-white"
-              >
-                {loadingStates.publicLink ? (
-                  <Spinner size="small" />
-                ) : (
-                  t('modals.agentDetails.generate')
-                )}
-              </Button>
-            )}
-          </div>
-          <div className="flex flex-col gap-3">
-            <h2 className="text-foreground dark:text-foreground text-base font-semibold">
-              {t('modals.agentDetails.apiKey')}
-            </h2>
-            {apiKey ? (
-              <div className="flex flex-col gap-2">
-                <div className="flex items-center gap-2">
-                  <div className="dark:text-foreground text-sm leading-normal font-medium break-all text-gray-700">
-                    {apiKey}
+              {sharedToken ? (
+                <div className="flex flex-col gap-2">
+                  <p className="text-foreground inline text-sm leading-normal font-medium break-all">
+                    <a
+                      href={`${baseURL}/shared/agent/${sharedToken}`}
+                      target="_blank"
+                      rel="noreferrer"
+                    >
+                      {`${baseURL}/shared/agent/${sharedToken}`}
+                    </a>
+                    <CopyButton
+                      textToCopy={`${baseURL}/shared/agent/${sharedToken}`}
+                      size="xs"
+                      className="absolute -mt-0.5 ml-1 inline-flex"
+                    />
+                  </p>
+                  <a
+                    href="https://docs.docsgpt.cloud/Agents/basics#core-components-of-an-agent"
+                    className="text-primary flex w-fit items-center gap-1 hover:underline"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    <span className="text-sm">
+                      {t('modals.agentDetails.learnMore')}
+                    </span>
+                    <img
+                      src={ExternalLinkIcon}
+                      alt="External link"
+                      className="h-3 w-3"
+                    />
+                  </a>
+                </div>
+              ) : (
+                <Button
+                  type="button"
+                  variant="outline-primary"
+                  shape="pill"
+                  onClick={handleGeneratePublicLink}
+                  className="w-28"
+                >
+                  {loadingStates.publicLink ? (
+                    <Spinner size="small" />
+                  ) : (
+                    t('modals.agentDetails.generate')
+                  )}
+                </Button>
+              )}
+            </div>
+            <div className="flex flex-col gap-3">
+              <h2 className="text-foreground dark:text-foreground text-base font-semibold">
+                {t('modals.agentDetails.apiKey')}
+              </h2>
+              {apiKey ? (
+                <div className="flex flex-col gap-2">
+                  <div className="flex items-center gap-2">
+                    <div className="text-foreground text-sm leading-normal font-medium break-all">
+                      {apiKey}
+                      {!apiKey.includes('...') && (
+                        <CopyButton
+                          textToCopy={apiKey}
+                          size="xs"
+                          className="absolute -mt-0.5 ml-1 inline-flex"
+                        />
+                      )}
+                    </div>
                     {!apiKey.includes('...') && (
-                      <CopyButton
-                        textToCopy={apiKey}
-                        padding="p-1"
-                        className="absolute -mt-0.5 ml-1 inline-flex"
-                      />
+                      <Button
+                        asChild
+                        variant="outline-primary"
+                        size="sm"
+                        shape="pill"
+                        className="group ml-8 w-[101px]"
+                      >
+                        <a
+                          href={`https://widget.docsgpt.cloud/?api-key=${apiKey}`}
+                          target="_blank"
+                          rel="noopener noreferrer"
+                        >
+                          {t('modals.agentDetails.test')}
+                          <img
+                            src={ExternalLinkIcon}
+                            alt="External link"
+                            className="h-3 w-3 group-hover:brightness-0 group-hover:invert"
+                          />
+                        </a>
+                      </Button>
+                    )}
+                    {apiKey.includes('...') && (
+                      <Button
+                        type="button"
+                        onClick={() => setResetKeyConfirmState('ACTIVE')}
+                        disabled={loadingStates.apiKey}
+                        variant="outline-primary"
+                        size="sm"
+                        shape="pill"
+                        className="ml-8"
+                      >
+                        {loadingStates.apiKey ? (
+                          <Spinner size="small" />
+                        ) : (
+                          t('modals.agentDetails.resetKey')
+                        )}
+                      </Button>
                     )}
                   </div>
-                  {!apiKey.includes('...') && (
-                    <a
-                      href={`https://widget.docsgpt.cloud/?api-key=${apiKey}`}
-                      className="group border-primary text-primary hover:bg-primary/90 ml-8 flex w-[101px] items-center justify-center gap-1 rounded-full border py-1.5 text-sm font-medium transition-colors hover:text-white"
-                      target="_blank"
-                      rel="noopener noreferrer"
-                    >
-                      {t('modals.agentDetails.test')}
-                      <img
-                        src={ExternalLinkIcon}
-                        alt="External link"
-                        className="h-3 w-3 group-hover:brightness-0 group-hover:invert"
-                      />
-                    </a>
-                  )}
-                  {apiKey.includes('...') && (
-                    <button
-                      type="button"
-                      onClick={() => setResetKeyConfirmState('ACTIVE')}
-                      disabled={loadingStates.apiKey}
-                      className="border-primary text-primary hover:bg-primary/90 ml-8 flex items-center justify-center gap-1 rounded-full border px-5 py-1.5 text-sm font-medium transition-colors hover:text-white disabled:opacity-60"
-                    >
-                      {loadingStates.apiKey ? (
-                        <Spinner size="small" />
-                      ) : (
-                        t('modals.agentDetails.resetKey')
-                      )}
-                    </button>
-                  )}
                 </div>
-              </div>
-            ) : (
-              <Button
-                type="button"
-                variant="outline"
-                className="border-primary text-primary hover:bg-primary/90 w-28 rounded-3xl border-solid px-5 hover:text-white"
-              >
-                {t('modals.agentDetails.generate')}
-              </Button>
-            )}
-          </div>
-          <div className="flex flex-col gap-3">
-            <div className="flex items-center gap-2">
-              <h2 className="text-foreground dark:text-foreground text-base font-semibold">
-                {t('modals.agentDetails.webhookUrl')}
-              </h2>
-            </div>
-            {webhookUrl ? (
-              <div className="flex flex-col gap-2">
-                <p className="dark:text-foreground text-sm leading-normal font-medium break-all text-gray-700">
-                  <a href={webhookUrl} target="_blank" rel="noreferrer">
-                    {webhookUrl}
-                  </a>
-                  <CopyButton
-                    textToCopy={webhookUrl}
-                    padding="p-1"
-                    className="absolute -mt-0.5 ml-1 inline-flex"
-                  />
-                </p>
-                <a
-                  href="https://docs.docsgpt.cloud/Agents/basics#core-components-of-an-agent"
-                  className="text-primary flex w-fit items-center gap-1 hover:underline"
-                  target="_blank"
-                  rel="noopener noreferrer"
+              ) : (
+                <Button
+                  type="button"
+                  variant="outline-primary"
+                  shape="pill"
+                  className="w-28"
                 >
-                  <span className="text-sm">
-                    {t('modals.agentDetails.learnMore')}
-                  </span>
-                  <img
-                    src={ExternalLinkIcon}
-                    alt="External link"
-                    className="h-3 w-3"
-                  />
-                </a>
+                  {t('modals.agentDetails.generate')}
+                </Button>
+              )}
+            </div>
+            <div className="flex flex-col gap-3">
+              <div className="flex items-center gap-2">
+                <h2 className="text-foreground dark:text-foreground text-base font-semibold">
+                  {t('modals.agentDetails.webhookUrl')}
+                </h2>
               </div>
-            ) : (
-              <Button
-                type="button"
-                variant="outline"
-                onClick={handleGenerateWebhook}
-                className="border-primary text-primary hover:bg-primary/90 w-28 rounded-3xl border-solid px-5 hover:text-white"
-              >
-                {loadingStates.webhook ? (
-                  <Spinner size="small" />
-                ) : (
-                  t('modals.agentDetails.generate')
-                )}
-              </Button>
-            )}
+              {webhookUrl ? (
+                <div className="flex flex-col gap-2">
+                  <p className="text-foreground text-sm leading-normal font-medium break-all">
+                    <a href={webhookUrl} target="_blank" rel="noreferrer">
+                      {webhookUrl}
+                    </a>
+                    <CopyButton
+                      textToCopy={webhookUrl}
+                      size="xs"
+                      className="absolute -mt-0.5 ml-1 inline-flex"
+                    />
+                  </p>
+                  <a
+                    href="https://docs.docsgpt.cloud/Agents/basics#core-components-of-an-agent"
+                    className="text-primary flex w-fit items-center gap-1 hover:underline"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    <span className="text-sm">
+                      {t('modals.agentDetails.learnMore')}
+                    </span>
+                    <img
+                      src={ExternalLinkIcon}
+                      alt="External link"
+                      className="h-3 w-3"
+                    />
+                  </a>
+                </div>
+              ) : (
+                <Button
+                  type="button"
+                  variant="outline-primary"
+                  shape="pill"
+                  onClick={handleGenerateWebhook}
+                  className="w-28"
+                >
+                  {loadingStates.webhook ? (
+                    <Spinner size="small" />
+                  ) : (
+                    t('modals.agentDetails.generate')
+                  )}
+                </Button>
+              )}
+            </div>
           </div>
         </div>
-      </div>
-    </Modal>
-    <ConfirmationModal
-      message={t('modals.agentDetails.resetKeyConfirm')}
-      modalState={resetKeyConfirmState}
-      setModalState={setResetKeyConfirmState}
-      submitLabel={t('modals.agentDetails.resetKey')}
-      handleSubmit={handleRegenerateKey}
-      variant="danger"
-    />
+      </Modal>
+      <ConfirmationModal
+        message={t('modals.agentDetails.resetKeyConfirm')}
+        modalState={resetKeyConfirmState}
+        setModalState={setResetKeyConfirmState}
+        submitLabel={t('modals.agentDetails.resetKey')}
+        handleSubmit={handleRegenerateKey}
+        variant="danger"
+      />
     </>
   );
 }
diff --git a/frontend/src/modals/ConfigToolModal.tsx b/frontend/src/modals/ConfigToolModal.tsx
index 7f657a07..a0ddf282 100644
--- a/frontend/src/modals/ConfigToolModal.tsx
+++ b/frontend/src/modals/ConfigToolModal.tsx
@@ -124,16 +124,16 @@ export default function ConfigToolModal({
           <Button
             type="button"
             variant="ghost"
+            shape="pill"
             onClick={handleClose}
-            className="rounded-3xl px-5"
           >
             {t('modals.configTool.closeButton')}
           </Button>
           <Button
             type="button"
             onClick={handleAddTool}
+            shape="pill"
             disabled={saving}
-            className="rounded-3xl px-5"
           >
             {saving
               ? t('modals.configTool.addButton') + '…'
@@ -143,9 +143,9 @@ export default function ConfigToolModal({
       }
     >
       <div>
-        <p className="mt-2 text-sm text-gray-500 dark:text-gray-400">
+        <p className="text-muted-foreground mt-2 text-sm">
           {t('modals.configTool.type')}:{' '}
-          <span className="font-medium text-gray-700 dark:text-gray-200">
+          <span className="text-foreground font-medium">
             {tool.displayName}
           </span>
         </p>
@@ -161,7 +161,6 @@ export default function ConfigToolModal({
               value={customName}
               onChange={(e) => setCustomName(e.target.value)}
               placeholder={tool.displayName}
-              className="rounded-xl"
             />
           </div>
 
diff --git a/frontend/src/modals/ConfirmationModal.tsx b/frontend/src/modals/ConfirmationModal.tsx
index 9c035166..e031eb4e 100644
--- a/frontend/src/modals/ConfirmationModal.tsx
+++ b/frontend/src/modals/ConfirmationModal.tsx
@@ -52,7 +52,7 @@ export default function ConfirmationModal({
             type="button"
             variant="ghost"
             onClick={handleCancelClick}
-            className="rounded-3xl px-5"
+            shape="pill"
           >
             {cancelLabel ? cancelLabel : t('cancel')}
           </Button>
@@ -60,7 +60,7 @@ export default function ConfirmationModal({
             type="button"
             variant={variant === 'danger' ? 'destructive' : 'default'}
             onClick={handleSubmitClick}
-            className="rounded-3xl px-5"
+            shape="pill"
           >
             {submitLabel}
           </Button>
diff --git a/frontend/src/modals/CreateAccessTokenModal.tsx b/frontend/src/modals/CreateAccessTokenModal.tsx
index db64674e..b1702fd7 100644
--- a/frontend/src/modals/CreateAccessTokenModal.tsx
+++ b/frontend/src/modals/CreateAccessTokenModal.tsx
@@ -1,3 +1,4 @@
+import { CircleAlert, TriangleAlert } from 'lucide-react';
 import React from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
@@ -9,6 +10,7 @@ import patService, {
 } from '../api/services/patService';
 import userService from '../api/services/userService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Label } from '../components/ui/label';
@@ -213,7 +215,8 @@ export default function CreateAccessTokenModal({
             variant="ghost"
             onClick={handleClose}
             disabled={submitting}
-            className="rounded-3xl px-6"
+            size="lg"
+            shape="pill"
           >
             {t('settings.accessTokens.create.cancel')}
           </Button>
@@ -221,7 +224,8 @@ export default function CreateAccessTokenModal({
             type="button"
             onClick={handleSubmit}
             disabled={!canSubmit}
-            className="rounded-3xl px-6 text-white"
+            size="lg"
+            shape="pill"
           >
             {submitting ? (
               <span className="flex items-center gap-2">
@@ -255,7 +259,7 @@ export default function CreateAccessTokenModal({
           <div className="flex flex-col gap-1.5">
             <Label htmlFor="pat-name">
               {t('settings.accessTokens.create.name')}
-              <span className="text-red-500">*</span>
+              <span className="text-destructive">*</span>
             </Label>
             <Input
               id="pat-name"
@@ -267,7 +271,6 @@ export default function CreateAccessTokenModal({
                 setError(null);
               }}
               placeholder={t('settings.accessTokens.create.namePlaceholder')}
-              className="rounded-xl"
               autoComplete="off"
             />
           </div>
@@ -279,11 +282,7 @@ export default function CreateAccessTokenModal({
               value={String(expiry)}
               onValueChange={(value) => setExpiry(Number(value))}
             >
-              <SelectTrigger
-                id="pat-expiry"
-                className="w-full rounded-xl px-4 py-2"
-                size="lg"
-              >
+              <SelectTrigger id="pat-expiry" className="w-full" size="lg">
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
@@ -294,29 +293,30 @@ export default function CreateAccessTokenModal({
                 ))}
               </SelectContent>
             </Select>
-            <p
-              className={`text-xs ${
-                expiry === NO_EXPIRY
-                  ? 'text-amber-700 dark:text-amber-400'
-                  : 'text-muted-foreground'
-              }`}
-            >
-              {expiry === NO_EXPIRY
-                ? t('settings.accessTokens.create.noExpirationHint')
-                : t('settings.accessTokens.create.expiresOn', {
-                    date: formatDateOnly(
-                      new Date(Date.now() + expiry * DAY_MS).toISOString(),
-                    ),
-                    ...NO_ESCAPE,
-                  })}
-            </p>
+            {expiry === NO_EXPIRY ? (
+              <Alert variant="warning">
+                <TriangleAlert className="size-4" aria-hidden="true" />
+                <AlertDescription>
+                  {t('settings.accessTokens.create.noExpirationHint')}
+                </AlertDescription>
+              </Alert>
+            ) : (
+              <p className="text-muted-foreground text-xs">
+                {t('settings.accessTokens.create.expiresOn', {
+                  date: formatDateOnly(
+                    new Date(Date.now() + expiry * DAY_MS).toISOString(),
+                  ),
+                  ...NO_ESCAPE,
+                })}
+              </p>
+            )}
           </div>
         </div>
 
         <fieldset className="m-0 flex min-w-0 flex-col gap-3 border-0 p-0">
           <legend className="text-foreground dark:text-foreground text-sm font-semibold">
             {t('settings.accessTokens.create.scopes')}
-            <span className="text-red-500">*</span>
+            <span className="text-destructive">*</span>
           </legend>
           <p className="text-muted-foreground text-xs">
             {t('settings.accessTokens.create.scopesHint')}
@@ -357,7 +357,7 @@ export default function CreateAccessTokenModal({
                           checked={checked}
                           disabled={implied}
                           onChange={() => toggleScope(scope.name)}
-                          className="accent-primary mt-0.5 size-4 shrink-0 rounded-sm border-gray-300 bg-transparent dark:[color-scheme:dark]"
+                          className="accent-primary border-input mt-0.5 size-4 shrink-0 rounded-sm bg-transparent dark:[color-scheme:dark]"
                         />
                         <span className="flex min-w-0 flex-col gap-0.5">
                           <code className="text-foreground dark:text-foreground font-mono text-xs font-medium">
@@ -416,7 +416,7 @@ export default function CreateAccessTokenModal({
                         <Button
                           type="button"
                           variant="link"
-                          className="h-auto p-0 text-xs"
+                          size="xs"
                           onClick={() => loadResources(family)}
                         >
                           {t('settings.accessTokens.create.retry')}
@@ -441,7 +441,6 @@ export default function CreateAccessTokenModal({
                         searchPlaceholder={t(
                           'settings.accessTokens.create.searchResources',
                         )}
-                        className="rounded-xl"
                         modal
                       />
                     )}
@@ -452,12 +451,10 @@ export default function CreateAccessTokenModal({
         )}
 
         {error && (
-          <div
-            role="alert"
-            className="rounded-lg bg-red-50 px-4 py-2 text-sm text-red-600 dark:bg-red-900/20 dark:text-red-400"
-          >
-            {error}
-          </div>
+          <Alert variant="destructive">
+            <CircleAlert className="size-4" aria-hidden="true" />
+            <AlertDescription>{error}</AlertDescription>
+          </Alert>
         )}
       </form>
     </Modal>
diff --git a/frontend/src/modals/CustomModelModal.test.tsx b/frontend/src/modals/CustomModelModal.test.tsx
new file mode 100644
index 00000000..7e7ee713
--- /dev/null
+++ b/frontend/src/modals/CustomModelModal.test.tsx
@@ -0,0 +1,56 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { CapabilityChip } from './CustomModelModal';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('CapabilityChip', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = (active: boolean, onClick = vi.fn()) => {
+    act(() => {
+      root.render(
+        <CapabilityChip label="Tools" active={active} onClick={onClick} />,
+      );
+    });
+    return container.querySelector<HTMLButtonElement>('[role="switch"]')!;
+  };
+
+  it('uses the secondary variant with a check when on', () => {
+    const chip = render(true);
+    expect(chip.dataset.variant).toBe('secondary');
+    expect(chip.dataset.size).toBe('sm');
+    expect(chip.dataset.shape).toBe('pill');
+    expect(chip.getAttribute('aria-checked')).toBe('true');
+    expect(chip.querySelector('svg')).not.toBeNull();
+    expect(chip.className).not.toMatch(/success/);
+  });
+
+  it('uses the ghost-muted variant without a check when off', () => {
+    const onClick = vi.fn();
+    const chip = render(false, onClick);
+    expect(chip.dataset.variant).toBe('ghost-muted');
+    expect(chip.getAttribute('aria-checked')).toBe('false');
+    expect(chip.querySelector('svg')).toBeNull();
+    expect(chip.textContent).toBe('Tools');
+    act(() => chip.click());
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/frontend/src/modals/CustomModelModal.tsx b/frontend/src/modals/CustomModelModal.tsx
index c217a616..0ef611ed 100644
--- a/frontend/src/modals/CustomModelModal.tsx
+++ b/frontend/src/modals/CustomModelModal.tsx
@@ -1,10 +1,11 @@
-import { Check } from 'lucide-react';
+import { Check, CircleAlert, CircleCheck } from 'lucide-react';
 import { useEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 
 import customModelsService from '../api/services/customModelsService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Label } from '../components/ui/label';
@@ -331,7 +332,7 @@ export default function CustomModelModal({
     >
       <div className="flex h-full flex-col">
         <div className="px-2 py-2">
-          <h2 className="text-foreground dark:text-foreground text-xl font-semibold">
+          <h2 className="text-foreground text-xl font-semibold">
             {isEditMode
               ? t('settings.customModels.editTitle')
               : t('settings.customModels.addTitle')}
@@ -347,7 +348,7 @@ export default function CustomModelModal({
               <div className="flex flex-col gap-1.5">
                 <Label htmlFor="cm-display-name">
                   {t('settings.customModels.fields.displayName')}
-                  <span className="text-red-500">*</span>
+                  <span className="text-destructive">*</span>
                 </Label>
                 <Input
                   id="cm-display-name"
@@ -358,7 +359,6 @@ export default function CustomModelModal({
                     'settings.customModels.placeholders.displayName',
                   )}
                   aria-invalid={!!errors.display_name || undefined}
-                  className="rounded-xl"
                 />
                 {errors.display_name && (
                   <p className="text-destructive text-xs">
@@ -370,7 +370,7 @@ export default function CustomModelModal({
               <div className="flex flex-col gap-1.5">
                 <Label htmlFor="cm-model-id">
                   {t('settings.customModels.fields.modelId')}
-                  <span className="text-red-500">*</span>
+                  <span className="text-destructive">*</span>
                 </Label>
                 <Input
                   id="cm-model-id"
@@ -381,7 +381,6 @@ export default function CustomModelModal({
                   }
                   placeholder={t('settings.customModels.placeholders.modelId')}
                   aria-invalid={!!errors.upstream_model_id || undefined}
-                  className="rounded-xl"
                 />
                 {errors.upstream_model_id && (
                   <p className="text-destructive text-xs">
@@ -396,7 +395,7 @@ export default function CustomModelModal({
               <div className="flex flex-col gap-1.5">
                 <Label htmlFor="cm-base-url">
                   {t('settings.customModels.fields.baseUrl')}
-                  <span className="text-red-500">*</span>
+                  <span className="text-destructive">*</span>
                 </Label>
                 <Input
                   id="cm-base-url"
@@ -411,7 +410,6 @@ export default function CustomModelModal({
                   aria-invalid={
                     !!errors.base_url || !!errors.base_url_remote || undefined
                   }
-                  className="rounded-xl"
                 />
                 {errors.base_url && (
                   <p className="text-destructive text-xs">{errors.base_url}</p>
@@ -426,7 +424,7 @@ export default function CustomModelModal({
               <div className="flex flex-col gap-1.5">
                 <Label htmlFor="cm-api-key">
                   {t('settings.customModels.fields.apiKey')}
-                  {!isEditMode && <span className="text-red-500">*</span>}
+                  {!isEditMode && <span className="text-destructive">*</span>}
                 </Label>
                 <Input
                   id="cm-api-key"
@@ -443,7 +441,6 @@ export default function CustomModelModal({
                       : t('settings.customModels.placeholders.apiKey')
                   }
                   aria-invalid={!!errors.api_key || undefined}
-                  className="rounded-xl"
                 />
                 {isEditMode && (
                   <p className="text-muted-foreground text-xs">
@@ -469,7 +466,6 @@ export default function CustomModelModal({
                 placeholder={t(
                   'settings.customModels.placeholders.description',
                 )}
-                className="rounded-xl"
               />
             </div>
 
@@ -604,7 +600,7 @@ export default function CustomModelModal({
                     }
                   }}
                   aria-invalid={!!errors.context_window || undefined}
-                  className="w-full rounded-xl sm:w-40"
+                  className="w-full sm:w-40"
                 />
                 {errors.context_window && (
                   <p className="text-destructive text-xs">
@@ -615,21 +611,21 @@ export default function CustomModelModal({
             </div>
 
             {testResult && (
-              <div
-                className={`rounded-xl p-3 text-sm ${
-                  testResult.ok
-                    ? 'bg-green-50 text-green-700 dark:bg-green-900/40 dark:text-green-300'
-                    : 'bg-red-50 text-red-700 dark:bg-red-900/40 dark:text-red-300'
-                }`}
-              >
-                {testResult.message}
-              </div>
+              <Alert variant={testResult.ok ? 'success' : 'destructive'}>
+                {testResult.ok ? (
+                  <CircleCheck className="size-4" aria-hidden="true" />
+                ) : (
+                  <CircleAlert className="size-4" aria-hidden="true" />
+                )}
+                <AlertDescription>{testResult.message}</AlertDescription>
+              </Alert>
             )}
 
             {errors.general && (
-              <div className="rounded-xl bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/40 dark:text-red-300">
-                {errors.general}
-              </div>
+              <Alert variant="destructive">
+                <CircleAlert className="size-4" aria-hidden="true" />
+                <AlertDescription>{errors.general}</AlertDescription>
+              </Alert>
             )}
           </div>
         </div>
@@ -642,7 +638,9 @@ export default function CustomModelModal({
               onClick={handleTest}
               disabled={!canTest || testing || saving}
               title={testDisabledHint}
-              className="w-full rounded-3xl px-6 disabled:cursor-not-allowed sm:w-auto"
+              size="lg"
+              shape="pill"
+              className="w-full sm:w-auto"
             >
               {testing ? (
                 <div className="flex items-center justify-center">
@@ -661,7 +659,9 @@ export default function CustomModelModal({
                 variant="ghost"
                 onClick={closeModal}
                 disabled={saving}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('cancel')}
               </Button>
@@ -669,7 +669,9 @@ export default function CustomModelModal({
                 type="button"
                 onClick={handleSave}
                 disabled={saving}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {saving ? (
                   <div className="flex items-center justify-center">
@@ -696,19 +698,20 @@ interface CapabilityChipProps {
   onClick: () => void;
 }
 
-function CapabilityChip({ label, active, onClick }: CapabilityChipProps) {
+export function CapabilityChip({
+  label,
+  active,
+  onClick,
+}: CapabilityChipProps) {
   return (
     <Button
       type="button"
-      variant="outline"
+      variant={active ? 'secondary' : 'ghost-muted'}
+      size="sm"
+      shape="pill"
       role="switch"
       aria-checked={active}
       onClick={onClick}
-      className={`h-auto rounded-full border px-3 py-1.5 shadow-none ${
-        active
-          ? 'border-emerald-500/50 bg-emerald-500/10 text-emerald-700 hover:bg-emerald-500/10 hover:text-emerald-700 dark:border-emerald-400/40 dark:bg-emerald-400/10 dark:text-emerald-300 dark:hover:bg-emerald-400/10 dark:hover:text-emerald-300'
-          : 'text-muted-foreground'
-      }`}
     >
       {active && <Check size={14} strokeWidth={2.5} />}
       {label}
diff --git a/frontend/src/modals/FolderManagementModal.tsx b/frontend/src/modals/FolderManagementModal.tsx
index e09cca65..9cc043e5 100644
--- a/frontend/src/modals/FolderManagementModal.tsx
+++ b/frontend/src/modals/FolderManagementModal.tsx
@@ -67,7 +67,7 @@ export default function FolderNameModal({
             type="button"
             variant="ghost"
             onClick={handleCancel}
-            className="rounded-3xl px-5"
+            shape="pill"
           >
             {t('cancel')}
           </Button>
@@ -75,7 +75,7 @@ export default function FolderNameModal({
             type="button"
             onClick={handleSubmit}
             disabled={!name.trim()}
-            className="rounded-3xl px-5"
+            shape="pill"
           >
             {mode === 'create'
               ? t('agents.folders.createFolder')
diff --git a/frontend/src/modals/ImportAgentModal.test.tsx b/frontend/src/modals/ImportAgentModal.test.tsx
new file mode 100644
index 00000000..910fa5cc
--- /dev/null
+++ b/frontend/src/modals/ImportAgentModal.test.tsx
@@ -0,0 +1,135 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: (selector: (state: unknown) => unknown) =>
+    selector({ preference: { token: 'token', sourceDocs: [] } }),
+}));
+
+vi.mock('react-router-dom', () => ({ useNavigate: () => vi.fn() }));
+
+// The picker is exercised through its onDrop handler: happy-dom can't drive a
+// real drag or a file chooser, and the drop is what stages the YAML.
+const dropzone = vi.hoisted(() => ({
+  onDrop: null as null | ((accepted: File[], rejected: unknown[]) => void),
+}));
+vi.mock('react-dropzone', () => ({
+  useDropzone: (options: {
+    onDrop: (accepted: File[], rejected: unknown[]) => void;
+  }) => {
+    dropzone.onDrop = options.onDrop;
+    return {
+      getRootProps: () => ({}),
+      getInputProps: () => ({}),
+      isDragActive: false,
+      isDragReject: false,
+    };
+  },
+}));
+
+const service = vi.hoisted(() => ({
+  planImportAgent: vi.fn(),
+  importAgent: vi.fn(),
+}));
+vi.mock('../api/services/userService', () => ({ default: service }));
+
+import ImportAgentModal from './ImportAgentModal';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const jsonResponse = (body: unknown) =>
+  ({ ok: true, json: async () => body }) as Response;
+
+const flush = () => act(async () => new Promise((r) => setTimeout(r, 0)));
+
+const clickButton = async (label: string) => {
+  const button = Array.from(document.querySelectorAll('button')).find(
+    (b) => b.textContent === label,
+  );
+  expect(button).toBeDefined();
+  await act(async () => button!.click());
+  await flush();
+};
+
+describe('ImportAgentModal', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    service.planImportAgent.mockResolvedValue(
+      jsonResponse({
+        success: true,
+        plan: {
+          target: { action: 'create', agent_id: null, matched_by: null },
+          sources: [],
+          tools: [],
+          prompt: { status: 'default' },
+          models: [],
+        },
+      }),
+    );
+    service.importAgent.mockResolvedValue(
+      jsonResponse({
+        success: true,
+        agent_id: 'agent-1',
+        agent_type: 'classic',
+        status: 'draft',
+        warnings: [
+          "Source 'Carrier Rate Cards' not found; left unattached",
+          "Model 'gpt-4o' not available; skipped",
+        ],
+      }),
+    );
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.clearAllMocks();
+  });
+
+  it('shows post-import warnings as a polite warning alert', async () => {
+    act(() => {
+      root.render(
+        <ImportAgentModal
+          modalState="ACTIVE"
+          setModalState={() => undefined}
+        />,
+      );
+    });
+
+    const file = new File(['name: Agent\n'], 'agent.yaml', {
+      type: 'application/x-yaml',
+    });
+    await act(async () => dropzone.onDrop!([file], []));
+    await flush();
+    await clickButton('modals.importAgent.review');
+    await clickButton('modals.importAgent.import');
+
+    const notice = document.querySelector('[role="status"]');
+    expect(notice).not.toBeNull();
+    expect(notice!.className).toContain('bg-warning/10');
+    expect(notice!.className).toContain('text-warning');
+    expect(notice!.querySelector('svg')?.getAttribute('aria-hidden')).toBe(
+      'true',
+    );
+    expect(notice!.querySelector('h5')?.textContent).toBe(
+      'modals.importAgent.warningsTitle',
+    );
+    const items = Array.from(notice!.querySelectorAll('ul > li')).map(
+      (li) => li.textContent,
+    );
+    expect(items).toEqual([
+      "Source 'Carrier Rate Cards' not found; left unattached",
+      "Model 'gpt-4o' not available; skipped",
+    ]);
+    expect(document.querySelector('[role="alert"]')).toBeNull();
+  });
+});
diff --git a/frontend/src/modals/ImportAgentModal.tsx b/frontend/src/modals/ImportAgentModal.tsx
index 47cc573d..fa566730 100644
--- a/frontend/src/modals/ImportAgentModal.tsx
+++ b/frontend/src/modals/ImportAgentModal.tsx
@@ -8,6 +8,7 @@ import { useNavigate } from 'react-router-dom';
 import userService from '../api/services/userService';
 import Upload from '../assets/upload.svg';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription, AlertTitle } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Modal } from '../components/ui/modal';
@@ -252,7 +253,7 @@ export default function ImportAgentModal({
             handleClose();
             if (path) navigate(path);
           }}
-          className="rounded-3xl px-5"
+          shape="pill"
         >
           {t('modals.importAgent.continueToAgent')}
         </Button>
@@ -264,7 +265,7 @@ export default function ImportAgentModal({
           type="button"
           variant="ghost"
           onClick={handleClose}
-          className="rounded-3xl px-5"
+          shape="pill"
         >
           {t('modals.importAgent.cancel')}
         </Button>
@@ -273,7 +274,8 @@ export default function ImportAgentModal({
             type="button"
             onClick={handleAnalyze}
             disabled={!yamlText || loading}
-            className="w-24 rounded-3xl px-5 disabled:cursor-not-allowed"
+            shape="pill"
+            className="w-24"
           >
             {loading ? (
               <Spinner size="small" />
@@ -286,7 +288,7 @@ export default function ImportAgentModal({
             type="button"
             onClick={handleImport}
             disabled={importing}
-            className="rounded-3xl px-5 disabled:cursor-not-allowed"
+            shape="pill"
           >
             {importing ? (
               <Spinner size="small" />
@@ -310,18 +312,21 @@ export default function ImportAgentModal({
     >
       <div className="flex flex-col gap-4">
         {warnings ? (
-          <div className="flex flex-col gap-3">
-            <p className="text-foreground text-sm">
+          <Alert variant="warning" role="status">
+            <AlertTriangle aria-hidden="true" />
+            <AlertTitle>
               {importedStatus === 'published'
                 ? t('modals.importAgent.warningsTitlePublished')
                 : t('modals.importAgent.warningsTitle')}
-            </p>
-            <ul className="list-disc space-y-1 pl-5 text-sm text-yellow-700 dark:text-yellow-400">
-              {warnings.map((w, i) => (
-                <li key={i}>{w}</li>
-              ))}
-            </ul>
-          </div>
+            </AlertTitle>
+            <AlertDescription>
+              <ul className="list-disc space-y-1 pl-5">
+                {warnings.map((w, i) => (
+                  <li key={i}>{w}</li>
+                ))}
+              </ul>
+            </AlertDescription>
+          </Alert>
         ) : !plan ? (
           <div className="flex flex-col gap-4">
             <p className="text-muted-foreground text-sm">
@@ -372,7 +377,7 @@ export default function ImportAgentModal({
                 </p>
               ) : (
                 <p className="flex items-center gap-2 text-sm">
-                  <CheckCircle2 className="h-4 w-4 text-green-600 dark:text-green-400" />
+                  <CheckCircle2 className="text-success h-4 w-4" />
                   {plan.workflow.action === 'update'
                     ? t('modals.importAgent.workflowUpdate', {
                         nodes: plan.workflow.nodes,
@@ -388,13 +393,13 @@ export default function ImportAgentModal({
                 {plan.sources.map((s) =>
                   s.status === 'matched' ? (
                     <p key={s.name} className="flex items-center gap-2 text-sm">
-                      <CheckCircle2 className="h-4 w-4 text-green-600 dark:text-green-400" />
+                      <CheckCircle2 className="text-success h-4 w-4" />
                       {t('modals.importAgent.sourceMatched', { name: s.name })}
                     </p>
                   ) : (
                     <div key={s.name} className="flex flex-col gap-1">
                       <p className="flex items-center gap-2 text-sm">
-                        <AlertTriangle className="h-4 w-4 text-yellow-600 dark:text-yellow-400" />
+                        <AlertTriangle className="text-warning h-4 w-4" />
                         {t('modals.importAgent.sourceMissing', {
                           name: s.name,
                         })}
@@ -437,7 +442,7 @@ export default function ImportAgentModal({
                   <div key={tool.key} className="flex flex-col gap-1">
                     {tool.status === 'builtin' && (
                       <p className="flex items-center gap-2 text-sm">
-                        <CheckCircle2 className="h-4 w-4 text-green-600 dark:text-green-400" />
+                        <CheckCircle2 className="text-success h-4 w-4" />
                         {t('modals.importAgent.toolBuiltin', {
                           type: tool.type,
                         })}
@@ -445,7 +450,7 @@ export default function ImportAgentModal({
                     )}
                     {tool.status === 'reuse' && (
                       <p className="flex items-center gap-2 text-sm">
-                        <CheckCircle2 className="h-4 w-4 text-green-600 dark:text-green-400" />
+                        <CheckCircle2 className="text-success h-4 w-4" />
                         {t('modals.importAgent.toolReuse', {
                           name: tool.name || tool.type,
                         })}
@@ -478,7 +483,6 @@ export default function ImportAgentModal({
                             onChange={(e) =>
                               setToolSecret(tool.key, field, e.target.value)
                             }
-                            className="bg-card h-auto rounded-lg px-3 py-2 text-sm md:text-sm"
                           />
                         ))}
                       </div>
@@ -509,7 +513,6 @@ export default function ImportAgentModal({
                             [m.display_name || '']: e.target.value,
                           }))
                         }
-                        className="bg-card h-auto rounded-lg px-3 py-2 text-sm md:text-sm"
                       />
                     </div>
                   ))}
diff --git a/frontend/src/modals/ImportSpecModal.tsx b/frontend/src/modals/ImportSpecModal.tsx
index a5bee57b..5a09c41e 100644
--- a/frontend/src/modals/ImportSpecModal.tsx
+++ b/frontend/src/modals/ImportSpecModal.tsx
@@ -6,13 +6,14 @@ import { useSelector } from 'react-redux';
 import userService from '../api/services/userService';
 import Upload from '../assets/upload.svg';
 import Spinner from '../components/Spinner';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Modal } from '../components/ui/modal';
 import { ActiveState } from '../models/misc';
 import { selectToken } from '../preferences/preferenceSlice';
 import { APIActionType } from '../settings/types';
-import { getMethodColorClass } from '../utils/httpMethodColors';
+import { getMethodBadgeVariant } from '../utils/httpMethodColors';
 
 interface ImportSpecModalProps {
   modalState: ActiveState;
@@ -181,7 +182,7 @@ export default function ImportSpecModal({
             type="button"
             variant="ghost"
             onClick={handleClose}
-            className="rounded-3xl px-5"
+            shape="pill"
           >
             {t('modals.importSpec.cancel')}
           </Button>
@@ -190,7 +191,8 @@ export default function ImportSpecModal({
               type="button"
               onClick={handleParse}
               disabled={!file || loading}
-              className="w-20 rounded-3xl px-5 disabled:cursor-not-allowed"
+              shape="pill"
+              className="w-20"
             >
               {loading && <Spinner size="small" />}
               {!loading && t('modals.importSpec.parse')}
@@ -200,7 +202,7 @@ export default function ImportSpecModal({
               type="button"
               onClick={handleImport}
               disabled={selectedActions.size === 0}
-              className="rounded-3xl px-5 disabled:cursor-not-allowed"
+              shape="pill"
             >
               {t('modals.importSpec.import', { count: selectedActions.size })}
             </Button>
@@ -211,7 +213,7 @@ export default function ImportSpecModal({
       <div className="flex flex-col gap-4">
         {!parsedResult ? (
           <div className="flex flex-col gap-4">
-            <p className="text-sm text-gray-600 dark:text-gray-400">
+            <p className="text-muted-foreground text-sm">
               {t('modals.importSpec.description')}
             </p>
 
@@ -234,15 +236,13 @@ export default function ImportSpecModal({
               <p className="text-foreground dark:text-foreground text-sm font-medium">
                 {file ? file.name : t('modals.importSpec.dropzoneText')}
               </p>
-              <p className="mt-1 text-xs text-gray-500 dark:text-gray-400">
+              <p className="text-muted-foreground mt-1 text-xs">
                 {t('modals.importSpec.supportedFormats')}
               </p>
               <input {...getInputProps()} />
             </div>
 
-            {error && (
-              <p className="text-sm text-red-500 dark:text-red-400">{error}</p>
-            )}
+            {error && <p className="text-destructive text-sm">{error}</p>}
           </div>
         ) : (
           <div className="flex flex-col gap-4">
@@ -251,7 +251,7 @@ export default function ImportSpecModal({
                 {parsedResult.metadata.title}
               </h3>
               {parsedResult.metadata.description && (
-                <p className="mt-1 line-clamp-2 text-sm text-gray-600 dark:text-gray-400">
+                <p className="text-muted-foreground mt-1 line-clamp-2 text-sm">
                   {parsedResult.metadata.description}
                 </p>
               )}
@@ -260,14 +260,14 @@ export default function ImportSpecModal({
                 {parsedResult.metadata.version}
               </p>
               <div className="mt-3">
-                <label className="mb-1 block text-xs font-medium text-gray-700 dark:text-gray-300">
+                <label className="text-foreground mb-1 block text-xs font-medium">
                   {t('modals.importSpec.baseUrl')}
                 </label>
                 <Input
                   type="text"
+                  variant="filled"
                   value={baseUrl}
                   onChange={(e) => setBaseUrl(e.target.value)}
-                  className="bg-card h-auto rounded-lg px-3 py-2 text-sm md:text-sm"
                   placeholder={
                     parsedResult.metadata.base_url || 'https://api.example.com'
                   }
@@ -286,7 +286,7 @@ export default function ImportSpecModal({
                 variant="link"
                 size="sm"
                 onClick={toggleAll}
-                className="h-auto p-0"
+                className="-my-1.5 -mr-3"
               >
                 {selectedActions.size === parsedResult.actions.length
                   ? t('modals.importSpec.deselectAll')
@@ -304,24 +304,22 @@ export default function ImportSpecModal({
                     type="checkbox"
                     checked={selectedActions.has(index)}
                     onChange={() => toggleAction(index)}
-                    className="text-primary focus:ring-ring mt-1 h-4 w-4 rounded border-gray-300"
+                    className="text-primary focus:ring-ring border-border mt-1 h-4 w-4 rounded"
                   />
                   <div className="min-w-0 flex-1">
                     <div className="flex items-center gap-2">
-                      <span
-                        className={`rounded px-2 py-0.5 text-xs font-medium ${getMethodColorClass(action.method)}`}
-                      >
+                      <Badge variant={getMethodBadgeVariant(action.method)}>
                         {action.method.toUpperCase()}
-                      </span>
+                      </Badge>
                       <span className="text-foreground dark:text-foreground truncate font-medium">
                         {action.name}
                       </span>
                     </div>
-                    <p className="mt-1 truncate text-sm text-gray-500 dark:text-gray-400">
+                    <p className="text-muted-foreground mt-1 truncate text-sm">
                       {action.url}
                     </p>
                     {action.description && (
-                      <p className="mt-1 line-clamp-1 text-xs text-gray-400 dark:text-gray-500">
+                      <p className="text-muted-foreground/70 mt-1 line-clamp-1 text-xs">
                         {action.description}
                       </p>
                     )}
diff --git a/frontend/src/modals/JWTModal.tsx b/frontend/src/modals/JWTModal.tsx
index 9734089d..626bab33 100644
--- a/frontend/src/modals/JWTModal.tsx
+++ b/frontend/src/modals/JWTModal.tsx
@@ -30,7 +30,6 @@ export default function JWTModal({
           <Input
             name="JWT Token"
             type="text"
-            className="rounded-md"
             value={jwtToken}
             onChange={(e) => setJwtToken(e.target.value)}
             data-testid="jwt-token-input"
@@ -40,7 +39,8 @@ export default function JWTModal({
           type="button"
           disabled={jwtToken.length === 0}
           onClick={handleTokenSubmit.bind(null, jwtToken)}
-          className="float-right mt-4 rounded-3xl px-5"
+          shape="pill"
+          className="float-right mt-4"
           data-testid="jwt-token-submit"
         >
           Save Token
diff --git a/frontend/src/modals/MCPServerModal.tsx b/frontend/src/modals/MCPServerModal.tsx
index 48628e5a..defd6279 100644
--- a/frontend/src/modals/MCPServerModal.tsx
+++ b/frontend/src/modals/MCPServerModal.tsx
@@ -1,3 +1,4 @@
+import { CircleAlert, CircleCheck, TriangleAlert } from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
@@ -5,6 +6,7 @@ import { useSelector } from 'react-redux';
 import { baseURL } from '../api/client';
 import userService from '../api/services/userService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Label } from '../components/ui/label';
@@ -456,7 +458,7 @@ export default function MCPServerModal({
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="api_key">
                 {t('settings.tools.mcp.authTypes.apiKey')}
-                <span className="text-red-500">*</span>
+                <span className="text-destructive">*</span>
               </Label>
               <Input
                 id="api_key"
@@ -465,7 +467,6 @@ export default function MCPServerModal({
                 onChange={(e) => handleInputChange('api_key', e.target.value)}
                 placeholder={t('settings.tools.mcp.placeholders.apiKey')}
                 aria-invalid={!!errors.api_key || undefined}
-                className="rounded-xl"
               />
               {errors.api_key && (
                 <p className="text-destructive text-xs">{errors.api_key}</p>
@@ -483,7 +484,6 @@ export default function MCPServerModal({
                   handleInputChange('header_name', e.target.value)
                 }
                 placeholder="X-API-Key"
-                className="rounded-xl"
               />
             </div>
           </div>
@@ -493,7 +493,7 @@ export default function MCPServerModal({
           <div className="flex flex-col gap-1.5">
             <Label htmlFor="bearer_token">
               {t('settings.tools.mcp.authTypes.bearer')}
-              <span className="text-red-500">*</span>
+              <span className="text-destructive">*</span>
             </Label>
             <Input
               id="bearer_token"
@@ -504,7 +504,6 @@ export default function MCPServerModal({
               }
               placeholder={t('settings.tools.mcp.placeholders.bearerToken')}
               aria-invalid={!!errors.bearer_token || undefined}
-              className="rounded-xl"
             />
             {errors.bearer_token && (
               <p className="text-destructive text-xs">{errors.bearer_token}</p>
@@ -517,7 +516,7 @@ export default function MCPServerModal({
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="username">
                 {t('settings.tools.mcp.username')}
-                <span className="text-red-500">*</span>
+                <span className="text-destructive">*</span>
               </Label>
               <Input
                 id="username"
@@ -526,7 +525,6 @@ export default function MCPServerModal({
                 onChange={(e) => handleInputChange('username', e.target.value)}
                 placeholder={t('settings.tools.mcp.placeholders.username')}
                 aria-invalid={!!errors.username || undefined}
-                className="rounded-xl"
               />
               {errors.username && (
                 <p className="text-destructive text-xs">{errors.username}</p>
@@ -535,7 +533,7 @@ export default function MCPServerModal({
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="password">
                 {t('settings.tools.mcp.password')}
-                <span className="text-red-500">*</span>
+                <span className="text-destructive">*</span>
               </Label>
               <Input
                 id="password"
@@ -544,7 +542,6 @@ export default function MCPServerModal({
                 onChange={(e) => handleInputChange('password', e.target.value)}
                 placeholder={t('settings.tools.mcp.placeholders.password')}
                 aria-invalid={!!errors.password || undefined}
-                className="rounded-xl"
               />
               {errors.password && (
                 <p className="text-destructive text-xs">{errors.password}</p>
@@ -566,7 +563,6 @@ export default function MCPServerModal({
                 handleInputChange('oauth_scopes', e.target.value)
               }
               placeholder="read, write"
-              className="rounded-xl"
             />
           </div>
         );
@@ -600,17 +596,20 @@ export default function MCPServerModal({
           <div className="flex flex-col gap-4 px-0.5 py-4">
             {server?.has_encrypted_credentials &&
               formData.auth_type !== 'oauth' && (
-                <div className="rounded-xl bg-amber-50 p-3 text-sm text-amber-700 dark:bg-amber-900/30 dark:text-amber-300">
-                  {t('settings.tools.mcp.reenterCredentials', {
-                    defaultValue:
-                      'Re-enter your credentials to test and update the connection.',
-                  })}
-                </div>
+                <Alert variant="warning">
+                  <TriangleAlert className="size-4" aria-hidden="true" />
+                  <AlertDescription>
+                    {t('settings.tools.mcp.reenterCredentials', {
+                      defaultValue:
+                        'Re-enter your credentials to test and update the connection.',
+                    })}
+                  </AlertDescription>
+                </Alert>
               )}
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="mcp-name">
                 {t('settings.tools.mcp.serverName')}
-                <span className="text-red-500">*</span>
+                <span className="text-destructive">*</span>
               </Label>
               <Input
                 id="mcp-name"
@@ -619,7 +618,6 @@ export default function MCPServerModal({
                 onChange={(e) => handleInputChange('name', e.target.value)}
                 placeholder={t('settings.tools.mcp.serverName')}
                 aria-invalid={!!errors.name || undefined}
-                className="rounded-xl"
               />
               {errors.name && (
                 <p className="text-destructive text-xs">{errors.name}</p>
@@ -629,7 +627,7 @@ export default function MCPServerModal({
             <div className="flex flex-col gap-1.5">
               <Label htmlFor="mcp-url">
                 {t('settings.tools.mcp.serverUrl')}
-                <span className="text-red-500">*</span>
+                <span className="text-destructive">*</span>
               </Label>
               <Input
                 id="mcp-url"
@@ -640,7 +638,6 @@ export default function MCPServerModal({
                 }
                 placeholder="https://example.com/mcp"
                 aria-invalid={!!errors.server_url || undefined}
-                className="rounded-xl"
               />
               {errors.server_url && (
                 <p className="text-destructive text-xs">{errors.server_url}</p>
@@ -653,11 +650,7 @@ export default function MCPServerModal({
                 value={formData.auth_type}
                 onValueChange={(v) => handleInputChange('auth_type', v)}
               >
-                <SelectTrigger
-                  variant="ghost"
-                  size="lg"
-                  className="w-full rounded-xl"
-                >
+                <SelectTrigger variant="ghost" size="lg" className="w-full">
                   <SelectValue placeholder={t('settings.tools.mcp.authType')} />
                 </SelectTrigger>
                 <SelectContent>
@@ -695,7 +688,6 @@ export default function MCPServerModal({
                 min={1}
                 max={300}
                 aria-invalid={!!errors.timeout || undefined}
-                className="rounded-xl"
               />
               {errors.timeout && (
                 <p className="text-destructive text-xs">{errors.timeout}</p>
@@ -703,41 +695,42 @@ export default function MCPServerModal({
             </div>
 
             {testResult && (
-              <div
-                className={`rounded-xl p-4 text-sm ${
-                  testResult.success
-                    ? 'bg-green-50 text-green-700 dark:bg-green-900/40 dark:text-green-300'
-                    : 'bg-red-50 text-red-700 dark:bg-red-900/40 dark:text-red-300'
-                }`}
-              >
-                <p>{testResult.message}</p>
-                {testResult.authorization_url && (
-                  <a
-                    href={testResult.authorization_url}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    onClick={(e) => {
-                      e.preventDefault();
-                      const popup = window.open(
-                        testResult.authorization_url,
-                        'oauthPopup',
-                        'width=600,height=700',
-                      );
-                      if (popup) oauthPopupRef.current = popup;
-                    }}
-                    className="mt-1.5 inline-block font-medium underline"
-                  >
-                    {t('settings.tools.mcp.openAuthPage', {
-                      defaultValue: 'Open authorization page',
-                    })}
-                  </a>
+              <Alert variant={testResult.success ? 'success' : 'destructive'}>
+                {testResult.success ? (
+                  <CircleCheck className="size-4" aria-hidden="true" />
+                ) : (
+                  <CircleAlert className="size-4" aria-hidden="true" />
                 )}
-              </div>
+                <AlertDescription>
+                  <p>{testResult.message}</p>
+                  {testResult.authorization_url && (
+                    <a
+                      href={testResult.authorization_url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      onClick={(e) => {
+                        e.preventDefault();
+                        const popup = window.open(
+                          testResult.authorization_url,
+                          'oauthPopup',
+                          'width=600,height=700',
+                        );
+                        if (popup) oauthPopupRef.current = popup;
+                      }}
+                      className="mt-1.5 inline-block font-medium underline"
+                    >
+                      {t('settings.tools.mcp.openAuthPage', {
+                        defaultValue: 'Open authorization page',
+                      })}
+                    </a>
+                  )}
+                </AlertDescription>
+              </Alert>
             )}
 
             {discoveredTools.length > 0 && testResult?.success && (
-              <div className="border-border dark:border-border rounded-xl border p-4">
-                <h4 className="mb-2 text-sm font-medium text-gray-900 dark:text-white">
+              <div className="border-border rounded-xl border p-4">
+                <h4 className="text-foreground mb-2 text-sm font-medium">
                   {t('settings.tools.mcp.discoveredTools', {
                     count: discoveredTools.length,
                     defaultValue: `Discovered Actions (${discoveredTools.length})`,
@@ -747,15 +740,15 @@ export default function MCPServerModal({
                   {discoveredTools.map((tool) => (
                     <li
                       key={tool.name}
-                      className="flex items-start gap-2 rounded-lg bg-gray-50 px-3 py-2 text-sm dark:bg-white/5"
+                      className="bg-muted flex items-start gap-2 rounded-lg px-3 py-2 text-sm"
                     >
                       <span className="text-primary mt-0.5">&#9679;</span>
                       <div className="min-w-0">
-                        <span className="font-medium text-gray-900 dark:text-white">
+                        <span className="text-foreground font-medium">
                           {tool.name}
                         </span>
                         {tool.description && (
-                          <p className="truncate text-xs text-gray-500 dark:text-gray-400">
+                          <p className="text-muted-foreground truncate text-xs">
                             {tool.description}
                           </p>
                         )}
@@ -766,9 +759,10 @@ export default function MCPServerModal({
               </div>
             )}
             {errors.general && (
-              <div className="rounded-xl bg-red-50 p-4 text-sm text-red-700 dark:bg-red-900/40 dark:text-red-300">
-                {errors.general}
-              </div>
+              <Alert variant="destructive">
+                <CircleAlert className="size-4" aria-hidden="true" />
+                <AlertDescription>{errors.general}</AlertDescription>
+              </Alert>
             )}
           </div>
         </div>
@@ -780,7 +774,9 @@ export default function MCPServerModal({
               variant="outline"
               onClick={testConnection}
               disabled={testing}
-              className="w-full rounded-3xl px-6 sm:w-auto"
+              size="lg"
+              shape="pill"
+              className="w-full sm:w-auto"
             >
               {testing ? (
                 <div className="flex items-center justify-center">
@@ -802,7 +798,9 @@ export default function MCPServerModal({
                   setModalState('INACTIVE');
                   resetForm();
                 }}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('settings.tools.mcp.cancel')}
               </Button>
@@ -810,7 +808,9 @@ export default function MCPServerModal({
                 type="button"
                 onClick={handleSave}
                 disabled={loading || !saveActive}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {loading ? (
                   <div className="flex items-center justify-center">
diff --git a/frontend/src/modals/MoveToFolderModal.test.tsx b/frontend/src/modals/MoveToFolderModal.test.tsx
new file mode 100644
index 00000000..4b577025
--- /dev/null
+++ b/frontend/src/modals/MoveToFolderModal.test.tsx
@@ -0,0 +1,252 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('../hooks', () => ({
+  useMediaQuery: () => ({ isMobile: false, isTablet: false, isDesktop: true }),
+}));
+
+const getAgentFolders = vi.fn();
+vi.mock('../api/services/userService', () => ({
+  default: {
+    getAgentFolders: (...args: unknown[]) => getAgentFolders(...args),
+    createAgentFolder: vi.fn(),
+    moveAgentToFolder: vi.fn(),
+  },
+}));
+
+vi.mock('react-redux', () => ({
+  useDispatch: () => vi.fn(),
+  useSelector: () => 'token',
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import MoveToFolderModal from './MoveToFolderModal';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const folders = [
+  { id: 'f1', name: 'Carriers', parent_id: null },
+  { id: 'f2', name: 'Customs', parent_id: null },
+  { id: 'f3', name: 'Rotterdam', parent_id: 'f1' },
+];
+
+describe('MoveToFolderModal', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    getAgentFolders.mockReset();
+    getAgentFolders.mockResolvedValue({
+      ok: true,
+      json: async () => ({ folders }),
+    });
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async (currentFolderId?: string) => {
+    await act(async () => {
+      root.render(
+        <MoveToFolderModal
+          modalState="ACTIVE"
+          setModalState={() => undefined}
+          agentName="Vendor Due Diligence"
+          agentId="a1"
+          currentFolderId={currentFolderId}
+          onMoveSuccess={() => undefined}
+        />,
+      );
+    });
+  };
+
+  const trail = () =>
+    document.body.querySelector('nav[aria-label="breadcrumb"]');
+  const rowFor = (name: string) =>
+    Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>('[data-slot="button"]'),
+    ).find((b) => b.textContent?.includes(name));
+
+  it('shows the root as the current breadcrumb page, not a button', async () => {
+    await render();
+    const page = trail()?.querySelector('[data-slot="breadcrumb-page"]');
+    expect(page?.textContent).toBe('agents.filters.byMe');
+    expect(page?.getAttribute('title')).toBe('agents.filters.byMe');
+    expect(trail()?.querySelector('button')).toBeNull();
+  });
+
+  const items = () =>
+    Array.from(
+      document.body.querySelectorAll<HTMLElement>('[data-slot="command-item"]'),
+    );
+  const itemFor = (name: string) =>
+    items().find((el) => el.textContent?.includes(name));
+  const chevronOf = (name: string) =>
+    itemFor(name)?.querySelector<HTMLButtonElement>('[data-slot="button"]');
+
+  it('turns ancestors into breadcrumb link buttons after navigating in', async () => {
+    await render();
+    await act(async () => chevronOf('Carriers')?.click());
+
+    const page = trail()?.querySelector('[data-slot="breadcrumb-page"]');
+    expect(page?.textContent).toBe('Carriers');
+    expect(page?.getAttribute('title')).toBe('Carriers');
+    const link = trail()?.querySelector<HTMLButtonElement>(
+      '[data-slot="breadcrumb-link"]',
+    );
+    expect(link?.tagName).toBe('BUTTON');
+    expect(link?.getAttribute('type')).toBe('button');
+    expect(link?.textContent).toBe('agents.filters.byMe');
+    expect(itemFor('Rotterdam')).toBeDefined();
+
+    await act(async () => link?.click());
+    expect(
+      trail()?.querySelector('[data-slot="breadcrumb-page"]')?.textContent,
+    ).toBe('agents.filters.byMe');
+  });
+
+  it('renders the folder rows as cmdk items in a focusable Command', async () => {
+    await render('f2');
+    const rows = items();
+    expect(rows.map((r) => r.textContent)).toEqual([
+      'agents.folders.noFolder',
+      'Carriers',
+      'Customs',
+    ]);
+    rows.forEach((r) => {
+      expect(r.hasAttribute('cmdk-item')).toBe(true);
+      expect(r.getAttribute('role')).toBe('option');
+    });
+    const cmd = document.body.querySelector('[data-slot="command"]');
+    expect(cmd?.getAttribute('tabindex')).toBe('0');
+    // No nested role="button" span inside a row any more.
+    expect(
+      document.body.querySelector('[cmdk-item] [role="button"]'),
+    ).toBeNull();
+  });
+
+  it('marks the chosen folder with CommandItem checked and aria-checked', async () => {
+    await render('f2');
+    expect(itemFor('Customs')?.getAttribute('data-checked')).toBe('true');
+    expect(itemFor('Customs')?.getAttribute('aria-checked')).toBe('true');
+    for (const name of ['Carriers', 'agents.folders.noFolder']) {
+      expect(itemFor(name)?.hasAttribute('data-checked')).toBe(false);
+      expect(itemFor(name)?.getAttribute('aria-checked')).toBe('false');
+      expect(itemFor(name)?.hasAttribute('aria-pressed')).toBe(false);
+    }
+
+    await act(async () => itemFor('Carriers')?.click());
+    expect(itemFor('Carriers')?.getAttribute('data-checked')).toBe('true');
+    expect(itemFor('Carriers')?.getAttribute('aria-checked')).toBe('true');
+    expect(itemFor('Customs')?.hasAttribute('data-checked')).toBe(false);
+
+    await act(async () => itemFor('agents.folders.noFolder')?.click());
+    expect(
+      itemFor('agents.folders.noFolder')?.getAttribute('aria-checked'),
+    ).toBe('true');
+    expect(itemFor('Carriers')?.getAttribute('aria-checked')).toBe('false');
+  });
+
+  it('highlights no row on open, not even "No folder (root)"', async () => {
+    await render('f2');
+    expect(items().length).toBe(3);
+    expect(
+      items().filter((r) => r.getAttribute('data-selected') === 'true'),
+    ).toHaveLength(0);
+  });
+
+  it('keys rows by folder id, so same-named folders highlight separately', async () => {
+    getAgentFolders.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        folders: [
+          { id: 'd1', name: 'Archive', parent_id: null },
+          { id: 'd2', name: 'Archive', parent_id: null },
+        ],
+      }),
+    });
+    await render();
+    const [first, second] = items();
+    await act(async () => {
+      first.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }));
+    });
+    expect(first.getAttribute('data-selected')).toBe('true');
+    expect(second.getAttribute('data-selected')).toBe('false');
+
+    await act(async () => second.click());
+    expect(second.getAttribute('data-checked')).toBe('true');
+    expect(first.hasAttribute('data-checked')).toBe(false);
+  });
+
+  it('drills in from the chevron without changing the chosen folder', async () => {
+    await render('f2');
+    const chevron = chevronOf('Carriers');
+    expect(chevron?.getAttribute('type')).toBe('button');
+    expect(chevron?.getAttribute('data-variant')).toBe('ghost-muted');
+    expect(chevron?.getAttribute('data-size')).toBe('icon-xs');
+    expect(chevron?.getAttribute('aria-label')).toBe(
+      'agents.folders.openFolder',
+    );
+    // The folder icon is decorative; the row's text names it.
+    expect(itemFor('Carriers')?.querySelector('img')?.getAttribute('alt')).toBe(
+      '',
+    );
+    expect(chevron?.querySelector('svg')).not.toBeNull();
+    // The chevron is the row's last child, and only rows with subfolders get one.
+    expect(itemFor('Carriers')?.lastElementChild).toBe(chevron);
+    expect(chevronOf('Customs')).toBeNull();
+
+    await act(async () => chevron?.click());
+    expect(itemFor('Rotterdam')).toBeDefined();
+    expect(itemFor('Rotterdam')?.getAttribute('aria-checked')).toBe('false');
+
+    await act(async () =>
+      trail()
+        ?.querySelector<HTMLButtonElement>('[data-slot="breadcrumb-link"]')
+        ?.click(),
+    );
+    expect(itemFor('Customs')?.getAttribute('data-checked')).toBe('true');
+    expect(itemFor('Carriers')?.hasAttribute('data-checked')).toBe(false);
+  });
+
+  it('does not choose the row when Enter is pressed on its chevron', async () => {
+    await render('f2');
+    const row = itemFor('Carriers')!;
+    // Highlight the row, as the pointer does on the way to the chevron, so
+    // cmdk's root Enter handler would select it if the key reached it.
+    await act(async () => {
+      row.dispatchEvent(new PointerEvent('pointermove', { bubbles: true }));
+    });
+    expect(row.getAttribute('data-selected')).toBe('true');
+
+    await act(async () => {
+      chevronOf('Carriers')?.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }),
+      );
+    });
+    expect(itemFor('Carriers')?.hasAttribute('data-checked')).toBe(false);
+    expect(itemFor('Customs')?.getAttribute('data-checked')).toBe('true');
+  });
+
+  it('renders the footer actions as pill buttons', async () => {
+    await render();
+    const newFolder = rowFor('agents.folders.newFolder');
+    expect(newFolder?.getAttribute('data-variant')).toBe('outline-primary');
+    // New Folder swaps in place with the 42px new-folder Input, so it is the
+    // field height too and the footer row doesn't jump.
+    expect(newFolder?.getAttribute('data-size')).toBe('field');
+    expect(newFolder?.getAttribute('data-shape')).toBe('pill');
+    expect(rowFor('agents.folders.move')?.getAttribute('data-shape')).toBe(
+      'pill',
+    );
+    expect(rowFor('cancel')?.getAttribute('data-shape')).toBe('pill');
+  });
+});
diff --git a/frontend/src/modals/MoveToFolderModal.tsx b/frontend/src/modals/MoveToFolderModal.tsx
index ae25db68..2f3a3517 100644
--- a/frontend/src/modals/MoveToFolderModal.tsx
+++ b/frontend/src/modals/MoveToFolderModal.tsx
@@ -1,17 +1,37 @@
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { ChevronRight } from 'lucide-react';
+import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 
 import { AgentFolder } from '../agents/types';
 import userService from '../api/services/userService';
-import ChevronRight from '../assets/chevron-right.svg';
 import FolderIcon from '../assets/folder.svg';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '../components/ui/breadcrumb';
 import { Button } from '../components/ui/button';
+import {
+  Command,
+  CommandGroup,
+  CommandItem,
+  CommandList,
+} from '../components/ui/command';
 import { Input } from '../components/ui/input';
 import { Modal } from '../components/ui/modal';
 import { ActiveState } from '../models/misc';
 import { selectToken, setAgentFolders } from '../preferences/preferenceSlice';
 
+// cmdk keys rows by `value`: the root row needs a value no folder id can take,
+// and the highlight starts on a value no row has, so nothing is highlighted
+// until the pointer or the arrow keys move it.
+const ROOT_ROW_VALUE = '__docsgpt-no-folder__';
+const NO_HIGHLIGHT = '__docsgpt-no-highlight__';
+
 type MoveToFolderModalProps = {
   modalState: ActiveState;
   setModalState: (state: ActiveState) => void;
@@ -40,6 +60,8 @@ export default function MoveToFolderModal({
   const newFolderInputRef = useRef<HTMLInputElement>(null);
   // Track navigation path for nested folders
   const [folderPath, setFolderPath] = useState<string[]>([]);
+  // The row cmdk highlights (pointer / arrow keys), apart from the chosen one.
+  const [highlightedRow, setHighlightedRow] = useState(NO_HIGHLIGHT);
 
   const currentNavigationFolderId =
     folderPath.length > 0 ? folderPath[folderPath.length - 1] : null;
@@ -49,6 +71,7 @@ export default function MoveToFolderModal({
       fetchFolders();
       setSelectedFolderId(currentFolderId || null);
       setFolderPath([]);
+      setHighlightedRow(NO_HIGHLIGHT);
     }
   }, [modalState]);
 
@@ -82,6 +105,9 @@ export default function MoveToFolderModal({
     });
   }, [folders, folderPath]);
 
+  const showRootRow = Boolean(currentFolderId) && folderPath.length === 0;
+  const hasRows = showRootRow || currentLevelFolders.length > 0;
+
   const handleNavigateIntoFolder = (folderId: string) => {
     setFolderPath((prev) => [...prev, folderId]);
   };
@@ -139,142 +165,157 @@ export default function MoveToFolderModal({
       open={modalState === 'ACTIVE'}
       onOpenChange={(o) => !o && setModalState('INACTIVE')}
       size="md"
-      className="w-[800px] max-w-[90vw] p-0! sm:max-w-[90vw]"
+      className="w-[800px] max-w-[90vw] p-0 sm:max-w-[90vw]"
       contentClassName="overflow-visible"
       hideTitle
       title={`${t('agents.folders.move')} "${agentName}" to`}
     >
       <div>
         <div className="px-6 pt-4">
-          <h2 className="text-foreground dark:text-foreground mb-2 text-2xl leading-7 font-semibold tracking-[0.15px]">
+          <h2 className="text-foreground mb-2 text-2xl leading-7 font-semibold">
             {t('agents.folders.move')} &quot;{agentName}&quot; to
           </h2>
         </div>
-        <div className="bg-muted dark:bg-muted text-muted-foreground flex items-center gap-1 px-8 py-2 text-xs font-semibold">
-          <Button
-            type="button"
-            variant="ghost"
-            onClick={() => handleNavigateToPath(-1)}
-            className={`hover:text-foreground h-auto px-0 py-0 text-xs font-semibold hover:bg-transparent dark:hover:text-white ${folderPath.length > 0 ? 'opacity-70' : ''}`}
-          >
-            {t('agents.filters.byMe')}
-          </Button>
-          {breadcrumbItems.map((item, index) => (
-            <span key={item.id} className="flex items-center gap-1">
-              <svg
-                className="mx-1"
-                width="5"
-                height="10"
-                viewBox="0 0 5 10"
-                fill="none"
-                xmlns="http://www.w3.org/2000/svg"
-              >
-                <path
-                  d="M0.134367 9.15687C0.0914459 9.20458 0.0578918 9.2607 0.0356192 9.32203C0.0133471 9.38335 0.00279279 9.44869 0.00455995 9.5143C0.00632664 9.57992 0.0203805 9.64452 0.045918 9.70443C0.0714555 9.76434 0.107977 9.81837 0.153397 9.86346C0.198817 9.90854 0.252247 9.94378 0.310635 9.96718C0.369022 9.99057 0.431225 10.0017 0.493692 9.9998C0.556159 9.99794 0.617665 9.98318 0.674701 9.95636C0.731736 9.92954 0.783183 9.89118 0.826104 9.84347L4.86996 5.34611C4.95347 5.25333 5 5.13049 5 5.00281C5 4.87513 4.95347 4.75229 4.86996 4.65951L0.826103 0.161649C0.783465 0.112896 0.73203 0.0735287 0.674785 0.045833C0.617539 0.0181364 0.555626 0.00266495 0.49264 0.000314153C0.429653 -0.00203665 0.36685 0.00878279 0.307878 0.0321411C0.248906 0.0555004 0.19494 0.0909342 0.149116 0.136384C0.103292 0.181836 0.0665217 0.236396 0.0409428 0.296899C0.0153638 0.357402 0.00148499 0.422641 0.000112656 0.488825C-0.00125968 0.55501 0.00990166 0.620821 0.0329486 0.682436C0.0559961 0.744051 0.0904695 0.800243 0.134366 0.847745L3.86994 5.00281L0.134367 9.15687Z"
-                  fill="currentColor"
-                />
-              </svg>
-              {index === breadcrumbItems.length - 1 ? (
-                <span>{item.name}</span>
+        <div className="bg-muted px-8 py-2">
+          <Breadcrumb className="min-w-0">
+            <BreadcrumbList className="flex-nowrap">
+              {folderPath.length === 0 ? (
+                <BreadcrumbItem className="min-w-0">
+                  <BreadcrumbPage
+                    title={t('agents.filters.byMe')}
+                    className="max-w-[32ch]"
+                  >
+                    {t('agents.filters.byMe')}
+                  </BreadcrumbPage>
+                </BreadcrumbItem>
               ) : (
-                <Button
-                  type="button"
-                  variant="ghost"
-                  onClick={() => handleNavigateToPath(index)}
-                  className="hover:text-foreground h-auto px-0 py-0 text-xs font-semibold opacity-70 hover:bg-transparent dark:hover:text-white"
-                >
-                  {item.name}
-                </Button>
+                <BreadcrumbItem>
+                  <BreadcrumbLink asChild>
+                    <button
+                      type="button"
+                      onClick={() => handleNavigateToPath(-1)}
+                    >
+                      {t('agents.filters.byMe')}
+                    </button>
+                  </BreadcrumbLink>
+                </BreadcrumbItem>
               )}
-            </span>
-          ))}
+              {breadcrumbItems.map((item, index) => (
+                <Fragment key={item.id}>
+                  <BreadcrumbSeparator />
+                  {index === breadcrumbItems.length - 1 ? (
+                    <BreadcrumbItem className="min-w-0">
+                      <BreadcrumbPage
+                        title={item.name}
+                        className="max-w-[32ch]"
+                      >
+                        {item.name}
+                      </BreadcrumbPage>
+                    </BreadcrumbItem>
+                  ) : (
+                    <BreadcrumbItem>
+                      <BreadcrumbLink asChild>
+                        <button
+                          type="button"
+                          onClick={() => handleNavigateToPath(index)}
+                        >
+                          {item.name}
+                        </button>
+                      </BreadcrumbLink>
+                    </BreadcrumbItem>
+                  )}
+                </Fragment>
+              ))}
+            </BreadcrumbList>
+          </Breadcrumb>
         </div>
-        <div className="dark:border-border max-h-60 min-h-[200px] overflow-y-auto border-t border-gray-200">
+        <div className="border-border border-t px-5 py-1">
           {isLoading ? (
             <div className="flex h-[200px] items-center justify-center">
               <span className="text-muted-foreground text-sm">
                 {t('modals.searchConversations.loading')}
               </span>
             </div>
-          ) : (
-            <div className="flex w-full flex-col">
-              {/* Option to move to root (no folder) - only show at root level */}
-              {currentFolderId && folderPath.length === 0 && (
-                <Button
-                  type="button"
-                  variant="ghost"
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    setSelectedFolderId(null);
-                  }}
-                  className={`dark:border-border h-auto w-full justify-start gap-2 rounded-none border-b border-gray-200 px-8 py-2 text-left text-sm ${
-                    selectedFolderId === null
-                      ? 'bg-primary hover:bg-primary text-white hover:text-white'
-                      : 'bg-muted hover:bg-accent dark:bg-muted'
-                  }`}
-                >
-                  <span
-                    className={
-                      selectedFolderId === null
-                        ? 'text-white'
-                        : 'text-gray-600 dark:text-gray-300'
-                    }
-                  >
-                    {t('agents.folders.noFolder')}
-                  </span>
-                </Button>
-              )}
-
-              {currentLevelFolders.map((folder) => (
-                <Button
-                  key={folder.id}
-                  type="button"
-                  variant="ghost"
-                  onClick={() => setSelectedFolderId(folder.id)}
-                  className={`dark:border-border h-auto w-full justify-between rounded-none border-b border-gray-200 px-8 py-2 text-left text-sm ${
-                    selectedFolderId === folder.id
-                      ? 'bg-primary hover:bg-primary text-white hover:text-white'
-                      : 'bg-muted hover:bg-accent dark:bg-muted'
-                  }`}
-                >
-                  <span className="flex flex-1 items-center gap-2">
-                    <img
-                      src={FolderIcon}
-                      alt="folder"
-                      className={`h-4 w-4 ${selectedFolderId === folder.id ? 'brightness-0 invert' : ''}`}
-                    />
-                    <span
-                      className={`truncate ${selectedFolderId === folder.id ? 'text-white' : 'text-foreground'}`}
+          ) : hasRows ? (
+            <Command
+              tabIndex={0}
+              value={highlightedRow}
+              onValueChange={setHighlightedRow}
+            >
+              <CommandList
+                label={t('agents.folders.moveToFolder')}
+                className="max-h-60 min-h-50"
+              >
+                <CommandGroup>
+                  {/* Option to move to root (no folder) - only show at root level */}
+                  {showRootRow && (
+                    <CommandItem
+                      value={ROOT_ROW_VALUE}
+                      keywords={[t('agents.folders.noFolder')]}
+                      checked={selectedFolderId === null}
+                      aria-checked={selectedFolderId === null}
+                      onSelect={() => setSelectedFolderId(null)}
                     >
-                      {folder.name}
-                    </span>
-                  </span>
-                  {/* Check if folder has subfolders */}
-                  {folders.some((f) => f.parent_id === folder.id) && (
-                    <span
-                      role="button"
-                      tabIndex={0}
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        handleNavigateIntoFolder(folder.id);
-                      }}
-                      onKeyDown={(e) => {
-                        if (e.key === 'Enter' || e.key === ' ') {
-                          e.stopPropagation();
-                          handleNavigateIntoFolder(folder.id);
+                      <span
+                        className={
+                          selectedFolderId === null
+                            ? undefined
+                            : 'text-muted-foreground'
                         }
-                      }}
-                      className="hover:bg-accent ml-2 flex h-6 w-6 items-center justify-center rounded-full"
-                    >
-                      <img
-                        src={ChevronRight}
-                        alt="expand"
-                        className={`h-3 w-3 ${selectedFolderId === folder.id ? 'brightness-0 invert' : 'dark:invert'}`}
-                      />
-                    </span>
+                      >
+                        {t('agents.folders.noFolder')}
+                      </span>
+                    </CommandItem>
                   )}
-                </Button>
-              ))}
+
+                  {currentLevelFolders.map((folder) => (
+                    <CommandItem
+                      key={folder.id}
+                      value={folder.id}
+                      keywords={[folder.name]}
+                      checked={selectedFolderId === folder.id}
+                      aria-checked={selectedFolderId === folder.id}
+                      onSelect={() => setSelectedFolderId(folder.id)}
+                      className="justify-between"
+                    >
+                      <span className="flex flex-1 items-center gap-2">
+                        <img
+                          src={FolderIcon}
+                          alt=""
+                          aria-hidden="true"
+                          className="h-4 w-4"
+                        />
+                        <span className="truncate">{folder.name}</span>
+                      </span>
+                      {/* Check if folder has subfolders */}
+                      {folders.some((f) => f.parent_id === folder.id) && (
+                        <Button
+                          type="button"
+                          variant="ghost-muted"
+                          size="icon-xs"
+                          aria-label={t('agents.folders.openFolder')}
+                          onClick={(e) => {
+                            // Keep cmdk's row click from choosing the folder.
+                            e.stopPropagation();
+                            handleNavigateIntoFolder(folder.id);
+                          }}
+                          onKeyDown={(e) => {
+                            // cmdk's root handles Enter by choosing the
+                            // highlighted row and cancelling this button's
+                            // click; stop it here so Enter drills in instead.
+                            if (e.key === 'Enter') e.stopPropagation();
+                          }}
+                        >
+                          <ChevronRight className="text-current" />
+                        </Button>
+                      )}
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              </CommandList>
+            </Command>
+          ) : (
+            <>
               {currentLevelFolders.length === 0 && folderPath.length > 0 && (
                 <div className="text-muted-foreground flex h-[200px] items-center justify-center text-sm">
                   {t('agents.folders.noSubfolders')}
@@ -287,11 +328,11 @@ export default function MoveToFolderModal({
                     {t('agents.folders.noFolders')}
                   </div>
                 )}
-            </div>
+            </>
           )}
         </div>
 
-        <div className="dark:border-border flex items-center justify-between border-t border-gray-200 px-8 py-4">
+        <div className="border-border flex items-center justify-between border-t px-8 py-4">
           {isCreatingFolder ? (
             <Input
               ref={newFolderInputRef}
@@ -314,19 +355,20 @@ export default function MoveToFolderModal({
                 }
               }}
               placeholder={t('agents.folders.newFolder')}
-              className="border-primary text-primary placeholder:text-primary/60 dark:placeholder:text-primary/60 dark:text-primary dark:border-primary h-auto rounded-full px-6 py-2 text-sm font-medium"
+              shape="pill"
               autoFocus
             />
           ) : (
             <Button
               type="button"
-              variant="outline"
+              variant="outline-primary"
+              size="field"
+              shape="pill"
               onClick={(e) => {
                 e.stopPropagation();
                 setIsCreatingFolder(true);
                 setTimeout(() => newFolderInputRef.current?.focus(), 0);
               }}
-              className="border-primary text-primary hover:bg-primary/10 hover:text-primary h-auto rounded-full bg-transparent px-6 py-2 text-sm font-medium"
             >
               {t('agents.folders.newFolder')}
             </Button>
@@ -345,7 +387,7 @@ export default function MoveToFolderModal({
                   setModalState('INACTIVE');
                 }
               }}
-              className="dark:text-foreground h-auto rounded-3xl px-5 py-2 text-sm font-medium"
+              shape="pill"
             >
               {t('cancel')}
             </Button>
@@ -361,7 +403,7 @@ export default function MoveToFolderModal({
                   }
                 }}
                 disabled={!newFolderName.trim()}
-                className="h-auto rounded-3xl px-5 py-2 text-sm text-white"
+                shape="pill"
               >
                 {t('agents.folders.createFolder')}
               </Button>
@@ -372,7 +414,7 @@ export default function MoveToFolderModal({
                   e.stopPropagation();
                   handleMove();
                 }}
-                className="h-auto rounded-3xl px-5 py-2 text-sm text-white"
+                shape="pill"
               >
                 {t('agents.folders.move')}
               </Button>
diff --git a/frontend/src/modals/RegenerateAccessTokenModal.tsx b/frontend/src/modals/RegenerateAccessTokenModal.tsx
index 1b217dbb..7c80510b 100644
--- a/frontend/src/modals/RegenerateAccessTokenModal.tsx
+++ b/frontend/src/modals/RegenerateAccessTokenModal.tsx
@@ -1,3 +1,4 @@
+import { TriangleAlert } from 'lucide-react';
 import React from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
@@ -9,6 +10,7 @@ import patService, {
   PersonalAccessToken,
 } from '../api/services/patService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Label } from '../components/ui/label';
 import { Modal } from '../components/ui/modal';
@@ -101,7 +103,8 @@ export default function RegenerateAccessTokenModal({
             variant="ghost"
             onClick={handleClose}
             disabled={submitting}
-            className="rounded-3xl px-6"
+            size="lg"
+            shape="pill"
           >
             {t('settings.accessTokens.create.cancel')}
           </Button>
@@ -109,7 +112,8 @@ export default function RegenerateAccessTokenModal({
             type="button"
             onClick={handleSubmit}
             disabled={submitting}
-            className="rounded-3xl px-6 text-white"
+            size="lg"
+            shape="pill"
           >
             {submitting ? (
               <span className="flex items-center gap-2">
@@ -125,7 +129,7 @@ export default function RegenerateAccessTokenModal({
     >
       <div className="flex flex-col gap-5 px-1">
         <div>
-          <h2 className="text-foreground dark:text-foreground text-xl font-semibold">
+          <h2 className="text-foreground text-xl font-semibold">
             {t('settings.accessTokens.regenerate.title')}
           </h2>
           <p className="text-muted-foreground mt-2 text-sm break-words">
@@ -146,7 +150,7 @@ export default function RegenerateAccessTokenModal({
           >
             <SelectTrigger
               id="pat-regenerate-expiry"
-              className="w-full rounded-xl px-4 py-2"
+              className="w-full"
               size="lg"
             >
               <SelectValue />
@@ -159,28 +163,29 @@ export default function RegenerateAccessTokenModal({
               ))}
             </SelectContent>
           </Select>
-          <p
-            className={`text-xs ${
-              expiry === NO_EXPIRY
-                ? 'text-amber-700 dark:text-amber-400'
-                : 'text-muted-foreground'
-            }`}
-          >
-            {expiry === NO_EXPIRY
-              ? t('settings.accessTokens.create.noExpirationHint')
-              : t('settings.accessTokens.create.expiresOn', {
-                  date: formatDateOnly(
-                    new Date(Date.now() + expiry * DAY_MS).toISOString(),
-                  ),
-                  ...NO_ESCAPE,
-                })}
-          </p>
+          {expiry === NO_EXPIRY ? (
+            <Alert variant="warning">
+              <TriangleAlert className="size-4" aria-hidden="true" />
+              <AlertDescription>
+                {t('settings.accessTokens.create.noExpirationHint')}
+              </AlertDescription>
+            </Alert>
+          ) : (
+            <p className="text-muted-foreground text-xs">
+              {t('settings.accessTokens.create.expiresOn', {
+                date: formatDateOnly(
+                  new Date(Date.now() + expiry * DAY_MS).toISOString(),
+                ),
+                ...NO_ESCAPE,
+              })}
+            </p>
+          )}
         </div>
 
         {error && (
           <p
             role="alert"
-            className="rounded-lg bg-red-50 px-4 py-2 text-sm text-red-600 dark:bg-red-900/20 dark:text-red-400"
+            className="bg-destructive/10 text-destructive rounded-lg px-4 py-2 text-sm"
           >
             {error}
           </p>
diff --git a/frontend/src/modals/SearchConversationsModal.test.tsx b/frontend/src/modals/SearchConversationsModal.test.tsx
new file mode 100644
index 00000000..6fa890d9
--- /dev/null
+++ b/frontend/src/modals/SearchConversationsModal.test.tsx
@@ -0,0 +1,196 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+const media = { isMobile: false, isTablet: false, isDesktop: true };
+vi.mock('../hooks', () => ({
+  useMediaQuery: () => media,
+}));
+
+const searchConversations = vi.fn();
+vi.mock('../preferences/preferenceApi', () => ({
+  searchConversations: (...args: unknown[]) => searchConversations(...args),
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import SearchConversationsModal from './SearchConversationsModal';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const conversations = [
+  { id: 'c1', name: 'Fuel surcharge policy summary' },
+  { id: 'c2', name: 'Q3 carrier rate negotiation' },
+];
+
+const serverResults = [
+  {
+    id: 'r1',
+    name: 'Q3 carrier rate negotiation',
+    match_field: 'response' as const,
+    match_snippet: 'Halvorsen agreed to cap the fuel surcharge at 18%.',
+  },
+  {
+    id: 'r2',
+    name: 'Customs hold on Rotterdam shipment',
+    match_field: 'prompt' as const,
+    match_snippet: 'The broker added a demurrage surcharge.',
+  },
+];
+
+describe('SearchConversationsModal', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let close: ReturnType<typeof vi.fn<() => void>>;
+  let onSelect: ReturnType<typeof vi.fn<(id: string) => void>>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    media.isMobile = false;
+    media.isDesktop = true;
+    searchConversations.mockReset();
+    searchConversations.mockResolvedValue({ data: serverResults });
+    close = vi.fn<() => void>();
+    onSelect = vi.fn<(id: string) => void>();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    vi.useRealTimers();
+  });
+
+  const render = async () => {
+    await act(async () => {
+      root.render(
+        <SearchConversationsModal
+          close={close}
+          conversations={conversations}
+          token="tok"
+          onSelectConversation={onSelect}
+        />,
+      );
+    });
+  };
+
+  const input = () =>
+    document.body.querySelector<HTMLInputElement>(
+      '[data-slot="command-input"]',
+    )!;
+
+  const items = () =>
+    Array.from(
+      document.body.querySelectorAll<HTMLElement>('[data-slot="command-item"]'),
+    );
+
+  const type = async (value: string) => {
+    await act(async () => {
+      const el = input();
+      const setter = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        'value',
+      )!.set!;
+      setter.call(el, value);
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await act(async () => {
+      vi.advanceTimersByTime(300);
+    });
+    await act(async () => {
+      await Promise.resolve();
+    });
+  };
+
+  const key = async (k: string) => {
+    await act(async () => {
+      input().dispatchEvent(
+        new KeyboardEvent('keydown', { key: k, bubbles: true }),
+      );
+    });
+  };
+
+  it('renders a CommandDialog without a close button at desktop width', async () => {
+    await render();
+    const content = document.body.querySelector('[data-slot="dialog-content"]');
+    expect(content).not.toBeNull();
+    expect(content!.querySelector('[data-slot="command"]')).not.toBeNull();
+    expect(document.body.querySelector('[data-slot="modal-content"]')).toBe(
+      null,
+    );
+    expect(document.body.querySelector('[data-slot="dialog-close"]')).toBe(
+      null,
+    );
+    expect(items().map((i) => i.textContent)).toEqual([
+      'Fuel surcharge policy summary',
+      'Q3 carrier rate negotiation',
+    ]);
+  });
+
+  it('shows server results as returned, with snippets on desktop', async () => {
+    await render();
+    await type('surcharge');
+    expect(searchConversations).toHaveBeenCalledWith('surcharge', 'tok');
+    const rows = items();
+    // r2's title does not contain the query: cmdk must not filter it out.
+    expect(rows).toHaveLength(2);
+    expect(rows[0].textContent).toContain('Q3 carrier rate negotiation');
+    expect(rows[0].textContent).toContain('Halvorsen agreed');
+    expect(rows[1].textContent).toContain('demurrage');
+    expect(rows[0].querySelector('mark')?.textContent).toBe('surcharge');
+    expect(rows[0].getAttribute('role')).toBe('option');
+  });
+
+  it('opens the highlighted conversation on Enter and follows arrow keys', async () => {
+    await render();
+    await type('surcharge');
+    expect(items()[0].getAttribute('data-selected')).toBe('true');
+    await key('ArrowDown');
+    expect(items()[1].getAttribute('data-selected')).toBe('true');
+    await key('Enter');
+    expect(onSelect).toHaveBeenCalledWith('r2');
+    expect(close).toHaveBeenCalled();
+  });
+
+  it('opens a conversation on click', async () => {
+    await render();
+    await act(async () => {
+      items()[1].click();
+    });
+    expect(onSelect).toHaveBeenCalledWith('c2');
+    expect(close).toHaveBeenCalled();
+  });
+
+  it('shows the empty state when the search returns nothing', async () => {
+    searchConversations.mockResolvedValue({ data: [] });
+    await render();
+    await type('zzz');
+    expect(items()).toHaveLength(0);
+    expect(document.body.textContent).toContain(
+      'modals.searchConversations.noResults',
+    );
+  });
+
+  it('renders a bottom sheet with title-only rows on phones', async () => {
+    media.isMobile = true;
+    media.isDesktop = false;
+    await render();
+    const sheet = document.body.querySelector('[data-slot="modal-content"]');
+    expect(sheet).not.toBeNull();
+    expect(sheet!.hasAttribute('data-mobile-sheet')).toBe(true);
+    expect(sheet!.querySelector('[data-slot="command"]')).not.toBeNull();
+    expect(document.body.querySelector('[data-slot="dialog-content"]')).toBe(
+      null,
+    );
+    await type('surcharge');
+    const rows = items();
+    expect(rows).toHaveLength(2);
+    expect(rows[0].textContent).toBe('Q3 carrier rate negotiation');
+    expect(rows[1].textContent).toBe('Customs hold on Rotterdam shipment');
+    await key('Enter');
+    expect(onSelect).toHaveBeenCalledWith('r1');
+  });
+});
diff --git a/frontend/src/modals/SearchConversationsModal.tsx b/frontend/src/modals/SearchConversationsModal.tsx
index 7ecb37b9..8c93c753 100644
--- a/frontend/src/modals/SearchConversationsModal.tsx
+++ b/frontend/src/modals/SearchConversationsModal.tsx
@@ -1,16 +1,16 @@
-import { Search as SearchIcon } from 'lucide-react';
-import {
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type KeyboardEvent,
-} from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
-import { Button } from '../components/ui/button';
-import { Input } from '../components/ui/input';
+import {
+  Command,
+  CommandDialog,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '../components/ui/command';
 import { Modal } from '../components/ui/modal';
+import { useMediaQuery } from '../hooks';
 import { searchConversations } from '../preferences/preferenceApi';
 
 type ConversationListItem = {
@@ -51,6 +51,13 @@ function HighlightedText({ text, query }: { text: string; query: string }) {
   );
 }
 
+/**
+ * Conversation search palette. At `sm`+ it is a `CommandDialog`; on phones it
+ * is the `Modal` bottom sheet with the same Command parts inside, showing
+ * titles only. Results come from the debounced server search and are shown
+ * unfiltered (`shouldFilter={false}`); cmdk owns arrow-key navigation and
+ * Enter/click open the highlighted conversation via `onSelect`.
+ */
 export default function SearchConversationsModal({
   close,
   conversations,
@@ -58,17 +65,21 @@ export default function SearchConversationsModal({
   onSelectConversation,
 }: SearchConversationsModalProps) {
   const { t } = useTranslation();
+  const { isMobile } = useMediaQuery();
   const inputRef = useRef<HTMLInputElement>(null);
-  const resultRefs = useRef<Array<HTMLButtonElement | null>>([]);
 
   const [query, setQuery] = useState('');
   const [results, setResults] = useState<ConversationListItem[] | null>(null);
   const [isSearching, setIsSearching] = useState(false);
-  const [activeIndex, setActiveIndex] = useState(-1);
+  const [selectedId, setSelectedId] = useState('');
 
+  const title = t('modals.searchConversations.searchPlaceholder');
+
+  // The branch can switch after mount (useMediaQuery settles in an effect),
+  // remounting the input, so refocus it whenever the branch changes.
   useEffect(() => {
     inputRef.current?.focus();
-  }, []);
+  }, [isMobile]);
 
   useEffect(() => {
     const trimmed = query.trim();
@@ -92,152 +103,143 @@ export default function SearchConversationsModal({
     return results ?? [];
   }, [query, results, conversations]);
 
+  // Keep the highlighted row when it survives a list change, otherwise
+  // highlight the first row, so Enter always has a target.
   useEffect(() => {
     if (isSearching || visibleConversations.length === 0) {
-      setActiveIndex(-1);
+      setSelectedId('');
       return;
     }
-
-    setActiveIndex((currentIndex) => {
-      if (currentIndex >= 0 && currentIndex < visibleConversations.length) {
-        return currentIndex;
-      }
-
-      return 0;
-    });
+    setSelectedId((current) =>
+      visibleConversations.some((c) => c.id === current)
+        ? current
+        : visibleConversations[0].id,
+    );
   }, [isSearching, visibleConversations]);
 
-  useEffect(() => {
-    if (activeIndex < 0) return;
-
-    resultRefs.current[activeIndex]?.scrollIntoView({
-      block: 'nearest',
-    });
-  }, [activeIndex]);
-
   const handleSelect = (id: string) => {
     onSelectConversation(id);
     close();
   };
 
-  const handleInputKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
-    if (visibleConversations.length === 0 || isSearching) return;
+  const trimmedQuery = query.trim();
+  const showEmptyState =
+    !!trimmedQuery && !isSearching && visibleConversations.length === 0;
 
-    if (event.key === 'ArrowDown') {
-      event.preventDefault();
-      setActiveIndex((currentIndex) =>
-        currentIndex < visibleConversations.length - 1 ? currentIndex + 1 : 0,
+  const status = (
+    <>
+      {isSearching && (
+        <div className="text-muted-foreground px-3 py-3 text-xs">
+          {t('modals.searchConversations.loading')}
+        </div>
+      )}
+      {showEmptyState && (
+        <div className="text-muted-foreground px-3 py-3 text-xs">
+          {t('modals.searchConversations.noResults')}
+        </div>
+      )}
+    </>
+  );
+
+  const renderItems = (withSnippet: boolean) =>
+    !isSearching &&
+    visibleConversations.map((conversation) => {
+      const titleNode = trimmedQuery ? (
+        <HighlightedText text={conversation.name} query={trimmedQuery} />
+      ) : (
+        conversation.name
       );
-      return;
-    }
+      const showSnippet =
+        withSnippet &&
+        !!trimmedQuery &&
+        !!conversation.match_snippet &&
+        conversation.match_field !== 'name';
 
-    if (event.key === 'ArrowUp') {
-      event.preventDefault();
-      setActiveIndex((currentIndex) =>
-        currentIndex > 0 ? currentIndex - 1 : visibleConversations.length - 1,
+      return (
+        <CommandItem
+          key={conversation.id}
+          value={conversation.id}
+          onSelect={() => handleSelect(conversation.id)}
+        >
+          {withSnippet ? (
+            <div className="flex min-w-0 flex-col gap-0.5">
+              <span className="truncate">{titleNode}</span>
+              {showSnippet && (
+                <span className="text-muted-foreground line-clamp-2 text-xs">
+                  <HighlightedText
+                    text={conversation.match_snippet as string}
+                    query={trimmedQuery}
+                  />
+                </span>
+              )}
+            </div>
+          ) : (
+            <span className="truncate">{titleNode}</span>
+          )}
+        </CommandItem>
       );
-      return;
-    }
+    });
 
-    if (event.key === 'Enter' && activeIndex >= 0) {
-      event.preventDefault();
-      handleSelect(visibleConversations[activeIndex].id);
-    }
+  const commandProps = {
+    shouldFilter: false,
+    label: title,
+    value: selectedId,
+    onValueChange: setSelectedId,
   };
 
-  const showEmptyState =
-    !!query.trim() && !isSearching && visibleConversations.length === 0;
+  const input = (
+    <CommandInput
+      ref={inputRef}
+      value={query}
+      onValueChange={setQuery}
+      placeholder={title}
+    />
+  );
+
+  const onOpenChange = (open: boolean) => {
+    if (!open) close();
+  };
+
+  if (isMobile) {
+    return (
+      <Modal
+        open={true}
+        onOpenChange={onOpenChange}
+        hideTitle
+        title={title}
+        showCloseButton={false}
+        mobileVariant="sheet"
+        contentClassName="-mx-3 -mt-3 flex flex-col"
+      >
+        <Command variant="palette" {...commandProps} className="min-h-0">
+          {input}
+          <CommandList className="max-h-none">
+            <div className="py-1">
+              {status}
+              {renderItems(false)}
+            </div>
+          </CommandList>
+        </Command>
+      </Modal>
+    );
+  }
 
   return (
-    <Modal
+    <CommandDialog
       open={true}
-      onOpenChange={(open) => {
-        if (!open) close();
-      }}
-      hideTitle
-      title={t('modals.searchConversations.searchPlaceholder')}
+      onOpenChange={onOpenChange}
+      title={title}
+      description={title}
       showCloseButton={false}
-      mobileVariant="sheet"
-      className="w-[92vw] !max-w-xl !p-0"
-      contentClassName="max-h-[70vh]"
+      commandProps={commandProps}
     >
-      <div className="flex flex-col">
-        <div className="border-sidebar-border flex items-center gap-2 border-b px-5 py-4">
-          <SearchIcon
-            className="text-muted-foreground size-4"
-            strokeWidth={1.75}
-            aria-label="search"
-          />
-          <Input
-            ref={inputRef}
-            type="text"
-            value={query}
-            onChange={(e) => setQuery(e.target.value)}
-            onKeyDown={handleInputKeyDown}
-            placeholder={t('modals.searchConversations.searchPlaceholder')}
-            className="h-auto rounded-none border-none px-0 py-0 text-sm shadow-none focus-visible:ring-0"
-          />
-        </div>
-
-        <div className="max-h-[55vh] overflow-y-auto py-2" role="listbox">
-          {isSearching && (
-            <div className="text-muted-foreground px-5 py-3 text-xs">
-              {t('modals.searchConversations.loading')}
-            </div>
-          )}
-          {showEmptyState && (
-            <div className="text-muted-foreground px-5 py-3 text-xs">
-              {t('modals.searchConversations.noResults')}
-            </div>
-          )}
-          {!isSearching &&
-            visibleConversations.map((conversation, index) => {
-              const trimmedQuery = query.trim();
-              const showSnippet =
-                !!trimmedQuery &&
-                !!conversation.match_snippet &&
-                conversation.match_field !== 'name';
-              const isActive = index === activeIndex;
-
-              return (
-                <Button
-                  key={conversation.id}
-                  type="button"
-                  variant="ghost"
-                  ref={(element) => {
-                    resultRefs.current[index] = element;
-                  }}
-                  onClick={() => handleSelect(conversation.id)}
-                  onMouseEnter={() => setActiveIndex(index)}
-                  role="option"
-                  aria-selected={isActive}
-                  className={`text-foreground flex h-auto w-full flex-col items-start gap-0.5 rounded-none px-5 py-2.5 text-left ${
-                    isActive ? 'bg-sidebar-accent' : 'hover:bg-sidebar-accent'
-                  }`}
-                >
-                  <span className="w-full truncate">
-                    {trimmedQuery ? (
-                      <HighlightedText
-                        text={conversation.name}
-                        query={trimmedQuery}
-                      />
-                    ) : (
-                      conversation.name
-                    )}
-                  </span>
-                  {showSnippet && (
-                    <span className="text-muted-foreground line-clamp-2 w-full text-xs">
-                      <HighlightedText
-                        text={conversation.match_snippet as string}
-                        query={trimmedQuery}
-                      />
-                    </span>
-                  )}
-                </Button>
-              );
-            })}
-        </div>
-      </div>
-    </Modal>
+      {input}
+      <CommandList>
+        {status}
+        {!isSearching && visibleConversations.length > 0 && (
+          <CommandGroup>{renderItems(true)}</CommandGroup>
+        )}
+      </CommandList>
+    </CommandDialog>
   );
 }
diff --git a/frontend/src/modals/ShareConversationModal.tsx b/frontend/src/modals/ShareConversationModal.tsx
index d0ac889c..0883da5a 100644
--- a/frontend/src/modals/ShareConversationModal.tsx
+++ b/frontend/src/modals/ShareConversationModal.tsx
@@ -132,7 +132,7 @@ export const ShareConversationModal = ({
                 if (opt) setSourcePath(opt);
               }}
             >
-              <SelectTrigger className="w-full rounded-xl px-5 py-3" size="lg">
+              <SelectTrigger className="w-full" size="lg">
                 <SelectValue placeholder={t('modals.createAPIKey.sourceDoc')} />
               </SelectTrigger>
               <SelectContent>
@@ -153,7 +153,8 @@ export const ShareConversationModal = ({
             <Button
               type="button"
               size="lg"
-              className="my-1 w-28 rounded-3xl"
+              shape="pill"
+              className="my-1 w-28"
               onClick={() => handleCopyKey(`${domain}/share/${identifier}`)}
             >
               {isCopied ? t('modals.saveKey.copied') : t('modals.saveKey.copy')}
@@ -162,7 +163,8 @@ export const ShareConversationModal = ({
             <Button
               type="button"
               size="lg"
-              className="my-1 w-28 justify-evenly rounded-3xl text-center"
+              shape="pill"
+              className="my-1 w-28 justify-evenly text-center"
               onClick={() => {
                 shareCoversationPublicly(allowPrompt);
               }}
diff --git a/frontend/src/navigation/DetailBreadcrumb.tsx b/frontend/src/navigation/DetailBreadcrumb.tsx
index 6f007a02..78026da3 100644
--- a/frontend/src/navigation/DetailBreadcrumb.tsx
+++ b/frontend/src/navigation/DetailBreadcrumb.tsx
@@ -40,10 +40,7 @@ export default function DetailBreadcrumb({
         </BreadcrumbItem>
         <BreadcrumbSeparator />
         <BreadcrumbItem className="min-w-0">
-          <BreadcrumbPage
-            title={currentLabel}
-            className="max-w-[32ch] truncate"
-          >
+          <BreadcrumbPage title={currentLabel} className="max-w-[32ch]">
             {currentLabel}
           </BreadcrumbPage>
         </BreadcrumbItem>
diff --git a/frontend/src/navigation/SectionPills.tsx b/frontend/src/navigation/SectionPills.tsx
index 4778f8f4..8c868f2a 100644
--- a/frontend/src/navigation/SectionPills.tsx
+++ b/frontend/src/navigation/SectionPills.tsx
@@ -46,8 +46,8 @@ export default function SectionPills({ className }: { className?: string }) {
             className={cn(
               'rounded-full px-4 py-2 text-sm whitespace-nowrap transition-colors',
               isActive
-                ? 'bg-border text-foreground dark:bg-accent dark:text-white'
-                : 'text-muted-foreground hover:bg-accent/50 dark:text-gray',
+                ? 'bg-border text-foreground dark:bg-accent'
+                : 'text-muted-foreground hover:bg-accent/50',
             )}
           >
             {t(entry.labelKey)}
diff --git a/frontend/src/navigation/SectionRail.tsx b/frontend/src/navigation/SectionRail.tsx
index 5ece5227..c62f5828 100644
--- a/frontend/src/navigation/SectionRail.tsx
+++ b/frontend/src/navigation/SectionRail.tsx
@@ -42,12 +42,11 @@ export default function SectionRail({
     >
       <Button
         type="button"
-        variant="ghost"
+        variant="ghost-muted"
         size="icon"
         onClick={onBack}
         aria-label={backLabel}
         title={backLabel}
-        className="text-muted-foreground hover:text-foreground"
       >
         <ArrowLeft className="size-5" strokeWidth={1.75} />
       </Button>
diff --git a/frontend/src/navigation/SidebarLevel.tsx b/frontend/src/navigation/SidebarLevel.tsx
index 20d15f10..a3989a29 100644
--- a/frontend/src/navigation/SidebarLevel.tsx
+++ b/frontend/src/navigation/SidebarLevel.tsx
@@ -58,6 +58,10 @@ export default function SidebarLevel({
         // the container clips once it comes to rest — so the layering only
         // shows while there is layering to show.
         offset === 0 &&
+          /* eslint-disable-next-line shadcn/no-arbitrary-values -- the
+             incoming panel's leading-edge shadow is horizontal; no scale
+             shadow is, and the container clips it at rest (DESIGN.md
+             Approved exceptions). */
           'visible translate-x-0 opacity-100 shadow-[-12px_0_24px_-6px_rgba(0,0,0,0.45)]',
         // Dimmed rather than faded out: at rest the panel in front covers it
         // completely, so there is nothing to hide, and keeping it legible
diff --git a/frontend/src/navigation/SidebarNavRow.test.tsx b/frontend/src/navigation/SidebarNavRow.test.tsx
new file mode 100644
index 00000000..df1cbf33
--- /dev/null
+++ b/frontend/src/navigation/SidebarNavRow.test.tsx
@@ -0,0 +1,55 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { MemoryRouter, NavLink } from 'react-router-dom';
+
+import { Button } from '../components/ui/button';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+// Navigation.tsx renders its sidebar rows as
+// <Button variant="sidebar-item" asChild><NavLink end /></Button>; the
+// variant keys its selected fill on the aria-current NavLink sets.
+function renderRow(path: string) {
+  act(() => {
+    root.render(
+      <MemoryRouter initialEntries={[path]}>
+        <Button variant="sidebar-item" asChild className="mx-4 mt-2 flex">
+          <NavLink to="/agents/manage" end>
+            Manage agents
+          </NavLink>
+        </Button>
+      </MemoryRouter>,
+    );
+  });
+  return container.querySelector('a') as HTMLAnchorElement;
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+describe('sidebar nav row', () => {
+  it('is marked current on the exact route', () => {
+    const link = renderRow('/agents/manage');
+    expect(link.getAttribute('aria-current')).toBe('page');
+    expect(link.dataset.variant).toBe('sidebar-item');
+    expect(link.className).toContain('aria-[current=page]:bg-sidebar-accent');
+    expect(link.className).toContain('mx-4');
+    expect(link.classList.contains('inline-flex')).toBe(false);
+  });
+
+  it('is not current on a nested route, because of end', () => {
+    const link = renderRow('/agents/manage/abc');
+    expect(link.hasAttribute('aria-current')).toBe(false);
+  });
+});
diff --git a/frontend/src/notifications/ActionToast.test.tsx b/frontend/src/notifications/ActionToast.test.tsx
new file mode 100644
index 00000000..e5a4e41b
--- /dev/null
+++ b/frontend/src/notifications/ActionToast.test.tsx
@@ -0,0 +1,94 @@
+import { configureStore } from '@reduxjs/toolkit';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { Provider } from 'react-redux';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import ActionToast, { ACTION_TOAST_DISMISS_MS } from './ActionToast';
+import actionToastReducer, { showActionToast } from './actionToastSlice';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const makeStore = () =>
+  configureStore({ reducer: { actionToast: actionToastReducer } });
+
+describe('ActionToast', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let store: ReturnType<typeof makeStore>;
+
+  beforeEach(async () => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    store = makeStore();
+    await act(async () => {
+      root.render(
+        <Provider store={store}>
+          <ActionToast />
+        </Provider>,
+      );
+    });
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    vi.useRealTimers();
+  });
+
+  const show = async (variant: 'success' | 'destructive', message: string) =>
+    act(async () => {
+      store.dispatch(showActionToast({ variant, message }));
+    });
+
+  it('renders nothing when there is no toast', () => {
+    expect(container.querySelector('[data-slot="toast"]')).toBeNull();
+  });
+
+  it('renders the message as a card with the variant header', async () => {
+    await show('success', 'lena deactivated');
+    const card = container.querySelector('[data-slot="toast"]');
+    expect(card?.textContent).toContain('lena deactivated');
+    // Cards carry no role; the shared ToastViewport is the live region.
+    expect(card?.getAttribute('role')).toBeNull();
+    expect(
+      container
+        .querySelector('[data-slot="toast-header"]')
+        ?.getAttribute('data-variant'),
+    ).toBe('success');
+  });
+
+  it('uses the destructive header for a failure', async () => {
+    await show('destructive', 'Action failed for lena');
+    expect(
+      container
+        .querySelector('[data-slot="toast-header"]')
+        ?.getAttribute('data-variant'),
+    ).toBe('destructive');
+  });
+
+  it('closes on the dismiss button', async () => {
+    await show('success', 'done');
+    const btn = container.querySelector(
+      'button[aria-label="notifications.dismiss"]',
+    ) as HTMLButtonElement;
+    await act(async () => btn.click());
+    expect(container.querySelector('[data-slot="toast"]')).toBeNull();
+  });
+
+  it('auto-dismisses after 4.5s, restarting for a new message', async () => {
+    vi.useFakeTimers();
+    expect(ACTION_TOAST_DISMISS_MS).toBe(4500);
+    await show('success', 'first');
+    await act(async () => vi.advanceTimersByTime(3000));
+    await show('success', 'second');
+    await act(async () => vi.advanceTimersByTime(3000));
+    expect(container.textContent).toContain('second');
+    await act(async () => vi.advanceTimersByTime(1600));
+    expect(container.querySelector('[data-slot="toast"]')).toBeNull();
+  });
+});
diff --git a/frontend/src/notifications/ActionToast.tsx b/frontend/src/notifications/ActionToast.tsx
new file mode 100644
index 00000000..0595ecb8
--- /dev/null
+++ b/frontend/src/notifications/ActionToast.tsx
@@ -0,0 +1,59 @@
+import { X } from 'lucide-react';
+import { useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useDispatch, useSelector } from 'react-redux';
+
+import { Button } from '../components/ui/button';
+import {
+  Toast,
+  ToastActions,
+  ToastHeader,
+  ToastTitle,
+} from '../components/ui/toast';
+
+import { dismissActionToast, selectActionToast } from './actionToastSlice';
+
+export const ACTION_TOAST_DISMISS_MS = 4500;
+
+/**
+ * The result of an action a page just ran (dispatch `showActionToast`),
+ * shown as a card in the shared `ToastViewport` mounted in App.tsx. Returns
+ * only the card; the viewport is the live region. Auto-dismisses after
+ * 4.5s, restarting whenever a new result replaces the card.
+ */
+export default function ActionToast() {
+  const dispatch = useDispatch();
+  const { t } = useTranslation();
+  const toast = useSelector(selectActionToast);
+  const id = toast?.id;
+
+  useEffect(() => {
+    if (id === undefined) return;
+    const timer = window.setTimeout(
+      () => dispatch(dismissActionToast(id)),
+      ACTION_TOAST_DISMISS_MS,
+    );
+    return () => window.clearTimeout(timer);
+  }, [id, dispatch]);
+
+  if (!toast) return null;
+
+  return (
+    <Toast>
+      <ToastHeader variant={toast.variant}>
+        <ToastTitle wrap>{toast.message}</ToastTitle>
+        <ToastActions>
+          <Button
+            type="button"
+            variant="ghost-muted"
+            size="icon-sm"
+            onClick={() => dispatch(dismissActionToast(toast.id))}
+            aria-label={t('notifications.dismiss')}
+          >
+            <X className="size-4" />
+          </Button>
+        </ToastActions>
+      </ToastHeader>
+    </Toast>
+  );
+}
diff --git a/frontend/src/notifications/TeamNotificationToast.test.tsx b/frontend/src/notifications/TeamNotificationToast.test.tsx
new file mode 100644
index 00000000..b034508f
--- /dev/null
+++ b/frontend/src/notifications/TeamNotificationToast.test.tsx
@@ -0,0 +1,109 @@
+import { configureStore } from '@reduxjs/toolkit';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { Provider } from 'react-redux';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, opts?: Record<string, unknown>) =>
+      opts && 'team' in opts ? `${key}:${opts.team}` : key,
+  }),
+}));
+
+import notificationsReducer, { sseEventReceived } from './notificationsSlice';
+import TeamNotificationToast from './TeamNotificationToast';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const makeStore = () =>
+  configureStore({ reducer: { notifications: notificationsReducer } });
+
+describe('TeamNotificationToast', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let store: ReturnType<typeof makeStore>;
+
+  beforeEach(() => {
+    localStorage.clear();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    store = makeStore();
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+    vi.useRealTimers();
+  });
+
+  const renderToast = async () => {
+    await act(async () => {
+      root.render(
+        <Provider store={store}>
+          <TeamNotificationToast />
+        </Provider>,
+      );
+    });
+  };
+
+  const addMember = (id: string) =>
+    store.dispatch(
+      sseEventReceived({
+        id,
+        type: 'team.member_added',
+        payload: { team_name: 'Ops', role: 'team_member' },
+      }),
+    );
+
+  it('renders nothing without team events', async () => {
+    await renderToast();
+    expect(container.innerHTML).toBe('');
+  });
+
+  it('renders title and body on the shared toast primitive', async () => {
+    addMember('e1');
+    await renderToast();
+    // Cards only: App.tsx owns the one shared ToastViewport (the live
+    // region), so the component renders neither a rail nor a role.
+    expect(container.querySelector('[data-slot="toast-viewport"]')).toBeNull();
+    expect(container.querySelector('[role="status"]')).toBeNull();
+    const toast = container.querySelector('[data-slot="toast"]');
+    expect(toast).not.toBeNull();
+    expect(toast?.parentElement).toBe(container);
+    const title = container.querySelector('[data-slot="toast-title"]');
+    expect(title?.textContent).toBe('notifications.memberAddedTitle');
+    // A long localized title wraps rather than truncating.
+    expect(title?.className).not.toContain('truncate');
+    const body = container.querySelector('[data-slot="toast-message"]');
+    expect(body?.textContent).toBe('notifications.memberAddedBody:Ops');
+    expect(body?.className).toContain('text-sm');
+  });
+
+  it('dismisses on the close button', async () => {
+    addMember('e1');
+    await renderToast();
+    const close = container.querySelector(
+      'button[aria-label="notifications.dismiss"]',
+    ) as HTMLButtonElement;
+    expect(close).not.toBeNull();
+    await act(async () => close.click());
+    expect(container.innerHTML).toBe('');
+    expect(
+      store
+        .getState()
+        .notifications.dismissedShareNotifications.map((e) => e.id),
+    ).toContain('e1');
+  });
+
+  it('auto-dismisses after its own timer', async () => {
+    vi.useFakeTimers();
+    addMember('e1');
+    await renderToast();
+    expect(container.querySelector('[data-slot="toast"]')).not.toBeNull();
+    await act(async () => {
+      vi.advanceTimersByTime(8000);
+    });
+    expect(container.innerHTML).toBe('');
+  });
+});
diff --git a/frontend/src/notifications/TeamNotificationToast.tsx b/frontend/src/notifications/TeamNotificationToast.tsx
index 27fccae9..ebb57e9e 100644
--- a/frontend/src/notifications/TeamNotificationToast.tsx
+++ b/frontend/src/notifications/TeamNotificationToast.tsx
@@ -4,6 +4,14 @@ import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 
 import { Button } from '../components/ui/button';
+import {
+  Toast,
+  ToastActions,
+  ToastContent,
+  ToastHeader,
+  ToastMessage,
+  ToastTitle,
+} from '../components/ui/toast';
 
 import {
   dismissShareNotification,
@@ -50,28 +58,25 @@ function ShareToast({
   }, [id, onDismiss]);
 
   return (
-    <div className="border-border bg-card shadow-toast w-[271px] overflow-hidden rounded-2xl border">
-      <div className="bg-accent/50 dark:bg-muted flex items-center justify-between px-4 py-3">
-        <h3 className="dark:text-foreground text-sm leading-[16.5px] font-medium text-black">
-          {title}
-        </h3>
-        <Button
-          type="button"
-          variant="ghost"
-          size="icon-sm"
-          onClick={() => onDismiss(id)}
-          className="h-8 w-8 p-0 text-black opacity-70 transition-opacity hover:bg-transparent hover:opacity-100 dark:text-white"
-          aria-label={dismissLabel}
-        >
-          <X className="h-4 w-4" />
-        </Button>
-      </div>
-      <div className="px-5 py-3">
-        <p className="dark:text-muted-foreground text-sm leading-[18px] font-normal text-black">
-          {body}
-        </p>
-      </div>
-    </div>
+    <Toast>
+      <ToastHeader variant="default">
+        <ToastTitle wrap>{title}</ToastTitle>
+        <ToastActions>
+          <Button
+            type="button"
+            variant="ghost-muted"
+            size="icon-sm"
+            onClick={() => onDismiss(id)}
+            aria-label={dismissLabel}
+          >
+            <X className="h-4 w-4" />
+          </Button>
+        </ToastActions>
+      </ToastHeader>
+      <ToastContent>
+        <ToastMessage size="sm">{body}</ToastMessage>
+      </ToastContent>
+    </Toast>
   );
 }
 
@@ -141,16 +146,10 @@ export default function TeamNotificationToast() {
     };
   };
 
+  // Cards only: App.tsx mounts the shared ToastViewport (the live region)
+  // and stacks these above ToolApprovalToast and UploadToast.
   return (
-    // Standard bottom-right toast rail. UploadToast / ToolApprovalToast use the
-    // same corner but rarely co-occur with team-share toasts.
-    <div
-      className="fixed right-4 bottom-4 z-50 flex max-w-md flex-col gap-2"
-      onMouseDown={(e) => e.stopPropagation()}
-      role="status"
-      aria-live="polite"
-      aria-atomic="true"
-    >
+    <>
       {visible.map((event) => {
         const { title, body } = describe(event);
         return (
@@ -164,6 +163,6 @@ export default function TeamNotificationToast() {
           />
         );
       })}
-    </div>
+    </>
   );
 }
diff --git a/frontend/src/notifications/ToolApprovalToast.test.tsx b/frontend/src/notifications/ToolApprovalToast.test.tsx
new file mode 100644
index 00000000..5dd68d59
--- /dev/null
+++ b/frontend/src/notifications/ToolApprovalToast.test.tsx
@@ -0,0 +1,144 @@
+import { configureStore } from '@reduxjs/toolkit';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { Provider } from 'react-redux';
+import { MemoryRouter, Route, Routes, useLocation } from 'react-router-dom';
+
+import en from '../locale/en.json';
+
+// Resolve keys against the English bundle so assertions read as the UI does.
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string) =>
+      key
+        .split('.')
+        .reduce<unknown>(
+          (node, part) => (node as Record<string, unknown>)?.[part],
+          en,
+        ) ?? key,
+  }),
+}));
+
+import notificationsReducer, { sseEventReceived } from './notificationsSlice';
+import ToolApprovalToast from './ToolApprovalToast';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const makeStore = () =>
+  configureStore({
+    reducer: {
+      notifications: notificationsReducer,
+      preference: () => ({
+        conversations: { data: [{ id: 'c1', name: 'Halvorsen review' }] },
+      }),
+    },
+  });
+
+function Location() {
+  return <span data-testid="location">{useLocation().pathname}</span>;
+}
+
+describe('ToolApprovalToast', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let store: ReturnType<typeof makeStore>;
+
+  beforeEach(() => {
+    localStorage.clear();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    store = makeStore();
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const renderAt = async (path: string) => {
+    await act(async () => {
+      root.render(
+        <Provider store={store}>
+          <MemoryRouter initialEntries={[path]}>
+            <Routes>
+              <Route
+                path="*"
+                element={
+                  <>
+                    <ToolApprovalToast />
+                    <Location />
+                  </>
+                }
+              />
+            </Routes>
+          </MemoryRouter>
+        </Provider>,
+      );
+    });
+  };
+
+  const pause = (id: string, conversationId: string) =>
+    store.dispatch(
+      sseEventReceived({
+        id,
+        type: 'tool.approval.required',
+        scope: { kind: 'conversation', id: conversationId },
+      }),
+    );
+
+  const toasts = () => container.querySelectorAll('[data-slot="toast"]');
+
+  it('renders a warning card with no rail of its own', async () => {
+    pause('e1', 'c1');
+    await renderAt('/');
+    expect(toasts()).toHaveLength(1);
+    // App.tsx owns the shared ToastViewport and its live region.
+    expect(container.querySelector('[data-slot="toast-viewport"]')).toBeNull();
+    expect(container.querySelector('[role="status"]')).toBeNull();
+    expect(container.querySelector('.fixed')).toBeNull();
+    expect(
+      container
+        .querySelector('[data-slot="toast-header"]')
+        ?.getAttribute('data-variant'),
+    ).toBe('warning');
+    expect(
+      container.querySelector('[data-slot="toast-title"]')?.textContent,
+    ).toBe('Tool approval needed');
+    const item = container.querySelector('[data-slot="toast-item"]');
+    expect(item?.textContent).toContain('Halvorsen review');
+    expect(item?.querySelector('[data-status="warning"]')).not.toBeNull();
+  });
+
+  it('dedups per conversation and hides the one in view', async () => {
+    pause('e1', 'c1');
+    pause('e2', 'c1');
+    pause('e3', 'c2');
+    await renderAt('/c/c2');
+    expect(toasts()).toHaveLength(1);
+    expect(container.textContent).toContain('Halvorsen review');
+  });
+
+  it('dismisses on close', async () => {
+    pause('e1', 'c1');
+    await renderAt('/');
+    const close = container.querySelector(
+      'button[aria-label="Dismiss"]',
+    ) as HTMLButtonElement;
+    await act(async () => close.click());
+    expect(toasts()).toHaveLength(0);
+  });
+
+  it('navigates to the conversation on Review', async () => {
+    pause('e1', 'c1');
+    await renderAt('/');
+    const review = Array.from(container.querySelectorAll('button')).find(
+      (b) => b.textContent === 'Review',
+    ) as HTMLButtonElement;
+    await act(async () => review.click());
+    expect(
+      container.querySelector('[data-testid="location"]')?.textContent,
+    ).toBe('/c/c1');
+    expect(toasts()).toHaveLength(0);
+  });
+});
diff --git a/frontend/src/notifications/ToolApprovalToast.tsx b/frontend/src/notifications/ToolApprovalToast.tsx
index 79e3dd65..1b12f226 100644
--- a/frontend/src/notifications/ToolApprovalToast.tsx
+++ b/frontend/src/notifications/ToolApprovalToast.tsx
@@ -1,9 +1,18 @@
 import { X } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 import { useMatch, useNavigate } from 'react-router-dom';
 
-import WarnIcon from '../assets/warn.svg';
 import { Button } from '../components/ui/button';
+import {
+  Toast,
+  ToastActions,
+  ToastContent,
+  ToastHeader,
+  ToastItem,
+  ToastStatus,
+  ToastTitle,
+} from '../components/ui/toast';
 import type { RootState } from '../store';
 
 import {
@@ -17,9 +26,10 @@ import {
 const APPROVAL_EVENT_MAX_AGE_MS = 35 * 60 * 1000;
 
 /**
- * Surface ``tool.approval.required`` events as toasts that look like
- * ``UploadToast`` (same fixed bottom-right rail) — but only when the
- * user is NOT already on the conversation that needs the approval.
+ * Surface ``tool.approval.required`` events as toast cards in the shared
+ * ``ToastViewport`` (mounted in App.tsx, between the team notifications
+ * and ``UploadToast``) — but only when the user is NOT already on the
+ * conversation that needs the approval.
  *
  * - Dedup by ``conversation_id`` (the SSE ``scope.id``): keep only
  *   the newest pending event per conversation, so multiple paused
@@ -29,6 +39,7 @@ const APPROVAL_EVENT_MAX_AGE_MS = 35 * 60 * 1000;
  * - Clicking "Review" navigates to ``/c/<id>`` and dismisses.
  */
 export default function ToolApprovalToast() {
+  const { t } = useTranslation();
   const dispatch = useDispatch();
   const navigate = useNavigate();
   const events = useSelector(selectRecentEvents);
@@ -98,74 +109,53 @@ export default function ToolApprovalToast() {
 
   const conversationName = (conversationId: string): string => {
     const found = conversations?.find((c) => c.id === conversationId);
-    return found?.name ?? 'Conversation';
+    return found?.name ?? t('notifications.toolApprovalFallbackName');
   };
 
   return (
-    // Sit above ``UploadToast`` (which owns ``bottom-4 right-4``)
-    // rather than overlapping it. ``bottom-24`` ≈ 96px clears one
-    // standard-height upload toast; multiple in-flight uploads will
-    // stack into the gap, at which point the approval toast still
-    // floats on top via ``z-50``. Acceptable v1 layout — the two
-    // surfaces are rarely competing.
-    <div
-      className="fixed right-4 bottom-24 z-50 flex max-w-md flex-col gap-2"
-      onMouseDown={(e) => e.stopPropagation()}
-      role="status"
-      aria-live="polite"
-      aria-atomic="true"
-    >
+    <>
       {Array.from(pendingByConversation.values()).map(
         ({ eventId, conversationId }) => (
-          <div
-            key={eventId}
-            className="border-border bg-card shadow-toast w-[271px] overflow-hidden rounded-2xl border"
-          >
-            <div className="bg-accent/50 dark:bg-muted flex items-center justify-between px-4 py-3">
-              <h3 className="dark:text-foreground text-sm leading-[16.5px] font-medium text-black">
-                Tool approval needed
-              </h3>
-              <Button
-                type="button"
-                variant="ghost"
-                size="icon-sm"
-                onClick={() => dispatch(dismissToolApproval(eventId))}
-                className="h-8 w-8 p-0 text-black opacity-70 transition-opacity hover:bg-transparent hover:opacity-100 dark:text-white"
-                aria-label="Dismiss"
-              >
-                <X className="h-4 w-4" />
-              </Button>
-            </div>
-            <div className="flex items-center justify-between gap-3 px-5 py-3">
-              <div className="flex min-w-0 items-center gap-2">
-                <img
-                  src={WarnIcon}
-                  alt=""
-                  className="h-5 w-5 shrink-0"
-                  aria-hidden="true"
-                />
-                <p
-                  className="dark:text-muted-foreground max-w-[140px] truncate text-sm leading-[16.5px] font-normal text-black"
-                  title={conversationName(conversationId)}
+          <Toast key={eventId}>
+            <ToastHeader variant="warning">
+              <ToastTitle>{t('notifications.toolApprovalTitle')}</ToastTitle>
+              <ToastActions>
+                <Button
+                  type="button"
+                  variant="ghost-muted"
+                  size="icon-sm"
+                  onClick={() => dispatch(dismissToolApproval(eventId))}
+                  aria-label={t('notifications.dismiss')}
                 >
-                  {conversationName(conversationId)}
-                </p>
-              </div>
-              <Button
-                type="button"
-                size="sm"
-                onClick={() => {
-                  dispatch(dismissToolApproval(eventId));
-                  navigate(`/c/${conversationId}`);
-                }}
-                className="h-auto rounded-full px-3 py-1 text-xs font-medium text-white shadow-sm"
+                  <X className="h-4 w-4" />
+                </Button>
+              </ToastActions>
+            </ToastHeader>
+            <ToastContent>
+              <ToastItem
+                icon={<ToastStatus status="warning" />}
+                label={
+                  <span title={conversationName(conversationId)}>
+                    {conversationName(conversationId)}
+                  </span>
+                }
               >
-                Review
-              </Button>
-            </div>
-          </div>
+                <Button
+                  type="button"
+                  size="xs"
+                  shape="pill"
+                  onClick={() => {
+                    dispatch(dismissToolApproval(eventId));
+                    navigate(`/c/${conversationId}`);
+                  }}
+                >
+                  {t('notifications.toolApprovalReview')}
+                </Button>
+              </ToastItem>
+            </ToastContent>
+          </Toast>
         ),
       )}
-    </div>
+    </>
   );
 }
diff --git a/frontend/src/notifications/actionToastSlice.test.ts b/frontend/src/notifications/actionToastSlice.test.ts
new file mode 100644
index 00000000..3a538d51
--- /dev/null
+++ b/frontend/src/notifications/actionToastSlice.test.ts
@@ -0,0 +1,54 @@
+import actionToastReducer, {
+  dismissActionToast,
+  selectActionToast,
+  showActionToast,
+} from './actionToastSlice';
+
+const state = (s: ReturnType<typeof actionToastReducer>) => ({
+  actionToast: s,
+});
+
+describe('actionToastSlice', () => {
+  it('starts empty', () => {
+    const s = actionToastReducer(undefined, { type: '@@init' });
+    expect(selectActionToast(state(s))).toBeNull();
+  });
+
+  it('shows a toast with a fresh id, replacing the previous one', () => {
+    let s = actionToastReducer(
+      undefined,
+      showActionToast({ variant: 'success', message: 'a deactivated' }),
+    );
+    const first = selectActionToast(state(s));
+    expect(first).toMatchObject({
+      variant: 'success',
+      message: 'a deactivated',
+    });
+
+    s = actionToastReducer(
+      s,
+      showActionToast({
+        variant: 'destructive',
+        message: 'Action failed for a',
+      }),
+    );
+    const second = selectActionToast(state(s));
+    expect(second).toMatchObject({
+      variant: 'destructive',
+      message: 'Action failed for a',
+    });
+    expect(second?.id).not.toBe(first?.id);
+  });
+
+  it('dismisses only the toast with the given id', () => {
+    let s = actionToastReducer(
+      undefined,
+      showActionToast({ variant: 'success', message: 'one' }),
+    );
+    const id = selectActionToast(state(s))!.id;
+    s = actionToastReducer(s, dismissActionToast(id + 1));
+    expect(selectActionToast(state(s))).not.toBeNull();
+    s = actionToastReducer(s, dismissActionToast(id));
+    expect(selectActionToast(state(s))).toBeNull();
+  });
+});
diff --git a/frontend/src/notifications/actionToastSlice.ts b/frontend/src/notifications/actionToastSlice.ts
new file mode 100644
index 00000000..cf2e745a
--- /dev/null
+++ b/frontend/src/notifications/actionToastSlice.ts
@@ -0,0 +1,43 @@
+import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
+
+export type ActionToastVariant = 'success' | 'destructive';
+
+export type ActionToastState = {
+  id: number;
+  variant: ActionToastVariant;
+  message: string;
+};
+
+type SliceState = { current: ActionToastState | null; nextId: number };
+
+const initialState: SliceState = { current: null, nextId: 1 };
+
+/**
+ * One transient result card for an action a page just ran (the admin Users
+ * actions today). A new result replaces the previous one; the fresh `id`
+ * restarts the card's auto-dismiss timer.
+ */
+const actionToastSlice = createSlice({
+  name: 'actionToast',
+  initialState,
+  reducers: {
+    showActionToast(
+      state,
+      action: PayloadAction<{ variant: ActionToastVariant; message: string }>,
+    ) {
+      state.current = { id: state.nextId, ...action.payload };
+      state.nextId += 1;
+    },
+    dismissActionToast(state, action: PayloadAction<number>) {
+      if (state.current?.id === action.payload) state.current = null;
+    },
+  },
+});
+
+export const { showActionToast, dismissActionToast } = actionToastSlice.actions;
+
+export const selectActionToast = (state: {
+  actionToast: SliceState;
+}): ActionToastState | null => state.actionToast.current;
+
+export default actionToastSlice.reducer;
diff --git a/frontend/src/preferences/PromptsModal.test.tsx b/frontend/src/preferences/PromptsModal.test.tsx
new file mode 100644
index 00000000..8e4268a5
--- /dev/null
+++ b/frontend/src/preferences/PromptsModal.test.tsx
@@ -0,0 +1,87 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('../hooks', () => ({
+  useMediaQuery: () => ({ isMobile: false, isTablet: false, isDesktop: true }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => 'token',
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('react-router-dom', () => ({
+  Link: ({ children }: { children: React.ReactNode }) => <a>{children}</a>,
+}));
+
+vi.mock('../api/services/userService', () => ({
+  default: {
+    getUserTools: () =>
+      Promise.resolve({ json: () => Promise.resolve({ success: false }) }),
+  },
+}));
+
+import PromptsModal from './PromptsModal';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('PromptsModal', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = async () => {
+    await act(async () => {
+      root.render(
+        <PromptsModal
+          existingPrompts={[]}
+          modalState="ACTIVE"
+          setModalState={() => undefined}
+          type="ADD"
+          newPromptName=""
+          setNewPromptName={() => undefined}
+          newPromptContent="Hello {{ source.content }}"
+          setNewPromptContent={() => undefined}
+          editPromptName=""
+          setEditPromptName={() => undefined}
+          editPromptContent=""
+          setEditPromptContent={() => undefined}
+          currentPromptEdit={{ name: '', id: '', type: '' }}
+        />,
+      );
+    });
+  };
+
+  it('edits the prompt text in a large Textarea', async () => {
+    await render();
+    const textarea = document.body.querySelector<HTMLTextAreaElement>(
+      '#new-prompt-content',
+    );
+    expect(textarea?.dataset.slot).toBe('textarea');
+    expect(textarea?.dataset.size).toBe('lg');
+  });
+
+  it('scrolls the highlight layer through custom properties, not a transform', async () => {
+    await render();
+    const layer = document.body.querySelector<HTMLElement>(
+      '.prompt-variable-highlight',
+    )?.parentElement;
+    expect(layer).toBeTruthy();
+    expect(layer?.style.transform).toBe('');
+    expect(layer?.style.getPropertyValue('--scroll-x')).toBe('0px');
+    expect(layer?.style.getPropertyValue('--scroll-y')).toBe('0px');
+  });
+});
diff --git a/frontend/src/preferences/PromptsModal.tsx b/frontend/src/preferences/PromptsModal.tsx
index b5c18187..c4da7bbe 100644
--- a/frontend/src/preferences/PromptsModal.tsx
+++ b/frontend/src/preferences/PromptsModal.tsx
@@ -1,6 +1,7 @@
 import { ChevronDown } from 'lucide-react';
 import { ActiveState } from '../models/misc';
 import { Input } from '../components/ui/input';
+import { Textarea } from '../components/ui/textarea';
 import { Link } from 'react-router-dom';
 
 import React from 'react';
@@ -18,6 +19,7 @@ import BookIcon from '../assets/book.svg';
 import userService from '../api/services/userService';
 import { selectToken } from '../preferences/preferenceSlice';
 import { UserToolType } from '../settings/types';
+import { cn } from '@/lib/utils';
 
 const variablePattern = /(\{\{\s*[^{}]+\s*\}\}|\{(?!\{)[^{}]+\})/g;
 
@@ -107,8 +109,8 @@ type VariableMenuProps = {
   textareaId: string;
   content: string;
   setContent: (content: string) => void;
-  triggerClassName?: string;
-  contentClassName?: string;
+  /** Which variables the menu inserts; sets the trigger's width. */
+  kind: 'system' | 'tool';
 };
 
 function VariableMenu({
@@ -117,8 +119,7 @@ function VariableMenu({
   textareaId,
   content,
   setContent,
-  triggerClassName,
-  contentClassName,
+  kind,
 }: VariableMenuProps) {
   const handleSelect = (value: string) => {
     const textarea = document.getElementById(textareaId) as HTMLTextAreaElement;
@@ -150,17 +151,20 @@ function VariableMenu({
       <DropdownMenuTrigger asChild>
         <Button
           type="button"
-          variant="outline"
-          className={`border-border bg-card text-foreground hover:bg-accent h-auto justify-between rounded-3xl px-5 py-3 text-xs sm:text-sm ${triggerClassName ?? ''}`}
+          variant="combobox"
+          shape="pill"
+          className={cn(
+            'justify-between',
+            kind === 'system'
+              ? 'w-[140px] sm:w-[185px]'
+              : 'w-[140px] sm:w-[171px]',
+          )}
         >
           <span className="truncate">{label}</span>
           <ChevronDown className="text-muted-foreground ml-2 h-4 w-4 shrink-0" />
         </Button>
       </DropdownMenuTrigger>
-      <DropdownMenuContent
-        align="start"
-        className={`max-h-72 overflow-y-auto ${contentClassName ?? ''}`}
-      >
+      <DropdownMenuContent align="start" className="max-h-72 overflow-y-auto">
         {options.map((opt) => (
           <DropdownMenuItem
             key={opt.value}
@@ -206,21 +210,26 @@ function PromptTextarea({
   return (
     <>
       <div
-        className="bg-card pointer-events-none absolute inset-0 z-0 overflow-hidden rounded px-3 py-2"
+        className="bg-card pointer-events-none absolute inset-0 z-0 overflow-hidden rounded-2xl border border-transparent px-4 py-3"
         aria-hidden="true"
       >
         <div
-          className="min-h-full text-base leading-normal wrap-break-word whitespace-pre-wrap text-transparent"
-          style={{
-            transform: `translate(${-scrollOffsets.left}px, ${-scrollOffsets.top}px)`,
-          }}
+          className="min-h-full translate-x-(--scroll-x) translate-y-(--scroll-y) text-base wrap-break-word whitespace-pre-wrap text-transparent md:text-sm"
+          style={
+            {
+              '--scroll-x': `${-scrollOffsets.left}px`,
+              '--scroll-y': `${-scrollOffsets.top}px`,
+            } as React.CSSProperties
+          }
         >
           {highlightedValue}
         </div>
       </div>
-      <textarea
+      <Textarea
         id={id}
-        className="peer border-border dark:border-border focus-visible:ring-ring/50 focus-visible:border-ring relative z-10 h-48 w-full resize-none rounded border-2 bg-transparent px-3 py-2 text-base text-gray-800 outline-none focus-visible:ring-[3px] md:h-64 lg:h-80 dark:text-white"
+        size="lg"
+        resize="none"
+        className="peer relative z-10 h-48 md:h-64 lg:h-80"
         value={value}
         onChange={onChange}
         onScroll={handleScroll}
@@ -325,12 +334,12 @@ function AddPrompt({
 
   return (
     <div>
-      <p className="mb-1 text-xl font-semibold text-[#2B2B2B] dark:text-white">
+      <p className="text-foreground mb-1 text-xl font-semibold">
         {duplicateSourceName
           ? t('modals.prompts.duplicatePrompt')
           : t('modals.prompts.addPrompt')}
       </p>
-      <p className="dark:text-muted-foreground mb-6 text-sm text-[#6B6B6B]">
+      <p className="text-muted-foreground mb-6 text-sm">
         {duplicateSourceName
           ? t('modals.prompts.duplicateDescription', {
               name: duplicateSourceName,
@@ -344,7 +353,6 @@ function AddPrompt({
           className="mb-5"
           value={newPromptName}
           onChange={(e) => setNewPromptName(e.target.value)}
-          labelBgClassName="bg-card"
         />
 
         <div className="relative w-full">
@@ -356,9 +364,10 @@ function AddPrompt({
           />
           <label
             htmlFor="new-prompt-content"
-            className={`absolute z-20 select-none ${
-              newPromptContent ? '-top-2.5 left-3 text-xs' : ''
-            } text-muted-foreground bg-card pointer-events-none max-w-[calc(100%-24px)] cursor-none overflow-hidden px-2 text-ellipsis whitespace-nowrap transition-all peer-placeholder-shown:top-2.5 peer-placeholder-shown:left-3 peer-placeholder-shown:text-base peer-focus:-top-2.5 peer-focus:left-3 peer-focus:text-xs`}
+            className={cn(
+              'text-muted-foreground bg-card pointer-events-none absolute z-20 max-w-[calc(100%-24px)] cursor-none overflow-hidden px-2 text-ellipsis whitespace-nowrap transition-all select-none peer-placeholder-shown:top-3 peer-placeholder-shown:left-2 peer-placeholder-shown:text-base peer-focus:-top-2.5 peer-focus:left-3 peer-focus:text-xs',
+              newPromptContent && '-top-2.5 left-3 text-xs',
+            )}
           >
             {t('modals.prompts.promptText')}
           </label>
@@ -366,7 +375,7 @@ function AddPrompt({
       </div>
 
       <div className="mt-6 flex flex-col items-start justify-between gap-4 sm:flex-row sm:items-center sm:gap-4">
-        <p className="flex flex-col text-sm font-medium text-gray-700 dark:text-gray-300">
+        <p className="text-foreground flex flex-col text-sm font-medium">
           <span className="font-bold">
             {t('modals.prompts.variablesLabel')}
           </span>
@@ -382,7 +391,7 @@ function AddPrompt({
             textareaId="new-prompt-content"
             content={newPromptContent}
             setContent={setNewPromptContent}
-            triggerClassName="w-[140px] sm:w-[185px]"
+            kind="system"
           />
 
           <VariableMenu
@@ -391,7 +400,7 @@ function AddPrompt({
             textareaId="new-prompt-content"
             content={newPromptContent}
             setContent={setNewPromptContent}
-            triggerClassName="w-[140px] sm:w-[171px]"
+            kind="tool"
           />
         </div>
       </div>
@@ -420,7 +429,7 @@ function AddPrompt({
             type="button"
             variant="destructive-outline"
             onClick={() => setModalState('INACTIVE')}
-            className="h-auto rounded-3xl px-5 py-2 text-sm font-medium"
+            shape="pill"
           >
             {t('modals.prompts.cancel')}
           </Button>
@@ -428,7 +437,8 @@ function AddPrompt({
           <Button
             type="button"
             onClick={handleAddPrompt}
-            className="h-auto rounded-3xl px-6 py-2 text-sm font-medium text-white"
+            size="lg"
+            shape="pill"
             disabled={disableSave}
           >
             {t('modals.prompts.save')}
@@ -470,14 +480,14 @@ function EditPrompt({
 
   return (
     <div>
-      <p className="mb-1 text-xl font-semibold text-[#2B2B2B] dark:text-white">
+      <p className="text-foreground mb-1 text-xl font-semibold">
         {t(
           isReadOnly
             ? 'modals.prompts.viewPrompt'
             : 'modals.prompts.editPrompt',
         )}
       </p>
-      <p className="dark:text-muted-foreground mb-6 text-sm text-[#6B6B6B]">
+      <p className="text-muted-foreground mb-6 text-sm">
         {t(
           isReadOnly
             ? 'modals.prompts.viewDescription'
@@ -491,7 +501,6 @@ function EditPrompt({
           className="mb-5"
           value={editPromptName}
           onChange={(e) => setEditPromptName(e.target.value)}
-          labelBgClassName="bg-card"
           disabled={isReadOnly}
         />
 
@@ -505,9 +514,10 @@ function EditPrompt({
           />
           <label
             htmlFor="edit-prompt-content"
-            className={`absolute z-20 select-none ${
-              editPromptContent ? '-top-2.5 left-3 text-xs' : ''
-            } text-muted-foreground bg-card pointer-events-none max-w-[calc(100%-24px)] cursor-none overflow-hidden px-2 text-ellipsis whitespace-nowrap transition-all peer-placeholder-shown:top-2.5 peer-placeholder-shown:left-3 peer-placeholder-shown:text-base peer-focus:-top-2.5 peer-focus:left-3 peer-focus:text-xs`}
+            className={cn(
+              'text-muted-foreground bg-card pointer-events-none absolute z-20 max-w-[calc(100%-24px)] cursor-none overflow-hidden px-2 text-ellipsis whitespace-nowrap transition-all select-none peer-placeholder-shown:top-3 peer-placeholder-shown:left-2 peer-placeholder-shown:text-base peer-focus:-top-2.5 peer-focus:left-3 peer-focus:text-xs',
+              editPromptContent && '-top-2.5 left-3 text-xs',
+            )}
           >
             {t('modals.prompts.promptText')}
           </label>
@@ -516,7 +526,7 @@ function EditPrompt({
 
       {!isReadOnly && (
         <div className="mt-6 flex flex-col items-start justify-between gap-4 sm:flex-row sm:items-center sm:gap-4">
-          <p className="flex flex-col text-sm font-medium text-gray-700 dark:text-gray-300">
+          <p className="text-foreground flex flex-col text-sm font-medium">
             <span className="font-bold">
               {t('modals.prompts.variablesLabel')}
             </span>
@@ -532,7 +542,7 @@ function EditPrompt({
               textareaId="edit-prompt-content"
               content={editPromptContent}
               setContent={setEditPromptContent}
-              triggerClassName="w-[140px] sm:w-[185px]"
+              kind="system"
             />
 
             <VariableMenu
@@ -541,7 +551,7 @@ function EditPrompt({
               textareaId="edit-prompt-content"
               content={editPromptContent}
               setContent={setEditPromptContent}
-              triggerClassName="w-[140px] sm:w-[171px]"
+              kind="tool"
             />
           </div>
         </div>
@@ -571,7 +581,7 @@ function EditPrompt({
             type="button"
             variant="destructive-outline"
             onClick={() => setModalState('INACTIVE')}
-            className="h-auto rounded-3xl px-5 py-2 text-sm font-medium"
+            shape="pill"
           >
             {t('modals.prompts.cancel')}
           </Button>
@@ -581,7 +591,8 @@ function EditPrompt({
               <Button
                 type="button"
                 onClick={onDuplicate}
-                className="h-auto rounded-3xl px-6 py-2 text-sm font-medium text-white"
+                size="lg"
+                shape="pill"
               >
                 {t('modals.prompts.duplicate')}
               </Button>
@@ -596,7 +607,8 @@ function EditPrompt({
                     currentPromptEdit.type,
                   );
               }}
-              className="h-auto rounded-3xl px-6 py-2 text-sm font-medium text-white"
+              size="lg"
+              shape="pill"
               disabled={disableSave || !editPromptName}
               title={
                 disableSave && editPromptName
@@ -734,7 +746,7 @@ export default function PromptsModal({
       }
       size="lg"
       mobileVariant="sheet"
-      className="bg-card dark:bg-card w-[95vw] max-w-[650px] rounded-2xl px-4 py-4 sm:px-6 sm:py-6 md:max-w-[860px] md:px-8 md:py-6 lg:max-w-[980px]"
+      className="w-[95vw] max-w-[650px] md:max-w-[860px] lg:max-w-[980px]"
       contentClassName="!overflow-visible"
     >
       {view}
diff --git a/frontend/src/settings/Analytics.tsx b/frontend/src/settings/Analytics.tsx
index f67855bd..38ad8670 100644
--- a/frontend/src/settings/Analytics.tsx
+++ b/frontend/src/settings/Analytics.tsx
@@ -11,6 +11,7 @@ import { useEffect, useMemo, useRef, useState } from 'react';
 import { Bar } from 'react-chartjs-2';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
+import { foldSeries, OTHER_SERIES_KEY } from './foldSeries';
 
 import userService from '../api/services/userService';
 import SkeletonLoader from '../components/SkeletonLoader';
@@ -43,6 +44,22 @@ function readCssVar(name: string, fallback: string): string {
   return value || fallback;
 }
 
+/**
+ * Build the hover fill for a bar: the same colour at 80% opacity.
+ *
+ * `color-mix()` accepts any CSS colour string (hex, `oklch()`, ...), which the
+ * theme tokens are. Canvas `fillStyle` parses it in current engines; where the
+ * browser doesn't support `color-mix()` at all, keep the base colour so the
+ * canvas never receives a string it would silently ignore.
+ */
+function hoverColor(color: string): string {
+  const mixed = `color-mix(in oklch, ${color} 80%, transparent)`;
+  if (typeof CSS === 'undefined' || !CSS.supports?.('color', mixed)) {
+    return color;
+  }
+  return mixed;
+}
+
 import type { ChartData } from 'chart.js';
 ChartJS.register(
   CategoryScale,
@@ -53,18 +70,34 @@ ChartJS.register(
   Legend,
 );
 
-// Extra series colors for grouped/stacked charts. The first dataset always
-// uses the resolved `--primary` color; these follow for datasets 2..n.
-const SERIES_COLORS = [
-  '#FF6384',
-  '#36A2EB',
-  '#FFCE56',
-  '#4BC0C0',
-  '#9966FF',
-  '#FF9F40',
-  '#2BC596',
+// Data-series tokens (DESIGN.md: `chart-1`..`chart-5`, data series only).
+// Fallbacks are the light-theme values from src/index.css.
+const SERIES_TOKENS: [string, string][] = [
+  ['--chart-1', '#7d54d1'],
+  ['--chart-2', '#2563eb'],
+  ['--chart-3', '#079455'],
+  ['--chart-4', '#ca8a04'],
+  ['--chart-5', '#ef4444'],
 ];
 
+/**
+ * Resolve every colour the charts use from the current theme tokens.
+ *
+ * Returns concrete colour strings for the canvas: brand, the five series
+ * colours, the status colours, and the axis chrome.
+ */
+function readChartPalette() {
+  return {
+    primary: readCssVar('--primary', '#7d54d1'),
+    series: SERIES_TOKENS.map(([name, fallback]) => readCssVar(name, fallback)),
+    success: readCssVar('--success', '#079455'),
+    warning: readCssVar('--warning', '#ca8a04'),
+    destructive: readCssVar('--destructive', '#ef4444'),
+    border: readCssVar('--border', '#d9d9d9'),
+    mutedForeground: readCssVar('--muted-foreground', '#737373'),
+  };
+}
+
 type TokenGroupBy = 'none' | 'model' | 'agent' | 'source';
 
 type AnalyticsProps = {
@@ -152,16 +185,29 @@ export default function Analytics({ agentId }: AnalyticsProps) {
   const [loadingTools, setLoadingTools] = useLoaderState(true);
   const [loadingSchedules, setLoadingSchedules] = useLoaderState(true);
   const [isDarkTheme] = useDarkTheme();
-  const primaryColor = useMemo(
-    () => readCssVar('--primary', '#7d54d1'),
-    // isDarkTheme drives the `.dark` class on document.body and changes the
-    // resolved value of `--primary`; re-read whenever it flips.
-    [isDarkTheme],
+  // Each useDarkTheme() call keeps its own state and applies the `.dark`
+  // class in an effect, so a flip of `isDarkTheme` alone can be read before
+  // the class lands, and a toggle made elsewhere never reaches this
+  // component. Watch the body class too so the charts recolour either way.
+  const [themeVersion, setThemeVersion] = useState(0);
+  useEffect(() => {
+    const observer = new MutationObserver(() =>
+      setThemeVersion((version) => version + 1),
+    );
+    observer.observe(document.body, {
+      attributes: true,
+      attributeFilter: ['class'],
+    });
+    return () => observer.disconnect();
+  }, []);
+  const palette = useMemo(
+    () => readChartPalette(),
+    // Not used inside the factory: they only signal a theme change.
+    [isDarkTheme, themeVersion],
   );
+  const primaryColor = palette.primary;
   const seriesColor = (index: number) =>
-    index === 0
-      ? primaryColor
-      : SERIES_COLORS[(index - 1) % SERIES_COLORS.length];
+    palette.series[index % palette.series.length];
 
   // Monotonic request ids, one per chart: a response only lands if no
   // newer request for that chart was issued meanwhile, so an
@@ -361,7 +407,9 @@ export default function Analytics({ agentId }: AnalyticsProps) {
     },
   ];
 
-  const tokenSeriesEntries = Object.entries(tokenSeries || {});
+  // Grouped series have no meaning of their own, so past five they fold into
+  // "Other" instead of repeating a colour (DESIGN.md, chart colours).
+  const tokenSeriesEntries = foldSeries(Object.entries(tokenSeries || {}));
   const tokenLabels = Object.keys(
     tokenSeriesEntries[0]?.[1] || tokenUsageData || {},
   ).map((item) => formatDate(item));
@@ -371,7 +419,9 @@ export default function Analytics({ agentId }: AnalyticsProps) {
         ? key === 'prompt'
           ? t('settings.analytics.promptTokens')
           : t('settings.analytics.generatedTokens')
-        : key,
+        : key === OTHER_SERIES_KEY
+          ? t('settings.analytics.otherSeries')
+          : key,
     data: Object.values(series),
     backgroundColor: seriesColor(index),
   }));
@@ -390,10 +440,7 @@ export default function Analytics({ agentId }: AnalyticsProps) {
             if (opt) setTimeFilter(opt);
           }}
         >
-          <SelectTrigger
-            className="w-[125px] rounded-3xl px-5 py-3 text-sm"
-            size="lg"
-          >
+          <SelectTrigger className="w-[125px]" size="lg" shape="pill">
             <SelectValue
               placeholder={t('settings.analytics.filterPlaceholder')}
             />
@@ -414,7 +461,7 @@ export default function Analytics({ agentId }: AnalyticsProps) {
           <div
             key={card.label}
             title={card.hint}
-            className={`border-border dark:border-border rounded-2xl border px-6 py-5${card.hint ? ' cursor-help' : ''}`}
+            className={`border-border dark:border-border rounded-2xl border px-6 py-5 ${card.hint ? 'cursor-help' : ''}`}
           >
             <p className="text-muted-foreground text-sm">{card.label}</p>
             <p className="text-foreground dark:text-foreground mt-1 text-2xl font-bold">
@@ -455,6 +502,8 @@ export default function Analytics({ agentId }: AnalyticsProps) {
                 }}
                 legendID="legend-container-1"
                 maxTicksLimitInX={8}
+                gridColor={palette.border}
+                tickColor={palette.mutedForeground}
                 isStacked={false}
               />
             )}
@@ -471,10 +520,7 @@ export default function Analytics({ agentId }: AnalyticsProps) {
               value={tokenGroupBy}
               onValueChange={(value) => setTokenGroupBy(value as TokenGroupBy)}
             >
-              <SelectTrigger
-                className="w-[110px] rounded-3xl px-5 py-3 text-sm"
-                size="lg"
-              >
+              <SelectTrigger className="w-[110px]" size="lg" shape="pill">
                 <SelectValue placeholder={t('settings.analytics.groupBy')} />
               </SelectTrigger>
               <SelectContent>
@@ -510,6 +556,8 @@ export default function Analytics({ agentId }: AnalyticsProps) {
                 }}
                 legendID="legend-container-2"
                 maxTicksLimitInX={8}
+                gridColor={palette.border}
+                tickColor={palette.mutedForeground}
                 isStacked={true}
               />
             )}
@@ -544,26 +592,28 @@ export default function Analytics({ agentId }: AnalyticsProps) {
                       data: Object.values(scheduleData || {}).map(
                         (item) => item.completed,
                       ),
-                      backgroundColor: primaryColor,
+                      backgroundColor: palette.success,
                     },
                     {
                       label: t('settings.analytics.failed'),
                       data: Object.values(scheduleData || {}).map(
                         (item) => item.failed,
                       ),
-                      backgroundColor: '#FF6384',
+                      backgroundColor: palette.destructive,
                     },
                     {
                       label: t('settings.analytics.skipped'),
                       data: Object.values(scheduleData || {}).map(
                         (item) => item.skipped,
                       ),
-                      backgroundColor: '#FFCE56',
+                      backgroundColor: palette.warning,
                     },
                   ],
                 }}
                 legendID="legend-container-4"
                 maxTicksLimitInX={8}
+                gridColor={palette.border}
+                tickColor={palette.mutedForeground}
                 isStacked={true}
               />
             )}
@@ -593,17 +643,19 @@ export default function Analytics({ agentId }: AnalyticsProps) {
                       data: (toolsData || []).map(
                         (tool) => tool.calls - tool.failures,
                       ),
-                      backgroundColor: primaryColor,
+                      backgroundColor: palette.success,
                     },
                     {
                       label: t('settings.analytics.failed'),
                       data: (toolsData || []).map((tool) => tool.failures),
-                      backgroundColor: '#FF6384',
+                      backgroundColor: palette.destructive,
                     },
                   ],
                 }}
                 legendID="legend-container-5"
                 maxTicksLimitInX={8}
+                gridColor={palette.border}
+                tickColor={palette.mutedForeground}
                 isStacked={true}
               />
             )}
@@ -638,19 +690,21 @@ export default function Analytics({ agentId }: AnalyticsProps) {
                       data: Object.values(feedbackData || {}).map(
                         (item) => item.positive,
                       ),
-                      backgroundColor: primaryColor,
+                      backgroundColor: palette.success,
                     },
                     {
                       label: t('settings.analytics.negativeFeedback'),
                       data: Object.values(feedbackData || {}).map(
                         (item) => item.negative,
                       ),
-                      backgroundColor: '#FF6384',
+                      backgroundColor: palette.destructive,
                     },
                   ],
                 }}
                 legendID="legend-container-3"
                 maxTicksLimitInX={8}
+                gridColor={palette.border}
+                tickColor={palette.mutedForeground}
                 isStacked={false}
               />
             )}
@@ -666,6 +720,10 @@ type AnalyticsChartProps = {
   legendID: string;
   maxTicksLimitInX: number;
   isStacked: boolean;
+  /** Grid lines and axis borders (`--border`). */
+  gridColor: string;
+  /** Axis tick labels (`--muted-foreground`). */
+  tickColor: string;
 };
 
 function AnalyticsChart({
@@ -673,6 +731,8 @@ function AnalyticsChart({
   legendID,
   maxTicksLimitInX,
   isStacked,
+  gridColor,
+  tickColor,
 }: AnalyticsChartProps) {
   const options = {
     responsive: true,
@@ -689,25 +749,29 @@ function AnalyticsChart({
       x: {
         grid: {
           lineWidth: 0.2,
-          color: '#C4C4C4',
+          color: gridColor,
         },
         border: {
           width: 0.2,
-          color: '#C4C4C4',
+          color: gridColor,
         },
         ticks: {
           maxTicksLimit: maxTicksLimitInX,
+          color: tickColor,
         },
         stacked: isStacked,
       },
       y: {
         grid: {
           lineWidth: 0.2,
-          color: '#C4C4C4',
+          color: gridColor,
         },
         border: {
           width: 0.2,
-          color: '#C4C4C4',
+          color: gridColor,
+        },
+        ticks: {
+          color: tickColor,
         },
         stacked: isStacked,
       },
@@ -721,7 +785,10 @@ function AnalyticsChart({
         ...data,
         datasets: data.datasets.map((dataset) => ({
           ...dataset,
-          hoverBackgroundColor: `${dataset.backgroundColor}CC`, // 80% opacity
+          hoverBackgroundColor:
+            typeof dataset.backgroundColor === 'string'
+              ? hoverColor(dataset.backgroundColor)
+              : dataset.backgroundColor,
         })),
       }}
     />
diff --git a/frontend/src/settings/ConvertToWikiModal.tsx b/frontend/src/settings/ConvertToWikiModal.tsx
index d024b8b2..2eb5c683 100644
--- a/frontend/src/settings/ConvertToWikiModal.tsx
+++ b/frontend/src/settings/ConvertToWikiModal.tsx
@@ -1,9 +1,11 @@
+import { CircleAlert, CircleCheck } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 
 import userService from '../api/services/userService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Modal } from '../components/ui/modal';
 import { ActiveState, Doc } from '../models/misc';
@@ -159,14 +161,18 @@ export default function ConvertToWikiModal({
                 type="button"
                 variant="ghost"
                 onClick={closeModal}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('cancel')}
               </Button>
               <Button
                 type="button"
                 onClick={handleConvert}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('settings.sources.wiki.convert.confirm')}
               </Button>
@@ -185,16 +191,19 @@ export default function ConvertToWikiModal({
 
         {phase === 'summary' && summary && (
           <>
-            <div className="rounded-xl bg-green-50 p-4 text-sm text-green-800 dark:bg-green-900/30 dark:text-green-200">
-              {[
-                t('settings.sources.wiki.convert.summaryPages', {
-                  count: summary.pagesCreated,
-                }),
-                t('settings.sources.wiki.convert.summarySkipped', {
-                  count: summary.skipped.length,
-                }),
-              ].join(' · ')}
-            </div>
+            <Alert variant="success">
+              <CircleCheck className="size-4" aria-hidden="true" />
+              <AlertDescription>
+                {[
+                  t('settings.sources.wiki.convert.summaryPages', {
+                    count: summary.pagesCreated,
+                  }),
+                  t('settings.sources.wiki.convert.summarySkipped', {
+                    count: summary.skipped.length,
+                  }),
+                ].join(' · ')}
+              </AlertDescription>
+            </Alert>
             {summary.skipped.length > 0 && (
               <div className="flex flex-col gap-1.5">
                 <p className="text-foreground text-sm font-medium">
@@ -214,7 +223,9 @@ export default function ConvertToWikiModal({
               <Button
                 type="button"
                 onClick={closeModal}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('settings.sources.wiki.convert.done')}
               </Button>
@@ -224,15 +235,18 @@ export default function ConvertToWikiModal({
 
         {phase === 'error' && (
           <>
-            <div className="rounded-xl bg-red-50 p-4 text-sm text-red-700 dark:bg-red-900/40 dark:text-red-300">
-              {error}
-            </div>
+            <Alert variant="destructive">
+              <CircleAlert className="size-4" aria-hidden="true" />
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
             <div className="flex justify-end">
               <Button
                 type="button"
                 variant="ghost"
                 onClick={closeModal}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('cancel')}
               </Button>
diff --git a/frontend/src/settings/CustomModels.tsx b/frontend/src/settings/CustomModels.tsx
index 743eaf82..511f4808 100644
--- a/frontend/src/settings/CustomModels.tsx
+++ b/frontend/src/settings/CustomModels.tsx
@@ -177,7 +177,7 @@ export default function CustomModels() {
         alt={t('settings.customModels.empty')}
         className="mx-auto mb-6 h-32 w-32"
       />
-      <p className="text-center text-lg text-gray-500 dark:text-gray-400">
+      <p className="text-muted-foreground text-center text-lg">
         {t('settings.customModels.empty')}
       </p>
     </div>
@@ -199,8 +199,8 @@ export default function CustomModels() {
               id="custom-models-search-input"
               value={searchTerm}
               onChange={(e) => setSearchTerm(e.target.value)}
-              labelBgClassName="bg-background"
-              className="rounded-full"
+              labelSurface="background"
+              shape="pill"
               leftIcon={
                 <SearchIcon
                   className="text-muted-foreground size-4"
@@ -211,7 +211,8 @@ export default function CustomModels() {
           </div>
           <Button
             type="button"
-            className="h-11 min-w-[108px] rounded-full whitespace-normal text-white"
+            shape="pill"
+            className="h-11 min-w-[108px] whitespace-normal"
             onClick={openAddModal}
           >
             {t('settings.customModels.addModel')}
diff --git a/frontend/src/settings/EnableGraphRAGModal.tsx b/frontend/src/settings/EnableGraphRAGModal.tsx
index 7709b771..b2948791 100644
--- a/frontend/src/settings/EnableGraphRAGModal.tsx
+++ b/frontend/src/settings/EnableGraphRAGModal.tsx
@@ -1,11 +1,14 @@
+import { CircleAlert, CircleCheck } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useDispatch, useSelector } from 'react-redux';
 
 import userService from '../api/services/userService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Modal } from '../components/ui/modal';
+import { Progress } from '../components/ui/progress';
 import { ActiveState, Doc } from '../models/misc';
 import { selectToken } from '../preferences/preferenceSlice';
 import type { AppDispatch, RootState } from '../store';
@@ -236,14 +239,18 @@ export default function EnableGraphRAGModal({
                 type="button"
                 variant="ghost"
                 onClick={closeModal}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('cancel')}
               </Button>
               <Button
                 type="button"
                 onClick={handleEnable}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('settings.sources.graphrag.enable.confirm')}
               </Button>
@@ -262,36 +269,36 @@ export default function EnableGraphRAGModal({
                 : t('settings.sources.graphrag.enable.inProgress')}
             </p>
             {progressPct !== null && (
-              <div className="bg-muted h-1.5 w-48 overflow-hidden rounded-full">
-                <div
-                  className="bg-foreground/70 h-full rounded-full transition-all"
-                  style={{ width: `${progressPct}%` }}
-                />
-              </div>
+              <Progress size="sm" value={progressPct} className="w-48" />
             )}
           </div>
         )}
 
         {phase === 'summary' && summary && (
           <>
-            <div className="rounded-xl bg-green-50 p-4 text-sm text-green-800 dark:bg-green-900/30 dark:text-green-200">
-              {[
-                t('settings.sources.graphrag.enable.summaryNodes', {
-                  count: summary.nodes,
-                }),
-                t('settings.sources.graphrag.enable.summaryEdges', {
-                  count: summary.edges,
-                }),
-                t('settings.sources.graphrag.enable.summaryChunks', {
-                  count: summary.chunksProcessed,
-                }),
-              ].join(' · ')}
-            </div>
+            <Alert variant="success">
+              <CircleCheck className="size-4" aria-hidden="true" />
+              <AlertDescription>
+                {[
+                  t('settings.sources.graphrag.enable.summaryNodes', {
+                    count: summary.nodes,
+                  }),
+                  t('settings.sources.graphrag.enable.summaryEdges', {
+                    count: summary.edges,
+                  }),
+                  t('settings.sources.graphrag.enable.summaryChunks', {
+                    count: summary.chunksProcessed,
+                  }),
+                ].join(' · ')}
+              </AlertDescription>
+            </Alert>
             <div className="flex justify-end">
               <Button
                 type="button"
                 onClick={closeModal}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('settings.sources.graphrag.enable.done')}
               </Button>
@@ -301,15 +308,18 @@ export default function EnableGraphRAGModal({
 
         {phase === 'error' && (
           <>
-            <div className="rounded-xl bg-red-50 p-4 text-sm text-red-700 dark:bg-red-900/40 dark:text-red-300">
-              {error}
-            </div>
+            <Alert variant="destructive">
+              <CircleAlert className="size-4" aria-hidden="true" />
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
             <div className="flex justify-end">
               <Button
                 type="button"
                 variant="ghost"
                 onClick={closeModal}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('cancel')}
               </Button>
diff --git a/frontend/src/settings/General.tsx b/frontend/src/settings/General.tsx
index 34fc18e7..bc4ab285 100644
--- a/frontend/src/settings/General.tsx
+++ b/frontend/src/settings/General.tsx
@@ -84,7 +84,7 @@ export default function General() {
             value !== selectedTheme && toggleTheme();
           }}
         >
-          <SelectTrigger className="w-56 rounded-3xl px-5 py-3" size="lg">
+          <SelectTrigger className="w-56" size="lg" shape="pill">
             <SelectValue />
           </SelectTrigger>
           <SelectContent>
@@ -107,7 +107,7 @@ export default function General() {
             if (opt) setSelectedLanguage(opt);
           }}
         >
-          <SelectTrigger className="w-56 rounded-3xl px-5 py-3" size="lg">
+          <SelectTrigger className="w-56" size="lg" shape="pill">
             <SelectValue />
           </SelectTrigger>
           <SelectContent>
@@ -125,7 +125,8 @@ export default function General() {
           type="button"
           variant="destructive-outline"
           title={t('settings.general.deleteAllLabel')}
-          className="w-fit rounded-3xl px-5 py-3 tracking-[0.015em] hover:font-bold hover:tracking-normal"
+          shape="pill"
+          className="w-fit"
           onClick={() => dispatch(setModalStateDeleteConv('ACTIVE'))}
         >
           {t('settings.general.deleteAllBtn')}
diff --git a/frontend/src/settings/Logs.tsx b/frontend/src/settings/Logs.tsx
index b5b80a9b..9f54b96b 100644
--- a/frontend/src/settings/Logs.tsx
+++ b/frontend/src/settings/Logs.tsx
@@ -15,6 +15,7 @@ import {
   SelectValue,
 } from '../components/ui/select';
 import { useLoaderState } from '../hooks';
+import { cn } from '../lib/utils';
 import { selectToken } from '../preferences/preferenceSlice';
 import { LogData } from './types';
 
@@ -136,10 +137,7 @@ export default function Logs({ agentId, tableHeader }: LogsProps) {
       </p>
       <div className="mb-3 flex flex-row flex-wrap items-center gap-3">
         <Select value={levelFilter} onValueChange={setLevelFilter}>
-          <SelectTrigger
-            className="w-[125px] rounded-3xl px-5 py-3 text-sm"
-            size="lg"
-          >
+          <SelectTrigger className="w-[125px]" size="lg" shape="pill">
             <SelectValue placeholder={t('settings.logs.levels.all')} />
           </SelectTrigger>
           <SelectContent>
@@ -151,10 +149,7 @@ export default function Logs({ agentId, tableHeader }: LogsProps) {
           </SelectContent>
         </Select>
         <Select value={typeFilter} onValueChange={setTypeFilter}>
-          <SelectTrigger
-            className="w-[140px] rounded-3xl px-5 py-3 text-sm"
-            size="lg"
-          >
+          <SelectTrigger className="w-[140px]" size="lg" shape="pill">
             <SelectValue placeholder={t('settings.logs.types.all')} />
           </SelectTrigger>
           <SelectContent>
@@ -169,7 +164,8 @@ export default function Logs({ agentId, tableHeader }: LogsProps) {
           value={searchInput}
           onChange={(e) => setSearchInput(e.target.value)}
           placeholder={t('settings.logs.searchPlaceholder')}
-          className="w-56 rounded-3xl"
+          shape="pill"
+          className="w-56"
         />
       </div>
       <div>
@@ -285,9 +281,9 @@ function Log({
 }) {
   const { t } = useTranslation();
   const logLevelColor = {
-    info: 'text-green-500',
-    error: 'text-red-500',
-    warning: 'text-yellow-500',
+    info: 'text-success',
+    error: 'text-destructive',
+    warning: 'text-warning',
   };
   const { id, action, timestamp, event_type, ...filteredLog } = log;
 
@@ -395,9 +391,10 @@ function Log({
     <div className="group dark:hover:bg-accent hover:bg-muted w-full rounded-xl bg-transparent">
       <div
         onClick={() => onToggle(log.id)}
-        className={`text-foreground flex cursor-pointer flex-row items-start gap-2 p-2 px-4 py-3 ${
-          isOpen ? 'dark:bg-background rounded-t-xl bg-[#F1F1F1]' : ''
-        }`}
+        className={cn(
+          'text-foreground flex cursor-pointer flex-row items-start gap-2 p-2 px-4 py-3',
+          isOpen && 'bg-muted rounded-t-xl',
+        )}
       >
         <img
           src={ChevronRight}
@@ -405,15 +402,18 @@ function Log({
           className={`mt-[3px] h-3 w-3 transition duration-300 dark:invert ${isOpen ? 'rotate-90' : ''}`}
         />
         <span className="flex flex-row flex-wrap gap-2">
-          <h2 className="dark:text-foreground text-xs text-black/60">{`${log.timestamp}`}</h2>
+          <h2 className="text-muted-foreground text-xs">{`${log.timestamp}`}</h2>
           {log.event_type && (
             <h2 className="text-muted-foreground text-xs">
               {t(`settings.logs.types.${log.event_type}`)}
             </h2>
           )}
-          <h2 className="text-xs text-[#913400] dark:text-orange-500">{`[${log.action}]`}</h2>
+          <h2 className="text-warning text-xs">{`[${log.action}]`}</h2>
           <h2
-            className={`max-w-72 text-xs ${logLevelColor[log.level]} wrap-break-word`}
+            className={cn(
+              'max-w-72 text-xs wrap-break-word',
+              logLevelColor[log.level],
+            )}
           >
             {`${log.question}`.length > 250
               ? `${log.question.substring(0, 250)}...`
@@ -422,7 +422,7 @@ function Log({
         </span>
       </div>
       {isOpen && (
-        <div className="dark:bg-background rounded-b-xl bg-[#F1F1F1] px-4 py-3">
+        <div className="bg-muted rounded-b-xl px-4 py-3">
           {detailRows.length > 0 && (
             <div className="flex flex-col gap-1 px-2 pb-2">
               {detailRows.map(([label, value]) => (
@@ -441,11 +441,10 @@ function Log({
             <div key={block.label} className="px-2 pb-2">
               <p className="text-muted-foreground text-xs">{block.label}</p>
               <pre
-                className={`font-mono text-xs leading-relaxed wrap-break-word whitespace-pre-wrap ${
-                  block.isError
-                    ? 'text-red-500'
-                    : 'text-gray-700 dark:text-gray-400'
-                }`}
+                className={cn(
+                  'font-mono text-xs leading-relaxed wrap-break-word whitespace-pre-wrap',
+                  block.isError ? 'text-destructive' : 'text-foreground',
+                )}
               >
                 {block.text}
               </pre>
@@ -455,7 +454,7 @@ function Log({
             <div key={block.label} className="px-2 pb-2">
               <p className="text-muted-foreground text-xs">{block.label}</p>
               <div className="scrollbar-overlay max-h-60 overflow-y-auto">
-                <pre className="font-mono text-xs leading-relaxed wrap-break-word whitespace-pre-wrap text-gray-700 dark:text-gray-400">
+                <pre className="text-foreground font-mono text-xs leading-relaxed wrap-break-word whitespace-pre-wrap">
                   {JSON.stringify(block.value, null, 2)}
                 </pre>
               </div>
diff --git a/frontend/src/settings/PairDeviceModal.tsx b/frontend/src/settings/PairDeviceModal.tsx
index 01890166..04ba127a 100644
--- a/frontend/src/settings/PairDeviceModal.tsx
+++ b/frontend/src/settings/PairDeviceModal.tsx
@@ -1,3 +1,4 @@
+import { ShieldAlert } from 'lucide-react';
 import React from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
@@ -145,7 +146,6 @@ export default function PairDeviceModal({
         onChange={(e) => setName(e.target.value)}
         label={t('settings.devices.pairing.nameLabel')}
         placeholder={t('settings.devices.pairing.namePlaceholder')}
-        labelBgClassName="bg-card"
       />
       <Input
         type="text"
@@ -153,7 +153,6 @@ export default function PairDeviceModal({
         onChange={(e) => setDescription(e.target.value)}
         label={t('settings.devices.pairing.descriptionLabel')}
         placeholder={t('settings.devices.pairing.descriptionPlaceholder')}
-        labelBgClassName="bg-card"
       />
       <div className="flex flex-col gap-2">
         <span className="text-muted-foreground text-xs">
@@ -176,9 +175,12 @@ export default function PairDeviceModal({
           </SelectContent>
         </Select>
         {approvalMode === 'full' && (
-          <p className="text-xs text-red-600 dark:text-red-400">
-            {t('settings.devices.pairing.fullAccessWarning')}
-          </p>
+          <Alert variant="destructive">
+            <ShieldAlert className="size-4" aria-hidden="true" />
+            <AlertDescription>
+              {t('settings.devices.pairing.fullAccessWarning')}
+            </AlertDescription>
+          </Alert>
         )}
       </div>
       {error && (
@@ -234,14 +236,14 @@ export default function PairDeviceModal({
     if (stage === 'form') {
       return (
         <>
-          <Button variant="ghost" onClick={close} className="rounded-3xl px-5">
+          <Button variant="ghost" shape="pill" onClick={close}>
             {t('settings.devices.pairing.cancel')}
           </Button>
           <Button
             type="button"
             onClick={handleStart}
             disabled={submitting}
-            className="rounded-3xl px-5 text-white"
+            shape="pill"
           >
             {submitting
               ? t('settings.devices.pairing.starting')
@@ -251,7 +253,7 @@ export default function PairDeviceModal({
       );
     }
     return (
-      <Button variant="ghost" onClick={close} className="rounded-3xl px-5">
+      <Button variant="ghost" shape="pill" onClick={close}>
         {t('settings.devices.pairing.cancel')}
       </Button>
     );
@@ -265,7 +267,6 @@ export default function PairDeviceModal({
       }}
       title={t('settings.devices.pairing.title')}
       footer={footer}
-      contentClassName="px-1"
     >
       {stage === 'form' && renderForm()}
       {stage === 'waiting' && renderWaiting()}
diff --git a/frontend/src/settings/PersonalAccessTokens.tsx b/frontend/src/settings/PersonalAccessTokens.tsx
index 27cebbb0..92575c24 100644
--- a/frontend/src/settings/PersonalAccessTokens.tsx
+++ b/frontend/src/settings/PersonalAccessTokens.tsx
@@ -14,6 +14,7 @@ import NoFilesDarkIcon from '../assets/no-files-dark.svg';
 import NoFilesIcon from '../assets/no-files.svg';
 import SkeletonLoader from '../components/SkeletonLoader';
 import { Alert, AlertDescription } from '../components/ui/alert';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import {
   Table,
@@ -53,7 +54,7 @@ function ScopeChips({ scopes }: { scopes: string[] }) {
       {visible.map((scope) => (
         <span
           key={scope}
-          className="bg-muted text-foreground dark:text-foreground rounded-full px-2 py-0.5 font-mono text-[11px] leading-4 whitespace-nowrap"
+          className="bg-muted text-foreground dark:text-foreground rounded-full px-2 py-0.5 font-mono text-xs leading-4 whitespace-nowrap"
         >
           {scope}
         </span>
@@ -64,7 +65,7 @@ function ScopeChips({ scopes }: { scopes: string[] }) {
           onClick={() => setExpanded((prev) => !prev)}
           aria-expanded={expanded}
           title={expanded ? undefined : scopes.slice(VISIBLE_SCOPES).join(', ')}
-          className="text-primary hover:bg-primary/10 cursor-pointer rounded-full px-2 py-0.5 text-[11px] leading-4 font-medium whitespace-nowrap"
+          className="text-primary hover:bg-primary/10 cursor-pointer rounded-full px-2 py-0.5 text-xs leading-4 font-medium whitespace-nowrap"
         >
           {expanded
             ? t('settings.accessTokens.showLess')
@@ -213,19 +214,12 @@ export default function PersonalAccessTokens() {
     if (status === 'ok') return date;
     const expired = status === 'expired';
     return (
-      <span
-        className={`inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-medium whitespace-nowrap ${
-          expired
-            ? 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-300'
-            : 'bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-300'
-        }`}
-        title={date}
-      >
+      <Badge variant={expired ? 'destructive' : 'warning'} title={date}>
         <TriangleAlert className="size-3 shrink-0" aria-hidden="true" />
         {expired
           ? t('settings.accessTokens.expired', { date, ...NO_ESCAPE })
           : t('settings.accessTokens.expiresSoon', { date, ...NO_ESCAPE })}
-      </span>
+      </Badge>
     );
   };
 
@@ -235,7 +229,7 @@ export default function PersonalAccessTokens() {
         type="button"
         variant="outline"
         size="sm"
-        className="rounded-full px-4"
+        shape="pill"
         onClick={() => setTokenToRegenerate(item)}
         aria-label={t('settings.accessTokens.regenerate.aria', {
           name: item.name,
@@ -249,9 +243,9 @@ export default function PersonalAccessTokens() {
   const renderRevokeButton = (item: PersonalAccessToken) => (
     <Button
       type="button"
-      variant="outline"
+      variant="destructive-outline"
       size="sm"
-      className="text-destructive hover:text-destructive border-destructive/40 hover:bg-destructive/10 rounded-full px-4"
+      shape="pill"
       onClick={() => requestRevoke(item)}
       aria-label={t('settings.accessTokens.revokeAria', {
         name: item.name,
@@ -275,7 +269,7 @@ export default function PersonalAccessTokens() {
         alt=""
         className="mx-auto mb-6 h-32 w-32"
       />
-      <p className="text-center text-lg text-gray-500 dark:text-gray-400">
+      <p className="text-muted-foreground text-center text-lg">
         {t('settings.accessTokens.empty')}
       </p>
       {policy?.enabled && (
@@ -305,7 +299,8 @@ export default function PersonalAccessTokens() {
           {policy?.enabled && (
             <Button
               type="button"
-              className="h-11 min-w-[108px] shrink-0 rounded-full whitespace-normal text-white"
+              shape="pill"
+              className="h-11 min-w-[108px] shrink-0 whitespace-normal"
               onClick={() => setCreateOpen(true)}
               disabled={limitReached}
               title={
diff --git a/frontend/src/settings/Prompts.test.tsx b/frontend/src/settings/Prompts.test.tsx
new file mode 100644
index 00000000..c7a302f5
--- /dev/null
+++ b/frontend/src/settings/Prompts.test.tsx
@@ -0,0 +1,118 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-redux', () => ({
+  useSelector: () => 'test-token',
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('../api/services/userService', () => ({ default: {} }));
+vi.mock('../teams/ShareToTeamModal', () => ({ default: () => null }));
+vi.mock('../preferences/PromptsModal', () => ({ default: () => null }));
+vi.mock('../modals/ConfirmationModal', () => ({ default: () => null }));
+
+import Prompts from './Prompts';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const prompts = [
+  { id: 'p1', name: 'Default', type: 'public' },
+  { id: 'p2', name: 'Vendor due diligence', type: 'private' },
+  { id: 'p3', name: 'Carrier rate summary', type: 'private' },
+];
+
+describe('Prompts', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.innerHTML = '';
+  });
+
+  const renderPrompts = () =>
+    act(() => {
+      root.render(
+        <Prompts
+          prompts={prompts}
+          selectedPrompt={prompts[1]}
+          onSelectPrompt={() => undefined}
+          setPrompts={() => undefined}
+        />,
+      );
+    });
+
+  it('gives the prompt pill the 42px form-row height', () => {
+    renderPrompts();
+    const trigger = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Toggle prompt list"]',
+    );
+    expect(trigger?.className).toMatch(/(^|\s)h-10\.5(\s|$)/);
+    expect(trigger?.className).toMatch(/(^|\s)items-stretch(\s|$)/);
+    // The label no longer pads itself to height; it centres in the fixed pill.
+    const label = trigger?.firstElementChild as HTMLElement | null;
+    expect(label?.className).not.toMatch(/(^|\s)py-3(\s|$)/);
+    expect(label?.className).toMatch(/(^|\s)pl-5(\s|$)/);
+    expect(label?.className).toMatch(/(^|\s)items-center(\s|$)/);
+  });
+
+  it('sizes the Add button to the field row', () => {
+    renderPrompts();
+    const add = Array.from(
+      container.querySelectorAll<HTMLButtonElement>('[data-slot="button"]'),
+    ).find((b) => b.textContent === 'settings.general.add');
+    expect(add?.getAttribute('data-size')).toBe('field');
+    expect(add?.getAttribute('data-shape')).toBe('pill');
+    expect(add?.getAttribute('data-variant')).toBe('default');
+    expect(add?.className).not.toMatch(/(^|\s)h-11\.5(\s|$)/);
+  });
+
+  it('marks only the active prompt as checked in the list', () => {
+    act(() => {
+      root.render(
+        <Prompts
+          prompts={prompts}
+          selectedPrompt={prompts[1]}
+          onSelectPrompt={() => undefined}
+          setPrompts={() => undefined}
+        />,
+      );
+    });
+
+    const trigger = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Toggle prompt list"]',
+    );
+    expect(trigger).not.toBeNull();
+    act(() => {
+      trigger!.dispatchEvent(
+        new PointerEvent('pointerdown', { bubbles: true, button: 0 }),
+      );
+      trigger!.click();
+    });
+
+    const items = Array.from(
+      document.body.querySelectorAll<HTMLElement>('[data-slot="command-item"]'),
+    );
+    expect(items).toHaveLength(3);
+
+    const byName = (name: string) =>
+      items.find((item) => item.textContent?.includes(name));
+    expect(byName('Vendor due diligence')?.dataset.checked).toBe('true');
+    expect(byName('Default')?.dataset.checked).toBeUndefined();
+    expect(byName('Carrier rate summary')?.dataset.checked).toBeUndefined();
+    // The fill comes from the checked API, not from page classes.
+    expect(byName('Vendor due diligence')?.className).not.toMatch(
+      /(^|\s)(bg-accent|font-medium)(\s|$)/,
+    );
+  });
+});
diff --git a/frontend/src/settings/Prompts.tsx b/frontend/src/settings/Prompts.tsx
index af264a22..2a947c6d 100644
--- a/frontend/src/settings/Prompts.tsx
+++ b/frontend/src/settings/Prompts.tsx
@@ -26,7 +26,6 @@ import { cn } from '@/lib/utils';
 
 type PromptsDropdownProps = {
   className?: string;
-  contentClassName?: string;
 };
 
 type ExtendedPromptProps = PromptProps & {
@@ -262,7 +261,7 @@ export default function Prompts({
   };
 
   const pillClassName = cn(
-    'border-border bg-card text-foreground hover:bg-accent flex w-56 items-stretch rounded-3xl border text-sm transition-colors',
+    'border-border bg-card text-foreground hover:bg-accent flex h-10.5 w-56 items-stretch rounded-3xl border text-sm transition-colors',
     dropdownProps.className,
   );
 
@@ -281,12 +280,12 @@ export default function Prompts({
                   aria-label="Toggle prompt list"
                   className={cn(
                     pillClassName,
-                    'focus-visible:ring-ring/50 outline-none focus-visible:ring-[3px]',
+                    'focus-visible:ring-ring/50 outline-none focus-visible:ring-3',
                   )}
                 >
                   <span
                     className={cn(
-                      'flex min-w-0 flex-1 items-center py-3 pl-5 text-left',
+                      'flex min-w-0 flex-1 items-center pl-5 text-left',
                       !selectedPrompt?.name && 'text-muted-foreground',
                     )}
                   >
@@ -310,7 +309,7 @@ export default function Prompts({
                             openEditModal(selectedPrompt);
                           }
                         }}
-                        className="text-muted-foreground hover:bg-foreground/15 hover:text-foreground dark:hover:bg-foreground/20 focus-visible:ring-ring/50 mx-1 my-auto shrink-0 rounded-full p-1.5 transition-colors outline-none focus-visible:ring-[3px]"
+                        className="text-muted-foreground hover:bg-foreground/15 hover:text-foreground dark:hover:bg-foreground/20 focus-visible:ring-ring/50 mx-1 my-auto shrink-0 rounded-full p-1.5 transition-colors outline-none focus-visible:ring-3"
                         aria-label="Edit prompt"
                       >
                         <Pencil className="h-4 w-4" />
@@ -333,10 +332,7 @@ export default function Prompts({
               </PopoverTrigger>
               <PopoverContent
                 align="start"
-                className={cn(
-                  'w-(--radix-popover-trigger-width) p-0',
-                  dropdownProps.contentClassName,
-                )}
+                className="w-(--radix-popover-trigger-width) p-0"
               >
                 <Command>
                   <CommandInput
@@ -359,51 +355,53 @@ export default function Prompts({
                         <CommandItem
                           key={prompt.id}
                           value={prompt.name}
+                          checked={isActive}
                           onSelect={() => handleSelectPrompt(prompt)}
-                          className={cn(
-                            'flex items-center justify-between gap-2',
-                            isActive && 'bg-accent font-medium',
-                          )}
+                          className="flex items-center justify-between"
                         >
                           <span className="truncate">{prompt.name}</span>
                           <div className="flex shrink-0 items-center gap-1">
                             <Button
                               type="button"
-                              variant="ghost"
-                              size="icon-sm"
+                              variant="ghost-muted"
+                              size="icon-xs"
+                              /* eslint-disable-next-line shadcn/no-restyle -- the row is already bg-accent while cmdk highlights it, so ghost's accent hover would be invisible; a foreground (or destructive) tint shows on it */
+                              className="hover:bg-foreground/15 dark:hover:bg-foreground/20"
                               onClick={(e) => {
                                 e.stopPropagation();
                                 openEditModal(prompt);
                               }}
-                              className="group/btn hover:bg-foreground/15 dark:hover:bg-foreground/20 h-auto w-auto rounded p-1"
                               aria-label={
                                 canModify ? 'Edit prompt' : 'View prompt'
                               }
                             >
                               {canModify ? (
-                                <Pencil className="text-muted-foreground group-hover/btn:text-foreground h-3.5 w-3.5" />
+                                <Pencil className="h-3.5 w-3.5 text-current" />
                               ) : (
-                                <Eye className="text-muted-foreground group-hover/btn:text-foreground h-3.5 w-3.5" />
+                                <Eye className="h-3.5 w-3.5 text-current" />
                               )}
                             </Button>
                             <Button
                               type="button"
-                              variant="ghost"
-                              size="icon-sm"
+                              variant="ghost-muted"
+                              size="icon-xs"
+                              /* eslint-disable-next-line shadcn/no-restyle -- the row is already bg-accent while cmdk highlights it, so ghost's accent hover would be invisible; a foreground (or destructive) tint shows on it */
+                              className="hover:bg-foreground/15 dark:hover:bg-foreground/20"
                               onClick={(e) => {
                                 e.stopPropagation();
                                 handleDuplicatePrompt(prompt);
                               }}
-                              className="group/btn hover:bg-foreground/15 dark:hover:bg-foreground/20 h-auto w-auto rounded p-1"
                               aria-label="Duplicate prompt"
                             >
-                              <Copy className="text-muted-foreground group-hover/btn:text-foreground h-3.5 w-3.5" />
+                              <Copy className="h-3.5 w-3.5 text-current" />
                             </Button>
                             {canShare && (
                               <Button
                                 type="button"
-                                variant="ghost"
-                                size="icon-sm"
+                                variant="ghost-muted"
+                                size="icon-xs"
+                                /* eslint-disable-next-line shadcn/no-restyle -- the row is already bg-accent while cmdk highlights it, so ghost's accent hover would be invisible; a foreground (or destructive) tint shows on it */
+                                className="hover:bg-foreground/15 dark:hover:bg-foreground/20"
                                 onClick={(e) => {
                                   e.stopPropagation();
                                   setOpen(false);
@@ -412,26 +410,26 @@ export default function Prompts({
                                     name: prompt.name,
                                   });
                                 }}
-                                className="group/btn hover:bg-foreground/15 dark:hover:bg-foreground/20 h-auto w-auto rounded p-1"
                                 aria-label={t('agents.shareWithTeam')}
                                 title={t('agents.shareWithTeam')}
                               >
-                                <Users className="text-muted-foreground group-hover/btn:text-foreground h-3.5 w-3.5" />
+                                <Users className="h-3.5 w-3.5 text-current" />
                               </Button>
                             )}
                             {canModify && (
                               <Button
                                 type="button"
-                                variant="ghost"
-                                size="icon-sm"
+                                variant="ghost-destructive"
+                                size="icon-xs"
+                                /* eslint-disable-next-line shadcn/no-restyle -- the row is already bg-accent while cmdk highlights it, so ghost's accent hover would be invisible; a foreground (or destructive) tint shows on it */
+                                className="hover:bg-destructive/15 dark:hover:bg-destructive/25"
                                 onClick={(e) => {
                                   e.stopPropagation();
                                   handleDeletePrompt(prompt.id);
                                 }}
-                                className="group/btn hover:bg-destructive/15 dark:hover:bg-destructive/25 h-auto w-auto rounded p-1"
                                 aria-label="Delete prompt"
                               >
-                                <Trash2 className="text-muted-foreground group-hover/btn:text-destructive h-3.5 w-3.5" />
+                                <Trash2 className="h-3.5 w-3.5 text-current" />
                               </Button>
                             )}
                           </div>
@@ -445,7 +443,9 @@ export default function Prompts({
             {showAddButton && (
               <Button
                 type="button"
-                className="h-auto w-20 rounded-3xl border border-transparent py-3"
+                size="field"
+                shape="pill"
+                className="w-20"
                 onClick={() => {
                   setModalType('ADD');
                   setDuplicateSource(null);
diff --git a/frontend/src/settings/RemoteDeviceConfig.test.tsx b/frontend/src/settings/RemoteDeviceConfig.test.tsx
new file mode 100644
index 00000000..d53d1e35
--- /dev/null
+++ b/frontend/src/settings/RemoteDeviceConfig.test.tsx
@@ -0,0 +1,104 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-redux', () => ({
+  useSelector: () => 'token',
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('../components/ToolIcon', () => ({ default: () => null }));
+vi.mock('../components/CopyButton', () => ({ default: () => null }));
+vi.mock('../navigation/DetailBreadcrumb', () => ({ default: () => null }));
+vi.mock('../modals/ConfirmationModal', () => ({ default: () => null }));
+
+const getDevice = vi.fn();
+vi.mock('../api/services/devicesService', () => ({
+  default: {
+    get: (...args: unknown[]) => getDevice(...args),
+    listAudit: () => Promise.resolve({ entries: [] }),
+  },
+}));
+
+import type { Device } from '../api/services/devicesService';
+import type { UserToolType } from './types';
+import RemoteDeviceConfig from './RemoteDeviceConfig';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const tool = {
+  id: 'tool-1',
+  name: 'remote_device',
+  displayName: 'Remote device',
+  config: { device_id: 'dev-1' },
+} as unknown as UserToolType;
+
+const device = (overrides: Partial<Device>): Device => ({
+  id: 'dev-1',
+  name: 'Laptop',
+  approval_mode: 'ask',
+  status: 'active',
+  last_seen_at: null,
+  ...overrides,
+});
+
+describe('RemoteDeviceConfig', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    getDevice.mockReset();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = async (d: Device) => {
+    getDevice.mockResolvedValue(d);
+    await act(async () => {
+      root.render(<RemoteDeviceConfig tool={tool} handleGoBack={() => {}} />);
+    });
+  };
+
+  const badges = () =>
+    Array.from(container.querySelectorAll<HTMLElement>('[data-slot="badge"]'));
+
+  it('shows an online device as a success badge', async () => {
+    await render(device({ last_seen_at: new Date().toISOString() }));
+    const pill = badges().find((el) =>
+      el.textContent?.includes('settings.devices.online'),
+    );
+    expect(pill?.dataset.variant).toBe('success');
+  });
+
+  it('shows an offline device as a neutral badge', async () => {
+    await render(device({}));
+    const pill = badges().find((el) =>
+      el.textContent?.includes('settings.devices.offline'),
+    );
+    expect(pill?.dataset.variant).toBe('neutral');
+  });
+
+  it('marks full approval with a destructive badge and alert', async () => {
+    await render(device({ approval_mode: 'full' }));
+    const pill = badges().find((el) =>
+      el.textContent?.includes('settings.devices.approvalFull'),
+    );
+    expect(pill?.dataset.variant).toBe('destructive');
+
+    const warning = Array.from(
+      container.querySelectorAll<HTMLElement>('[role="alert"]'),
+    ).find((el) =>
+      el.textContent?.includes('settings.devices.fullAccessWarning'),
+    );
+    expect(warning?.className).toContain('text-destructive');
+    expect(warning?.querySelector('svg')).not.toBeNull();
+  });
+});
diff --git a/frontend/src/settings/RemoteDeviceConfig.tsx b/frontend/src/settings/RemoteDeviceConfig.tsx
index afc04833..f334f6ca 100644
--- a/frontend/src/settings/RemoteDeviceConfig.tsx
+++ b/frontend/src/settings/RemoteDeviceConfig.tsx
@@ -1,3 +1,4 @@
+import { ShieldAlert } from 'lucide-react';
 import React from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
@@ -18,6 +19,7 @@ import {
   AccordionTrigger,
 } from '../components/ui/accordion';
 import { Alert, AlertDescription } from '../components/ui/alert';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import {
@@ -204,7 +206,8 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
         />
         <Button
           type="button"
-          className="rounded-full px-3 py-2 text-xs text-nowrap text-white sm:px-4 sm:py-2"
+          size="sm"
+          shape="pill"
           onClick={handleSaveChanges}
           disabled={!hasUnsavedChanges || saving || loading}
         >
@@ -224,28 +227,20 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
           title={`${tool.displayName} icon`}
           className="h-7 w-7"
         />
-        <h2 className="text-foreground dark:text-foreground text-xl font-semibold">
+        <h2 className="text-foreground text-xl font-semibold">
           {device?.name || tool.customName || tool.displayName || 'device'}
         </h2>
-        <span
-          className={`rounded-full px-3 py-0.5 text-xs font-medium ${
-            online
-              ? 'bg-green-100 text-green-900 dark:bg-green-900/30 dark:text-green-300'
-              : 'bg-gray-200 text-gray-700 dark:bg-gray-700/40 dark:text-gray-300'
-          }`}
-        >
-          {pillText}
-        </span>
+        <Badge variant={online ? 'success' : 'neutral'}>{pillText}</Badge>
         {approvalMode === 'full' && (
-          <span className="rounded-full bg-red-200 px-3 py-0.5 text-xs font-medium text-red-900 dark:bg-red-900/40 dark:text-red-300">
+          <Badge variant="destructive">
             {t('settings.devices.approvalFull')}
-          </span>
+          </Badge>
         )}
       </div>
 
       {/* Identity */}
       <section className="flex flex-col gap-4">
-        <h3 className="text-foreground dark:text-foreground text-sm font-semibold">
+        <h3 className="text-foreground text-sm font-semibold">
           {t('settings.devices.identity')}
         </h3>
         <div className="flex flex-col gap-1 sm:flex-row sm:items-start sm:gap-4">
@@ -258,7 +253,6 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
               value={name}
               onChange={(e) => setName(e.target.value)}
               placeholder={t('settings.devices.nameLabel')}
-              className="rounded-xl"
             />
           </div>
         </div>
@@ -272,7 +266,6 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
               value={description}
               onChange={(e) => setDescription(e.target.value)}
               placeholder={t('settings.devices.descriptionPlaceholder')}
-              className="rounded-xl"
             />
           </div>
         </div>
@@ -280,7 +273,7 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
 
       {/* Access */}
       <section className="flex flex-col gap-4">
-        <h3 className="text-foreground dark:text-foreground text-sm font-semibold">
+        <h3 className="text-foreground text-sm font-semibold">
           {t('settings.devices.access')}
         </h3>
         <div className="flex flex-col gap-1 sm:flex-row sm:items-start sm:gap-4">
@@ -292,7 +285,7 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
               value={approvalMode}
               onValueChange={(value) => setApprovalMode(value as ApprovalMode)}
             >
-              <SelectTrigger className="w-full rounded-xl px-4 py-2" size="lg">
+              <SelectTrigger className="w-full" size="lg">
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
@@ -310,9 +303,12 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
                 : t('settings.devices.approvalAskDescription')}
             </p>
             {approvalMode === 'full' && (
-              <div className="rounded-lg bg-red-50 px-4 py-2 text-sm text-red-600 dark:bg-red-900/20 dark:text-red-400">
-                {t('settings.devices.fullAccessWarning')}
-              </div>
+              <Alert variant="destructive">
+                <ShieldAlert className="size-4" aria-hidden="true" />
+                <AlertDescription>
+                  {t('settings.devices.fullAccessWarning')}
+                </AlertDescription>
+              </Alert>
             )}
           </div>
         </div>
@@ -320,7 +316,7 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
 
       {/* Connection */}
       <section className="flex flex-col gap-4">
-        <h3 className="text-foreground dark:text-foreground text-sm font-semibold">
+        <h3 className="text-foreground text-sm font-semibold">
           {t('settings.devices.connection')}
         </h3>
         <div className="flex flex-col gap-1 sm:flex-row sm:items-start sm:gap-4">
@@ -341,7 +337,7 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
             {t('settings.devices.deviceIdLabel')}
           </span>
           <div className="flex w-full max-w-md flex-wrap items-center gap-2">
-            <code className="text-foreground dark:text-foreground bg-muted max-w-full truncate rounded px-2 py-0.5 font-mono text-xs">
+            <code className="text-foreground bg-muted max-w-full truncate rounded px-2 py-0.5 font-mono text-xs">
               {deviceId || '-'}
             </code>
             {deviceId && <CopyButton textToCopy={deviceId} />}
@@ -364,61 +360,62 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
 
       {/* Recent activity */}
       <section className="flex flex-col gap-3">
-        <h3 className="text-foreground dark:text-foreground text-sm font-semibold">
+        <h3 className="text-foreground text-sm font-semibold">
           {t('settings.devices.auditTitle')}
         </h3>
-        <Accordion
-          type="single"
-          collapsible
-          onValueChange={handleAuditToggle}
-          className="border-border dark:border-border w-full rounded-xl border"
-        >
-          <AccordionItem value="audit" className="border-b-0">
-            <AccordionTrigger className="px-4 py-3 text-sm font-semibold">
-              {t('settings.devices.auditTitle')}
-              {audit !== null ? ` (${audit.length})` : ''}
-            </AccordionTrigger>
-            <AccordionContent className="px-4 pb-4">
-              {auditLoading ? (
-                <p className="text-muted-foreground py-2 text-sm">
-                  {t('settings.devices.auditLoading')}
-                </p>
-              ) : !audit || audit.length === 0 ? (
-                <p className="text-muted-foreground py-2 text-sm">
-                  {t('settings.devices.auditEmpty')}
-                </p>
-              ) : (
-                <ul className="flex flex-col gap-2">
-                  {audit.map((entry) => (
-                    <li
-                      key={entry.id}
-                      className="bg-muted/40 flex flex-col gap-1 rounded-md px-3 py-2 text-xs"
-                    >
-                      <code className="text-foreground dark:text-foreground block font-mono break-all whitespace-pre-wrap">
-                        {entry.command}
-                      </code>
-                      <div className="text-muted-foreground flex flex-wrap gap-3">
-                        <span>
-                          {t('settings.devices.auditDecision')}:{' '}
-                          {entry.decision}
-                        </span>
-                        <span>
-                          {t('settings.devices.auditExit')}:{' '}
-                          {entry.exit_code ?? '-'}
-                        </span>
-                        <span>
-                          {t('settings.devices.auditDuration')}:{' '}
-                          {entry.duration_ms ?? '-'} ms
-                        </span>
-                        <span>{formatTimestamp(entry.created_at)}</span>
-                      </div>
-                    </li>
-                  ))}
-                </ul>
-              )}
-            </AccordionContent>
-          </AccordionItem>
-        </Accordion>
+        <div className="border-border w-full rounded-xl border">
+          <Accordion
+            type="single"
+            collapsible
+            onValueChange={handleAuditToggle}
+          >
+            <AccordionItem value="audit">
+              <AccordionTrigger>
+                {t('settings.devices.auditTitle')}
+                {audit !== null ? ` (${audit.length})` : ''}
+              </AccordionTrigger>
+              <AccordionContent>
+                {auditLoading ? (
+                  <p className="text-muted-foreground py-2 text-sm">
+                    {t('settings.devices.auditLoading')}
+                  </p>
+                ) : !audit || audit.length === 0 ? (
+                  <p className="text-muted-foreground py-2 text-sm">
+                    {t('settings.devices.auditEmpty')}
+                  </p>
+                ) : (
+                  <ul className="flex flex-col gap-2">
+                    {audit.map((entry) => (
+                      <li
+                        key={entry.id}
+                        className="bg-muted/40 flex flex-col gap-1 rounded-md px-3 py-2 text-xs"
+                      >
+                        <code className="text-foreground block font-mono break-all whitespace-pre-wrap">
+                          {entry.command}
+                        </code>
+                        <div className="text-muted-foreground flex flex-wrap gap-3">
+                          <span>
+                            {t('settings.devices.auditDecision')}:{' '}
+                            {entry.decision}
+                          </span>
+                          <span>
+                            {t('settings.devices.auditExit')}:{' '}
+                            {entry.exit_code ?? '-'}
+                          </span>
+                          <span>
+                            {t('settings.devices.auditDuration')}:{' '}
+                            {entry.duration_ms ?? '-'} ms
+                          </span>
+                          <span>{formatTimestamp(entry.created_at)}</span>
+                        </div>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+              </AccordionContent>
+            </AccordionItem>
+          </Accordion>
+        </div>
       </section>
 
       {/* Danger zone */}
@@ -433,7 +430,8 @@ export default function RemoteDeviceConfig({ tool, handleGoBack }: Props) {
           <Button
             type="button"
             variant="destructive"
-            className="shrink-0 rounded-full px-5 text-white"
+            shape="pill"
+            className="shrink-0"
             onClick={() => setRevokeState('ACTIVE')}
           >
             {t('settings.devices.revoke')}
diff --git a/frontend/src/settings/SourceConfigModal.tsx b/frontend/src/settings/SourceConfigModal.tsx
index 50e9a117..64c4c19e 100644
--- a/frontend/src/settings/SourceConfigModal.tsx
+++ b/frontend/src/settings/SourceConfigModal.tsx
@@ -1,9 +1,11 @@
+import { CircleAlert, TriangleAlert } from 'lucide-react';
 import { useEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 
 import userService from '../api/services/userService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Modal } from '../components/ui/modal';
 import { ActiveState, Doc } from '../models/misc';
@@ -170,9 +172,12 @@ export default function SourceConfigModal({
         <div className="flex-1 px-2">
           {reingestPrompt ? (
             <div className="flex flex-col gap-4 px-0.5 py-4">
-              <div className="rounded-xl bg-amber-50 p-4 text-sm text-amber-800 dark:bg-amber-900/30 dark:text-amber-200">
-                {t('settings.sources.configModal.reingestRequired')}
-              </div>
+              <Alert variant="warning">
+                <TriangleAlert className="size-4" aria-hidden="true" />
+                <AlertDescription>
+                  {t('settings.sources.configModal.reingestRequired')}
+                </AlertDescription>
+              </Alert>
             </div>
           ) : (
             <div className="flex flex-col gap-4 px-0.5 py-4">
@@ -191,19 +196,26 @@ export default function SourceConfigModal({
                 availableModels={availableModels}
               />
               {willRequireReingest && !isReadOnly && (
-                <div className="rounded-xl bg-amber-50 p-3 text-xs text-amber-800 dark:bg-amber-900/30 dark:text-amber-200">
-                  {t('settings.sources.configModal.chunkingChangeHint')}
-                </div>
+                <Alert variant="warning">
+                  <TriangleAlert className="size-4" aria-hidden="true" />
+                  <AlertDescription>
+                    {t('settings.sources.configModal.chunkingChangeHint')}
+                  </AlertDescription>
+                </Alert>
               )}
               {!prescreenValid && !isReadOnly && (
-                <div className="rounded-xl bg-amber-50 p-3 text-xs text-amber-800 dark:bg-amber-900/30 dark:text-amber-200">
-                  {t('settings.sources.configModal.prescreenInvalidHint')}
-                </div>
+                <Alert variant="warning">
+                  <TriangleAlert className="size-4" aria-hidden="true" />
+                  <AlertDescription>
+                    {t('settings.sources.configModal.prescreenInvalidHint')}
+                  </AlertDescription>
+                </Alert>
               )}
               {error && (
-                <div className="rounded-xl bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/40 dark:text-red-300">
-                  {error}
-                </div>
+                <Alert variant="destructive">
+                  <CircleAlert className="size-4" aria-hidden="true" />
+                  <AlertDescription>{error}</AlertDescription>
+                </Alert>
               )}
             </div>
           )}
@@ -216,14 +228,18 @@ export default function SourceConfigModal({
                 type="button"
                 variant="ghost"
                 onClick={closeModal}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('settings.sources.configModal.reingestLater')}
               </Button>
               <Button
                 type="button"
                 onClick={handleConfirmReingest}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('settings.sources.reingest')}
               </Button>
@@ -235,7 +251,9 @@ export default function SourceConfigModal({
                 variant="ghost"
                 onClick={closeModal}
                 disabled={saving}
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {t('cancel')}
               </Button>
@@ -245,7 +263,9 @@ export default function SourceConfigModal({
                 disabled={
                   saving || isReadOnly || !hasChanges || !prescreenValid
                 }
-                className="w-full rounded-3xl px-6 sm:w-auto"
+                size="lg"
+                shape="pill"
+                className="w-full sm:w-auto"
               >
                 {saving ? (
                   <div className="flex items-center justify-center">
diff --git a/frontend/src/settings/Sources.tsx b/frontend/src/settings/Sources.tsx
index c6847247..a72f0be4 100644
--- a/frontend/src/settings/Sources.tsx
+++ b/frontend/src/settings/Sources.tsx
@@ -23,6 +23,7 @@ import CalendarIcon from '../assets/calendar.svg';
 import DiscIcon from '../assets/disc.svg';
 import Pagination from '../components/DocumentPagination';
 import SkeletonLoader from '../components/SkeletonLoader';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import {
   DropdownMenu,
@@ -32,6 +33,7 @@ import {
 } from '../components/ui/dropdown-menu';
 import { Input } from '../components/ui/input';
 import { useDarkTheme, useDebouncedValue, useLoaderState } from '../hooks';
+import { cn } from '../lib/utils';
 import ConfirmationModal from '../modals/ConfirmationModal';
 import { ActiveState, Doc, DocumentsProps } from '../models/misc';
 import type { Model } from '../models/types';
@@ -553,7 +555,8 @@ export default function Sources({
     <Button
       type="button"
       variant="outline"
-      className="h-[38px] rounded-full px-4 text-sm font-medium whitespace-nowrap"
+      shape="pill"
+      className="h-[38px]"
       onClick={() => {
         setDocumentToTest(documentToView);
         setTestRetrievalState('ACTIVE');
@@ -636,8 +639,8 @@ export default function Sources({
                 setSearchTerm(e.target.value);
                 setCurrentPage(1);
               }}
-              labelBgClassName="bg-background"
-              className="rounded-full"
+              labelSurface="background"
+              shape="pill"
               leftIcon={
                 <SearchIcon
                   className="text-muted-foreground size-4"
@@ -648,7 +651,8 @@ export default function Sources({
           </div>
           <Button
             type="button"
-            className="h-11 min-w-[108px] rounded-full whitespace-normal text-white"
+            shape="pill"
+            className="h-11 min-w-[108px] whitespace-normal"
             title={t('settings.sources.addSource')}
             onClick={() => {
               setIsOnboarding(false);
@@ -670,7 +674,7 @@ export default function Sources({
                 alt={t('settings.sources.noData')}
                 className="mx-auto mb-6 h-32 w-32"
               />
-              <p className="text-center text-lg text-gray-500 dark:text-gray-400">
+              <p className="text-muted-foreground text-center text-lg">
                 {t('settings.sources.noData')}
               </p>
             </div>
@@ -692,17 +696,18 @@ export default function Sources({
                           setDocumentToView(document);
                         }
                       }}
-                      className={`bg-muted dark:bg-accent focus-visible:ring-ring/50 flex min-h-[130px] w-full cursor-pointer flex-col rounded-2xl p-5 transition-all duration-200 outline-none focus-visible:ring-[3px] ${
+                      className={cn(
+                        'bg-muted dark:bg-accent focus-visible:ring-ring/50 flex min-h-[130px] w-full cursor-pointer flex-col rounded-2xl p-5 transition-all duration-200 outline-none focus-visible:ring-3',
                         actionMenuDocId === docId ||
-                        syncMenuState.docId === docId
+                          syncMenuState.docId === docId
                           ? 'scale-[1.05]'
-                          : 'hover:scale-[1.05]'
-                      }`}
+                          : 'hover:scale-[1.05]',
+                      )}
                     >
                       <div className="w-full flex-1">
                         <div className="flex w-full items-center justify-between gap-2">
                           <h3
-                            className="dark:text-foreground text-foreground line-clamp-2 min-w-0 flex-1 text-sm leading-[18px] font-semibold wrap-anywhere"
+                            className="text-foreground line-clamp-2 min-w-0 flex-1 text-sm leading-4.5 font-semibold wrap-anywhere"
                             title={document.name}
                           >
                             {document.name}
@@ -811,7 +816,7 @@ export default function Sources({
 
                       <div className="flex flex-col items-start justify-start gap-1">
                         {document.ownership === 'team' && (
-                          <span className="bg-muted-foreground/10 text-muted-foreground flex items-center gap-1 rounded-full px-2 py-0.5 text-xs leading-[16px] font-medium">
+                          <Badge variant="neutral">
                             <Users
                               size={11}
                               strokeWidth={2}
@@ -820,17 +825,17 @@ export default function Sources({
                             {document.team_access === 'editor'
                               ? t('teamAccess.editor')
                               : t('teamAccess.viewer')}
-                          </span>
+                          </Badge>
                         )}
                         {document.ingestStatus === 'failed' && (
-                          <span className="rounded-full bg-red-100 px-2 py-0.5 text-xs leading-[16px] font-medium text-red-700 dark:bg-red-900/30 dark:text-red-400">
+                          <Badge variant="destructive">
                             {t('settings.sources.ingestFailed')}
-                          </span>
+                          </Badge>
                         )}
                         {document.ingestStatus === 'processing' && (
-                          <span className="bg-muted-foreground/10 text-muted-foreground rounded-full px-2 py-0.5 text-xs leading-[16px] font-medium">
+                          <Badge variant="neutral">
                             {t('settings.sources.ingestProcessing')}
-                          </span>
+                          </Badge>
                         )}
                         {document.config?.kind === 'graphrag' &&
                           (() => {
@@ -848,7 +853,7 @@ export default function Sources({
                                   )
                                 : null;
                             return (
-                              <span className="bg-muted-foreground/10 text-muted-foreground flex items-center gap-1 rounded-full px-2 py-0.5 text-xs leading-[16px] font-medium">
+                              <Badge variant="neutral">
                                 <Network
                                   size={11}
                                   strokeWidth={2}
@@ -862,7 +867,7 @@ export default function Sources({
                                       )
                                     : t('settings.sources.graphrag.building')
                                   : t('settings.sources.graphrag.badge')}
-                              </span>
+                              </Badge>
                             );
                           })()}
                         <div className="flex items-center gap-2">
@@ -871,13 +876,13 @@ export default function Sources({
                             alt=""
                             className="h-3.5 w-3.5"
                           />
-                          <span className="text-muted-foreground text-xs leading-[18px] font-medium">
+                          <span className="text-muted-foreground text-xs leading-4.5 font-medium">
                             {document.date ? formatDate(document.date) : ''}
                           </span>
                         </div>
                         <div className="flex items-center gap-2">
                           <img src={DiscIcon} alt="" className="h-3.5 w-3.5" />
-                          <span className="text-muted-foreground text-xs leading-[18px] font-medium">
+                          <span className="text-muted-foreground text-xs leading-4.5 font-medium">
                             {document.tokens
                               ? formatTokens(+document.tokens)
                               : ''}
diff --git a/frontend/src/settings/Teams.tsx b/frontend/src/settings/Teams.tsx
index d77ec619..540b433d 100644
--- a/frontend/src/settings/Teams.tsx
+++ b/frontend/src/settings/Teams.tsx
@@ -27,7 +27,9 @@ import DetailBreadcrumb from '../navigation/DetailBreadcrumb';
 import { SectionBackLink } from '../navigation/SectionPageHeader';
 import { SETTINGS_SECTION } from '../navigation/sections';
 import { Avatar } from '../components/ui/avatar';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
+import { Card } from '../components/ui/card';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -43,6 +45,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '../components/ui/select';
+import { Textarea } from '../components/ui/textarea';
 import { useDarkTheme } from '../hooks';
 import ConfirmationModal from '../modals/ConfirmationModal';
 import { ActiveState } from '../models/misc';
@@ -483,17 +486,11 @@ export default function Teams() {
   const isAdmin = selected?.member_role === 'team_admin';
 
   const roleBadge = (role: TeamRole) => (
-    <span
-      className={`rounded-full px-2 py-0.5 text-xs ${
-        role === 'team_admin'
-          ? 'bg-muted-foreground/15 text-foreground'
-          : 'bg-muted-foreground/10 text-muted-foreground'
-      }`}
-    >
+    <Badge variant={role === 'team_admin' ? 'outline' : 'neutral'}>
       {role === 'team_admin'
         ? t('settings.teams.roleAdmin')
         : t('settings.teams.roleMember')}
-    </span>
+    </Badge>
   );
 
   const emptyState = (message: string, extra?: ReactNode) => (
@@ -554,58 +551,58 @@ export default function Teams() {
           ) : (
             <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
               {teams.map((team) => (
-                <button
+                <Card
                   key={team.id}
-                  className="border-border bg-muted dark:bg-accent hover:border-primary/40 group flex h-full flex-col gap-3 rounded-2xl border p-4 text-left transition-colors"
-                  onClick={() => openTeam(team)}
+                  asChild
+                  interactive
+                  className="group h-full"
                 >
-                  <div className="flex items-center gap-3">
-                    <span aria-hidden="true" className="contents">
-                      <Avatar
-                        alt=""
-                        className="bg-muted-foreground/15 text-foreground flex size-9 shrink-0 items-center justify-center rounded-md text-sm font-medium"
-                      >
-                        {initialOf(team.name)}
-                      </Avatar>
-                    </span>
-                    <span className="text-foreground min-w-0 flex-1 truncate text-sm font-semibold">
-                      {team.name}
-                    </span>
-                    {roleBadge(team.member_role ?? 'team_member')}
-                    <ChevronRight
-                      className="text-muted-foreground shrink-0 transition-transform group-hover:translate-x-0.5"
-                      size={18}
-                      strokeWidth={1.75}
-                      aria-hidden
-                    />
-                  </div>
-                  {team.description ? (
-                    <p className="text-muted-foreground line-clamp-2 text-xs leading-relaxed">
-                      {team.description}
-                    </p>
-                  ) : (
-                    <p className="text-muted-foreground/50 text-xs italic">
-                      {t('settings.teams.noDescription')}
-                    </p>
-                  )}
-                  <div className="text-muted-foreground mt-auto flex items-center gap-1.5 text-xs">
-                    <Users size={13} strokeWidth={1.75} aria-hidden />
-                    <span>
-                      {t(
-                        (team.member_count ?? 0) === 1
-                          ? 'settings.teams.memberCountOne'
-                          : 'settings.teams.memberCountOther',
-                        { count: team.member_count ?? 0 },
-                      )}
-                    </span>
-                    <span aria-hidden>·</span>
-                    <span>
-                      {t('settings.teams.sharedCount', {
-                        count: team.shared_count ?? 0,
-                      })}
-                    </span>
-                  </div>
-                </button>
+                  <button onClick={() => openTeam(team)}>
+                    <div className="flex items-center gap-3">
+                      <span aria-hidden="true" className="contents">
+                        <Avatar alt="" size="lg" shape="square" variant="muted">
+                          {initialOf(team.name)}
+                        </Avatar>
+                      </span>
+                      <span className="text-foreground min-w-0 flex-1 truncate text-sm font-semibold">
+                        {team.name}
+                      </span>
+                      {roleBadge(team.member_role ?? 'team_member')}
+                      <ChevronRight
+                        className="text-muted-foreground shrink-0 transition-transform group-hover:translate-x-0.5"
+                        size={18}
+                        strokeWidth={1.75}
+                        aria-hidden
+                      />
+                    </div>
+                    {team.description ? (
+                      <p className="text-muted-foreground line-clamp-2 text-xs leading-relaxed">
+                        {team.description}
+                      </p>
+                    ) : (
+                      <p className="text-muted-foreground/50 text-xs italic">
+                        {t('settings.teams.noDescription')}
+                      </p>
+                    )}
+                    <div className="text-muted-foreground mt-auto flex items-center gap-1.5 text-xs">
+                      <Users size={13} strokeWidth={1.75} aria-hidden />
+                      <span>
+                        {t(
+                          (team.member_count ?? 0) === 1
+                            ? 'settings.teams.memberCountOne'
+                            : 'settings.teams.memberCountOther',
+                          { count: team.member_count ?? 0 },
+                        )}
+                      </span>
+                      <span aria-hidden>·</span>
+                      <span>
+                        {t('settings.teams.sharedCount', {
+                          count: team.shared_count ?? 0,
+                        })}
+                      </span>
+                    </div>
+                  </button>
+                </Card>
               ))}
             </div>
           )}
@@ -626,10 +623,7 @@ export default function Teams() {
           <div className="flex items-start justify-between gap-3">
             <div className="flex min-w-0 items-center gap-3">
               <span aria-hidden="true" className="contents">
-                <Avatar
-                  alt=""
-                  className="bg-muted-foreground/15 text-foreground flex size-10 shrink-0 items-center justify-center rounded-md text-base font-medium"
-                >
+                <Avatar alt="" size="xl" shape="square" variant="muted">
                   {initialOf(selected.name)}
                 </Avatar>
               </span>
@@ -648,9 +642,9 @@ export default function Teams() {
               <DropdownMenu>
                 <DropdownMenuTrigger asChild>
                   <Button
-                    variant="ghost"
+                    variant="ghost-muted"
                     size="icon-sm"
-                    className="text-muted-foreground shrink-0"
+                    className="shrink-0"
                     aria-label={t('settings.teams.teamActions')}
                   >
                     <MoreVertical size={18} strokeWidth={1.75} aria-hidden />
@@ -708,7 +702,9 @@ export default function Teams() {
                     <span aria-hidden="true" className="contents">
                       <Avatar
                         alt=""
-                        className="bg-muted-foreground/15 text-foreground flex size-8 items-center justify-center rounded-full text-sm font-medium"
+                        size="default"
+                        shape="circle"
+                        variant="muted"
                       >
                         {initialOf(memberLabel(m))}
                       </Avatar>
@@ -752,9 +748,9 @@ export default function Teams() {
                     )}
                     {isAdmin && (
                       <Button
-                        variant="ghost"
+                        variant="ghost-destructive"
                         size="icon-sm"
-                        className="text-muted-foreground hover:text-destructive shrink-0"
+                        className="shrink-0"
                         aria-label={t('settings.teams.remove')}
                         title={t('settings.teams.remove')}
                         onClick={() => requestRemoveMember(m.user_id)}
@@ -794,14 +790,14 @@ export default function Teams() {
                     >
                       {resolveResourceName(g)}
                     </span>
-                    <span className="bg-muted-foreground/10 text-muted-foreground shrink-0 rounded-full px-2 py-0.5 text-xs">
+                    <Badge variant="neutral">
                       {accessLevelLabel(g.access_level)}
-                    </span>
+                    </Badge>
                     {isAdmin && (
                       <Button
-                        variant="ghost"
+                        variant="ghost-destructive"
                         size="icon-sm"
-                        className="text-muted-foreground hover:text-destructive shrink-0"
+                        className="shrink-0"
                         aria-label={t('settings.teams.unshare')}
                         title={t('settings.teams.unshare')}
                         onClick={() => handleUnshare(g)}
@@ -886,10 +882,10 @@ export default function Teams() {
             >
               {t('settings.teams.descriptionLabel')}
             </label>
-            <textarea
+            <Textarea
               id="team-edit-description"
               rows={3}
-              className="border-border bg-background text-foreground focus-visible:ring-ring/50 focus-visible:border-ring placeholder:text-muted-foreground w-full resize-none rounded-lg border px-3 py-2 text-sm outline-none focus-visible:ring-[3px]"
+              resize="none"
               placeholder={t('settings.teams.descriptionPlaceholder')}
               value={editDescription}
               onChange={(e) => setEditDescription(e.target.value)}
diff --git a/frontend/src/settings/TestRetrievalModal.notices.test.tsx b/frontend/src/settings/TestRetrievalModal.notices.test.tsx
new file mode 100644
index 00000000..30cec609
--- /dev/null
+++ b/frontend/src/settings/TestRetrievalModal.notices.test.tsx
@@ -0,0 +1,117 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('../hooks', () => ({
+  useMediaQuery: () => ({ isMobile: false, isTablet: false, isDesktop: true }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => 'token',
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+const testSourceRetrieval = vi.fn();
+vi.mock('../api/services/userService', () => ({
+  default: {
+    testSourceRetrieval: (...args: unknown[]) => testSourceRetrieval(...args),
+  },
+}));
+
+import type { Doc } from '../models/misc';
+import TestRetrievalModal from './TestRetrievalModal';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const doc = (config: Doc['config']): Doc =>
+  ({ id: 'src-1', name: 'Handbook', config }) as Doc;
+
+const alerts = () =>
+  Array.from(document.body.querySelectorAll<HTMLElement>('[role="alert"]'));
+
+describe('TestRetrievalModal notices', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    testSourceRetrieval.mockReset();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = (document: Doc) =>
+    act(() => {
+      root.render(
+        <TestRetrievalModal
+          modalState="ACTIVE"
+          setModalState={() => undefined}
+          document={document}
+        />,
+      );
+    });
+
+  it('sizes the Run button to the query field row', () => {
+    render(doc(undefined));
+    const run = Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>('[data-slot="button"]'),
+    ).find((b) => b.textContent === 'settings.sources.testRetrieval.run');
+    expect(run?.getAttribute('data-size')).toBe('field');
+    expect(run?.getAttribute('data-shape')).toBe('pill');
+    // 42px, the height of the Input beside it.
+    expect(run?.className).toContain('h-10.5');
+  });
+
+  it('shows an invalid prescreen config as a warning Alert with an icon', () => {
+    render(
+      doc({
+        retrieval: { chunks: 10, prescreen: { candidate_k: 5, max_keep: 3 } },
+      } as Doc['config']),
+    );
+
+    const warning = alerts().find((el) =>
+      el.textContent?.includes(
+        'settings.sources.configModal.prescreenInvalidHint',
+      ),
+    );
+    expect(warning).toBeDefined();
+    expect(warning?.className).toContain('text-warning');
+    expect(warning?.querySelector('svg')).not.toBeNull();
+  });
+
+  it('shows a failed run as a destructive Alert with an icon', async () => {
+    testSourceRetrieval.mockRejectedValue(new Error('network'));
+    render(doc(undefined));
+
+    const input =
+      document.body.querySelector<HTMLInputElement>('input[type="text"]');
+    expect(input).not.toBeNull();
+    const setValue = Object.getOwnPropertyDescriptor(
+      HTMLInputElement.prototype,
+      'value',
+    )?.set;
+    act(() => {
+      setValue?.call(input, 'fuel surcharge');
+      input?.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await act(async () => {
+      input?.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }),
+      );
+    });
+
+    const error = alerts().find((el) =>
+      el.textContent?.includes('settings.sources.testRetrieval.errors.failed'),
+    );
+    expect(error).toBeDefined();
+    expect(error?.className).toContain('text-destructive');
+    expect(error?.querySelector('svg')).not.toBeNull();
+  });
+});
diff --git a/frontend/src/settings/TestRetrievalModal.tsx b/frontend/src/settings/TestRetrievalModal.tsx
index 6de11f45..e596d7d8 100644
--- a/frontend/src/settings/TestRetrievalModal.tsx
+++ b/frontend/src/settings/TestRetrievalModal.tsx
@@ -1,9 +1,11 @@
+import { CircleAlert, TriangleAlert } from 'lucide-react';
 import { useEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
 
 import userService from '../api/services/userService';
 import Spinner from '../components/Spinner';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Modal } from '../components/ui/modal';
@@ -182,14 +184,14 @@ export default function TestRetrievalModal({
       mobileVariant="sheet"
       // Same width ramp and padding as PromptsModal so the two large modals
       // read as one family.
-      className="bg-card dark:bg-card w-[95vw] max-w-[650px] rounded-2xl px-4 py-4 sm:px-6 sm:py-6 md:max-w-[860px] md:px-8 md:py-6 lg:max-w-[980px]"
+      className="w-[95vw] max-w-[650px] md:max-w-[860px] lg:max-w-[980px]"
       contentClassName="max-h-[70vh]"
     >
       <div className="flex flex-col">
-        <p className="mb-1 text-xl font-semibold text-[#2B2B2B] dark:text-white">
+        <p className="text-foreground mb-1 text-xl font-semibold">
           {tr('title')}
         </p>
-        <p className="dark:text-muted-foreground mb-6 text-sm text-[#6B6B6B]">
+        <p className="text-muted-foreground mb-6 text-sm">
           {document?.name
             ? tr('subtitle', { name: document.name })
             : tr('subtitleGeneric')}
@@ -202,7 +204,8 @@ export default function TestRetrievalModal({
               value={query}
               autoFocus
               placeholder={tr('queryPlaceholder')}
-              className="h-[42px] flex-1 rounded-3xl px-4"
+              shape="pill"
+              className="flex-1"
               onChange={(e) => setQuery(e.target.value)}
               onKeyDown={(e) => {
                 if (e.key === 'Enter') handleRun();
@@ -212,7 +215,9 @@ export default function TestRetrievalModal({
               type="button"
               disabled={!canRun}
               onClick={handleRun}
-              className="h-[42px] min-w-[96px] shrink-0 rounded-3xl px-6 text-sm font-medium"
+              size="field"
+              shape="pill"
+              className="min-w-[96px] shrink-0"
             >
               {running ? <Spinner size="small" /> : tr('run')}
             </Button>
@@ -230,15 +235,19 @@ export default function TestRetrievalModal({
           <p className="text-muted-foreground text-xs">{tr('notSavedHint')}</p>
 
           {!prescreenValid && (
-            <div className="rounded-xl bg-amber-50 p-3 text-xs text-amber-800 dark:bg-amber-900/30 dark:text-amber-200">
-              {t('settings.sources.configModal.prescreenInvalidHint')}
-            </div>
+            <Alert variant="warning">
+              <TriangleAlert className="size-4" aria-hidden="true" />
+              <AlertDescription>
+                {t('settings.sources.configModal.prescreenInvalidHint')}
+              </AlertDescription>
+            </Alert>
           )}
 
           {error && (
-            <div className="rounded-xl bg-red-50 p-3 text-sm text-red-700 dark:bg-red-900/40 dark:text-red-300">
-              {error}
-            </div>
+            <Alert variant="destructive">
+              <CircleAlert className="size-4" aria-hidden="true" />
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
           )}
 
           {result && (
@@ -297,8 +306,9 @@ export default function TestRetrievalModal({
                       <Button
                         type="button"
                         variant="link"
+                        size="xs"
                         onClick={() => toggleExpanded(chunk.rank)}
-                        className="text-muted-foreground h-auto px-0 py-1 text-xs"
+                        className="-ml-2"
                       >
                         {isOpen ? tr('showLess') : tr('showMore')}
                       </Button>
diff --git a/frontend/src/settings/ToolConfig.test.tsx b/frontend/src/settings/ToolConfig.test.tsx
new file mode 100644
index 00000000..97093762
--- /dev/null
+++ b/frontend/src/settings/ToolConfig.test.tsx
@@ -0,0 +1,265 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-redux', () => ({
+  useSelector: () => 'token',
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (key: string, fallback?: unknown) =>
+      typeof fallback === 'string' ? fallback : key,
+  }),
+}));
+
+vi.mock('../hooks', () => ({ useDarkTheme: () => [false, () => {}] }));
+vi.mock('../navigation/DetailBreadcrumb', () => ({ default: () => null }));
+vi.mock('../modals/ConfirmationModal', () => ({ default: () => null }));
+vi.mock('../modals/AddActionModal', () => ({ default: () => null }));
+vi.mock('../modals/ImportSpecModal', () => ({ default: () => null }));
+
+const updateTool = vi.fn();
+vi.mock('../api/services/userService', () => ({
+  default: {
+    updateTool: (...args: unknown[]) => updateTool(...args),
+    deleteTool: () => Promise.resolve(),
+  },
+}));
+
+import type { APIToolType, UserToolType } from './types';
+import ToolConfig from './ToolConfig';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const userTool = {
+  id: 'tool-1',
+  name: 'brave_search',
+  displayName: 'Brave',
+  description: '',
+  status: true,
+  config: {},
+  actions: [
+    {
+      name: 'search',
+      description: 'Search the web',
+      active: true,
+      parameters: {
+        type: 'object',
+        properties: {
+          q: {
+            type: 'string',
+            description: '',
+            value: '',
+            filled_by_llm: true,
+          },
+        },
+      },
+    },
+  ],
+} as unknown as UserToolType;
+
+const apiTool = {
+  id: 'tool-2',
+  name: 'api_tool',
+  displayName: 'API',
+  description: '',
+  status: true,
+  config: {
+    actions: {
+      list: {
+        name: 'list',
+        method: 'POST',
+        url: 'https://example.com',
+        description: 'List things',
+        active: true,
+        body: { type: 'object', properties: {} },
+        headers: {
+          type: 'object',
+          properties: {
+            Accept: {
+              type: 'string',
+              description: '',
+              value: '',
+              filled_by_llm: false,
+            },
+          },
+        },
+        query_params: { type: 'object', properties: {} },
+        body_content_type: 'application/json',
+        body_encoding_rules: {},
+      },
+    },
+  },
+} as unknown as APIToolType;
+
+describe('ToolConfig', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    updateTool.mockReset();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const render = async (tool: UserToolType | APIToolType) => {
+    await act(async () => {
+      root.render(
+        <ToolConfig tool={tool} setTool={() => {}} handleGoBack={() => {}} />,
+      );
+    });
+  };
+
+  const buttonByText = (text: string) =>
+    Array.from(container.querySelectorAll<HTMLElement>('button')).find(
+      (el) => el.textContent === text,
+    );
+
+  it('renders the header Save as a small pill with no class overrides', async () => {
+    await render(userTool);
+    const save = buttonByText('settings.tools.save');
+    expect(save?.dataset.size).toBe('sm');
+    expect(save?.dataset.shape).toBe('pill');
+    expect(save?.className).not.toMatch(/text-white|text-xs/);
+  });
+
+  it('renders the actions search as a pill Input with an inset icon', async () => {
+    await render(userTool);
+    const search = container.querySelector<HTMLInputElement>(
+      'input[placeholder="settings.tools.searchActions"]',
+    );
+    expect(search?.dataset.shape).toBe('pill');
+    expect(search?.className).toContain('pl-10');
+    expect(search?.parentElement?.querySelector('svg')).not.toBeNull();
+  });
+
+  it('renders the parameter table fields at the small Input size', async () => {
+    await render(userTool);
+    await act(async () => {
+      (
+        container.querySelector('[class*="cursor-pointer"]') as HTMLElement
+      ).click();
+    });
+    const tableInputs = Array.from(
+      container.querySelectorAll<HTMLInputElement>('table input[data-slot]'),
+    );
+    expect(tableInputs.length).toBeGreaterThan(0);
+    tableInputs.forEach((input) => {
+      expect(input.dataset.size).toBe('sm');
+      expect(input.className).not.toMatch(/rounded-lg|h-auto/);
+    });
+  });
+
+  it('shows a failed save as a destructive Alert', async () => {
+    updateTool.mockRejectedValue(new Error('nope'));
+    await render({ ...userTool, customName: '' });
+    const name = container.querySelector<HTMLInputElement>(
+      'input[placeholder="settings.tools.customNamePlaceholder"]',
+    );
+    await act(async () => {
+      const setter = Object.getOwnPropertyDescriptor(
+        HTMLInputElement.prototype,
+        'value',
+      )?.set;
+      setter?.call(name, 'Renamed');
+      name?.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    await act(async () => {
+      buttonByText('settings.tools.save')?.click();
+    });
+    const alert = container.querySelector<HTMLElement>('[role="alert"]');
+    expect(alert?.textContent).toBe('settings.tools.saveFailed');
+    expect(alert?.className).toContain('text-destructive');
+  });
+
+  it('renders the API tool header actions as outline-primary pills', async () => {
+    await render(apiTool);
+    for (const label of [
+      'settings.tools.importSpec',
+      'settings.tools.addAction',
+    ]) {
+      const button = buttonByText(label);
+      expect(button?.dataset.variant).toBe('outline-primary');
+      expect(button?.dataset.shape).toBe('pill');
+    }
+  });
+
+  it('renders the API action form as 42px pills with remove icons', async () => {
+    await render(apiTool);
+    const deleteAction = container.querySelector<HTMLElement>(
+      'button[title="convTile.delete"]',
+    );
+    expect(deleteAction?.dataset.variant).toBe('ghost-destructive');
+    expect(deleteAction?.dataset.size).toBe('icon-xs');
+
+    await act(async () => {
+      (
+        container.querySelector('[class*="cursor-pointer"]') as HTMLElement
+      ).click();
+    });
+    const urlField = container.querySelector<HTMLInputElement>(
+      'input[value="https://example.com"]',
+    );
+    expect(urlField?.dataset.shape).toBe('pill');
+    expect(urlField?.dataset.size).toBe('default');
+    const triggers = Array.from(
+      container.querySelectorAll<HTMLElement>('[data-slot="select-trigger"]'),
+    );
+    expect(triggers).toHaveLength(2);
+    triggers.forEach((trigger) => {
+      expect(trigger.dataset.size).toBe('lg');
+      expect(trigger.className).not.toContain('rounded-3xl');
+    });
+    const addNew = buttonByText('settings.tools.addNew');
+    expect(addNew?.dataset.variant).toBe('outline-primary');
+    expect(addNew?.dataset.shape).toBe('pill');
+    const removeRow = container.querySelector<HTMLElement>(
+      'table button[data-variant="ghost-destructive"]',
+    );
+    expect(removeRow?.dataset.size).toBe('icon-xs');
+  });
+
+  it('renders the property type as a small Select, not a native select', async () => {
+    const list = (apiTool.config as { actions: Record<string, object> }).actions
+      .list;
+    await render({
+      ...apiTool,
+      config: {
+        actions: {
+          list: {
+            ...list,
+            query_params: {
+              type: 'object',
+              properties: {
+                limit: {
+                  type: 'integer',
+                  description: '',
+                  value: '',
+                  filled_by_llm: true,
+                },
+              },
+            },
+          },
+        },
+      },
+    } as unknown as APIToolType);
+    await act(async () => {
+      (
+        container.querySelector('[class*="cursor-pointer"]') as HTMLElement
+      ).click();
+    });
+    expect(container.querySelector('select:not([aria-hidden])')).toBeNull();
+    const typeTrigger = container.querySelector<HTMLElement>(
+      'table [data-slot="select-trigger"]',
+    );
+    expect(typeTrigger?.dataset.size).toBe('sm');
+    expect(typeTrigger?.getAttribute('aria-label')).toBe('settings.tools.type');
+    expect(typeTrigger?.textContent).toContain('integer');
+  });
+});
diff --git a/frontend/src/settings/ToolConfig.tsx b/frontend/src/settings/ToolConfig.tsx
index 6c845131..9d6b9d71 100644
--- a/frontend/src/settings/ToolConfig.tsx
+++ b/frontend/src/settings/ToolConfig.tsx
@@ -1,3 +1,4 @@
+import { Search, Trash2 } from 'lucide-react';
 import React from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSelector } from 'react-redux';
@@ -8,8 +9,8 @@ import CircleCheck from '../assets/circle-check.svg';
 import CircleX from '../assets/circle-x.svg';
 import NoFilesDarkIcon from '../assets/no-files-dark.svg';
 import NoFilesIcon from '../assets/no-files.svg';
-import Trash from '../assets/trash.svg';
 import ConfigFields from '../components/ConfigFields';
+import { Alert, AlertDescription } from '../components/ui/alert';
 import {
   Select,
   SelectContent,
@@ -17,6 +18,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '../components/ui/select';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Switch } from '../components/ui/switch';
@@ -27,7 +29,7 @@ import DetailBreadcrumb from '../navigation/DetailBreadcrumb';
 import ImportSpecModal from '../modals/ImportSpecModal';
 import { ActiveState } from '../models/misc';
 import { selectToken } from '../preferences/preferenceSlice';
-import { getMethodColorClass } from '../utils/httpMethodColors';
+import { getMethodBadgeVariant } from '../utils/httpMethodColors';
 import { areObjectsEqual } from '../utils/objectUtils';
 import { APIActionType, APIToolType, UserToolType } from './types';
 
@@ -338,7 +340,8 @@ export default function ToolConfig({
         />
         <Button
           type="button"
-          className="rounded-full px-3 py-2 text-xs text-nowrap text-white sm:px-4 sm:py-2"
+          size="sm"
+          shape="pill"
           onClick={handleSaveChanges}
           disabled={!hasUnsavedChanges || saving}
         >
@@ -346,9 +349,9 @@ export default function ToolConfig({
         </Button>
       </div>
       {saveError && (
-        <div className="mb-2 rounded-lg bg-red-50 px-4 py-2 text-sm text-red-600 dark:bg-red-900/20 dark:text-red-400">
-          {saveError}
-        </div>
+        <Alert variant="destructive" className="mb-2">
+          <AlertDescription>{saveError}</AlertDescription>
+        </Alert>
       )}
       <div className="mt-1">
         <p className="text-foreground dark:text-foreground text-sm font-semibold">
@@ -360,7 +363,6 @@ export default function ToolConfig({
             value={customName}
             onChange={(e) => setCustomName(e.target.value)}
             placeholder={t('settings.tools.customNamePlaceholder')}
-            className="rounded-xl"
           />
         </div>
       </div>
@@ -387,7 +389,7 @@ export default function ToolConfig({
           )}
       </div>
       <div className="flex flex-col gap-4">
-        <div className="mx-0 my-2 h-[0.8px] w-full rounded-full bg-[#C4C4C4]/40"></div>
+        <div className="bg-border mx-0 my-2 h-[0.8px] w-full rounded-full"></div>
         <div className="flex w-full flex-row items-center justify-between gap-2">
           <p className="text-foreground dark:text-foreground text-base font-semibold">
             {t('settings.tools.actions')}
@@ -396,17 +398,17 @@ export default function ToolConfig({
             <div className="flex gap-2">
               <Button
                 type="button"
-                variant="outline"
+                variant="outline-primary"
+                shape="pill"
                 onClick={() => setImportModalState('ACTIVE')}
-                className="border-primary text-primary hover:bg-primary hover:text-primary-foreground rounded-full px-5 py-1"
               >
                 {t('settings.tools.importSpec')}
               </Button>
               <Button
                 type="button"
-                variant="outline"
+                variant="outline-primary"
+                shape="pill"
                 onClick={() => setActionModalState('ACTIVE')}
-                className="border-primary text-primary hover:bg-primary hover:text-primary-foreground rounded-full px-5 py-1"
               >
                 {t('settings.tools.addAction')}
               </Button>
@@ -425,7 +427,7 @@ export default function ToolConfig({
                   alt="No actions found"
                   className="mx-auto mb-4 h-24 w-24"
                 />
-                <p className="text-center text-gray-500 dark:text-gray-400">
+                <p className="text-muted-foreground text-center">
                   {t('settings.tools.noActionsFound')}
                 </p>
               </div>
@@ -435,29 +437,22 @@ export default function ToolConfig({
           <div className="flex flex-col gap-4">
             {'actions' in tool && tool.actions && tool.actions.length > 0 ? (
               <>
-                <div className="relative">
-                  <svg
-                    className="text-muted-foreground absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2"
-                    xmlns="http://www.w3.org/2000/svg"
-                    fill="none"
-                    viewBox="0 0 24 24"
-                    strokeWidth={2}
-                    stroke="currentColor"
-                  >
-                    <circle cx="11" cy="11" r="8" />
-                    <path strokeLinecap="round" d="m21 21-4.35-4.35" />
-                  </svg>
-                  <Input
-                    type="text"
-                    value={userActionsSearch}
-                    onChange={(e) => setUserActionsSearch(e.target.value)}
-                    placeholder={t('settings.tools.searchActions')}
-                    className="h-10 rounded-full pr-4 pl-10 text-sm md:text-sm"
-                  />
-                </div>
+                <Input
+                  type="text"
+                  value={userActionsSearch}
+                  onChange={(e) => setUserActionsSearch(e.target.value)}
+                  placeholder={t('settings.tools.searchActions')}
+                  shape="pill"
+                  leftIcon={
+                    <Search
+                      className="text-muted-foreground size-4"
+                      aria-hidden
+                    />
+                  }
+                />
 
                 {filteredUserActions.length === 0 && userActionsSearch && (
-                  <p className="py-4 text-center text-gray-500 dark:text-gray-400">
+                  <p className="text-muted-foreground py-4 text-center">
                     {t('settings.tools.noActionsMatch')}
                   </p>
                 )}
@@ -483,7 +478,7 @@ export default function ToolConfig({
                             {action.name}
                           </p>
                           {action.description && (
-                            <p className="hidden truncate text-sm text-gray-500 md:block md:max-w-xs lg:max-w-md dark:text-gray-400">
+                            <p className="text-muted-foreground hidden truncate text-sm md:block md:max-w-xs lg:max-w-md">
                               {action.description}
                             </p>
                           )}
@@ -493,7 +488,7 @@ export default function ToolConfig({
                           onClick={(e) => e.stopPropagation()}
                         >
                           <div className="flex items-center gap-1">
-                            <span className="text-xs text-gray-500 dark:text-gray-400">
+                            <span className="text-muted-foreground text-xs">
                               {t('settings.tools.requireApproval', 'Approval')}
                             </span>
                             <Switch
@@ -539,6 +534,7 @@ export default function ToolConfig({
                               type="text"
                               className="w-full"
                               label={t('settings.tools.descriptionPlaceholder')}
+                              labelSurface="background"
                               value={action.description}
                               onChange={(e) => {
                                 setTool({
@@ -592,7 +588,7 @@ export default function ToolConfig({
                                               checked={param[1].filled_by_llm}
                                               id={uniqueKey}
                                               type="checkbox"
-                                              className="size-4 rounded-sm border-gray-300 bg-transparent"
+                                              className="border-border size-4 rounded-sm bg-transparent"
                                               onChange={() =>
                                                 handleCheckboxChange(
                                                   originalIndex,
@@ -607,7 +603,7 @@ export default function ToolConfig({
                                         <Input
                                           key={uniqueKey}
                                           value={param[1].description}
-                                          className="h-auto rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                                          size="sm"
                                           onChange={(e) => {
                                             setTool({
                                               ...tool,
@@ -645,7 +641,7 @@ export default function ToolConfig({
                                           value={param[1].value}
                                           key={uniqueKey}
                                           disabled={param[1].filled_by_llm}
-                                          className={`h-auto rounded-lg px-2 py-1 text-sm shadow-none md:text-sm ${param[1].filled_by_llm ? 'opacity-50' : ''}`}
+                                          size="sm"
                                           onChange={(e) => {
                                             setTool({
                                               ...tool,
@@ -697,7 +693,7 @@ export default function ToolConfig({
                   alt="No actions found"
                   className="mx-auto mb-4 h-24 w-24"
                 />
-                <p className="text-center text-gray-500 dark:text-gray-400">
+                <p className="text-muted-foreground text-center">
                   {t('settings.tools.noActionsFound')}
                 </p>
               </div>
@@ -869,29 +865,19 @@ function APIToolConfig({
 
   return (
     <div className="scrollbar-overlay flex flex-col gap-4">
-      <div className="relative">
-        <svg
-          className="text-muted-foreground absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2"
-          xmlns="http://www.w3.org/2000/svg"
-          fill="none"
-          viewBox="0 0 24 24"
-          strokeWidth={2}
-          stroke="currentColor"
-        >
-          <circle cx="11" cy="11" r="8" />
-          <path strokeLinecap="round" d="m21 21-4.35-4.35" />
-        </svg>
-        <Input
-          type="text"
-          value={searchQuery}
-          onChange={(e) => setSearchQuery(e.target.value)}
-          placeholder={t('settings.tools.searchActions')}
-          className="h-10 rounded-full pr-4 pl-10 text-sm md:text-sm"
-        />
-      </div>
+      <Input
+        type="text"
+        value={searchQuery}
+        onChange={(e) => setSearchQuery(e.target.value)}
+        placeholder={t('settings.tools.searchActions')}
+        shape="pill"
+        leftIcon={
+          <Search className="text-muted-foreground size-4" aria-hidden />
+        }
+      />
 
       {filteredActions.length === 0 && searchQuery && (
-        <p className="py-4 text-center text-gray-500 dark:text-gray-400">
+        <p className="text-muted-foreground py-4 text-center">
           {t('settings.tools.noActionsMatch')}
         </p>
       )}
@@ -914,16 +900,14 @@ function APIToolConfig({
                     alt="expand"
                     className={`h-4 w-4 opacity-60 transition-transform duration-200 dark:invert ${isExpanded ? 'rotate-90' : ''}`}
                   />
-                  <span
-                    className={`rounded px-2 py-0.5 text-xs font-medium ${getMethodColorClass(action.method)}`}
-                  >
+                  <Badge variant={getMethodBadgeVariant(action.method)}>
                     {action.method}
-                  </span>
+                  </Badge>
                   <p className="text-foreground dark:text-foreground font-semibold">
                     {action.name}
                   </p>
                   {action.description && (
-                    <p className="hidden truncate text-sm text-gray-500 md:block md:max-w-xs lg:max-w-md dark:text-gray-400">
+                    <p className="text-muted-foreground hidden truncate text-sm md:block md:max-w-xs lg:max-w-md">
                       {action.description}
                     </p>
                   )}
@@ -934,20 +918,18 @@ function APIToolConfig({
                 >
                   <Button
                     type="button"
-                    variant="ghost"
-                    size="icon-sm"
+                    variant="ghost-destructive"
+                    size="icon-xs"
+                    shape="pill"
                     onClick={() => handleDeleteActionClick(actionName)}
-                    className="mr-2 h-6 w-6 rounded-full"
+                    className="mr-2"
                     title={t('convTile.delete')}
+                    aria-label={t('convTile.delete')}
                   >
-                    <img
-                      src={Trash}
-                      alt="delete"
-                      className="h-4 w-4 opacity-40 transition-opacity hover:opacity-100"
-                    />
+                    <Trash2 aria-hidden />
                   </Button>
                   <div className="flex items-center gap-1">
-                    <span className="text-xs text-gray-500 dark:text-gray-400">
+                    <span className="text-muted-foreground text-xs">
                       {t('settings.tools.requireApproval', 'Approval')}
                     </span>
                     <Switch
@@ -1007,11 +989,13 @@ function APIToolConfig({
                         });
                       }}
                       label={t('settings.tools.urlPlaceholder')}
+                      labelSurface="background"
+                      shape="pill"
                     />
                   </div>
                   <div className="mt-4 px-5 py-2">
                     <div className="relative w-full">
-                      <span className="text-muted-foreground bg-card absolute -top-2 left-5 z-10 px-2 text-xs">
+                      <span className="text-muted-foreground bg-background absolute -top-2 left-5 z-10 px-2 text-xs">
                         {t('settings.tools.method')}
                       </span>
                       <Select
@@ -1043,10 +1027,7 @@ function APIToolConfig({
                           });
                         }}
                       >
-                        <SelectTrigger
-                          className="w-56 rounded-3xl px-5 py-3"
-                          size="lg"
-                        >
+                        <SelectTrigger className="w-56" size="lg" shape="pill">
                           <SelectValue />
                         </SelectTrigger>
                         <SelectContent>
@@ -1091,6 +1072,8 @@ function APIToolConfig({
                         });
                       }}
                       label={t('settings.tools.descriptionPlaceholder')}
+                      labelSurface="background"
+                      shape="pill"
                     />
                   </div>
                   {(action.method === 'POST' ||
@@ -1100,7 +1083,7 @@ function APIToolConfig({
                     action.method === 'OPTIONS') && (
                     <div className="mt-4 px-5 py-2">
                       <div className="relative w-full">
-                        <span className="text-muted-foreground bg-card absolute -top-2 left-5 z-10 px-2 text-xs">
+                        <span className="text-muted-foreground bg-background absolute -top-2 left-5 z-10 px-2 text-xs">
                           {t('settings.tools.bodyContentType')}
                         </span>
                         <Select
@@ -1132,8 +1115,9 @@ function APIToolConfig({
                           }}
                         >
                           <SelectTrigger
-                            className="w-56 rounded-3xl px-5 py-3"
+                            className="w-56"
                             size="lg"
+                            shape="pill"
                           >
                             <SelectValue />
                           </SelectTrigger>
@@ -1405,7 +1389,8 @@ function APIActionTable({
                   <div className="flex flex-row items-center justify-between gap-2">
                     <Input
                       value={newPropertyKey}
-                      className="h-auto min-w-[130.5px] rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                      size="sm"
+                      className="min-w-[130.5px]"
                       onChange={(e) => setNewPropertyKey(e.target.value)}
                       onKeyDown={(e) => {
                         if (e.key === 'Enter') {
@@ -1417,9 +1402,9 @@ function APIActionTable({
                       <Button
                         type="button"
                         variant="ghost"
-                        size="icon-sm"
+                        size="icon-xs"
                         onClick={handleRenameProperty}
-                        className="mr-1 h-5 w-5"
+                        className="mr-1"
                       >
                         <img
                           src={CircleCheck}
@@ -1430,9 +1415,8 @@ function APIActionTable({
                       <Button
                         type="button"
                         variant="ghost"
-                        size="icon-sm"
+                        size="icon-xs"
                         onClick={handleRenamePropertyCancel}
-                        className="h-5 w-5"
                       >
                         <img src={CircleX} alt="cancel" className="h-5 w-5" />
                       </Button>
@@ -1441,27 +1425,35 @@ function APIActionTable({
                 ) : (
                   <Input
                     value={key}
-                    className="h-auto min-w-[175.5px] rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                    size="sm"
+                    className="min-w-[175.5px]"
                     onFocus={() => handleRenamePropertyStart(section, key)}
                     readOnly
                   />
                 )}
               </td>
               <td>
-                <select
+                <Select
                   value={param.type}
-                  onChange={(e) =>
+                  onValueChange={(value) =>
                     handlePropertyTypeChange(
                       section,
                       key,
-                      e.target.value as 'string' | 'integer',
+                      value as 'string' | 'integer',
                     )
                   }
-                  className="border-border dark:border-border focus-visible:ring-ring/50 rounded-lg border bg-transparent px-2 py-1 text-sm outline-hidden focus-visible:ring-2"
                 >
-                  <option value="string">string</option>
-                  <option value="integer">integer</option>
-                </select>
+                  <SelectTrigger
+                    size="sm"
+                    aria-label={t('settings.tools.type')}
+                  >
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="string">string</SelectItem>
+                    <SelectItem value="integer">integer</SelectItem>
+                  </SelectContent>
+                </Select>
               </td>
               <td>
                 <label className="ml-2.5 flex cursor-pointer items-start gap-4">
@@ -1469,7 +1461,7 @@ function APIActionTable({
                     <input
                       checked={param.filled_by_llm}
                       type="checkbox"
-                      className="size-4 rounded-sm border-gray-300 bg-transparent"
+                      className="border-border size-4 rounded-sm bg-transparent"
                       onChange={(e) =>
                         handlePropertyChange(
                           section,
@@ -1485,7 +1477,7 @@ function APIActionTable({
               <td className="w-10">
                 <Input
                   value={param.description}
-                  className="h-auto rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                  size="sm"
                   onChange={(e) =>
                     handlePropertyChange(
                       section,
@@ -1503,7 +1495,7 @@ function APIActionTable({
                   onChange={(e) =>
                     handlePropertyChange(section, key, 'value', e.target.value)
                   }
-                  className={`h-auto rounded-lg px-2 py-1 text-sm shadow-none md:text-sm ${param.filled_by_llm ? 'opacity-50' : ''}`}
+                  size="sm"
                 />
               </td>
               <td
@@ -1511,12 +1503,12 @@ function APIActionTable({
               >
                 <Button
                   type="button"
-                  variant="ghost"
-                  size="icon-sm"
+                  variant="ghost-destructive"
+                  size="icon-xs"
                   onClick={() => handlePorpertyDelete(section, key)}
-                  className="h-4 w-4 opacity-60 hover:opacity-100"
+                  aria-label={t('convTile.delete')}
                 >
-                  <img src={Trash} alt="delete" className="h-4 w-4"></img>
+                  <Trash2 aria-hidden />
                 </Button>
               </td>
             </tr>
@@ -1534,28 +1526,34 @@ function APIActionTable({
                   }
                 }}
                 placeholder={t('settings.tools.propertyName')}
-                className="h-auto min-w-[130.5px] rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                size="sm"
+                className="min-w-[130.5px]"
               />
             </td>
             <td>
-              <select
+              <Select
                 value={newPropertyType}
-                onChange={(e) =>
-                  setNewPropertyType(e.target.value as 'string' | 'integer')
+                onValueChange={(value) =>
+                  setNewPropertyType(value as 'string' | 'integer')
                 }
-                className="border-border dark:border-border focus-visible:ring-ring/50 rounded-lg border bg-transparent px-2 py-1 text-sm outline-hidden focus-visible:ring-2"
               >
-                <option value="string">string</option>
-                <option value="integer">integer</option>
-              </select>
+                <SelectTrigger size="sm" aria-label={t('settings.tools.type')}>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="string">string</SelectItem>
+                  <SelectItem value="integer">integer</SelectItem>
+                </SelectContent>
+              </Select>
             </td>
             <td colSpan={3} className="text-right">
               <Button
                 type="button"
                 variant="default"
                 size="sm"
+                shape="pill"
                 onClick={handleAddProperty}
-                className="mr-1 rounded-full px-5 text-white"
+                className="mr-1"
               >
                 {t('settings.tools.add')}
               </Button>
@@ -1563,8 +1561,8 @@ function APIActionTable({
                 type="button"
                 variant="destructive-outline"
                 size="sm"
+                shape="pill"
                 onClick={handleAddPropertyCancel}
-                className="rounded-full px-5"
               >
                 {t('settings.tools.cancel')}
               </Button>
@@ -1576,10 +1574,10 @@ function APIActionTable({
             <td colSpan={5}>
               <Button
                 type="button"
-                variant="outline"
+                variant="outline-primary"
                 size="sm"
+                shape="pill"
                 onClick={() => handleAddPropertyStart(section)}
-                className="border-primary text-primary hover:bg-primary/90 rounded-full px-5 text-nowrap hover:text-white"
               >
                 {t('settings.tools.addNew')}
               </Button>
@@ -1603,7 +1601,8 @@ function APIActionTable({
                   <div className="flex flex-row items-center justify-between gap-2">
                     <Input
                       value={newPropertyKey}
-                      className="h-auto min-w-[130.5px] rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                      size="sm"
+                      className="min-w-[130.5px]"
                       onChange={(e) => setNewPropertyKey(e.target.value)}
                       onKeyDown={(e) => {
                         if (e.key === 'Enter') {
@@ -1615,9 +1614,9 @@ function APIActionTable({
                       <Button
                         type="button"
                         variant="ghost"
-                        size="icon-sm"
+                        size="icon-xs"
                         onClick={handleRenameProperty}
-                        className="mr-1 h-5 w-5"
+                        className="mr-1"
                       >
                         <img
                           src={CircleCheck}
@@ -1628,9 +1627,8 @@ function APIActionTable({
                       <Button
                         type="button"
                         variant="ghost"
-                        size="icon-sm"
+                        size="icon-xs"
                         onClick={handleRenamePropertyCancel}
-                        className="h-5 w-5"
                       >
                         <img src={CircleX} alt="cancel" className="h-5 w-5" />
                       </Button>
@@ -1639,7 +1637,8 @@ function APIActionTable({
                 ) : (
                   <Input
                     value={key}
-                    className="h-auto min-w-[175.5px] rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                    size="sm"
+                    className="min-w-[175.5px]"
                     onFocus={() => handleRenamePropertyStart('headers', key)}
                     readOnly
                   />
@@ -1657,13 +1656,13 @@ function APIActionTable({
                     )
                   }
                   placeholder="e.g., application/json"
-                  className="h-auto rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                  size="sm"
                 />
               </td>
               <td>
                 <Input
                   value={param.description}
-                  className="h-auto rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                  size="sm"
                   onChange={(e) =>
                     handlePropertyChange(
                       'headers',
@@ -1679,12 +1678,12 @@ function APIActionTable({
               >
                 <Button
                   type="button"
-                  variant="ghost"
-                  size="icon-sm"
+                  variant="ghost-destructive"
+                  size="icon-xs"
                   onClick={() => handlePorpertyDelete('headers', key)}
-                  className="h-4 w-4 opacity-60 hover:opacity-100"
+                  aria-label={t('convTile.delete')}
                 >
-                  <img src={Trash} alt="delete" className="h-4 w-4"></img>
+                  <Trash2 aria-hidden />
                 </Button>
               </td>
             </tr>
@@ -1702,7 +1701,8 @@ function APIActionTable({
                   }
                 }}
                 placeholder={t('settings.tools.propertyName')}
-                className="h-auto min-w-[130.5px] rounded-lg px-2 py-1 text-sm shadow-none md:text-sm"
+                size="sm"
+                className="min-w-[130.5px]"
               />
             </td>
             <td colSpan={2} className="text-right">
@@ -1710,8 +1710,9 @@ function APIActionTable({
                 type="button"
                 variant="default"
                 size="sm"
+                shape="pill"
                 onClick={handleAddProperty}
-                className="mr-1 rounded-full px-5 text-white"
+                className="mr-1"
               >
                 {t('settings.tools.add')}
               </Button>
@@ -1719,8 +1720,8 @@ function APIActionTable({
                 type="button"
                 variant="destructive-outline"
                 size="sm"
+                shape="pill"
                 onClick={handleAddPropertyCancel}
-                className="rounded-full px-5"
               >
                 {t('settings.tools.cancel')}
               </Button>
@@ -1732,10 +1733,10 @@ function APIActionTable({
             <td colSpan={3}>
               <Button
                 type="button"
-                variant="outline"
+                variant="outline-primary"
                 size="sm"
+                shape="pill"
                 onClick={() => handleAddPropertyStart('headers')}
-                className="border-primary text-primary hover:bg-primary/90 rounded-full px-5 text-nowrap hover:text-white"
               >
                 {t('settings.tools.addNew')}
               </Button>
diff --git a/frontend/src/settings/Tools.tsx b/frontend/src/settings/Tools.tsx
index 2960ee18..8acf5d4c 100644
--- a/frontend/src/settings/Tools.tsx
+++ b/frontend/src/settings/Tools.tsx
@@ -12,6 +12,7 @@ import NoFilesIcon from '../assets/no-files.svg';
 import ThreeDotsIcon from '../assets/three-dots.svg';
 import SkeletonLoader from '../components/SkeletonLoader';
 import ToolIcon from '../components/ToolIcon';
+import { Badge } from '../components/ui/badge';
 import { Button } from '../components/ui/button';
 import { Switch } from '../components/ui/switch';
 import {
@@ -157,7 +158,7 @@ export default function Tools() {
         variant: 'default',
         iconWidth: 16,
         iconHeight: 16,
-        iconClassName: 'text-[#747474]',
+        iconClassName: 'text-muted-foreground',
       });
     }
     return options;
@@ -294,8 +295,8 @@ export default function Tools() {
                   id="tool-search-input"
                   value={searchTerm}
                   onChange={(e) => setSearchTerm(e.target.value)}
-                  labelBgClassName="bg-background"
-                  className="rounded-full"
+                  labelSurface="background"
+                  shape="pill"
                   leftIcon={
                     <SearchIcon
                       className="text-muted-foreground size-4"
@@ -306,7 +307,8 @@ export default function Tools() {
               </div>
               <Button
                 type="button"
-                className="h-11 min-w-[108px] rounded-full whitespace-normal text-white"
+                shape="pill"
+                className="h-11 min-w-[108px] whitespace-normal"
                 onClick={() => {
                   setAddToolModalState('ACTIVE');
                 }}
@@ -328,7 +330,7 @@ export default function Tools() {
                       alt={t('settings.tools.noToolsFound')}
                       className="mx-auto mb-6 h-32 w-32"
                     />
-                    <p className="text-center text-lg text-gray-500 dark:text-gray-400">
+                    <p className="text-muted-foreground text-center text-lg">
                       {t('settings.tools.noToolsFound')}
                     </p>
                   </div>
@@ -346,7 +348,7 @@ export default function Tools() {
                           alt={t('settings.tools.noToolsFound')}
                           className="mx-auto mb-6 h-32 w-32"
                         />
-                        <p className="text-center text-lg text-gray-500 dark:text-gray-400">
+                        <p className="text-muted-foreground text-center text-lg">
                           {t('settings.tools.noToolsFound')}
                         </p>
                       </div>
@@ -425,20 +427,20 @@ export default function Tools() {
                                 className="h-6 w-6"
                               />
                               {tool.default && (
-                                <span className="inline-flex items-center rounded-full bg-gray-100 px-2 py-0.5 text-xs leading-none font-medium text-gray-600 dark:bg-gray-700/40 dark:text-gray-300">
+                                <Badge variant="neutral">
                                   {t('settings.tools.builtIn')}
-                                </span>
+                                </Badge>
                               )}
                               {tool.name === 'mcp_tool' &&
                                 mcpStatuses[tool.id] && (
-                                  <span
-                                    className={`inline-flex items-center rounded-full px-2 py-0.5 text-xs leading-none font-medium ${
+                                  <Badge
+                                    variant={
                                       mcpStatuses[tool.id] === 'connected'
-                                        ? 'bg-green-100 text-green-700 dark:bg-green-900/40 dark:text-green-300'
+                                        ? 'success'
                                         : mcpStatuses[tool.id] === 'needs_auth'
-                                          ? 'bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-300'
-                                          : 'bg-gray-100 text-gray-600 dark:bg-gray-700/40 dark:text-gray-300'
-                                    }`}
+                                          ? 'warning'
+                                          : 'neutral'
+                                    }
                                   >
                                     {mcpStatuses[tool.id] === 'connected'
                                       ? t('settings.tools.authStatus.connected')
@@ -449,10 +451,10 @@ export default function Tools() {
                                         : t(
                                             'settings.tools.authStatus.configured',
                                           )}
-                                  </span>
+                                  </Badge>
                                 )}
                               {tool.ownership === 'team' && (
-                                <span className="bg-muted-foreground/10 text-muted-foreground inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs leading-none font-medium">
+                                <Badge variant="neutral">
                                   <Users
                                     size={11}
                                     strokeWidth={2}
@@ -461,7 +463,7 @@ export default function Tools() {
                                   {tool.team_access === 'editor'
                                     ? t('teamAccess.editor')
                                     : t('teamAccess.viewer')}
-                                </span>
+                                </Badge>
                               )}
                             </div>
                             <div className="mt-[9px]">
diff --git a/frontend/src/settings/components/RetrievalOptions.tsx b/frontend/src/settings/components/RetrievalOptions.tsx
index b9dec5d6..64a5135b 100644
--- a/frontend/src/settings/components/RetrievalOptions.tsx
+++ b/frontend/src/settings/components/RetrievalOptions.tsx
@@ -1,3 +1,4 @@
+import { ChevronRight } from 'lucide-react';
 import { type ReactNode, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
@@ -22,8 +23,6 @@ import type {
 } from '../../models/misc';
 import type { Model } from '../../models/types';
 
-import ChevronRight from '../../assets/chevron-right.svg';
-
 // Defaults mirror the backend SourceConfig
 // (application/storage/db/source_config.py). A form seeded with these and sent
 // verbatim reproduces today's behavior, so the backend's "absent == default"
@@ -462,7 +461,7 @@ export default function RetrievalOptions({
             >
               <SelectTrigger
                 id="retrieval-retriever"
-                className="w-52 rounded-md"
+                className="w-52"
                 size="lg"
               >
                 <SelectValue />
@@ -559,7 +558,7 @@ export default function RetrievalOptions({
               >
                 <SelectTrigger
                   id="retrieval-exposure"
-                  className="w-52 rounded-md"
+                  className="w-52"
                   size="lg"
                 >
                   <SelectValue />
@@ -600,7 +599,6 @@ export default function RetrievalOptions({
               label={tr('prescreen.candidateK')}
               value={String(value.retrieval.prescreen.candidate_k)}
               disabled={disabled}
-              labelBgClassName="bg-card"
               onChange={(e) =>
                 setPrescreen({
                   candidate_k: Math.max(
@@ -616,7 +614,6 @@ export default function RetrievalOptions({
               label={tr('prescreen.maxKeep')}
               value={String(value.retrieval.prescreen.max_keep)}
               disabled={disabled}
-              labelBgClassName="bg-card"
               onChange={(e) =>
                 setPrescreen({
                   max_keep: Math.min(
@@ -632,7 +629,6 @@ export default function RetrievalOptions({
               label={tr('prescreen.batchSize')}
               value={String(value.retrieval.prescreen.batch_size)}
               disabled={disabled}
-              labelBgClassName="bg-card"
               onChange={(e) =>
                 setPrescreen({
                   batch_size: Math.max(1, Number(e.target.value) || 1),
@@ -670,7 +666,7 @@ export default function RetrievalOptions({
               >
                 <SelectTrigger
                   id="graph-seed-strategy"
-                  className="w-52 rounded-md"
+                  className="w-52"
                   size="lg"
                 >
                   <SelectValue />
@@ -744,7 +740,7 @@ export default function RetrievalOptions({
               >
                 <SelectTrigger
                   id="graph-extraction-model"
-                  className="w-52 rounded-md"
+                  className="w-52"
                   size="lg"
                 >
                   <SelectValue />
@@ -814,11 +810,7 @@ export default function RetrievalOptions({
                 setChunking({ strategy: v as ChunkingStrategy })
               }
             >
-              <SelectTrigger
-                id="chunking-strategy"
-                className="w-52 rounded-md"
-                size="lg"
-              >
+              <SelectTrigger id="chunking-strategy" className="w-52" size="lg">
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
@@ -896,15 +888,13 @@ export default function RetrievalOptions({
       <Button
         type="button"
         variant="link"
+        size="sm"
         onClick={() => setOpen((o) => !o)}
-        className="text-foreground hover:text-foreground h-auto w-fit justify-start px-0 py-2 text-sm font-normal hover:no-underline"
+        className="-ml-3 w-fit justify-start"
       >
-        <img
-          src={ChevronRight}
-          alt=""
-          className={`h-3 w-3 transform transition-transform dark:invert ${
-            expanded ? 'rotate-90' : ''
-          }`}
+        <ChevronRight
+          aria-hidden
+          className={cn('size-3 transition-transform', expanded && 'rotate-90')}
         />
         <span>{tr('title')}</span>
       </Button>
diff --git a/frontend/src/settings/components/UsageQuota.tsx b/frontend/src/settings/components/UsageQuota.tsx
index a2147beb..157990e2 100644
--- a/frontend/src/settings/components/UsageQuota.tsx
+++ b/frontend/src/settings/components/UsageQuota.tsx
@@ -4,6 +4,7 @@ import { useSelector } from 'react-redux';
 
 import { usagePercent } from '../../admin/quotaUtils';
 import userService from '../../api/services/userService';
+import { Progress } from '../../components/ui/progress';
 import { selectToken } from '../../preferences/preferenceSlice';
 
 type Budget = { limit: number | null; used: number };
@@ -27,11 +28,7 @@ function Meter({
   if (budget.limit === null) return null;
   const percent = usagePercent(budget.used, budget.limit);
   const tone =
-    percent >= 100
-      ? 'bg-red-500'
-      : percent >= 80
-        ? 'bg-amber-500'
-        : 'bg-[#7D54D1]';
+    percent >= 100 ? 'destructive' : percent >= 80 ? 'warning' : 'default';
   return (
     <div className="min-w-48 flex-1">
       <div className="flex items-baseline justify-between gap-3 text-sm">
@@ -43,19 +40,16 @@ function Meter({
           })}
         </span>
       </div>
-      <div
-        className="bg-muted mt-1 h-1.5 w-full overflow-hidden rounded-full"
-        role="progressbar"
+      <Progress
+        size="sm"
+        variant={tone}
+        value={percent}
+        className="mt-1"
         aria-label={label}
         aria-valuemin={0}
         aria-valuemax={100}
         aria-valuenow={Math.round(percent)}
-      >
-        <div
-          className={`h-full rounded-full ${tone}`}
-          style={{ width: `${percent}%` }}
-        />
-      </div>
+      />
     </div>
   );
 }
diff --git a/frontend/src/settings/foldSeries.test.ts b/frontend/src/settings/foldSeries.test.ts
new file mode 100644
index 00000000..8f12d7f2
--- /dev/null
+++ b/frontend/src/settings/foldSeries.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import { foldSeries, OTHER_SERIES_KEY } from './foldSeries';
+
+const day = (a: number, b: number) => ({ '2026-09-22': a, '2026-09-23': b });
+
+describe('foldSeries', () => {
+  it('keeps five or fewer series as they are, in order', () => {
+    const entries: [string, Record<string, number>][] = [
+      ['gpt-4.1', day(1, 1)],
+      ['claude-sonnet-4-5', day(9, 9)],
+    ];
+    expect(foldSeries(entries)).toEqual(entries);
+  });
+
+  it('keeps the four largest series and sums the rest into Other', () => {
+    const entries: [string, Record<string, number>][] = [
+      ['a', day(1, 0)],
+      ['b', day(50, 50)],
+      ['c', day(2, 3)],
+      ['d', day(40, 40)],
+      ['e', day(30, 30)],
+      ['f', day(20, 25)],
+      ['g', day(4, 1)],
+    ];
+    const folded = foldSeries(entries);
+    expect(folded.map(([key]) => key)).toEqual([
+      'b',
+      'd',
+      'e',
+      'f',
+      OTHER_SERIES_KEY,
+    ]);
+    // a + c + g, per day.
+    expect(folded[4][1]).toEqual({ '2026-09-22': 7, '2026-09-23': 4 });
+  });
+
+  it('treats a missing day in a folded series as zero', () => {
+    const entries: [string, Record<string, number>][] = [
+      ['a', day(10, 10)],
+      ['b', day(10, 10)],
+      ['c', day(10, 10)],
+      ['d', day(10, 10)],
+      ['e', { '2026-09-22': 1 }],
+      ['f', day(2, 2)],
+    ];
+    expect(foldSeries(entries)[4][1]).toEqual({
+      '2026-09-22': 3,
+      '2026-09-23': 2,
+    });
+  });
+
+  it('lists Other buckets in the first series order, which the axis uses', () => {
+    const entries: [string, Record<string, number>][] = [
+      ['a', { d1: 9, d2: 9, d3: 9 }],
+      ['b', { d1: 9, d2: 9, d3: 9 }],
+      ['c', { d1: 9, d2: 9, d3: 9 }],
+      ['d', { d1: 9, d2: 9, d3: 9 }],
+      ['e', { d3: 1, d1: 2 }],
+      ['f', { d2: 4 }],
+    ];
+    expect(Object.keys(foldSeries(entries)[4][1])).toEqual(['d1', 'd2', 'd3']);
+  });
+});
diff --git a/frontend/src/settings/foldSeries.ts b/frontend/src/settings/foldSeries.ts
new file mode 100644
index 00000000..f7a64b4d
--- /dev/null
+++ b/frontend/src/settings/foldSeries.ts
@@ -0,0 +1,51 @@
+/** Key of the synthetic series that sums everything past the chart's colours. */
+export const OTHER_SERIES_KEY = '__other__';
+
+/** DESIGN.md: charts have five series colours, `chart-1` to `chart-5`. */
+const MAX_SERIES = 5;
+
+type SeriesEntry = [string, Record<string, number>];
+
+const total = (series: Record<string, number>): number =>
+  Object.values(series).reduce((sum, value) => sum + (value || 0), 0);
+
+/**
+ * Fit series with no meaning (models, agents, sources) into the five chart
+ * colours without repeating one.
+ *
+ * Five or fewer series are returned unchanged. With more, the four largest
+ * by total keep their original order and everything else is summed, bucket
+ * by bucket, into one {@link OTHER_SERIES_KEY} series at the end, which the
+ * chart draws in `chart-5`.
+ *
+ * @param entries Series as `[key, {bucket: value}]`, in server order.
+ * @returns The series to draw, at most five.
+ */
+export function foldSeries(entries: SeriesEntry[]): SeriesEntry[] {
+  if (entries.length <= MAX_SERIES) return entries;
+
+  const keep = new Set(
+    [...entries]
+      .sort((a, b) => total(b[1]) - total(a[1]))
+      .slice(0, MAX_SERIES - 1)
+      .map(([key]) => key),
+  );
+
+  // Bucket order follows the first series (the chart's axis labels), then any
+  // bucket only a later series reports, so Object.values lines up.
+  const other: Record<string, number> = {};
+  for (const [, series] of entries) {
+    for (const bucket of Object.keys(series)) other[bucket] ??= 0;
+  }
+  for (const [key, series] of entries) {
+    if (keep.has(key)) continue;
+    for (const [bucket, value] of Object.entries(series)) {
+      other[bucket] += value || 0;
+    }
+  }
+
+  return [
+    ...entries.filter(([key]) => keep.has(key)),
+    [OTHER_SERIES_KEY, other],
+  ];
+}
diff --git a/frontend/src/store.ts b/frontend/src/store.ts
index c9a72491..429eb5cd 100644
--- a/frontend/src/store.ts
+++ b/frontend/src/store.ts
@@ -8,6 +8,7 @@ import {
   conversationSlice,
 } from './conversation/conversationSlice';
 import { sharedConversationSlice } from './conversation/sharedConversationSlice';
+import actionToastReducer from './notifications/actionToastSlice';
 import notificationsReducer from './notifications/notificationsSlice';
 import { getStoredRecentDocs } from './preferences/preferenceApi';
 import {
@@ -70,6 +71,7 @@ const store = configureStore({
     agentPreview: agentPreviewReducer,
     workflowPreview: workflowPreviewReducer,
     notifications: notificationsReducer,
+    actionToast: actionToastReducer,
     schedules: schedulesReducer,
     teams: teamsReducer,
     graphBuild: graphBuildReducer,
diff --git a/frontend/src/teams/ShareToTeamModal.tsx b/frontend/src/teams/ShareToTeamModal.tsx
index 49ac442b..c18f0137 100644
--- a/frontend/src/teams/ShareToTeamModal.tsx
+++ b/frontend/src/teams/ShareToTeamModal.tsx
@@ -417,7 +417,7 @@ export default function ShareToTeamModal({
             variant="ghost"
             size="sm"
             disabled={rowBusy}
-            className="shrink-0 gap-1 px-2 font-normal"
+            className="shrink-0"
             aria-label={t('settings.teams.share.access')}
           >
             {t(`settings.teams.share.accessLevel.${share.access_level}`)}
@@ -465,10 +465,9 @@ export default function ShareToTeamModal({
       <li key={shareKey(share)} className="flex items-center gap-3 py-2">
         <Avatar
           alt=""
-          className={cn(
-            'bg-primary/10 text-primary dark:bg-primary/20 flex size-9 items-center justify-center text-sm font-medium',
-            isTeam ? 'rounded-md' : 'rounded-full',
-          )}
+          variant="primary"
+          size="lg"
+          shape={isTeam ? 'square' : 'circle'}
         >
           {initialOf(primary)}
         </Avatar>
@@ -529,11 +528,12 @@ export default function ShareToTeamModal({
               <PopoverTrigger asChild>
                 <Button
                   type="button"
-                  variant="outline"
+                  variant="combobox"
                   role="combobox"
                   aria-expanded={pickerOpen}
                   disabled={committing}
-                  className="text-muted-foreground h-9 min-w-0 flex-1 justify-start gap-2 px-3 font-normal"
+                  data-placeholder=""
+                  className="min-w-0 flex-1 justify-start"
                 >
                   <span className="truncate">
                     {t('settings.teams.share.addPlaceholder')}
@@ -566,11 +566,12 @@ export default function ShareToTeamModal({
                             key={suggestion.key}
                             value={suggestion.key}
                             onSelect={() => commitSuggestion(suggestion)}
-                            className="gap-3"
                           >
                             <Avatar
                               alt=""
-                              className="bg-primary/10 text-primary dark:bg-primary/20 flex size-7 items-center justify-center rounded-md text-xs font-medium"
+                              variant="primary"
+                              size="sm"
+                              shape="square"
                             >
                               {initialOf(suggestion.teamName)}
                             </Avatar>
@@ -591,11 +592,12 @@ export default function ShareToTeamModal({
                               key={suggestion.key}
                               value={`${suggestion.key} ${suggestion.label} ${suggestion.teamName}`}
                               onSelect={() => commitSuggestion(suggestion)}
-                              className="gap-3"
                             >
                               <Avatar
                                 alt=""
-                                className="bg-primary/10 text-primary dark:bg-primary/20 flex size-7 items-center justify-center rounded-full text-xs font-medium"
+                                variant="primary"
+                                size="sm"
+                                shape="circle"
                               >
                                 {initialOf(suggestion.label)}
                               </Avatar>
@@ -646,10 +648,7 @@ export default function ShareToTeamModal({
             <ul className="mt-1 max-h-72 overflow-auto">
               {/* Owner — pinned, non-interactive. */}
               <li className="flex items-center gap-3 py-2">
-                <Avatar
-                  alt=""
-                  className="bg-primary/10 text-primary dark:bg-primary/20 flex size-9 items-center justify-center rounded-full text-sm font-medium"
-                >
+                <Avatar alt="" variant="primary" size="lg" shape="circle">
                   {initialOf(t('settings.teams.share.you'))}
                 </Avatar>
                 <div className="min-w-0 flex-1">
diff --git a/frontend/src/teams/TeamSwitcher.tsx b/frontend/src/teams/TeamSwitcher.tsx
index 4c1fa533..de658f19 100644
--- a/frontend/src/teams/TeamSwitcher.tsx
+++ b/frontend/src/teams/TeamSwitcher.tsx
@@ -169,22 +169,24 @@ export default function TeamSwitcher({
         )}
       </DropdownMenuTrigger>
       <DropdownMenuContent align="start" className="w-62">
-        <DropdownMenuLabel className="flex items-center gap-2">
-          <span className="bg-muted dark:bg-accent flex size-7 shrink-0 items-center justify-center rounded-md">
-            {currentTeam ? (
-              <Users className="size-4" strokeWidth={1.75} />
-            ) : (
-              <User className="size-4" strokeWidth={1.75} />
-            )}
-          </span>
-          <span className="min-w-0 flex-1">
-            <span className="text-foreground block truncate text-sm font-semibold">
-              {currentName}
+        <DropdownMenuLabel>
+          <div className="flex items-center gap-2">
+            <span className="bg-muted dark:bg-accent flex size-7 shrink-0 items-center justify-center rounded-md">
+              {currentTeam ? (
+                <Users className="size-4" strokeWidth={1.75} />
+              ) : (
+                <User className="size-4" strokeWidth={1.75} />
+              )}
             </span>
-            <span className="text-muted-foreground block truncate text-xs font-normal">
-              {currentRoleLabel}
+            <span className="min-w-0 flex-1">
+              <span className="text-foreground block truncate text-sm font-semibold">
+                {currentName}
+              </span>
+              <span className="text-muted-foreground block truncate text-xs font-normal">
+                {currentRoleLabel}
+              </span>
             </span>
-          </span>
+          </div>
         </DropdownMenuLabel>
 
         {currentTeam && (
diff --git a/frontend/src/upload/Upload.test.tsx b/frontend/src/upload/Upload.test.tsx
new file mode 100644
index 00000000..f7ff6c36
--- /dev/null
+++ b/frontend/src/upload/Upload.test.tsx
@@ -0,0 +1,101 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock('react-redux', () => ({
+  useSelector: () => null,
+  useDispatch: () => vi.fn(),
+  useStore: () => ({ getState: () => ({}) }),
+}));
+
+vi.mock('../api/services/userService', () => ({
+  default: {
+    getConfig: () => Promise.resolve({ json: () => Promise.resolve({}) }),
+  },
+}));
+
+import Upload from './Upload';
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+describe('Upload source-type tiles', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => root.unmount());
+    container.remove();
+  });
+
+  const render = async () => {
+    await act(async () => {
+      root.render(
+        <Upload
+          receivedFile={[]}
+          setModalState={vi.fn()}
+          isOnboarding={false}
+          renderTab={null}
+          close={vi.fn()}
+        />,
+      );
+    });
+  };
+
+  const tiles = () =>
+    Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>(
+        '[data-slot="option-card"]',
+      ),
+    );
+
+  it('renders each source type as a button tile', async () => {
+    await render();
+    const found = tiles();
+    expect(found.length).toBeGreaterThan(0);
+    for (const tile of found) {
+      expect(tile.tagName).toBe('BUTTON');
+      expect(tile.getAttribute('type')).toBe('button');
+    }
+    const crawler = found.find((tile) =>
+      tile.textContent?.includes('modals.uploadDoc.ingestors.crawler.label'),
+    );
+    expect(crawler).toBeDefined();
+    expect(crawler!.querySelector('img')?.className).toContain('size-6');
+  });
+
+  it('selects the clicked source type', async () => {
+    await render();
+    const crawler = tiles().find((tile) =>
+      tile.textContent?.includes('modals.uploadDoc.ingestors.crawler.label'),
+    )!;
+    await act(async () => crawler.click());
+    expect(tiles()).toHaveLength(0);
+    expect(document.body.textContent).toContain(
+      'modals.uploadDoc.ingestors.crawler.heading',
+    );
+  });
+
+  it('leaves the disabled Train button on the default variant', async () => {
+    await render();
+    const crawler = tiles().find((tile) =>
+      tile.textContent?.includes('modals.uploadDoc.ingestors.crawler.label'),
+    )!;
+    await act(async () => crawler.click());
+    const train = Array.from(
+      document.body.querySelectorAll<HTMLButtonElement>('button'),
+    ).find((b) => b.textContent === 'modals.uploadDoc.train');
+    expect(train).toBeDefined();
+    expect(train!.disabled).toBe(true);
+    expect(train!.className).not.toContain('bg-gray-300');
+    expect(train!.className).toContain('bg-primary');
+  });
+});
diff --git a/frontend/src/upload/Upload.tsx b/frontend/src/upload/Upload.tsx
index dc4989a9..75a85d32 100644
--- a/frontend/src/upload/Upload.tsx
+++ b/frontend/src/upload/Upload.tsx
@@ -22,6 +22,7 @@ import {
 } from '../components/ui/select';
 import { Switch } from '../components/ui/switch';
 import { Modal } from '../components/ui/modal';
+import { OptionCard } from '../components/ui/option-card';
 import { ActiveState, Doc } from '../models/misc';
 
 import { getDocs } from '../preferences/preferenceApi';
@@ -151,7 +152,7 @@ function Upload({
             }`}
           >
             <div className="flex flex-col gap-4 overflow-hidden">
-              <hr className="my-4 border border-[#C4C4C4]/40" />
+              <hr className="border-border my-4 border" />
               <div className="flex flex-col gap-4">
                 {advancedFields.map((field: FormField) => renderField(field))}
               </div>
@@ -182,7 +183,6 @@ function Upload({
               )
             }
             required={isRequired}
-            labelBgClassName="bg-card"
           />
         );
       case 'number':
@@ -202,7 +202,6 @@ function Upload({
               )
             }
             required={isRequired}
-            labelBgClassName="bg-card"
           />
         );
       case 'enum': {
@@ -220,10 +219,7 @@ function Upload({
               );
             }}
           >
-            <SelectTrigger
-              className="w-full rounded-3xl px-5 py-3 text-sm"
-              size="lg"
-            >
+            <SelectTrigger className="w-full" size="lg" shape="pill">
               <SelectValue placeholder={field.label} />
             </SelectTrigger>
             <SelectContent>
@@ -291,7 +287,7 @@ function Upload({
         return (
           <div key={field.name}>
             <div className="mb-3" {...getRootProps()}>
-              <span className="text-primary dark:text-muted-foreground inline-block rounded-3xl border border-[#7F7F82] bg-transparent px-4 py-2 font-medium hover:cursor-pointer">
+              <span className="text-primary dark:text-muted-foreground border-border inline-block rounded-3xl border bg-transparent px-4 py-2 font-medium hover:cursor-pointer">
                 <input type="button" {...getInputProps()} />
                 {t('modals.uploadDoc.choose')}
               </span>
@@ -1026,30 +1022,20 @@ function Upload({
     return (
       <div className="grid w-full grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3">
         {ingestorOptions.map((option) => (
-          <div
+          <OptionCard
             key={option.value}
-            className={`relative mx-auto flex h-[91.2px] w-full cursor-pointer flex-col justify-between gap-2 rounded-2xl border border-solid pt-[21.1px] pr-[21px] pb-[15px] pl-[21px] transition-colors duration-300 ease-out ${
-              ingestor.type === option.value
-                ? 'border-primary bg-primary text-white'
-                : 'border-border hover:bg-accent/30 dark:border-border/30 bg-transparent transition-shadow duration-300 hover:shadow-[0_0_15px_0_#00000026]'
-            }`}
+            icon={
+              <img
+                src={option.icon}
+                alt={option.label}
+                className="size-6 dark:invert"
+              />
+            }
+            title={t(`modals.uploadDoc.ingestors.${option.value}.label`)}
             onClick={() =>
               handleIngestorTypeChange(option.value as IngestorType)
             }
-          >
-            <div className="flex h-full flex-col justify-between">
-              <div className="h-6 w-6">
-                <img
-                  src={option.icon}
-                  alt={option.label}
-                  className={`${ingestor.type === option.value ? 'invert filter' : ''} dark:invert dark:filter`}
-                />
-              </div>
-              <p className="self-start text-sm leading-[18px] font-semibold">
-                {t(`modals.uploadDoc.ingestors.${option.value}.label`)}
-              </p>
-            </div>
-          </div>
+          />
         ))}
       </div>
     );
@@ -1067,7 +1053,7 @@ function Upload({
     >
       <div className="flex w-full flex-col gap-6">
         {!ingestor.type && (
-          <p className="text-foreground dark:text-foreground text-left text-xl leading-7 font-semibold tracking-[0.15px]">
+          <p className="text-foreground dark:text-foreground text-left text-xl leading-7 font-semibold">
             {t('modals.uploadDoc.selectSource')}
           </p>
         )}
@@ -1079,9 +1065,10 @@ function Upload({
               <div className="flex flex-col gap-4">
                 <Button
                   type="button"
-                  variant="ghost"
+                  variant="ghost-muted"
+                  size="sm"
                   onClick={() => handleIngestorTypeChange(null)}
-                  className="h-auto w-fit gap-2 px-0 py-0 text-[#777777] hover:bg-transparent hover:text-[#555555]"
+                  className="-ml-3 w-fit justify-start"
                 >
                   <img
                     src={ChevronRight}
@@ -1091,7 +1078,7 @@ function Upload({
                   <span>{t('modals.uploadDoc.back')}</span>
                 </Button>
 
-                <h2 className="text-foreground text-2xl leading-7 font-semibold tracking-[0.15px]">
+                <h2 className="text-foreground text-2xl leading-7 font-semibold">
                   {ingestor.type &&
                     t(`modals.uploadDoc.ingestors.${ingestor.type}.heading`)}
                 </h2>
@@ -1108,7 +1095,6 @@ function Upload({
                   }}
                   label={t('modals.uploadDoc.name')}
                   required={true}
-                  labelBgClassName="bg-card"
                   className="w-full"
                 />
                 {renderFormFields()}
@@ -1131,8 +1117,9 @@ function Upload({
                 <Button
                   type="button"
                   variant="link"
+                  size="sm"
                   onClick={() => setShowAdvancedOptions(!showAdvancedOptions)}
-                  className="h-auto w-fit justify-start px-0 py-2 text-sm font-normal hover:no-underline"
+                  className="-ml-3 w-fit justify-start"
                 >
                   {showAdvancedOptions
                     ? t('modals.uploadDoc.hideAdvanced')
@@ -1147,11 +1134,7 @@ function Upload({
               type="button"
               onClick={handleUpload}
               disabled={isUploadDisabled()}
-              className={`h-auto rounded-3xl px-4 py-2 text-sm font-medium ${
-                isUploadDisabled()
-                  ? 'dark:bg-muted dark:text-muted-foreground bg-gray-300 text-gray-500'
-                  : ''
-              }`}
+              shape="pill"
             >
               {ingestor.type === 'wiki'
                 ? t('modals.uploadDoc.create')
diff --git a/frontend/src/utils/httpMethodColors.test.ts b/frontend/src/utils/httpMethodColors.test.ts
new file mode 100644
index 00000000..8813c2c5
--- /dev/null
+++ b/frontend/src/utils/httpMethodColors.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { getMethodBadgeVariant } from './httpMethodColors';
+
+describe('getMethodBadgeVariant', () => {
+  it('maps each HTTP method to a Badge variant by meaning', () => {
+    expect(getMethodBadgeVariant('GET')).toBe('success');
+    expect(getMethodBadgeVariant('POST')).toBe('info');
+    expect(getMethodBadgeVariant('PUT')).toBe('warning');
+    expect(getMethodBadgeVariant('DELETE')).toBe('destructive');
+    expect(getMethodBadgeVariant('PATCH')).toBe('default');
+    expect(getMethodBadgeVariant('HEAD')).toBe('neutral');
+    expect(getMethodBadgeVariant('OPTIONS')).toBe('neutral');
+  });
+
+  it('ignores case', () => {
+    expect(getMethodBadgeVariant('get')).toBe('success');
+    expect(getMethodBadgeVariant('Delete')).toBe('destructive');
+  });
+
+  it('falls back to neutral for an unknown method', () => {
+    expect(getMethodBadgeVariant('TRACE')).toBe('neutral');
+  });
+});
diff --git a/frontend/src/utils/httpMethodColors.ts b/frontend/src/utils/httpMethodColors.ts
index 424b3074..e2b4c9c8 100644
--- a/frontend/src/utils/httpMethodColors.ts
+++ b/frontend/src/utils/httpMethodColors.ts
@@ -1,15 +1,24 @@
-const METHOD_COLORS: Record<string, string> = {
-  GET: 'bg-[#D1FAE5] text-[#065F46] dark:bg-[#064E3B]/60 dark:text-[#6EE7B7]',
-  POST: 'bg-[#DBEAFE] text-[#1E40AF] dark:bg-[#1E3A8A]/60 dark:text-[#93C5FD]',
-  PUT: 'bg-[#FEF3C7] text-[#92400E] dark:bg-[#78350F]/60 dark:text-[#FCD34D]',
-  DELETE:
-    'bg-[#FEE2E2] text-[#991B1B] dark:bg-[#7F1D1D]/60 dark:text-[#FCA5A5]',
-  PATCH: 'bg-[#EDE9FE] text-[#5B21B6] dark:bg-[#4C1D95]/60 dark:text-[#C4B5FD]',
-  HEAD: 'bg-[#F3F4F6] text-[#374151] dark:bg-[#374151]/60 dark:text-[#D1D5DB]',
-  OPTIONS:
-    'bg-[#F3F4F6] text-[#374151] dark:bg-[#374151]/60 dark:text-[#D1D5DB]',
+type MethodBadgeVariant =
+  'default' | 'neutral' | 'success' | 'warning' | 'destructive' | 'info';
+
+// Reads, writes, replaces and deletes take the status tokens that match
+// their weight; PATCH is the brand tint, and the rest are neutral.
+const METHOD_VARIANTS: Record<string, MethodBadgeVariant> = {
+  GET: 'success',
+  POST: 'info',
+  PUT: 'warning',
+  DELETE: 'destructive',
+  PATCH: 'default',
+  HEAD: 'neutral',
+  OPTIONS: 'neutral',
 };
 
-export function getMethodColorClass(method: string): string {
-  return METHOD_COLORS[method.toUpperCase()] ?? METHOD_COLORS.GET;
+/**
+ * The `Badge` variant for an HTTP method pill.
+ *
+ * @param method - The HTTP method, in any case.
+ * @returns The variant for `<Badge>`; `neutral` for an unknown method.
+ */
+export function getMethodBadgeVariant(method: string): MethodBadgeVariant {
+  return METHOD_VARIANTS[method.toUpperCase()] ?? 'neutral';
 }