Skip to the content
docs

Styles

Cloudfield was named Aether until November 2026. The commands, paths and hostnames in this guide still use that name. View this guide on GitHub.

Browse guides / Styles

Workbench language

The dashboard is a dense developer workbench on graphite surfaces with one teal accent. Adjoining panes are flat and quiet. Elevation is restrained: cards and secondary buttons carry a light shadow, floating surfaces a deeper one, panes none. Do not add saturated colours, gradients or backdrop blur. The desktop launch splash is an intentional original-animation exception; see Session state and motion.

Surface the common actions

A control nobody can see is a control nobody uses. Put the actions people reach for most on the surface, beside what they act on: a row's main actions are visible buttons on that row, and a value someone changes in place, such as a member's role, is a select in the cell that shows it. Pick a list of checkboxes with a search field over adding items one at a time from a dropdown. Keep the overflow menu (Ellipsis) for rare actions, and never make it, or a hover-only control, the only way to a common one. A destructive action may sit on its row as a ghost icon button behind a confirm. A page someone needs often gets its own sidebar row, not a menu item two levels down. When a surface gets crowded, regroup it rather than folding actions into menus.

Type

Fonts ship in the bundle; nothing is fetched from Google.

Face Use Source
DM Sans (variable, Latin subset) All UI text @fontsource-variable/dm-sans, one WOFF2
Saira (variable, Latin subset) text-title only web/public/fonts/saira-latin.woff2
VT323 (Latin subset, 400) Launch-splash wordmark web/public/fonts/vt323-latin.woff2
JetBrainsMono NFM xterm primary font; UI private-use symbols through Aether Nerd Symbols web/public/fonts/jetbrains-mono-nfm-*.woff2
Noto Sans Symbols 2 Braille and geometric symbols through Aether Symbols web/public/fonts/noto-sans-symbols-2-spinners.woff2
ui-monospace, 'SF Mono', Menlo, Consolas, monospace Code, paths and SHAs (font-code), after symbol fallbacks system

DM Sans loads with font-display: swap behind DM Sans Fallback, Arial scaled to DM Sans's metrics to reduce layout shift. Sans, title and code stacks include two symbol-only fallbacks: Aether Symbols covers Geometric Shapes (U+25A0–25FF) and Braille Patterns (U+2800–28FF), including OMP's spinner frames; Aether Nerd Symbols covers the Unicode private-use areas used by agent title icons. The latter reuses the terminal's regular and bold font files. unicode-range keeps both aliases from replacing ordinary text. Other scripts and symbols outside those ranges still use platform fallbacks. The aliases use font-display: swap and load only when a matching character appears; xterm keeps its own full-font family and cell metrics.

The header shows the Cloudfield logo at 32px tall: web/public/cloudfield-logo-small.svg, the c and single-line letters, in the dark theme, and cloudfield-logo-for-light-backgrounds.svg, the c and three-line letters, in the light one; the set has no light single-line file. Where the navigation's destinations do not all fit beside the 162px logo, the 32px cloudfield-favicon.svg tile replaces it, and the navigation still counts 90px, the old brand's width, when it decides what fits, so it collapses at the same widths as before and the spare space falls at the row's empty right end. The launch splash shows cloudfield-mark.svg at clamp(150px, 22vw, 260px) wide, with no glow, above the wordmark: lowercase cloudfield in --font-pixel, in the logo's Cream #f7f0e4, at its original clamp(32px, 4vw, 48px) size and 0.12em letter spacing; other headings stay Saira.

The type scale, in web/src/index.css:

Class Size / line height Use
text-ui-xs 11/16 Dense meta
text-ui-sm 12/16 Supporting copy, section labels
text-ui 13/20 Default UI text; the body is 13px
text-prose 14/22 Agent prose and rendered markdown
text-title 16/24, Saira 600 Pane, dialog, step and empty-state headings
text-stat 24/28, 500 The figure in a StatTile only

text-avatar (10px) is reserved for avatar initials. Settings > General > Text size (Default, Large, Larger) sets data-text-size on the root, which raises every step of the scale and the title size; terminals keep their own zoom.

Weights are 400 and 500, 600 for titles. Times, counts and +a -d use tabular-nums. Labels are sentence case; nothing is uppercase, and no letter-spacing is added. cn() in web/src/lib/utils.ts knows the scale, so cn('text-ui', 'text-muted') keeps both classes. It also knows the radius, shadow, easing, animation and duration names below, so a later rounded-panel replaces rounded-control and animate-none replaces animate-overlay-in. text-title sets its own family and weight; do not pair it with font-* classes.

Semantic palette

web/src/index.css is authoritative: light values sit on :root, dark ones on .dark. The theme preference is dark (the default), light or system; system follows prefers-color-scheme live. A theme stored before the dark default as system, which is how a never-chosen theme was saved, becomes dark; a stored light or dark is kept. An inline script in web/src/app/layout.tsx applies the stored theme before the first paint, so a light device never flashes light. The desktop window and the Android WebView and its launch window start on the dark --canvas for the same reason; Android's system bar icons are light over the dashboard and follow the system theme over the native error and update panels.

