Surface system#

The UI splits into two surface contexts. Each surface has its own interaction language so the eye can tell at a glance which "layer" of the app it is hovering: navigation vs content. These rules apply in light and dark themes. Light-theme tokens are the ones that usually go wrong (white fill on a pale rail).

The two surfaces#

─────────────────────────────────────────────────────────────────
surface        background tone           where it lives
─────────────────────────────────────────────────────────────────
deep           `--bg-secondary`          the page behind the
                                         three columns (`.app`)
─────────────────────────────────────────────────────────────────
panel          raised cards:             the left and right rails
               `--bg-input` (rails),     (`--bg-input`, same
               `--bg-primary` (centre)   material as the input
                                         box) and the centre
                                         column (`--bg-primary`:
                                         chat stream, settings
                                         and every other page)
─────────────────────────────────────────────────────────────────

The window is three floating cards on one page — the shadcn Sidebar floating shell for both rails (components/ui/sidebar.tsx, the registry's shell only) and its inset idea for the centre column at once. Each card has 14px corners (rounded-2xl) and the per-theme raised shadow (--composer-shadow), no border and no ring; the rails keep a 7px gutter on every side (p-2), the centre card sits 7px off the top and bottom edges and takes its side gaps from the rails' gutters. The rails are white (--bg-input) so they share a material with the input box and the user bubble; the centre card stays --bg-primary so those white raised elements keep their contrast on it.

In a split layout the centre card dissolves and every pane is its own card of the same material (.center-col[data-split]): each pane keeps 7px to the rail cards and the window edges, and the panes sit 8px apart. Empty panes draw the same card themselves.

Collapsed, a rail is --rail-collapsed-w (63px: the 49px icon rail inside the card plus the two gutters); components/layout/use-resizable-rail.ts carries the same number. Everything inside the cards — rows, section headers, the footer — is unchanged by the shell and keeps the recipes below.

Interaction language per surface#

Mouse interaction never draws an outer focus ring on buttons. Keyboard focus on buttons uses a small brightness change without an outline or box-shadow. The top tab strip is the exception: its role="tab" targets use each theme's own --focus-ring, which is lighter in dark themes and darker in light themes.

Deep surface (sidebars)#

Components on the deep surface are list rows — conversation items, branch entries, function favourites, and the same row used in a content-pane rail (MCP drawio / linear / + Add server). They should NOT behave like buttons:

• no border, no outline, no fill in the idle state
• hover / selected → switch background to a visible grey (--bg-hover / --bg-selected), text stays in --text-primary or --text-secondary
• never fill selected rows with --bg-input. The rail card is already that white; a white row on it disappears
• avoid the brand-coloured glyph treatment except for the very small status / activity indicators (.indicator-dot)

Rationale: the sidebar is dense and frequently scanned. A field of brand-coloured pills makes it loud and visually competes with the content column. Greying-on-hover keeps the layer calm and still gives the click target enough feedback.

Panel surface (chat content + dialogs)#

Components on the panel surface ARE buttons / pills / cards:

• they sit on a lifted background, so a "ghost outline" pattern reads cleanly
• idle state — --bg-surface background, --text-primary text or brand-coloured text for primary actions
• hover — fill with the brand colour, swap text to its contrast pair (--text-on-accent)
• the inverted hover is what makes the chain of "actions" feel like one design family — the user knows that the colour shift is universally the "this is going to do something" affordance

Header tab pills on a manage page (Abilities / Programs / Plugins / Skills) are the one bright exception: the selected tab uses --bg-input so it reads like the search box (lighter, not darker). That fill is only for those pills. Do not copy it onto sidebar rows or MCP server rows.

One list-row recipe#

Sidebar nav (+ New chat, Agents, Abilities, History, Scheduler) and content-pane list rows (MCP drawio / linear / + Add server) share one box. Do not invent a second height, padding, radius, or selected fill for the rail on the right.

property     token / value
─────────────────────────────────────────────────────────────────
height       `--ui-list-h` → `--ui-button-h` → 30px
padding      6px 8px
gap          12px
radius       `--ui-list-radius` (10px)
idle         transparent, 1px transparent border if needed for
             box-sizing only
hover        `--bg-hover`
selected     `--bg-hover`  (same grey, never white / `--bg-input`)

+ Add server is the same row as + New chat: a normal list row, slightly muted text. Not italic, not a different add-style.

Implementation: .ui-list-item in apps/web/app/styles/base.css is the source. MCP .serverItem must match those metrics (prefer composing .ui-list-item over a parallel recipe).

Size system — list rows and Buttons#

List rows keep one fixed set. CSS variables in apps/web/app/styles/base.css:

set         height    radius    css tokens
─────────────────────────────────────────────────────────────────
list        30 px     10 px     --ui-list-h · --ui-list-radius
─────────────────────────────────────────────────────────────────

Sidebar rows, MCP tab pills, and MCP server rows all sit on this 30px rhythm. There is no sm / md / lg ladder for list rows: when one slot may pick from several sizes, every author negotiates with the design and the sizes drift apart.

Buttons are the shadcn/ui Button in the radix-luma style. apps/web/components/ui/button.tsx is copied verbatim from the official registry (npx shadcn add button, style radix-luma); the only local changes are its imports and a forwardRef wrapper for React 18. Every size is a pill (rounded-4xl); the call site picks one of the official sizes and never edits the classes.

The sizes are rem-based and this app's root font size is 14px (html { font-size: 14px } in base.css, which ~560 existing utilities are tuned to), so every shadcn size renders at 7/8 of its nominal value:

size        app height  app text   use
─────────────────────────────────────────────────────────────────
xs          21 px       10.5 px    avoid — text is too small here
sm          28 px       12.25 px   chips and compact control rows
default     31.5 px     12.25 px   dialog and settings actions
lg          35 px       12.25 px   hero / empty-state actions
icon-sm/default/lg                 square = circle at those heights
─────────────────────────────────────────────────────────────────

Elements that cannot be a <Button> (a span that hosts its own ✕, a Radix trigger rendered as a span) take the same look through cn(buttonVariants({ variant, size })) on their className — the cn() merge matters: the raw class list carries both border-transparent and the variant's border colour.

A header row (search + tab pills + icon buttons) must share one vertical center. A 1–2 px height mismatch between those controls is a bug, not a variant.

Inputs, selects, and borders#

Inputs and dropdowns share one single-layer 1px edge (border: 1px solid var(--border), fill --bg-input).

• Do not stack a 2px :focus-visible halo on that 1px edge. After a native <select> closes and focus remains, the stacked ring reads as a double frame.
• Hover must keep the 1px border. Setting border-color: transparent on hover makes the box look like it vanished (MCP catalog buttons had this).
• Do not invent a second input chrome per page. Settings, dialogs, plugins, and MCP editors use the same 1px + --bg-input treatment.

Dialogs#

Dialogs fade in and out only (about 300ms). No slide from the top, no snap-close. Motion is opacity, not translate.

Settings rows#

Settings pages (General, Memory, System, and the rest) use one two-column row:

• left: name, left-aligned. Description stays in this column and does not run into the control
• right: the control / value, right-aligned
• left and right are isolated columns. Do not stack the label above the input
• status chips (LIVE, NEXT START, …) sit to the left of their control, never mixed left/right across rows

Button variant guidance#

The variants are shadcn's, plus one app-owned elevated; colours come from the shadcn tokens (--primary, --secondary, --muted, --input, --ring, …), which apps/web/app/globals.css bridges onto each theme's palette — so every theme restyles Buttons without touching them.

variant      idle                                 hover
─────────────────────────────────────────────────────────────────
default      bg-primary + primary-foreground      bg-primary/80
outline      1px border-border; transparent        bg-muted (light),
             in dark, bg-background in light       bg-input/30 (dark)
secondary    bg-secondary                         secondary + 5% ink
elevated     --bg-input, no border, shadow-sm      shadow-md, + 5% ink
ghost        transparent                          bg-muted (/50 dark)
destructive  bg-destructive/10 + destructive text bg-destructive/20
link         primary text                         underline
─────────────────────────────────────────────────────────────────

All variants press down 1px while active, show a 3px ring/30 halo on keyboard focus, and drop to 50% opacity when disabled.

elevated is the one variant Luma's registry does not have: Luma ships no shadowed Button (only its Card carries shadow-md), and the composer's pills want the same borderless raised look as the input box. It reuses the per-theme composer shadow pair through the shadow-raised / shadow-raised-hover utilities declared in app/globals.css @theme, so the pills and the box lift together in every theme.

Pick per surface:

• Primary action (Run, Save, Test, Apply, Send) → default.
• Secondary action (Cancel, Close, Reset, Browse) → outline or secondary.
• Controls in a dense row (the composer's model / effort / permission triggers, icon toggles, environment chips) → elevated: no border, lifted off the page by the same shadow as the input box, a step deeper on hover.
• Purely incidental actions that should vanish until hovered → ghost.
• Destructive (Delete, Remove, Stop) → destructive.
• Deep surface — sidebar rows → don't use the Button primitive. Use .ui-list-item / nav-classes.ts.

Composer controls#

The chat composer is built from the same parts:

• Environment chips above the box (channel, web surface, project, working folders, DAG HUD) → elevated sm; the add-folder chip is elevated icon-sm.
• Bottom row (permission, chat / exec model, effort, plus, tool toggles, context ring) → elevated, sm / icon-sm. The composer CSS hands its older base rules back to the Button with revert-layer rather than drawing its own chip.
• Send → icon-sm: default when there is something to send, ghost when empty, destructive while it stops a run.
• Input box → the shadcn Luma Card look through the per-theme --composer-* tokens: --bg-input surface with no border, shadow-sm at rest and shadow-md on hover or focus (shadow alpha 0.1 on light themes, 0.25 on dark), no focus ring; 23px corners (a pill at one line).

Web page preview and browser toolbar#

The floating page preview over chat (components/center-tabs/web-tab-pip.tsx) is a popover card: bg-popover, ring-1 ring-foreground/10 in place of a border, shadow-lg, 10px corners on all four sides, and the stage below the header clips the page at the same bottom radius. The radius is pinned to the native page view's corner radius (apps/desktop/main/web-views.js), which the DOM cannot clip: a larger frame radius would let page pixels show past the bottom corners, so the two change together or not at all. The 32px header holds the title (text-sm font-medium text-foreground), the status (text-xs text-muted-foreground), and ghost icon-xs icon buttons with 14px icons whose hover tips are HoverTip + TipBody (hover-tips.md); a resume error is one line of text-xs text-destructive, no box. The CSS module keeps geometry only (position, size, drag cursor, resize handles), because unlayered module rules would beat the utilities.

The browser toolbar's icon buttons (back / forward / reload / home / bookmark / library / open in browser / menu, and the control bar) are the same ghost Button through webToolbarButton() (components/center-tabs/toolbar-button.ts): icon-sm for its 14px icon rule, held at the toolbar's 26px by .webToolbarBtn, which carries geometry only, so the 40px row keeps its rhythm.

Don'ts#

• Don't invent a new hover / selected / border treatment per page. One recipe, then reuse it. A new look needs a line in this file first.
• Don't introduce a new pill background colour without listing it here first. Flavours in budget: deep grey hover, panel, brand fill, and the header-tab --bg-input exception above.
• Don't put brand-coloured fills on the deep surface — the contrast against the rail makes a brand pill look like an alert, not a click target.
• Don't use white / --bg-input as the selected fill on sidebar or content-pane list rows. Light theme washes out.
• Don't give MCP server rows (or any other content-pane list) a different height, padding, or selected fill than sidebar nav.
• Don't add hover motion (translate-y, scale-105) on either surface. Hover swaps the background; the only motion is the Button's own 1px press while active.
• Don't edit the official classes in components/ui/button.tsx (elevated is the one app-owned variant) or restate a Button lookalike in CSS. Pick a variant / size; if a legacy rule still overrides a Button, remove it or hand it back with revert-layer.
• Don't stack a 2px focus glow on a 1px input/select edge.
• Don't drop a control's 1px border on hover.
• Don't slide dialogs. Fade only.
• Don't let a settings description overflow into the right-hand control column, or stack label above control.

Implementation status#

• Done: Button (radix-luma), the composer environment chips, bottom-row controls, send button, input box, the web page preview (frame, header, icon buttons), and the browser toolbar's icon buttons.
• Not yet migrated: popover / menu panels (MENU_PANEL, components/ui/popover.tsx, dropdown-menu.tsx), tooltips, badges, and the hand-styled CSS-module popups — they still use the glass surface tokens (--glass-*). Form inputs and selects keep the 1px-edge rule above until they move to the shadcn input. Sidebar list rows stay on the list set above.