# Workspace UI Design Guidelines

How settings and workspace views in AgentWorks (Builder automations and Crew
projects) are built. New views follow this page; existing views converge to
it. See `setup-consolidation.md` for the consolidation that established it.

## Shared header

Every workspace view renders one `WorkspaceViewHeader`
(`frontend/src/components/workflow/WorkspaceViewHeader.tsx`).
Plan and Report are the only views without one (canvas overlays,
not titled views). See `header-consolidation.md` for the migration
that established this.

- Leading icon in an `h-9 w-9` tile (`h-4` glyph), sized to span the
  title + subtitle block.
- Title `text-sm font-semibold`, subtitle `text-xs
  text-muted-foreground`, both rendered by the header — views never
  override the sizes. Optional inline `context` (counts, badges) sits
  next to the title; a full-width `below` row holds stats or pills.
- Actions on the right: Ask AI left, refresh right, via
  `WorkspaceViewActions`. The order is a product rule. Per-tab extras
  (`tabActions`) render left of the pair; pickers and dropdowns live
  in the content, never in the header row.
- Tabs, when a view has them, belong to the header via its `tabs` prop
  (`{ value, onChange, options, ariaLabel }`), rendered by the shared
  `WorkspaceViewTabs` pinned to the header's bottom edge. Tabs may
  carry icons and counts. Never build a second tab row.
- `bare` variant when the shell owns the row (Costs, Execution Logs),
  `sticky` for scroll views — both visually identical to the standard.

## Ask AI and chat

One function sends every right-pane message to chat:
`sendWorkspacePaneMessageToChat`
(`frontend/src/utils/workspacePaneChat.ts`). It resolves the
conversation (automation, tab, or Crew project), opens the left chat,
queues behind a running turn, and restores stuck sessions. Every Ask
AI button, report widget, human-decision card, and Pulse action
funnels through it; new senders need only call it. Product surfaces
with their own lane (Crew) route through `AskAIButton`'s `onAsk` prop
and still land in the same function.

- The header button is `AskAIButton` (icon-only, expands on hover,
  two-click arm/confirm, "Sent!" acknowledgement), paired with the
  shared `WorkspaceViewIconButton` refresh.
- Ask AI copy is user-visible plain words: no tool names, skill paths,
  or config keys. Builder messages use the `workspaceAskAI` marker
  blocks (visible summary + hidden builder instructions), one per view
  in `WORKSPACE_ASK_AI_MESSAGE`, exhaustive over registered views so
  a new view cannot ship without one. Views with distinct tabs follow
  the active tab. Crew messages stay plain strings sent to the
  project chat.

## Toolbar

Toolbars use open/close groups (`WorkspaceToolbarGroup`), never dropdown
menus: primary icon buttons stay visible, Ops and Setup collapse into
labeled groups that follow the active view. Group buttons are icon-only
with tooltips (`aria-label` + `title`), in a fixed order — Setup runs
Identity → Integrations → Playbooks.

## Split layout

The chat/workspace split has one decision point per surface: Builder
uses `resolveWorkspaceLayout`
(`frontend/src/components/workflow/workspaceLayoutResolver.ts`), Crew
uses `resolveWorkSurfaceLayout`
(`frontend/src/products/work/workSurfaceLayoutResolver.ts`). Each is a
pure function of its flags (visibility, focus, preview tier, split
ratio) returning every pane class, the grid style, and the mount
branches — call sites render from it and never branch on the flags
themselves. Truth-table unit tests pin every combination, so a new
flag or mode cannot silently break an old one.

- Panes stay mounted; states toggle visibility and width only. Never
  swap display modes or layout engines between states.
- Visibility restores its own display: a flex pane hidden below md
  comes back as `hidden md:flex`, never `md:block`. Responsive
  variants win over base utilities, so `md:block` would override
  `flex`, collapse `flex-1` scroll regions to content height, and
  freeze pane scrolling with no error.
- Scroll invariant: every `overflow-y-auto` keeps a definite-height
  ancestor chain in all modes (see Scroll).
- Narrow viewports stay single-pane: `focusedPane` picks which pane
  owns the content row below md; at md+ both panes show as the
  normal split.

## Cards

Tab content is built from the shared `SettingsCard`
(`frontend/src/components/ui/SettingsCard.tsx`), matching the shared
knowledge-bases design:

