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:
Switchis a 28×16px track with a 10px thumb that glides 12px in 150ms (ease-pop, none under reduced motion); on isbg-accent, off aborder-controloutline with anicon-faintthumb. Use it for a setting that applies at once or for one session, beside itsLabel.- 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-dialogfor the panel,shadow-overlayfor the preview. With the sidebar hidden or on a phone it slides in from the window edge. Tabsdraws oneSlidingIndicatorper list: the underline look slides a 2px accent bar, the segmented look abg-raisedpill with a seam ring. It follows keyboard selection and stays attached in a scrolling strip.SlidingIndicatorserves any other set the same way: items carrydata-indicator-key, and the indicator's parent is the positioned container.TextSwapreplaces 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.IconSwapdoes the same for an icon;useTimedFlaginweb/src/lib/hooks.tsholds a confirmation such as Copied.RadioPillsis 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 aSlidingIndicator(bg-hover-chrome, seam ring). A pill may carry a muted count. Memory's filters and kinds use it.FadeStripscrolls a row sideways with no scrollbar and masks whichever edge hides content over 22px, so the fade matches any surface.CountBadgeis 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.PageBodyis the centred column of a scrolling page (md3xl,lg4xl,xl6xl), 32px between sections, fading in on arrival. A page that needs a tighter rhythm passes its owngap-*.InsetListis a bordered, divided list that clips its rows to the 12px edge; anInsetListItemis 44px or taller with 12px gutters. WithonOpenthe row is one button, named by its content, and fillsbg-hoveron hover.StatTileis a bordered tile: a muted label, the figure intext-stat(compactfor a line of words), detail lines and asparkslot pinned to the foot, so tiles of one row align their charts.IconTileis a 28px framed square for a glyph;EmptyStatedraws itsiconin a 32px one above a title that carries no period.ProgressBaris a 4px track whose fill glides to its value. Withrole="meter"orrole="progressbar"it reportsvalueofmax; without one it only draws, for a parent that carries the role. With novaluethe 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.DropZoneis a dashedrounded-panelbutton that opens a chooser throughonBrowseand takes dragged files throughonFiles; its border turnsborder-controlon hover andborder-accentoverbg-accent-softwhile 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.Kbdis an outlined keycap, 20px (md) or 16px (sm).RequestCard(request-card.tsx) is anything waiting on the viewer: abg-raisedcard with a seam border and no shadow. Its header holds a 28px avatar (IconTilefor a glyph, or a memberAvatar), the title over a muted source line, meta and aStatusDotin 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 andCountBadge;RequestRowsshows three rows, then N more, whose rows fade in 30ms apart; a row that opens its detail takes abg-hoverfill 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 thebg-chromeband that sticks to the bottom of a scrolling parent;RequestPillsare its 26px How long pills (34px coarse) on abg-hover-chrometrack, the chosen onebg-raisedwith a seam ring;RequestActioncrossfades its label throughTextSwapand shows its answer digit as aKbdon a fine pointer. Answers split a narrow card in halves and sit at their own width on the right of a wide one.RequestTimeBardrains 2px of needs-you toward a deadline. Amber appears only in the dot and that bar; accent only on the primary answer.Spinnerdraws a ring: a track at--opacity-trackunder a quarter arc turning every 900ms.Skeletonsweeps abg-hover-chromeband acrossbg-chrome. A page that loads shows skeletons shaped like its result, capped at about ten rows, afteruseDelayed's 200ms.CopyButtoncopies without a toast: its icon turns to astate-donecheck and its name to Copied for 1.8s.- The step rail (
steps.tsx): a 28pxStepsHeaderwith 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 14pxicon-faintmark and a 1px rail inicon-faintat 40% that stops 3px short of each mark; 28pxStepLines with theStepStatuscluster (Spinnerinstate-working, anicon-faintcheck, astate-failedcross, or the needs-you dot); and 24pxStepChips (32px coarse),font-codeattext-ui-xsonbg-chromewith 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.
Labelcaptions are block-level, so stacked caption-to-field spacing measures 4px, including wrapped fields. - Four radii:
--radius-chip5px (rounded-chip) for badges, counts, keys, inline code and checkboxes;--radius-control8px (rounded-sm,rounded-control) for buttons, fields, rows, menu items and tooltips;--radius-panel12px (rounded-mdand up,rounded-panel) for cards, callouts, dialogs, menus, popovers, toasts and the palette; and--radius-composer14px (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-fullis 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 toshadow-card-hoveron hover; secondary buttonsshadow-button; menus, popovers, selects, tooltips, toasts and the session details boxshadow-overlay; dialogs, the palette and sheetsshadow-dialog. Values differ per theme inweb/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 written0 0 #0000, nevernone, so it still composes with ring utilities. Headers stay attext-titleor smaller. - Scrollbars are 8px with an
--icon-faintthumb. - 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-chrometiles intext-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-chromefooter band. Inline placeholder fields are 22px chips that size to their text:bg-accent-softandtext-accentonce they have a value,bg-hover-chromewith a seam ring while empty, and the field focus outline. The fill dots are 6px,bg-accentfilled andbg-seamempty. - A Board column is a
bg-chromewell, 8px from the next, with a 36px header (sentence-case label andCountBadge) and a 3px inset around cards 4px apart. Its cards passraisedtoCard: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 intext-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, thecard:metaslot and the action). A Needs you reason reads in the text colour, the others inmuted, 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-chromecanvas:bg-canvaswithshadow-card, a 22pxbg-chromeagent tile, the state as a softBadgeled by itsStatusDot, and no pulse. Owner sections, when there are two or more, and Needs you elsewhere areborder-seamframes 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) throughtransform, leaving thetranslatethat centres them alone. Sheets slide in from their edge; a session's details box wipes in from the row it docks to. Collapsiblebodies glide their height, clipped only while they move, and unmount once shut.- The Session request dock fades a request that left
pendingout 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
SlidingIndicatorthat 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-entrancefades in and rises 4px.playEntrancestaggers 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-fadeover 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.tsglides 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-rowup 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 rowanimate-shakes once (360ms) and a dragged-over drop zone's arrowanimate-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-chromehighlight is aSlidingIndicator. Its detail fades in over 220ms on--ease-standardwhen the selection changes, never on mount; its footer swaps text withTextSwapand Copy's icon withIconSwap. 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-mutedand 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-scaleand--trace-originover--duration-glide; the first measured layout after the view opens jumps into place. Unfolded rows enter withanimate-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.