Desktop UI Reference
AgentHub Desktop is the local control surface for visible agent work. This reference maps the expected UI regions, states, and interactions so previews and screenshots can be evaluated consistently.
Layout Model
Desktop stays dense, readable, and work-focused. The primary layout is:
| Region | Purpose | Expected behavior |
|---|---|---|
| Sidebar | Projects, workspaces, recent runs, runtime shortcuts | Compact rows, clear active state, no oversized marketing cards |
| Chat stream | User request, agent messages, tool state, approvals | Stable layout while messages stream |
| Context rail | Files, diff, artifacts, preview, terminal | Switchable panels with read-only defaults |
| Composer | Prompt, target runtime, approval mode, submit/cancel | Keyboard-friendly, no layout jump |
| Status area | Edge, runtime, run state, sync | Small status indicators, not a noisy banner |
The website hero mock follows the same model. It can compress content for presentation, but it must not invent a different product.
Run States
Use consistent language across Desktop, Web, docs, and screenshots:
| State | Meaning | UI rule |
|---|---|---|
| Idle | No active run | Composer enabled, context remains visible |
| Preparing | Edge is validating workspace/runtime | Show quiet progress, not a full-screen spinner |
| Running | Runtime is producing messages or tool events | Stream content without shifting side panels |
| Needs approval | Runtime requested write, shell, apply, or publish permission | Require explicit user action |
| Completed | Run ended successfully | Keep transcript, diff, and artifacts reviewable |
| Failed | Run ended with a recoverable error | Show code, safe message, and next action |
| Cancelled | User or policy stopped the run | Keep partial transcript and audit trail |
Do not use browser focus outlines, selection boxes, or hover colors inside the static website mock that do not exist in Desktop. Mock interactions should feel like the product, not like raw DOM elements.
Workspace And Edge Selector
The workspace selector makes the execution boundary obvious:
- show the selected workspace name without exposing private absolute paths in public screenshots;
- show whether the connected Edge is local, remote, or unavailable;
- explain blocked state through policy language, not generic failure text;
- keep Local Edge loopback state distinct from Hub/Web session state.
If Desktop is connected to Local Edge, the UI may show local execution controls. If Web is open without an authorized Edge target, it must not display controls that imply direct local file access.
Runtime Picker
The runtime picker shows only configured or discoverable adapters:
| Runtime | Display rule |
|---|---|
| Mock | Safe default for UI and event verification |
| Claude Code | Use the Claude Code mark, not a generic Anthropic mark |
| Codex | Use the Codex/OpenAI-compatible mark configured by the product |
| OpenCode | Use the configured OpenCode mark |
| Custom | Use a neutral adapter icon and explicit profile label |
Unavailable runtimes remain visible only when that helps diagnosis. Their disabled state explains whether the CLI is missing, authentication is missing, or the adapter profile failed validation.
Diff And File Panels
Diff and file panels are review surfaces, not automatic write surfaces.
Required behaviors:
- render changed files as read-only until the user approves an apply action;
- show added, changed, deleted, and renamed files clearly;
- keep long lines scrollable without breaking the page shell;
- preserve syntax highlighting when available, but do not rely on color alone;
- show generated artifacts separately from source diffs when possible.
Approval buttons use concise action labels: apply, reject, continue, ask, cancel. High-risk actions include a short reason or policy label.
Motion And Feedback
Desktop motion stays subtle:
- no jumping hero text;
- no heavy hover shadow on the mock window;
- no rainbow/color strips unrelated to TokenDance Blue;
- no flash from full-size mock to scaled mock after hydration;
- respect
prefers-reduced-motion.
Interactive previews can auto-play scenario changes, but transitions are state changes inside the mock, not layout reflow of the whole hero.
Screenshot QA
Before using a Desktop screenshot or mock on the public site, verify:
| Check | Pass condition |
|---|---|
| Theme | Light/dark follows site theme toggle if the mock is interactive |
| Language | zh/en mock copy changes with site language |
| Runtime logos | Claude Code, Codex, OpenCode icons match configured sources |
| Focus | No unwanted blue DOM outline in hover/click states |
| Density | Mock remains compact on desktop and mobile |
| Privacy | No private paths, keys, tokens, emails, or host names |
Related pages: Desktop Guide, Design System, and Troubleshooting.