docs: Add v2 wireframes and theme specification
14 files in docs/wireframes/v2/ addressing 13 UX gaps from v1: - Theme spec with indigo brand, status tokens, terminal/diff tokens, dark mode, Geist typography, 6px radius, layered shadows - Wireframes for all pages with loading/error/empty states - Shared component specs (SaveIndicator, EmptyState, ErrorState, CommandPalette, ThemeToggle)
This commit is contained in:
Lukas May
289
docs/wireframes/v2/agents.md
Normal file
289
docs/wireframes/v2/agents.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Agents Page (v2)
|
||||
|
||||
### Route: `/agents`
|
||||
### Source: `packages/web/src/routes/agents.tsx`
|
||||
|
||||
---
|
||||
|
||||
## v1 -> v2 Changes
|
||||
|
||||
| Aspect | v1 | v2 |
|
||||
|--------|----|----|
|
||||
| Provider filter | None | Dropdown: All / Claude / Codex / Gemini / etc. |
|
||||
| Mode filter | None | Dropdown: All / discuss / plan / detail / execute / verify / etc. |
|
||||
| Search | None | Text input filtering agent name |
|
||||
| Agent card context | Name + status + provider + mode + time only | Added context row: "Task: ..." or "Initiative: ..." with link |
|
||||
| Loading state | 5 skeleton cards (basic) | 5 skeleton cards with shimmer animation |
|
||||
| Error state | AlertCircle + retry (exists) | Same (unchanged) |
|
||||
| Empty (filtered) | "No agents match this filter" | "No matching agents" + `[Clear filters]` link |
|
||||
| Empty (zero agents) | None | Centered empty state with description |
|
||||
|
||||
---
|
||||
|
||||
## Default State (with agents)
|
||||
|
||||
```
|
||||
+=============================================================================+
|
||||
| [CW] Initiatives [*Agents*] *3 Inbox (2) Settings [cmd-k] [sun] * |
|
||||
+=============================================================================+
|
||||
| |
|
||||
| Agents (7) [ Refresh ] |
|
||||
| [search___________] [All providers v] [All modes v] |
|
||||
| |
|
||||
| Agent List 320px | Agent Output |
|
||||
| -------------------------+-------------------------------------------------|
|
||||
| +----------------------+ | |
|
||||
| | * blue-fox-7 [...] | | Session 1 |
|
||||
| | claude . execute | | > Analyzing codebase structure... |
|
||||
| | Task: PKCE flow | | > Found 12 files matching pattern |
|
||||
| | 2m ago | | > Creating src/auth/pkce.ts |
|
||||
| +----------------------+ | > Writing test file... |
|
||||
| | |
|
||||
| +----------------------+ | |
|
||||
| | - red-elk-3 [...] | | |
|
||||
| | claude . plan | | |
|
||||
| | Init: Auth Overhaul | | |
|
||||
| | 1h ago | | |
|
||||
| +----------------------+ | |
|
||||
| | |
|
||||
| +----------------------+ | |
|
||||
| | ? green-bear-1 [...] | | |
|
||||
| | codex . detail | | |
|
||||
| | Task: DB schema | | |
|
||||
| | 5m ago | | |
|
||||
| +----------------------+ | |
|
||||
+=============================================================================+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Search + Filter Controls
|
||||
|
||||
```
|
||||
[search___________] [All providers v] [All modes v]
|
||||
```
|
||||
|
||||
### Search input
|
||||
- Placeholder: "Search agents..."
|
||||
- Client-side filter on `agent.name` (case-insensitive substring match)
|
||||
- Debounced 150ms
|
||||
- Clear button `[x]` appears when non-empty
|
||||
|
||||
### Provider filter dropdown `[All providers v]`
|
||||
|
||||
```
|
||||
[All providers v]
|
||||
+-----------------+
|
||||
| All |
|
||||
| claude |
|
||||
| codex |
|
||||
| gemini |
|
||||
| ... |
|
||||
+-----------------+
|
||||
```
|
||||
|
||||
Populated dynamically from `listProviderNames` tRPC query. Only shows providers
|
||||
that have at least one registered account.
|
||||
|
||||
### Mode filter dropdown `[All modes v]`
|
||||
|
||||
```
|
||||
[All modes v]
|
||||
+-----------------+
|
||||
| All |
|
||||
| discuss |
|
||||
| plan |
|
||||
| detail |
|
||||
| execute |
|
||||
| verify |
|
||||
| refine |
|
||||
| research |
|
||||
| merge |
|
||||
| review |
|
||||
+-----------------+
|
||||
```
|
||||
|
||||
Static list of all task category values.
|
||||
|
||||
---
|
||||
|
||||
## Agent Card Anatomy (v2)
|
||||
|
||||
### Running agent with task context
|
||||
|
||||
```
|
||||
+------------------------------+
|
||||
| * blue-fox-7 [...] |
|
||||
| claude . execute |
|
||||
| Task: PKCE flow | <-- clickable link to task/initiative
|
||||
| 2m ago |
|
||||
+------------------------------+
|
||||
```
|
||||
|
||||
### Running agent with initiative context (no specific task)
|
||||
|
||||
```
|
||||
+------------------------------+
|
||||
| * blue-fox-7 [...] |
|
||||
| claude . plan |
|
||||
| Init: Auth Overhaul | <-- clickable link to initiative
|
||||
| 2m ago |
|
||||
+------------------------------+
|
||||
```
|
||||
|
||||
### Waiting for input
|
||||
|
||||
```
|
||||
+------------------------------+
|
||||
| ? green-bear-1 [...] |
|
||||
| codex . detail |
|
||||
| Task: DB schema |
|
||||
| 5m ago |
|
||||
| Answer questions -> | <-- link to /inbox
|
||||
+------------------------------+
|
||||
```
|
||||
|
||||
### Exited
|
||||
|
||||
```
|
||||
+------------------------------+
|
||||
| - red-elk-3 [...] |
|
||||
| claude . plan |
|
||||
| Init: Auth Overhaul |
|
||||
| 1h ago |
|
||||
+------------------------------+
|
||||
```
|
||||
|
||||
### Context row rules
|
||||
- If agent has a `taskId`: show "Task: <task name>" linking to the initiative detail (Execution tab)
|
||||
- Else if agent has an `initiativeId`: show "Init: <initiative name>" linking to the initiative detail
|
||||
- Else: omit the context row entirely
|
||||
- Context text: `text-xs text-muted-foreground`, clickable portion gets `hover:underline cursor-pointer`
|
||||
|
||||
### Status dot legend
|
||||
- `*` green/active = `running`
|
||||
- `?` orange/waiting = `waiting_for_input`
|
||||
- `-` grey/exited = `stopped`, `crashed`, `idle`, `completed`
|
||||
|
||||
---
|
||||
|
||||
## Loading State (5 skeleton cards with shimmer)
|
||||
|
||||
```
|
||||
+=============================================================================+
|
||||
| |
|
||||
| Agents [ Refresh ] |
|
||||
| [search___________] [All providers v] [All modes v] |
|
||||
| |
|
||||
| Agent List 320px | Agent Output |
|
||||
| -------------------------+-------------------------------------------------|
|
||||
| +----------------------+ | |
|
||||
| | [.] ░░░░░░░░░░░░ | | |
|
||||
| | ░░░░░ . ░░░░░░ | | |
|
||||
| | ░░░░░░░░░░░░░ | | |
|
||||
| +----------------------+ | Select an agent |
|
||||
| +----------------------+ | to view output |
|
||||
| | [.] ░░░░░░░░░░░░ | | |
|
||||
| | ░░░░░ . ░░░░░░ | | |
|
||||
| | ░░░░░░░░░░░░░ | | |
|
||||
| +----------------------+ | |
|
||||
| +----------------------+ | |
|
||||
| | [.] ░░░░░░░░░░░░ | | |
|
||||
| | ░░░░░ . ░░░░░░ | | |
|
||||
| | ░░░░░░░░░░░░░ | | |
|
||||
| +----------------------+ | |
|
||||
| +----------------------+ | |
|
||||
| | [.] ░░░░░░░░░░░░ | | |
|
||||
| | ░░░░░ . ░░░░░░ | | |
|
||||
| | ░░░░░░░░░░░░░ | | |
|
||||
| +----------------------+ | |
|
||||
| +----------------------+ | |
|
||||
| | [.] ░░░░░░░░░░░░ | | |
|
||||
| | ░░░░░ . ░░░░░░ | | |
|
||||
| | ░░░░░░░░░░░░░ | | |
|
||||
| +----------------------+ | |
|
||||
+=============================================================================+
|
||||
```
|
||||
|
||||
Skeleton cards mirror card anatomy: status dot placeholder, name line, provider/mode line,
|
||||
context line. Shimmer animation sweeps left-to-right on a 1.5s loop.
|
||||
|
||||
---
|
||||
|
||||
## Error State
|
||||
|
||||
```
|
||||
+=============================================================================+
|
||||
| |
|
||||
| Agents [ Refresh ] |
|
||||
| |
|
||||
| |
|
||||
| [AlertCircle] |
|
||||
| Failed to load agents |
|
||||
| |
|
||||
| [ Retry ] |
|
||||
| |
|
||||
+=============================================================================+
|
||||
```
|
||||
|
||||
- `[AlertCircle]` icon: `h-8 w-8 text-destructive`
|
||||
- Error message: `text-sm text-destructive`
|
||||
- `[ Retry ]` button: `variant="outline" size="sm"`, calls `agentsQuery.refetch()`
|
||||
|
||||
---
|
||||
|
||||
## Empty State -- No Agents
|
||||
|
||||
```
|
||||
+=============================================================================+
|
||||
| |
|
||||
| Agents [ Refresh ] |
|
||||
| [search___________] [All providers v] [All modes v] |
|
||||
| |
|
||||
| +-----------------------------------------------------------------------+ |
|
||||
| | | |
|
||||
| | [bot] | |
|
||||
| | No agents yet | |
|
||||
| | Agents appear here when dispatched from initiatives. | |
|
||||
| | | |
|
||||
| +-----------------------------------------------------------------------+ |
|
||||
| |
|
||||
+=============================================================================+
|
||||
```
|
||||
|
||||
- `[bot]` icon: `Bot` from Lucide, `h-8 w-8 text-muted-foreground`
|
||||
- Shown when the `listAgents` query returns an empty array and no filters are active
|
||||
|
||||
---
|
||||
|
||||
## Empty State -- Filters Active, No Match
|
||||
|
||||
```
|
||||
+=============================================================================+
|
||||
| |
|
||||
| Agents [ Refresh ] |
|
||||
| [codex_____________] [claude v] [execute v] |
|
||||
| |
|
||||
| +-----------------------------------------------------------------------+ |
|
||||
| | | |
|
||||
| | No matching agents | |
|
||||
| | Try a different search or filter. | |
|
||||
| | | |
|
||||
| | [Clear filters] | |
|
||||
| | | |
|
||||
| +-----------------------------------------------------------------------+ |
|
||||
| |
|
||||
+=============================================================================+
|
||||
```
|
||||
|
||||
- "Clear filters" is a text link (`text-primary hover:underline cursor-pointer`)
|
||||
- Resets search input to empty, provider filter to "All", mode filter to "All"
|
||||
|
||||
---
|
||||
|
||||
## Source
|
||||
|
||||
- `packages/web/src/routes/agents.tsx`
|
||||
- `packages/web/src/components/AgentOutputViewer.tsx`
|
||||
- `packages/web/src/components/AgentActions.tsx`
|
||||
- `packages/web/src/components/StatusDot.tsx`
|
||||
Reference in New Issue
Block a user