Token Utility Light Dark Use
--canvas bg-canvas #ffffff #141516 Main view, fields
--chrome bg-chrome #f7f7f7 #1b1c1d Sidebar, app header, toolbars, code, browser chrome
--hover bg-hover #f3f3f3 #1d1e1f Hovered rows and cards on canvas
--hover-chrome bg-hover-chrome #ececec #262728 Hover on chrome and raised surfaces: sidebar and list rows, menu items, ghost and secondary buttons
--raised bg-raised #ffffff #222324 Floating surfaces, secondary buttons
--seam border-seam black 8% white 8% Every border; the default border colour
--control-border border-control #8a8a8a #767676 Fields, checkboxes, radios
--scrim bg-scrim black 56% black 56% Dialogs and sheets
--scrim-strong bg-scrim-strong black 85% black 85% ACP image viewer
--text text-text #1f1f1f #e8e8e8 Text
--text-muted text-muted #6b6b6b #9a9a9a Placeholders, timestamps, meta
--icon-faint text-icon-faint #8a8a8a #7a7a7a Disabled text, decorative icons, scrollbar thumbs, tree connectors
--accent-fill bg-accent, border-accent #367f77 #367f77 The one primary button, control outline
--focus-ring outline-focus #367f77 #5fb3a8 Keyboard focus ring; 3:1 on every surface and on the selected row in both themes
--accent-text text-accent #306f69 #5fb3a8 Links, accent text
--on-accent text-on-accent #ffffff #ffffff Text on bg-accent
--selection bg-selection #dfebe9 #17413d Selected rows

accent is a fill for backgrounds and borders but the link colour for text; bg-accent-hover darkens the fill for a hovered primary button. The accent marks selection, focus, the one primary button per view, links and the Finished: review state, nothing else. Inside a selected row, secondary text uses text-text. A floating surface is bg-raised, a 1px seam and shadow-overlay; dialogs, the palette and sheets take shadow-dialog and sit over bg-scrim. Geometry lists every shadow.

The session states (see dashboard-frontend.md), used on dots, state lines, badges, callouts and request cards. Finished: review, a reported success awaiting its owner, takes the accent and a filled check circle; it asks nothing, so it is never amber. A subsession's success, which is for its parent agent only, draws the done check in icon-faint (the held tone):

State Utility Light Dark
Needs you state-needs-you #8a5d00 #e0a52a
Working state-working #1b65c2 #4a9eff
Paused state-paused #6e6e6e #8a8a8a
Done state-done #1a7a36 #45c26a
Failed state-failed #c8321f #f05c4a
Finished: review text-accent, bg-accent-soft (review tone) #306f69 #5fb3a8

Each state has a -soft fill (bg-state-failed-soft) at 8% light, 12% dark; bg-accent-soft likewise. text-on-failed is the text on a bg-state-failed fill, and text-on-done on a bg-state-done fill. Diffs use text-diff-add/text-diff-del (the done and failed colours) and bg-diff-add-bg/bg-diff-del-bg at 8% light, 10% dark.

Agent vendor colours (text-agent-claude, -pi, -omp, -cursor, -gemini, -antigravity) appear only on the Agents page, the launch picker and the head of a Board card, through AgentGlyph colored. Codex, OpenCode and Copilot glyphs take text-text there instead: OpenAI, OpenCode and GitHub forbid recolouring their marks.

Member colours are the only arbitrary server data applied inline: avatar rings, the owner rail in session lists, the owner mark on sidebar session rows and member names on conflict chips. Identity colour never replaces run-state colour.

Primitives

web/src/components/ui/ holds the shared primitives: Button, Input, Textarea, Select, Checkbox, Radio, Label, FormField, Menu, Popover, Tooltip, Dialog, AlertDialog, Command, Tabs, SlidingIndicator, Collapsible, Card, ListRow, PageBody, InsetList, PaneHeader, SectionLabel, EmptyState, IconTile, StatTile, Callout, Badge, CountBadge, RadioPills, FadeStrip, RequestCard, StatusDot and StateLine, Avatar, AgentGlyph, Code and CodeBlock, Kbd, Markdown, RelativeTime, Spinner, Skeleton, ProgressBar, DropZone, TextSwap and IconSwap, CopyButton, Toaster, LineGutter (a code line's clickable number gutter, for the Changes view's comments) and the Chat view's timeline rows, step rail (steps.tsx) and blocks. Reach for one before writing markup, and pass its variant, size or tone rather than restyling it.

Button variants:

Variant Look Use
primary (default) bg-accent, text-on-accent The one primary action in a view
secondary Seam border on bg-raised, shadow-button Other actions
ghost Muted text, bg-hover-chrome on hover Toolbar and icon buttons
danger bg-state-failed, text-on-failed Confirming a destructive action
confirm bg-state-done, text-on-done Approve, beside a danger Deny
link Accent text, underline on hover Inline actions that read as links
quiet Muted text; text-text and an underline on hover Inline secondary actions inside muted copy

A secondary button the app suggests, such as a card's approval rule after three approvals of its kind, adds a 2px border-l-accent over bg-accent-soft and a muted line saying why; it never becomes primary or confirm, which stay the card's own Approve.

Sizes are md (28px, the default), sm (24px), icon (28px square), icon-sm (24px square), and the composer's and the Notes field's send control: round (28px circle) and pill (28px, fully rounded); each grows to 44px on a coarse pointer. link and quiet have no height or padding of their own and widen their touch target to 44px. An icon, icon-sm or round button requires label, which becomes its accessible name and tooltip; hint puts a tooltip on any button. Colour, fill, border and shadow fade on the hover tokens. Under a fine pointer every variant but link and quiet presses in to --scale-press (0.97); a finger darkens it instead. Joined buttons and the terminal's hold-to-take control never scale.

