GAIA UI redesign

​

Product boundary

​

One design language across all three surfaces

​

Original palette: graphite, ivory, copper

​

What the current code establishes

​

Design reference and the smallest useful UI

┌──────────────────┬────────────────────────────────────────────┐
│ GAIA             │ Conversation title                     ··· │
│                  │                                            │
│ + New chat       │ > Summarize this document                  │
│ Search           │                                            │
│                  │ GAIA's clear, readable response            │
│ Recent chats     │ Sources or a useful result, when relevant  │
│ Travel planning  │                                            │
│ Document summary │ ▸ Read 3 documents                         │
│                  │                                            │
│                  │ ┌────────────────────────────────────────┐ │
│                  │ │ > Ask GAIA anything…                   │ │
│ Settings         │ │ +                     Local · Model  ↑ │ │
│                  │ └────────────────────────────────────────┘ │
└──────────────────┴────────────────────────────────────────────┘

​

Keep, remove, and reveal only when needed

​

Interaction rules

• Start: open straight into the conversation shell. A new chat has an immediately usable composer once ready. Show setup guidance only for an actual blocker; do not animate a welcome sequence before accepting input.
• Ask: multiline composer, Enter to send, Shift+Enter for newline, attachment chips with progress/removal, and a Send/Stop button reflecting real run state. Starter prompts fill the composer and wait for submission. Preserve draft text.
• Follow: answers stay on the open canvas. One expandable activity summary shows what GAIA is doing. Keep scrolling under the reader’s control when they look back.
• Respond: questions and approvals appear inline at the moment needed. Show the question or exact action clearly and only choices the agent actually supports. A reply resumes that run; it does not create another conversation.
• Use the result: show readable answers, citations, and existing result cards inline. Open/download an attachment when selected. No new preview workspace, split panes, terminal panel, or review surface in v1.
• Recover: say what failed and what to do next. Retain the conversation and draft. Unknown/malformed results display an explicit diagnostic. Never automatically retry an action that may already have completed.

​

Visual constraints

• Dark-first charcoal surfaces, subtle borders, one restrained accent, consistent Lucide icons. Use the mascot sparingly; remove glow, hacker typing, and decorative status badges.
• Prototype a 240–260px collapsible sidebar and roughly 760px readable content width. Use 15–16px readable body text, a system monospace for composer input, prompt, labels and activity, generous spacing, and restrained rounding. Avoid heavy bubble chrome. These are starting points for visual review, not measurements of the screenshot. No simulated typing, ASCII dashboard, decorative blinking cursor, or dense command log.
• Evolve existing CSS variables and component CSS. No new design framework. Support light/dark/system appearance, reduced motion, visible keyboard focus, and accessible text contrast. Status must not depend on color alone.
• Keep the existing mobile spec’s 768px boundary and drawer navigation. At narrow widths or 200% zoom, the conversation/composer remain usable without horizontal page scrolling. Use 44px touch targets.
• Preserve existing voice access where supported; no new voice engine. Keep keyboard access to new chat, search, composer, and dismiss, with platform-specific shortcuts verified against browser conflicts. Stop remains an explicit action.

​

Parity contract and drift prevention

​

Transport and session scope

• Adapt the persistent flagship stdio/control transport in the web backend. It already supports approvals and live model commands, but needs correlated question responses added to both the agent control protocol and TUI subprocess client.
• Reuse the HTTP sidecar and its retained session registry. Persistence and input responses already exist; resumable approval and TUI-equivalent model switching need to be verified and completed before claiming parity.

• Session identity → owned agent process, working context, actual provider/model, loaded state, lifecycle, and the explicit limits of restart recovery.
• Run identity → canonical events, exactly one terminal outcome, bounded event retention, reader attachment, and cancel acknowledgement.
• Control request → session/run/request correlation, permitted choices, expiry, single-use reply handling, and rejection of stale/cross-session requests.
• Capability report → available commands, render types, supported input methods, provider readiness, and whether a pending gate can actually be answered.

​

Delivery sequence

​

Test and review bar

• Extend existing Vitest/Testing Library suites for default routing, legacy task retention, run-state transitions, keyboard access, cards, drafts, and scrolling.
• Add integration coverage for any backend adapter/control endpoints, including stale approvals, cross-session replies, process failure, and duplicate submissions.
• Replay a shared JSON fixture corpus in Go and TypeScript, plus adapter tests in Python. Schema/behavior changes require both clients’ expectations to be reviewed.
• Run browser and Electron golden journeys: start → attach document → ask → answer question → review/approve action → inspect output → follow up → stop → reopen. Also cover offline startup and remote-provider state. Use isolated test data.
• Test the website’s navigation, keyboard access, responsive layout, and current download selection; run its existing Vitest suite and Astro check/build. Test TUI wrapping, input, questions, approvals, status, and theme contrast at 80×24 and larger sizes, including limited-color terminals. Run affected Go tests.
• Before the implementation PR is ready for review, inspect actual local renders, review the diff, and exercise functionality. Open the website and agent WebUI in browser tabs, launch Electron, and open the TUI in a terminal for a side-by-side showcase. Record startup instructions and leave the review instances running. Capture design evidence with test data; expose any unavailable platform checks. Gather user feedback and iterate before presenting the redesign as finished.
• Human usability target: at least 4 of 5 representative users can start a task, attach context, answer a decision, and find a previous task without coaching. Measure UI readiness separately from model startup; decorative animation must never delay input. Profile long transcripts with at least 1,000 activity events.
• Require code review, architecture review for transport/lifecycle changes, the repository’s automated reviewer, and human UX approval before implementation merges. Check stop-the-line paths again before each PR; consumer-critical issues need implementation-ready specs before work is assigned.

​

Explicit boundaries and decisions for review