Files

Lukas May 478a7f18e9 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)

2026-03-02 18:13:17 +09:00

7.3 KiB

Raw Blame History

App Layout (v2)

Route: `*` (all pages)

Source: `packages/web/src/routes/__root.tsx`

v1 -> v2 Changes

Aspect	v1	v2
Header height	56px + nav row	Single 48px row
Nav layout	Wordmark on row 1, tabs on row 2	Logo + tabs + utilities all on one row
Badges	None	Live agent count on Agents, unresolved count on Inbox
Theme toggle	None	3-state Sun/Monitor/Moon
Command palette	None	Cmd+K trigger in header
Health indicator	None	Status dot (green/yellow/red)

Default State

+=============================================================================+
| [CW]  Initiatives  Agents *3  Inbox (2)  Settings     [cmd-k]  [sun]  *   |
+=============================================================================+
|                                                                             |
|                                                                             |
|                         max-w-7xl padded content                            |
|                                                                             |
|                              <Page Outlet>                                  |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
+=============================================================================+

Active Tab Highlighted

+=============================================================================+
| [CW]  [*Initiatives*]  Agents *3  Inbox (2)  Settings  [cmd-k]  [sun]  *  |
+=============================================================================+
|                                                                             |
|                              <Page Outlet>                                  |
|                                                                             |
+=============================================================================+

Active tab gets bg-muted rounded-md treatment. Text is bold.

Zero Badges (no running agents, no pending conversations)

+=============================================================================+
| [CW]  Initiatives  Agents  Inbox  Settings             [cmd-k]  [sun]  *   |
+=============================================================================+
|                                                                             |
|                              <Page Outlet>                                  |
|                                                                             |
+=============================================================================+

Badges are completely hidden when count is 0 — no empty () or *0.

Health Dot States

  *   ← green: WebSocket connected, last heartbeat < 5s ago
  ?   ← yellow: connected but heartbeat > 5s (slow/degraded)
  -   ← red: WebSocket disconnected or server unreachable

Tooltip on hover shows details:

  * Connected (42ms)
  ? Slow response (2.3s)
  - Disconnected — retrying...

Collapsed Mobile View (not yet implemented)

+=============================================================================+
| [CW]                                          [cmd-k]  [sun]  *   [☰]     |
+=============================================================================+
|                                                                             |
|                              <Page Outlet>                                  |
|                                                                             |
+=============================================================================+

Note: Mobile hamburger menu is not implemented. This is a placeholder for future work. At < 768px, nav tabs collapse into a hamburger [☰] dropdown.

404 Page

+=============================================================================+
| [CW]  Initiatives  Agents  Inbox  Settings             [cmd-k]  [sun]  *   |
+=============================================================================+
|                                                                             |
|                                                                             |
|                          [AlertCircle]                                      |
|                         Page not found                                      |
|                                                                             |
|                      [ Back to Initiatives ]                                |
|                                                                             |
|                                                                             |
+=============================================================================+

48px Header Anatomy

+-----------------------------------------------------------------------------+
|  LEFT CLUSTER                              SPACER          RIGHT CLUSTER    |
|  [CW] [Nav] [Nav *N] [Nav (N)] [Nav]      --------        [cmd-k] [◐] [●] |
+-----------------------------------------------------------------------------+
     ↑                                                          ↑     ↑    ↑
   16px icon                                              Cmd+K btn  Theme Health

Left cluster (nav)

[CW] — 24x24 logo icon, links to /initiatives
Nav tabs: Initiatives, Agents, Inbox, Settings
Each tab is an <a> with gap-1.5 between label and optional badge
Active tab: bg-muted text-foreground font-medium rounded-md px-3 py-1.5
Inactive tab: text-muted-foreground hover:text-foreground px-3 py-1.5

Badge rendering

Agents *N — small filled circle + count, only when N > 0, green tint
Inbox (N) — parenthetical count, only when N > 0, yellow tint for unresolved

Right cluster (utilities)

[cmd-k] — Cmd+K on Mac, Ctrl+K on Windows. Shows shortcut text as label. Clicking opens the CommandPalette overlay (see shared-components.md).
[◐] — ThemeToggle, 3-state segmented control (see shared-components.md)
[●] — Health status dot, 8px circle with color

Spacing

Left cluster: gap-1 between items
Between clusters: flex-1 spacer pushes them apart
Right cluster: gap-3 between items

Responsive Notes

Breakpoint	Behavior
`>= 1024px`	Full header as shown
`768px - 1023px`	Cmd+K label shortens to icon only `[search]`
`< 768px`	Nav tabs collapse into hamburger (future)

Content area is always max-w-7xl mx-auto px-4 sm:px-6 lg:px-8.

Global Components (rendered in root layout)

<Toaster> (sonner) — bottom-right toast notifications
<ErrorBoundary> — wraps the page outlet
<CommandPalette> — overlay, triggered by Cmd+K or header button

Source

packages/web/src/routes/__root.tsx
packages/web/src/layouts/AppLayout.tsx
packages/web/src/components/ThemeToggle.tsx (proposed)
packages/web/src/components/CommandPalette.tsx (proposed)
packages/web/src/components/HealthDot.tsx (proposed)

7.3 KiB Raw Blame History