The other primitives with motion or a fixed size:

  • Switch is a 28×16px track with a 10px thumb that glides 12px in 150ms (ease-pop, none under reduced motion); on is bg-accent, off a border-control outline with an icon-faint thumb. Use it for a setting that applies at once or for one session, beside its Label.
  • The split New session button is two 28px halves (44px coarse) cut on a forward slash that leans 8px (about 16°) with 3px radii on the cut and 8px on the outer corners, 2px apart; its clip paths come from split-shape.ts, and the focus outline follows the cut. SlideOut (slide-out.tsx) is the surface that slides out of the sidebar edge (220ms, --ease-sheet) for the launch panel and the right half's preview: clipped at that edge, no scrim, shadow-dialog for the panel, shadow-overlay for the preview. With the sidebar hidden or on a phone it slides in from the window edge.
  • Tabs draws one SlidingIndicator per list: the underline look slides a 2px accent bar, the segmented look a bg-raised pill with a seam ring. It follows keyboard selection and stays attached in a scrolling strip. SlidingIndicator serves any other set the same way: items carry data-indicator-key, and the indicator's parent is the positioned container.
  • TextSwap replaces a word in place, the new copy fading in from a 2px blur, and exposes only the incoming copy to assistive technology. Key it by the state word, never by a ticking value. IconSwap does the same for an icon; useTimedFlag in web/src/lib/hooks.ts holds a confirmation such as Copied.
  • RadioPills is a single choice as a row of 28px pills with seam borders, one tab stop: arrows move and select, Home and End select the ends, and the checked pill sits on a SlidingIndicator (bg-hover-chrome, seam ring). A pill may carry a muted count. Memory's filters and kinds use it.
  • FadeStrip scrolls a row sideways with no scrollbar and masks whichever edge hides content over 22px, so the fade matches any surface.
  • CountBadge is an 18px chip of tabular figures; a count changes at once. A group header, the Activity filter and the Agents disclosure carry one, and the count stays in the control's accessible name.
  • PageBody is the centred column of a scrolling page (md 3xl, lg 4xl, xl 6xl), 32px between sections, fading in on arrival. A page that needs a tighter rhythm passes its own gap-*.
  • InsetList is a bordered, divided list that clips its rows to the 12px edge; an InsetListItem is 44px or taller with 12px gutters. With onOpen the row is one button, named by its content, and fills bg-hover on hover.
  • StatTile is a bordered tile: a muted label, the figure in text-stat (compact for a line of words), detail lines and a spark slot pinned to the foot, so tiles of one row align their charts.
  • IconTile is a 28px framed square for a glyph; EmptyState draws its icon in a 32px one above a title that carries no period.
  • ProgressBar is a 4px track whose fill glides to its value. With role="meter" or role="progressbar" it reports value of max; without one it only draws, for a parent that carries the role. With no value the fill is a third of the track sweeping across it (animate-progress-sweep, 1.4s), for work with no known progress; under reduced motion it fills the track at --opacity-muted.
  • DropZone is a dashed rounded-panel button that opens a chooser through onBrowse and takes dragged files through onFiles; its border turns border-control on hover and border-accent over bg-accent-soft while a file drag is over it (data-drag). DropIllustration, its two tilted sheets behind an upload tile, lifts on hover, splays on a drag and bobs the arrow.
  • Kbd is an outlined keycap, 20px (md) or 16px (sm).
  • RequestCard (request-card.tsx) is anything waiting on the viewer: a bg-raised card with a seam border and no shadow. Its header holds a 28px avatar (IconTile for a glyph, or a member Avatar), the title over a muted source line, meta and a StatusDot in the card's tone. A description follows behind a 2px quote bar, indented to the title column once the card is 21rem wide. RequestSection (request-section.tsx) adds a seam-topped region with a muted label and CountBadge; RequestRows shows three rows, then N more, whose rows fade in 30ms apart; a row that opens its detail takes a bg-hover fill on hover. The card's focus outline sits inside its border, so a scrolling parent never clips it, and the Session dock draws the frame on its scroll box so the frame stays closed around the sticky footer. RequestFooter (request-choice.tsx) is the bg-chrome band that sticks to the bottom of a scrolling parent; RequestPills are its 26px How long pills (34px coarse) on a bg-hover-chrome track, the chosen one bg-raised with a seam ring; RequestAction crossfades its label through TextSwap and shows its answer digit as a Kbd on a fine pointer. Answers split a narrow card in halves and sit at their own width on the right of a wide one. RequestTimeBar drains 2px of needs-you toward a deadline. Amber appears only in the dot and that bar; accent only on the primary answer.
  • Spinner draws a ring: a track at --opacity-track under a quarter arc turning every 900ms.
  • Skeleton sweeps a bg-hover-chrome band across bg-chrome. A page that loads shows skeletons shaped like its result, capped at about ten rows, after useDelayed's 200ms.
  • CopyButton copies without a toast: its icon turns to a state-done check and its name to Copied for 1.8s.
  • The step rail (steps.tsx): a 28px StepsHeader with up to three 20px tool tiles (IconStack, rounded-chip, seam border, bg-chrome) or, while live, the state dot; StepRows with a 24px gutter holding a 14px icon-faint mark and a 1px rail in icon-faint at 40% that stops 3px short of each mark; 28px StepLines with the StepStatus cluster (Spinner in state-working, an icon-faint check, a state-failed cross, or the needs-you dot); and 24px StepChips (32px coarse), font-code at text-ui-xs on bg-chrome with a seam border.

