nsaspy/a0-symbolics
1
1
Fork 0
Code Issues 140 Pull requests 7 Projects Releases Packages Wiki Activity Actions 1

EPIC: Rebuild the Symbolics WebUI without sacrificing plugin-level UI control #23

New issue
Open
opened 2026-08-24 00:46:59 +00:00 by lost-rob0t · 0 comments
lost-rob0t commented 2026-08-24 00:46:59 +00:00 (Migrated from github.com)
Copy link

Goal

Design and implement a modern Agent Zero WebUI while preserving the defining capability that plugins can materially extend and modify the interface.

This is not just a visual reskin. The current WebUI has accumulated strong plugin contracts (<x-extension>, JS extension hooks, <x-component>, modal/surface APIs, runtime extension manifests) but the core shell/navigation does not scale cleanly to large chat collections and is difficult to evolve as a coherent product surface.

Design principles

Modern core experience

  • clean, dense-but-readable visual hierarchy
  • responsive desktop/mobile shell
  • first-class keyboard navigation/command palette
  • strong chat/task/project navigation
  • clear running/paused/error/status treatment
  • modern settings/model/profile/project surfaces
  • accessibility and reduced-motion support
  • consistent design tokens and primitives rather than component-local one-offs

Plugins remain first-class

A redesign must not turn plugins into a few decorative buttons. Plugins need a documented, stable ability to contribute to or replace meaningful regions of the UI.

Preserve existing extension IDs/hooks through a compatibility layer and define a public slot/surface contract for at least:

  • global navigation / command palette entries
  • chat navigator rows, badges, filters, groups, actions and context menus
  • task navigator rows/actions
  • top bar / status rail
  • composer controls
  • message/process-step renderers and decorations
  • right-side/work surfaces
  • modals/settings pages
  • themes/design-token overlays where safe
  • plugin-owned full surfaces/pages

Plugins should be able to register capabilities declaratively from the existing runtime extension manifest rather than monkey-patching core DOM.

Performance is an API requirement

Plugin extension points on large lists or streaming DOM paths need explicit performance contracts. A plugin must not force the core to re-sort 10,000 chats once per row or rescan the whole document on every token.

Compatibility

Current contracts under webui/AGENTS.md and webui/js/AGENTS.md are migration constraints:

  • existing <x-extension id="..."> breakpoints
  • callJsExtensions() hook names/mutable contexts
  • <x-component> loader
  • modal/surface APIs
  • same-origin/offline-capable assets
  • Alpine store compatibility for existing bundled/third-party extensions

Do not require all plugins to rewrite on day one. If the core shell architecture changes, ship a compatibility adapter and explicit deprecation/version policy.

Framework choice is secondary to the plugin ABI. Do not casually rewrite to React/Vue/etc. if doing so strands the existing extension ecosystem; any framework change requires an ADADR design proving compatibility, performance, and migration.

2026-08-24 full-UI redesign directive

This epic is now a whole-product visual and interaction redesign, not incremental cleanup.

Use Impeccable-style design discipline as the working quality bar: establish clear product hierarchy first, avoid generic dashboard/card soup, use deliberate typography/spacing, keep decoration subordinate to function, then run explicit critique/audit/hardening/polish passes before calling a surface done.

Product direction

Symbolics should feel like a serious symbolic-agent workstation rather than an upstream Agent Zero skin.

The default desktop composition should prioritize:

  1. active conversation/work surface;
  2. agent/run state and symbolic context state;
  3. project/chat/task navigation;
  4. tools/artifacts/debug surfaces only when needed.

Do not permanently consume large areas for controls that are rarely touched. Prefer compact rails, command surfaces, progressive disclosure, and contextual panes.

Required redesign surfaces

  • global shell and responsive layout
  • left navigation/chat/task hierarchy
  • welcome/new-chat surface
  • chat message/process rendering
  • composer/input controls
  • top/status rail
  • project/profile/model selectors
  • settings navigation and forms
  • plugin management/configuration
  • system jobs/tasks
  • memory/knowledge surfaces
  • right canvas/work surfaces
  • errors/retries/paused/running states
  • empty/loading/offline states
  • mobile layout used by Android WebView

Symbolics-specific status

The UI should surface symbolic runtime state without flooding the user with implementation detail.

Useful inspectable status includes:

  • Prolog-RLM ready/degraded/off
  • current provider/model
  • current context budget and actual projected tokens
  • active symbolic tools/capabilities
  • live task/run state
  • memory KB status
  • debug I/O capture state from #59

Detailed traces belong behind an inspector/developer surface, not the main chat chrome.

Developer/debug integration

Developer Settings must include the raw debug capture controls from #59 and make the danger/state visually unambiguous. When raw I/O capture is enabled, show a persistent but compact indicator so the user cannot forget sensitive logging is active.

Accessibility and interaction quality

  • keyboard-first navigation for desktop
  • visible focus treatment
  • sensible tab order
  • WCAG-aware contrast
  • reduced-motion support
  • no hover-only critical controls
  • minimum touch targets on mobile
  • responsive behavior verified at phone, tablet, laptop and wide desktop sizes

