Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Vibe Remote Web UI Redesign Plan
Branch:
feature/web-ui-redesignStatus: In progress Design source:design.pentop-levelvibe-remotescreens andVR/*reusable components Reference frontend:../avibe-bot-backendUI architecture and theme primitives
Summary
Vibe Remote's current Web UI is functionally useful but structurally behind the new product design.
The redesign will:
- rebuild the Web UI around the new
design.penconsole and wizard flows - support desktop, mobile, light, and dark variants from the start
- align frontend architecture with
avibe-bot-backendwithout migrating the runtime from Vite SPA to Next.js - move the UI to a reusable token + primitive + feature architecture so future
work across
vibe-remoteandavibe.botfeels like one product family
Goals
- Deliver a high-fidelity implementation of the new Vibe Remote Web UI from
design.pen - Keep Vibe Remote on
React + Vite + TypeScript + Tailwind v4 - Align visual tokens, component primitives, naming, and layout semantics with
avibe-bot-backend - Make light theme and mobile first-class architectural concerns instead of post-hoc patches
- Simplify future maintenance by separating page rendering from API and config persistence logic
Non-Goals
- Do not migrate
vibe-remote/uito Next.js - Do not proxy local Web UI traffic through
avibe.bot - Do not preserve the current route tree if it conflicts with the new information architecture
- Do not preserve the current page markup when a clean rewrite is simpler
Constraints and Product Decisions
- Vibe Remote remains a locally served Web UI bundled by the Python project.
- New architecture should be UI-homologous with
avibe-bot-backend, not framework-identical. Remote Accessis absorbed intoSettings -> Servicein the new design.- The redesign is allowed to introduce a new route hierarchy and shell.
- Frontend user-facing strings must continue to go through
ui/src/i18n/en.jsonandui/src/i18n/zh.json.
Current State
Current frontend stack in vibe-remote/ui:
- React 19 + Vite 7 + TypeScript 5
- Tailwind CSS v4
- React Router 7
- partial shadcn-style building blocks (
cn,popover,command,combobox) - page-level components still own too much fetch/save behavior
Current gaps vs. design:
- route map is flatter and narrower than the new console IA
- shell/navigation does not match the new desktop/mobile layouts
- theme tokens do not match the new product family tokens
- light/mobile are not built as first-class layout concerns
- there is no full primitive layer for cards, buttons, badges, tables, dialogs, settings rows, wizard progress, and console navigation
Reference Architecture Alignment
The new Vibe Remote UI should align with avibe-bot-backend in these areas:
- semantic theme tokens and naming
- Tailwind v4 token exposure via CSS custom properties
- shadcn/ui-style primitive layer
class-variance-authority-based variant composition where it reduces class duplication- component naming, spacing language, border/radius system, and page shell vocabulary
The new Vibe Remote UI should intentionally differ in these areas:
- keep Vite SPA routing instead of Next.js App Router
- keep client-side API access to the local Vibe Remote Web UI backend
- avoid server-component or server-action assumptions
Target Information Architecture
Main routes
/dashboard/groups/users/logs/settings/service/settings/platforms/settings/backends/settings/messaging/settings/diagnostics
Setup routes
/setup/setup/:step
Mapping from old UI
- old
/doctorconcepts split intoSettings -> DiagnosticsandLogs - old
/doctor/logsmoves to/logs - old
/remote-accessmoves intoSettings -> Service
Design Source Mapping
Primary top-level screen families detected in design.pen:
- Dashboard
- Channels
- Users
- Logs
- Settings: Service / Platforms / Backends / Messaging / Diagnostics
- Wizard: Welcome / Backends / Platforms / Slack creds / Channels / Summary
Primary reusable VR/* design components:
VR/SidebarVR/RoutingConfigVR/CM/BackendsVR/CM/ServiceVR/CM/PlatformsVR/CM/MessagingVR/CM/Diagnostics
These should drive implementation structure rather than be treated as mere visual references.
Reuse Interpretation from Design
The design intentionally reuses the same configuration modules across setup and settings. Do not fork business UI just because a module appears in two flows.
Shared module surfaces:
- platform choice and platform credential setup share the
VR/CM/Platformsinteraction model across Wizard andSettings -> Platforms - backend detection, CLI path editing, default Agent selection, and install
affordances share
VR/CM/Backendsacross Wizard andSettings -> Backends - messaging rows, diagnostics checks, routing configuration, and service runtime
controls should map to their
VR/CM/*modules wherever the same controls appear
Container-specific surfaces:
- Wizard owns setup chrome: progress bar, step badge, Back/Next/Skip actions, and first-run guidance copy
- Settings owns console chrome: sidebar, settings tabs, save/autosave actions, and persistent management copy
- Dashboard, Groups, Users, and Logs should not reuse Wizard containers; they reuse only lower-level rows, badges, buttons, routing controls, and data display primitives
Implementation rule: extract reusable configuration modules first, then render them through Wizard or Settings adapters. Avoid copying save/validation logic, but also avoid embedding a whole Wizard step inside Settings unchanged.
Target Frontend Structure
ui/src/
app/
AppProviders.tsx
router.tsx
shell/
api/
client.ts
config.ts
settings.ts
users.ts
logs.ts
doctor.ts
remote-access.ts
components/
ui/
shared/
features/
dashboard/
groups/
users/
logs/
settings/
setup/
context/
hooks/
i18n/
lib/
theme/
utils/
routes/
platforms/
layout/
Execution Plan
Phase 0: Foundation and Safety
- create isolated git worktree
- write plan and lock route + architecture decisions
- inspect current API surface and preserve working behaviors
Phase 1: Theme and Primitive Alignment
- replace current global tokens with the new shared product token system
- add light/dark theme support based on
data-theme - align fonts, radii, border strengths, surfaces, gradients, and focus rings
- add missing primitives inspired by
avibe-bot-backend:- button
- badge
- card
- input
- label
- separator
- dialog
- table/list building blocks
Phase 2: App Shell and Routing Rewrite
- rebuild route tree around the new IA
- replace the current shell with the design-driven desktop sidebar and mobile bottom navigation
- add shared page header, section, stats, status, and settings-row primitives
Phase 3: Setup Wizard Rewrite
- implement the new wizard layout and step flow
- map current setup state and persistence logic into the new feature structure
- keep API behavior correct while replacing page markup and routing
Phase 4: Console Pages Rewrite
- implement Dashboard
- implement Channels
- implement Users
- implement Logs
- implement Settings pages:
- Service
- Platforms
- Backends
- Messaging
- Diagnostics
Phase 5: Mobile and Light Polish
- verify all routes for mobile layout correctness
- verify light theme semantic contrast and component parity
- fix page-specific overflow, density, and interaction issues
Phase 6: Validation and Packaging
npm run buildinui/- targeted manual preview of new routes
- local Incus regression when user-facing behavior needs end-to-end confirmation
- ensure built assets still package correctly through the existing Python flow
Architectural Rules During Implementation
- Pages should not own raw fetch orchestration when a feature-level hook or API module can own it.
- Visual primitives should be reusable across pages; avoid one-off page-only button/card/input variants unless the design truly requires it.
- Mobile and light theme support must be validated while building each feature, not deferred until the very end.
- Existing backend API contracts should remain intact unless a separate backend change is explicitly required.
- Prefer replacing whole legacy page implementations when incremental patching would leave structural debt behind.
Initial Implementation Order
- Theme tokens + primitive layer
- New app shell + route map
- Setup wizard screens
- Dashboard
- Settings pages
- Channels / Users / Logs
- Mobile/light cleanup and QA
Risks
- Large route and layout rewrite may temporarily break navigation if done in the wrong order.
- Current components mix rendering and data writes; careless migration can cause silent config regression.
- Font parity and gradients matter to perceived fidelity; token alignment alone is not enough.
- Mobile table/list behavior likely needs design-aware reinterpretation rather than literal desktop compression.
Success Criteria
- New console visually matches the design direction across desktop/mobile and light/dark.
- Vibe Remote and
avibe.botlook and feel like one product family. - The UI codebase is easier to maintain because primitives, theme, routing, and feature logic are clearly separated.
- The local packaging model remains intact.