Charts

The Insights activity charts, heatmap and sparklines are hand-drawn SVG; the Insights > System charts use recharts through ChartContainer in web/src/components/ui/chart.tsx, with recharts' animation off. Marks use fill-* and stroke-* token utilities or currentColor, never inline colours. Outcomes use the session state tokens (state-done, state-failed, state-paused). A neutral count such as sessions launched is outlined in stroke-icon-faint on fill-chrome, so it never reads as the solid paused grey. A sequential scale steps one hue: fill-accent at 25%, 50%, 75% and 100% over fill-chrome for zero. Every colour has a text legend, and every mark is named by its own label or a summary, so nothing depends on colour alone. Axis and legend text stays at text-ui-xs or text-ui-sm in text-muted; bars carry no gradients, shadows or animation. A chart scaled with preserveAspectRatio="none" draws strokes with vector-effect: non-scaling-stroke.

The Trace waterfall is the exception. Its bars are 14px high (10px stacked) with a 3px radius, segments inside them 2px. A finished tool call is bg-accent-soft with an accent border; running, failed, stopped and waiting bars take the -soft fill and border of state-working, state-failed, state-paused and state-needs-you. Turn and subagent bars are bg-chrome with a seam border, holding icon-faint model time and accent tool density at 50%, 75% and 100% for one, two and three or more calls at once. The session's own bar is its state history in the -soft state fills. A running bar carries trace-live, the live shimmer's band in working blue; history that is not loaded is hatched (trace-unknown). A duration that would run past the track sits inside the bar's end, on the bar's own fill. The Slowest pill is neutral, bg-hover-chrome and muted, because amber means Needs you.

Lanes

Board's Lanes view (dashboard-frontend.md) follows the chart rules: flat fills, token strokes with vector-effect: non-scaling-stroke, and a Legend popover that names every fill and link. Every encoding differs by line style or marker as well as colour.

Bars, rounded-control, 24px in a 36px lane (32px in 44px on a coarse pointer), with 1px between state spans. Bar text that does not fit ends in an ellipsis and keeps clear of the Needs you tag; a bar under 48px shows only its colour. Dragging a track selects no text. Every lane but a note takes cursor-pointer. A filled span is its state's text colour at --lane-tint (16% light, 26% dark), bg-current/(--lane-tint), so every state reads as a tinted bar in both themes; bar text is text-text, which stays at 4.5:1 or more on every fill (design-system.test.ts checks it). Subagent sub-lanes use the same fills.

Span Colour
Working text-state-working; a live bar adds a 2px border-state-working end cap and live-shimmer on its activity text
Needs you, or Needed attention in history text-state-needs-you; a live bar ends in a bg-raised Needs you tag with a pulsing dot
Paused text-state-paused
Finished: review text-accent, matching its dot; never the Needs you tag. The lane's label carries a review-tone Finished: review chip
Done, Failed text-state-done, text-state-failed; a finished session's working spans take its outcome's colour
Waiting, answered, closed text-muted
Starting hollow, dashed border-seam
History not loaded hollow, dotted border-icon-faint

Neighbouring spans that share a fill draw as one. A bar that starts before the window fades in over its first 32px (a mask, not a colour). Strips (folded Finished) are 6px and 8px bg-current pills in the state's text colour, neighbours of one colour drawn as one; each stretch is at least 1/300 of the window, so a brief failure still shows.

Mail marks and links use the categorical series by meaning:

Mark or link Colour Style Ends
Agent message, at rest text-series-5 sent: 5.5px filled dot with a 1px --canvas halo; received: 6px --canvas ring, 1.5px stroke; 2px outside the bar edge facing the other lane a text-ui-xs tabular count on a --canvas halo when marks merge
Agent message, at rest, between drawn lanes text-series-5/45 (/30 below 768px); text-seam while a lane is focused solid 1px hairline under the bars, no hit path, one layer apart from the links its two marks
Agent message, focused lane text-series-5 solid 1.5px, round caps dot at the sender; arrowhead at the recipient, filled once acknowledged, hollow before; a count chip on bundles
Agent message, live text-series-5 over a 4px --canvas halo; the recipient's track bg-series-5/10 dashed 4 3 2px, round caps, an arc bowing left of the send time dot at the sender, filled arrowhead along the arc at the recipient; a ×n chip left of the arc
File overlap text-state-needs-you dashed 4 2 bracket at the now line warning chip with the file count
Subagent border-icon-faint elbow tree connectors in the label column none

Marks sit above the bars with hit targets as wide as a bar is tall (24px, 32px on a coarse pointer), 12px deep and inside their own lane, ending halfway to a closer mark on the same edge; link hit paths are 16px wide. Links and their chips draw under the bars and labels, over the hover and selection fills; only their 16px hit paths sit above. A focused lane's marks give way to its links and every other mark turns text-icon-faint. Label chips are 16px rounded-chip, border-series-5 on bg-raised with the MessageSquare glyph, left of the age. A mark added after the view opens fades in once with motion-safe:animate-fade-in; nothing loops. A live arrow draws above the bars for --duration-mail-live (4.5s, under WCAG 2.2.2's five seconds): animate-mail-live fades it and the recipient's tint in over 150ms, holds them to 2s and fades them out on --ease-in-out; animate-mail-travel (down, linear) and animate-mail-bow (sideways, quadratic) run an 8px dot along the arc from sender to recipient once over 500ms, and animate-mail-ping grows a ring at the head once. Each arrow is its own HTML box and animates only opacity and transform, which an SVG child could not keep on the compositor. Under reduced motion the arrow and tint show still, without the dot or ring, and go when their time ends. Tree focus without hover or a popover takes the bg-hover row fill, like hover. nothing uses opacity. The axis is 28px with text-ui-xs muted tabular labels over dashed border-seam gridlines, dropping any label within 48px of the now chip; the now line is 1px bg-icon-faint under a neutral bg-raised now chip, never accent. The label column is 240px, 48px under 768px. Lanes that change section glide 220ms on --ease-enter; new lanes fade in over 250ms, staggered by --stagger-row up to the eighth. Under reduced motion the pulse, shimmer, glide and fade stop.