Design verification

A substantial redesign slice is not done from code inspection alone. Capture/render the actual UI and perform a design QA pass against the intended hierarchy and states. Validate both dark and light modes and at least one narrow mobile viewport.

Architecture work

Use the repository ADADR control plane (roam/, once #17 lands) to define:

  • UI shell ownership and state boundaries
  • slot/surface registry
  • extension capability/version negotiation
  • event/state contracts
  • performance budgets
  • theme/design-token contract
  • backwards-compatibility adapter
  • failure isolation for broken plugins
  • testing strategy for core + plugin combinations

Acceptance

  • Modern shell/design spec approved through ADADR.
  • Existing public/bundled extension points are inventoried before redesign.
  • Stable versioned plugin UI capability/slot registry exists.
  • Legacy x-extension / JS hooks continue working through documented compatibility or are migrated with an explicit supported path.
  • Plugins can add/replace meaningful UI surfaces, not just append controls.
  • One broken/slow plugin cannot permanently break initial shell rendering; failures are isolated/diagnosable.
  • UI has defined frame/render/startup budgets and large-chat benchmarks.
  • Desktop and mobile accessibility gates exist.
  • Core surfaces share a consistent tokenized design system.
  • Modern chat navigation work integrates with the large-chat performance/catalog issues rather than rendering the full corpus.
  • Main shell, welcome screen, chat, composer, settings and plugin surfaces are visually redesigned as one coherent product.
  • Symbolics runtime/context/memory state is inspectable without cluttering the main workspace.
  • Debug I/O enabled state from #59 is visible and cannot be forgotten accidentally.
  • Dark/light and desktop/mobile states are visually QA'd before merge.
  • Existing plugin UI compatibility remains a release gate.
## Goal Design and implement a modern Agent Zero WebUI while preserving the defining capability that plugins can materially extend and modify the interface. This is not just a visual reskin. The current WebUI has accumulated strong plugin contracts (`<x-extension>`, JS extension hooks, `<x-component>`, modal/surface APIs, runtime extension manifests) but the core shell/navigation does not scale cleanly to large chat collections and is difficult to evolve as a coherent product surface. ## Design principles ### Modern core experience - clean, dense-but-readable visual hierarchy - responsive desktop/mobile shell - first-class keyboard navigation/command palette - strong chat/task/project navigation - clear running/paused/error/status treatment - modern settings/model/profile/project surfaces - accessibility and reduced-motion support - consistent design tokens and primitives rather than component-local one-offs ### Plugins remain first-class A redesign must **not** turn plugins into a few decorative buttons. Plugins need a documented, stable ability to contribute to or replace meaningful regions of the UI. Preserve existing extension IDs/hooks through a compatibility layer and define a public slot/surface contract for at least: - global navigation / command palette entries - chat navigator rows, badges, filters, groups, actions and context menus - task navigator rows/actions - top bar / status rail - composer controls - message/process-step renderers and decorations - right-side/work surfaces - modals/settings pages - themes/design-token overlays where safe - plugin-owned full surfaces/pages Plugins should be able to register capabilities declaratively from the existing runtime extension manifest rather than monkey-patching core DOM. ### Performance is an API requirement Plugin extension points on large lists or streaming DOM paths need explicit performance contracts. A plugin must not force the core to re-sort 10,000 chats once per row or rescan the whole document on every token. ## Compatibility Current contracts under `webui/AGENTS.md` and `webui/js/AGENTS.md` are migration constraints: - existing `<x-extension id="...">` breakpoints - `callJsExtensions()` hook names/mutable contexts - `<x-component>` loader - modal/surface APIs - same-origin/offline-capable assets - Alpine store compatibility for existing bundled/third-party extensions Do not require all plugins to rewrite on day one. If the core shell architecture changes, ship a compatibility adapter and explicit deprecation/version policy. Framework choice is secondary to the plugin ABI. Do not casually rewrite to React/Vue/etc. if doing so strands the existing extension ecosystem; any framework change requires an ADADR design proving compatibility, performance, and migration. ## 2026-08-24 full-UI redesign directive This epic is now a **whole-product visual and interaction redesign**, not incremental cleanup. Use Impeccable-style design discipline as the working quality bar: establish clear product hierarchy first, avoid generic dashboard/card soup, use deliberate typography/spacing, keep decoration subordinate to function, then run explicit critique/audit/hardening/polish passes before calling a surface done. ### Product direction Symbolics should feel like a serious symbolic-agent workstation rather than an upstream Agent Zero skin. The default desktop composition should prioritize: 1. active conversation/work surface; 2. agent/run state and symbolic context state; 3. project/chat/task navigation; 4. tools/artifacts/debug surfaces only when needed. Do not permanently consume large areas for controls that are rarely touched. Prefer compact rails, command surfaces, progressive disclosure, and contextual panes. ### Required redesign surfaces - global shell and responsive layout - left navigation/chat/task hierarchy - welcome/new-chat surface - chat message/process rendering - composer/input controls - top/status rail - project/profile/model selectors - settings navigation and forms - plugin management/configuration - system jobs/tasks - memory/knowledge surfaces - right canvas/work surfaces - errors/retries/paused/running states - empty/loading/offline states - mobile layout used by Android WebView ### Symbolics-specific status The UI should surface symbolic runtime state without flooding the user with implementation detail. Useful inspectable status includes: - Prolog-RLM ready/degraded/off - current provider/model - current context budget and actual projected tokens - active symbolic tools/capabilities - live task/run state - memory KB status - debug I/O capture state from #59 Detailed traces belong behind an inspector/developer surface, not the main chat chrome. ### Developer/debug integration Developer Settings must include the raw debug capture controls from #59 and make the danger/state visually unambiguous. When raw I/O capture is enabled, show a persistent but compact indicator so the user cannot forget sensitive logging is active. ### Accessibility and interaction quality - keyboard-first navigation for desktop - visible focus treatment - sensible tab order - WCAG-aware contrast - reduced-motion support - no hover-only critical controls - minimum touch targets on mobile - responsive behavior verified at phone, tablet, laptop and wide desktop sizes ### Design verification A substantial redesign slice is not done from code inspection alone. Capture/render the actual UI and perform a design QA pass against the intended hierarchy and states. Validate both dark and light modes and at least one narrow mobile viewport. ## Architecture work Use the repository ADADR control plane (`roam/`, once #17 lands) to define: - UI shell ownership and state boundaries - slot/surface registry - extension capability/version negotiation - event/state contracts - performance budgets - theme/design-token contract - backwards-compatibility adapter - failure isolation for broken plugins - testing strategy for core + plugin combinations ## Acceptance - [ ] Modern shell/design spec approved through ADADR. - [ ] Existing public/bundled extension points are inventoried before redesign. - [ ] Stable versioned plugin UI capability/slot registry exists. - [ ] Legacy `x-extension` / JS hooks continue working through documented compatibility or are migrated with an explicit supported path. - [ ] Plugins can add/replace meaningful UI surfaces, not just append controls. - [ ] One broken/slow plugin cannot permanently break initial shell rendering; failures are isolated/diagnosable. - [ ] UI has defined frame/render/startup budgets and large-chat benchmarks. - [ ] Desktop and mobile accessibility gates exist. - [ ] Core surfaces share a consistent tokenized design system. - [ ] Modern chat navigation work integrates with the large-chat performance/catalog issues rather than rendering the full corpus. - [ ] Main shell, welcome screen, chat, composer, settings and plugin surfaces are visually redesigned as one coherent product. - [ ] Symbolics runtime/context/memory state is inspectable without cluttering the main workspace. - [ ] Debug I/O enabled state from #59 is visible and cannot be forgotten accidentally. - [ ] Dark/light and desktop/mobile states are visually QA'd before merge. - [ ] Existing plugin UI compatibility remains a release gate.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
upstream/v2.12
feat/prolog-rlm-tool-flow
feat/upstream-replayable-model
fix/drop-forced-tool-choice-mid-stream
fix/boot-enable-symbolic-plugins
fix/prolog-rlm-pin-rlm_direct
fix/ui-scroll-autoscroll
fix/responses-upstream-tool-choice
feat/task-kb-and-run-reset
feat/runner-deploy-kit
feature/symbolics-runtime-mode
fix/dev-path-display-mapping
rage/43-context-id-containment
rage/33-log-secret-mask-fail-closed
ci/split-concurrency-lanes
feat/android-native-app-redesign
ci/serialize-heavy-jobs
fix/prolog-rlm-native-routing
fix/nix-mcp-rootless-tests
fix/ci-missing-actions
codex/issue-110
fix/persistent-home-restore
fix/context-compiler-unused
fix/native-responses-xml-tool-calls
fix/rlm-empty-query-runtime-error
feat/77-prolog-rlm-python-harness
fix/docker-oom-smoke-crash-loop
docs/sync-runtime-contracts-20260902
feat/zara-bridge-66
feat/chat-ui-rework
fix/launch-build-memory
chore/add-launch-script
fix/api-startup-smoke
feature/symbolics-live-ci-ui-debug-io
fix/openrouter-responses-system-jobs
rage/8-prolog-rlm-current-api
fix/android-default-localhost
fix/android-connection-ui
feature/issue-49-android-app
codex/move-prolog-adaptor
codex/sol-high-integration
fix/openrouter-prompt-cache-policy
fix/openrouter-reasoning-effort
chore/local-compose-example
feat/nix-cron-skill
bootstrap/context-debloat
feat/canonical-agent-pack
feat/symbolics-home-manager-image
No results found.
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
wontfix
This will not be worked on

No labels
accessibility
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
nsaspy/a0-symbolics#23
No description provided.