- Header row: leading icon (`h-4 w-4 text-primary`), `text-sm font-semibold`
  title, optional muted count pill (`SettingsCount`, e.g. "3 attached"),
  optional right-side action.
- A muted plain-words explainer under the header.
- Content below, separated by the card's own spacing.
- Empty states use the dashed box (`SettingsEmpty`); loading states use a
  muted spinner or status line; errors use the destructive banner
  (`border-destructive/30 bg-destructive/10 text-destructive`).

Cards stack with `space-y-4`. Do not nest cards inside cards, and do not
repeat the tab title as an in-content heading — the shared header already
titles the view.

## Connect tab

Setup → Integrations carries a `Connect` tab (tab value `cli`) on Crew
projects and Builder automations, both rendering one shared
`CliMcpSetupPanel`
(`frontend/src/components/integrations/CliMcpSetupPanel.tsx`). The tab
points at the installation's API origin on both hosted and local installs.

- Lead with AI agent connection over HTTP MCP. Claude Code and Codex get
  direct registration commands; ChatGPT and Cowork get the same URL or a
  Cowork plugin. No CLI binary or pasted token is needed.
- Browser OAuth handles consent. List connected clients with a Revoke action.
- Hosted apps need a public HTTPS URL. A local AI agent may use a configured
  loopback HTTP URL from the same computer.

## Access and users

Users & access is a workspace view (`WorkflowAccessView` via
`WorkspaceViewHost`), not a top-menu entry: it follows the shared
header and cards rules like any other view, and is gated on
multi-user mode with admin/owner checks for management actions.
Personal access tokens are managed from the account menu
(`AccountControl` → `AccessTokensDialog`), never the top bar.

## Forms

Build every form from the kit (`frontend/src/components/ui/`):

- `Input`, `Textarea`, `Label`, `Button` (+ variants), `Checkbox`,
  `Switch`/`ToggleRow`, `SecretField`, `Badge`, `ConfirmationDialog`.
- Surfaces and text use theme tokens only: `border-border`, `bg-card`,
  `bg-muted`, `text-foreground`, `text-muted-foreground`, `text-primary`,
  `hover:bg-muted`. Status states use the semantic tokens — `warning`
  (needs attention: running, missed, partly paused), `info` (waiting),
  `success` (enabled, healthy), `destructive` (errors) — with alpha
  modifiers for tints (e.g. `border-warning/30 bg-warning/10
  text-warning`, paralleling the destructive banner). No hardcoded
  gray/amber/red/blue/green/purple palettes — the one exception is a
  documented semantic state color (e.g. the amber bot-enabled toggle,
  whose meaning is spelled out in the adjacent copy).
- Native elements stay only where the kit has no equivalent and the
  adoption test records the exception: radios and single selects.

## Buttons, badges, counts

- Primary `Button` for the page's main save; `outline`/`ghost` `sm` for
  secondary actions; `ghost` `icon` (`h-7 w-7`) for row actions with
  `title` tooltips.
- Pills are kit `Badge` (`default`/`secondary`/`outline`), not hand-rolled
  spans — except `SettingsCount` for card-header counts.
- Counts read as plain words: "3 attached", "2 saved", "0 attached".

## Delete

Destructive removes use `ConfirmationDialog` with `requireText`: the user
types the object's name to confirm (GitHub-style). Copy states what is
removed and that it cannot be undone.

## Identity icons

All identity badges render through `EntityIdentityIcon` (`WorkflowIcon`
for automations). An icon value is an emoji/short glyph or an uploaded
image stored as a downscaled (~128px) data URL, edited through the shared
`IconUploadField` (emoji field + Upload + Remove). Server validation
(`agent_go/pkg/workflowtypes/icons.go`) accepts both shapes; prompts and
tool results redact image bytes to "(custom uploaded image)".

## Scroll

One scroll surface per pane: the tab container owns `overflow-y-auto` and
embedded panels join it with `manageOwnScroll={false}`. Never nest a
self-scrolling panel inside a scrolling container. Refresh remounts the
active tab (a nonce key), since every tab loads on mount.

## Copy

Plain business words everywhere the user reads: "apps", "passwords and
keys", "folders", "bots". Workflow nouns for automations, project nouns
for Crew. No jargon, no config keys, no emoji as icons.