Enforcement

web/src/design-system.test.ts scans every non-test source file under web/src and fails on:

Rule Fails on
Type scale text-xs to text-9xl, text-base, or an arbitrary size such as text-[13px]
Token colours Tailwind palette colours (bg-gray-100, text-white) or arbitrary hex, rgb, hsl or oklch colours
Sentence case uppercase; a group heading is a SectionLabel
No HeroUI Any @heroui/ import
Icons through components/icons A lucide-react import outside web/src/components/icons.ts
One name per icon lucide aliases such as XIcon, Loader2, AlertTriangle or MoreHorizontal
No bare buttons <button outside components/ui/; use Button
No opacity on rows opacity-* in components/shell/ and routes/board/; a receding row uses text-muted
Token names Colour names that are not tokens and render nothing: background, foreground, card, popover, sidebar, primary, secondary, muted-foreground, destructive, input, ring, border, toolbar-hover, field, and state-attention, -success, -warn, -waiting, -needs-attention, -idle

It also fails when a looping keyframe in index.css or motion.css animates anything but transform and opacity.

A rule can carry a legacy list of files that predate it; only no bare buttons still has one. The test also fails when a listed file already complies, so the lists only shrink.

The same file checks contrast in both themes: text and text-muted on every surface, text on selection, accent text on canvas and chrome, on-accent on the accent fill, on-failed and on-done on their fills, and the states and diff colours on canvas at 4.5:1; control borders, icon-faint and the agent colours on canvas at 3:1. It also checks that every text-* and bg-* class in components/ui/ names a token defined in index.css.

Icons

Icons come from web/src/components/icons.ts, which re-exports the lucide icons the dashboard uses at stroke width 1.75. Add a name there rather than importing lucide-react. The same module holds the agent marks AgentGlyph draws, filled in the text colour rather than stroked, each in a viewBox that fits the mark as its source draws it, never stretched. Gemini CLI and Antigravity CLI show their initial, because Google allows its product icons only on request. notices.md lists where each mark comes from.

Geometry and responsive behavior

Use compact workbench geometry rather than landing-page ornament:

  • A branded header with horizontal navigation; destinations that do not fit move into More navigation, except Board. One sidebar, 260px by default and resizable from 220px to 400px; under 768px it is a side sheet, opened from a second, 48px toolbar. The desktop window bar is 35px.
  • 44px view headers (PaneHeader), 56px for a session's header, 32px terminal toolbars, 28px list rows and menu items (44px coarse).
  • 28px fields and buttons, 24px small and toolbar icon buttons (44px on a coarse pointer), 12px form gaps, 4px label gaps, 16px content gutters and 12px compact gutters. Label captions are block-level, so stacked caption-to-field spacing measures 4px, including wrapped fields.
  • Four radii: --radius-chip 5px (rounded-chip) for badges, counts, keys, inline code and checkboxes; --radius-control 8px (rounded-sm, rounded-control) for buttons, fields, rows, menu items and tooltips; --radius-panel 12px (rounded-md and up, rounded-panel) for cards, callouts, dialogs, menus, popovers, toasts and the palette; and --radius-composer 14px (rounded-composer) for the session composer and Board's column wells. A radius nested in another is the outer one minus the inset: a 12px menu with 4px padding holds 8px items. Edges that meet another surface stay square: sheets at the screen edge, a session's details box where it docks, joined buttons and dock tabs. rounded-full is for dots, radios, avatars, meters, switches and the composer's and the Notes field's send control only. The Context window's grid cells and legend swatches are 2px (rounded-xs).
  • Elevation: panes and headers have none; cards shadow-card, lifting to shadow-card-hover on hover; secondary buttons shadow-button; menus, popovers, selects, tooltips, toasts and the session details box shadow-overlay; dialogs, the palette and sheets shadow-dialog. Values differ per theme in web/src/index.css. Every shadow sits over a seam border, which forced-colors mode keeps when it drops shadows. A shadow that must read as none is written 0 0 #0000, never none, so it still composes with ring utilities. Headers stay at text-title or smaller.
  • Scrollbars are 8px with an --icon-faint thumb.
  • The Trace view has a 66px stats strip with 1px seams between cells (a 3×2 grid when stacked), a 29px axis header, a 256px span pane and 30px rows (44px coarse). Below 561px of its own width the rows stack to 46px (52px coarse): the name line, then the bar. Each level indents 14px, up to the sixth. Span glyphs sit in 20px seam-bordered bg-chrome tiles in text-muted; the details use a 30px tile.
  • The template library: a 256px list pane (224px in the composer and palette pickers, stacked above the detail below a 544px container) of 32px rows (44px coarse), each with the agent glyph, the name, a clock when scheduled and a neutral 18px mode badge; a 44px bg-chrome footer band. Inline placeholder fields are 22px chips that size to their text: bg-accent-soft and text-accent once they have a value, bg-hover-chrome with a seam ring while empty, and the field focus outline. The fill dots are 6px, bg-accent filled and bg-seam empty.
  • A Board column is a bg-chrome well, 8px from the next, with a 36px header (sentence-case label and CountBadge) and a 3px inset around cards 4px apart. Its cards pass raised to Card: bg-raised, keeping that fill and lifting the shadow on hover. A card is a head (coloured agent glyph, title of at most two lines), a description of at most two lines in text-ui-sm (one line for live Working activity), and a 16px footer whose 24px action overhangs it (dot, label, compact age, workspace; then agent name, owner avatar, +a −d, the card:meta slot and the action). A Needs you reason reads in the text colour, the others in muted, never with a second dot or a New pill. From 365px of card width (@container) the description and footer indent under the title. See Dashboard SPA: Board.
  • Board's Map draws its own compact cards (288×128 by default, larger for the larger text sizes, 20px taller on a coarse pointer) on a bg-chrome canvas: bg-canvas with shadow-card, a 22px bg-chrome agent tile, the state as a soft Badge led by its StatusDot, and no pulse. Owner sections, when there are two or more, and Needs you elsewhere are border-seam frames with no fill; identity colour stays on the shared avatars. The N needs you and N failed chips are small buttons on their state's soft fill, a 20% mix of the state colour on hover and while open. The Sessions toolbar wraps its counts, scope, Mine, archive and camera controls on phones. Live presentation updates do not move nodes or reset the camera.

At 390px every operation remains available through compact navigation or overflow, stacked forms, bounded dialogs and tree-to-file navigation. The main page never gains horizontal overflow; text and code may scroll inside their own surfaces. Floating menus stay inside the available viewport and scroll to their last action. Route roots own the shell's bounded height; their content regions use min-h-0 and vertical overflow.

The session Browser view has one bg-chrome toolbar row over the page: ghost icon buttons for Back, Forward and Reload, the address field, Ports with its count, Viewport, the beside-or-tab toggle and Browser actions, then who is driving. A listening port is a secondary button, its address in font-code and its process name muted, with a ghost icon button beside it. A second page adds a row of small tab buttons. Messages are laid over the top of the page on a floating surface and never take a row. A page that does not fill its pane is centred on bg-chrome and never enlarged, and the page that has the keyboard wears a 1px inset accent outline. Beside another view the Browser is a pane with a seam and a resize handle like the sidebar's. Browser view has the behaviour.

The terminal toolbar holds the terminal tabs, Tools (a menu; a bottom sheet under 768px) and, at its end, who controls the terminal beside Take control or Release (terminal.md). A session shell adds Shell actions. The Environment page puts Save environment and Environment actions in its header.

Shell, palette and focus

The shell has a branded navigation header above one sidebar and the content view, with no icon rail or status bar. The Cloudfield logo sits at its left; Board through Templates follow as horizontal ListRows. Measure available width rather than assuming every label fits a breakpoint, and keep Board outside the overflow menu. The header and sidebar use bg-chrome with seams against the content; navigation rows have muted icons and the open page in bg-selection. New session at the sidebar's top is the only filled button in the shell. Session rows carry a shaped StatusDot, a 6×7px owner mark (a right-pointing triangle in the owner's colour, 4px from the dot and from the title), the agent's title, a compact age ("15m") in text-ui-sm muted tabular figures and a monochrome AgentGlyph. The people on a session follow as 16px avatars overlapping by 6px, the first one whole at the right edge, each ringed in the row's own background so the one in front cuts into the one behind. Subsessions are indented 26px under their parent and joined to it by 1px icon-faint tree connectors: a trunk under the centre of the root's status dot, and for each child a wire from the trunk to the row's left edge, level with the child's dot. The trunk ends at the last child's wire. Connectors stay in the indent, outside every row's hover, selection and focus box. A row that recedes shows its title in text-muted, never with opacity; a finished row no member has opened yet keeps text-text (see dashboard-frontend.md). A row's details box is a 288px floating surface docked flush to the row's right edge, its top-left corner square where it meets the row. Group headers are sentence-case 12px muted disclosure buttons with their count. The footer holds the avatar, name and a connection dot; the update notice above it is one 12px muted line with an Update link.

Under 768px the header is one 48px row (bg-chrome): the view title in 13/20 medium and Search. A bg-chrome tab bar along the bottom holds Needs you, Sessions, New, Assistant and More: 56px tall, a 20px icon in the same 28 × 44px box over a 12px label, muted at rest and accent when current, with a 2px accent bar along the top edge. Counts over 99 read 99+. The Needs you count is an amber chip with text-canvas figures, the one place amber fills a count, because it is the needs-you signal. New is an accent pill unless the page has its own primary action, so the screen keeps one filled button. More opens as a bottom sheet. Content views draw PaneHeader: the title in text-title, one optional muted line under it, and actions on the right. A connection problem is a failed-tone StateLine, in the header on desktop and under the top bar on a phone.

The command palette is mounted exactly once in AppShell and opened from the Search buttons, Mod+K or Mod+Shift+P, top-centred, max 600px, with 32px rows (44px on a coarse pointer). Theme is in Settings > General and the footer menu, with explicit Dark, Light and System choices and matching palette commands.

focusRing, fieldFocus and field in web/src/lib/utils.ts are the shared focus and field styles. Buttons and navigation show their outlines only after Tab, never after a click or another key. One exception: Cancel in a close confirmation takes focus when the confirmation opens and shows its outline then (focusRingShown), so the safe default is visible; text fields use a 1px inset accent outline over the existing border with a faint 4px glow and no offset gap. The outline remains visible in forced-colors mode, where box shadows disappear. The Chat composer draws this treatment on its enclosing box, not its embedded textarea, so attachments do not clip the highlight. Preserve readable placeholders, disabled and read-only states, menu roving focus, typeahead, portalling and viewport flipping. Shared primitives retain their props, events, refs and accessibility contracts.

The session header shows one primary action for the session's state, a Details toggle and More; destructive verbs stay last in More, behind their existing gates and confirmations. The view switch (Session, Trace on an Enhanced session, Terminal, Changes, Files, Browser) is a segmented tab list. A session with a pull request ends that row with its number as a muted link and its check state as a ghost button led by a StatusDot: failed, working, done or neutral. Details is a 320px side panel at 1280px and wider, a side sheet below that and a bottom sheet on phones; it never overlays the terminal on wide screens. Standard sessions keep control in the terminal toolbar; Enhanced sessions keep a compact Multiplayer strip below the view switch on every view. Names and member avatars identify the controller and watchers directly in that strip, which stays one row while the controls fit beside a 6rem roster and otherwise wraps them to a second line. The roster scrolls horizontally, and below 34rem watchers show as avatars and below 30rem Multiplayer as its icon. Takeover progress uses state-failed with on-failed text in both themes. One session-owned holder decision dialog sits above every sheet and dialog. Request cards are neutral, with a needs-you dot in the header; the Session transcript column is 736px wide with no row borders and no card around a block of steps. In it a person's message is a bg-chrome bubble at the right, at most 85% wide, with rounded-composer; everything the agent wrote starts after the step rail's 24px gutter, where state dots and step marks sit. Turns are 24px apart and a turn's header and answer 12px. Its composer fills the available pane with balanced 16px side gutters, including when Details is open. An empty ACP conversation shows a subdued Cloudfield mark, cloudfield-mark.svg as a mask at min(144px, 24vh), above the centered session title and metadata rows: workspace, agent, branch, owner and creation time. Symmetric scrollbar gutters keep the overview centered when its content needs scrolling.

Session state and motion

The --state-* tokens in Semantic palette are the status vocabulary for a session's presentation state. Domain status enums remain unchanged.

Motion confirms a change the viewer caused or marks the one live thing; it never decorates still data. web/src/motion.css holds the tokens:

Token Value Use
--duration-hover, --ease-hover 150ms, CSS ease Colour, fill, border and shadow fades; the default for a bare transition-*
--duration-press, --duration-release, --ease-press 150ms, 130ms Button press scale, --scale-press (0.97)
--duration-popover, --ease-enter 130ms Menus, popovers, selects and tooltips growing from --scale-popover (0.98)
--duration-glide, --ease-glide 300ms Tab indicators, meters and layout glides
--duration-expand 250ms Disclosures opening
--duration-pulse 1600ms The live shimmer's period
--duration-instant 0ms Swaps with no fade

Raw steps (--duration-100 to --duration-1600) cover the rest: 100ms row, menu-item and tab-label fades; 200ms chevron turns, word swaps, dialog entrances, scrim fades and disclosures closing; 220ms sheets on --ease-sheet; 360ms row entrances; 500ms number tweens (useNumberTween); 1000ms the Working pulse. Each role has a duration-<role> utility that also sets --tw-duration, so a later transition-* cannot reset it. web/src/lib/motion.ts reads the same tokens for script animations (play, playEntrance); code names a token, never a literal time or curve.

  • Overlays fade and grow from their trigger (the Radix transform origin) and leave at once. A closing tooltip must not animate, or Radix keeps it above the layer the next Escape is meant for. A tooltip opens 250ms after hover, at once on keyboard focus, and at once within 300ms of another closing.
  • Dialogs fade in from --scale-enter (0.95) through transform, leaving the translate that centres them alone. Sheets slide in from their edge; a session's details box wipes in from the row it docks to.
  • Collapsible bodies glide their height, clipped only while they move, and unmount once shut.
  • The Session request dock fades a request that left pending out over 200ms, then glides its height (--duration-glide) to the next card, which fades in over 250ms, or to nothing. A preview that arrives late glides the card open; nothing animates on hydration.
  • A selection that moves between a set of buttons, the header navigation and Settings' categories, is one SlidingIndicator that sits beside the list and glides on --duration-glide; the selected row's own fill is transparent so the two never double up. A sidebar group turns its chevron and fades its list back in when the viewer reopens it; it never glides its height, since a group can hold hundreds of rows.
  • Only rows added after the first render enter: animate-entrance fades in and rises 4px. playEntrance staggers a burst by --stagger-row (30ms) up to the eighth row; the rest arrive with it. The Session list plays it only for rows new since its last render: a streamed burst of at most eight, or the steps a viewer just opened, never a first load, replay or history page. A streaming answer's new Markdown blocks fade in from --blur-fade over 270ms. Opening a block of steps splices rows into the virtual list, so it does not glide its height. A note in the Notes thread plays it on its header and, 100ms later, its body, on --ease-glide; only notes newer than the thread's first page do, each once.
  • web/src/lib/flip.ts glides reordered items, translating only, for short lists the viewer reorders; never a virtualized list. The one store-driven use is Board moving at most eight cards between columns; see Board.
  • The Map repacks with motion: units and cards glide from their old layout coordinates on --duration-glide / --ease-glide (never DOM-measured, since the world is scaled), new cards rise 6px and fade in over 220ms after a 150ms hold, staggered by --stagger-row up to the eighth, and removed cards fade out over 130ms. Hydration and scope changes never animate.
  • A popover may animate what it shows: the Context window tweens its token total over 500ms and recolours its grid cells on the glide curve, each 2ms after the one before (--stagger-cell). Nothing runs on open; the number and cells move when a new report arrives or the pointer singles out a category, and the hover dim moves every cell together.
  • File chips and attachment rows confirm a change the viewer caused: a landed file's check and disc animate-pop-in (scale 0.5 to 1 on --ease-pop, 250ms), a failed row animate-shakes once (360ms) and a dragged-over drop zone's arrow animate-bobs 3px (450ms, alternating).
  • A list the viewer refilters keeps its old rows at half opacity until the answer lands, then fades in rising 3px. Rows arriving from elsewhere enter one by one only when five or fewer arrive together; more just appear.
  • Row selection, focus outlines and exits change at once, except the template library's selected row, whose bg-hover-chrome highlight is a SlidingIndicator. Its detail fades in over 220ms on --ease-standard when the selection changes, never on mount; its footer swaps text with TextSwap and Copy's icon with IconSwap.
  • state-pulse (the session header's working dot, the Chat view's live row and live steps header, a plan's step in progress, the dot under a streaming answer) breathes: opacity to --opacity-muted and size to two thirds and back each second. live-shimmer, on those rows' reasons and on a working lane's activity in Board's Lanes, sweeps a light band across muted text in 1.4s of each 1.6s. A Needs you tag in Lanes pulses its dot, never its text. Sidebar rows, board cards, the palette and All workspaces never pulse.
  • The Trace view shimmers its live Duration and its running bars on the same period, and moves its now line once a second. A zoom or an axis scale step glides --trace-scale and --trace-origin over --duration-glide; the first measured layout after the view opens jumps into place. Unfolded rows enter with animate-entrance, unless more than eight arrive at once.

A looping animation animates only transform and opacity, which Chromium runs on the compositor. A tweened custom property, a background position, or scale, translate or rotate on an <svg> restyles and repaints on every frame for as long as an agent works. So live-shimmer (Shimmer in web/src/components/ui/shimmer.tsx) draws its band as a bright copy of the text, the band's ::after from data-text, masked to 60px: the band slides right while the copy slides left by as much, so the glyphs hold still.

Under prefers-reduced-motion: reduce every animation and transition stops: overlays and sheets appear, indicators and bodies jump, the pulse holds, the shimmer leaves plain muted text, the spinner shows a still arc and a skeleton a flat fill. Holds and timers do not change. useReducedMotion() and prefersReducedMotion() in web/src/lib/hooks.ts answer the query in scripts.

The desktop launch splash deliberately retains its original animation, independent of these workbench motion tokens: the grain, three drifting cloud layers, stepped starfield and coloured stars, satellites and shooting stars, 700ms logo entrance and 260ms fade. Its status dot uses the local launch-status-pulse: the original 1.8s ease-in-out loop from opacity 1 to 0.4 and back, not the shared state-pulse. The splash's original palette and keyframes stay scoped to launch-splash in web/src/index.css; do not restyle them to match the workbench. Only the logo follows the Cloudfield set: its mark, and the wordmark in the set's Cream. Reduced motion skips the splash entirely, and its CSS stops animation if the preference changes while it is visible. Launch splash defines the session and startup timing.

The bar that holds Take control and Release shows who steers: the Enhanced Multiplayer strip, or the agent terminal's toolbar in a Standard session. Its background is a grid of 2px round dots on a 6px pitch, behind the bar's text and controls. The dots are neutral, --text at 24%, until this tab has live, acknowledged writable control; then they turn --control-light, the accent teal in light theme and a brighter teal in dark. A lost takeover and an occupied hold turn them --state-failed. Colored dots sit at --control-dots opacity (100% light, 70% dark), scaled by a strength of 70% while they move or turn red. Once acquisition settles the strength dims to half over 1.2s, then breathes between 42% and 60% on an 8-second cycle. The dots fade out around each group of text and buttons on the bar, to 10% under them over about 20px, and the bar's text uses --text, not --text-muted. src/design-system.test.ts checks text over the faded teal and red dots at full strength. Release, shown while you control, has the accent fill; Take control is a secondary button. The matrix is pointer-transparent and does not change layout. Terminal replay and history reading return it to neutral; reading earlier Enhanced items does not disable the composer or clear its color. The right end, under Take control and Release, is the color's source: acquisition pours it leftward across the bar and voluntary release drains it back to the right, each over 720ms and decelerating toward the endpoint. A control-lost takeover turns the dots red over 540ms and drains them to the right over 1440ms. An occupied three-second hold fills Take control and the holder's Release diagonally in red and spreads red dots leftward from the right end of the holder's bar, blending into the teal over 4rem; text on either side of the fill edge keeps its own contrast. The fill decelerates (logarithmic) while the countdown stays linear. A seven-second holder decision follows. Under prefers-reduced-motion: reduce, ownership changes are instant, settled dots hold at half without breathing, and takeover fills and dots become static red indicators with countdowns; labels keep the state meaning. Loading spinners and delayed skeletons remain functional feedback.