USER-INTERFACE.md

User Interface

1. Enduring vision, principles, and rationale

WorldSharp is dark-first with restrained violet accents. Dark mode is the application baseline rather than a device-dependent alternate, giving desktop and mobile a predictable visual system.

WorldSharp uses self-hosted Lucide icons, matching its LLMToy and Marinara lineage. Icons support labels rather than replacing them except for familiar, accessible controls. The application does not require a JavaScript icon runtime or public icon CDN.

Interaction rules:

• prefer native HTML and shared CSS before adding a component framework;
• retain text labels for navigation and consequential actions;
• give icon-only controls an accessible name and tooltip;
• use the shared Icon component rather than copying SVG paths;
• keep Lucide's native 0 0 24 24 viewport;
• maintain at least 44px touch targets and mobile safe-area spacing;
• keep color roles in CSS custom properties rather than page-local colors;
• use WorldSharp.UI.Avatar for identity artwork and fallback initials.

The UI should expose domain truth rather than inventing it. Imported history is read-only because exact source IDs and ordering support reconstruction. Scene state, archive state, Persona grouping, and time boundaries must come from Core and feature services.

2. Proposed and future experience

The persistent shell and drawer/tool rationale is detailed in UI Architecture. The intended result is an active Interface that remains visibly present while navigation, settings, and tools open around it.

Convo should remain a familiar direct-message experience: one composer sends the user message and requests a Character reply, while generation appears when the latest user message lacks one. Character identity should replace generic role labels. Generation feedback belongs inline and must not block navigation or pretend an inline operation is already a durable background job.

Messages use readable row-based presentation rather than speech bubbles. Desktop hover or mobile tap can reveal copy, edit, generate, and timeline-fork controls. Edits need explicit save/cancel and an edited marker. Imported rows show provenance/read-only status instead. The latest locally authored Character response exposes inline previous/next version controls and an alternate generation action. Selecting a version keeps the same transcript message and does not append a new turn; imported source alternatives remain a read-only provenance view.

Convo settings belong near the Interface header and own chat-specific fields such as title, Persona, and optional system prompt. Provider-wide sampling defaults do not belong there.

Alternate conversation timelines belong in a right-side drawer on desktop and a fullscreen surface on mobile; they must not clutter the Universe Interface list. The drawer distinguishes the path being viewed from the one being continued. Choosing an available path persists it as the Interface's continuation. A path behind an already wrapped day/Scene boundary must explain that continuing there requires a duplicated, rolled-back Universe rather than presenting a cryptic branch conflict.

The global Library should remain a home for reusable content rather than fragmenting each content kind into unrelated navigation. Character Cards are the implemented first section; future Lorebook, Persona, Scenario, and Content Pack libraries should join only when their domain models exist.

The desired mobile Universe landing prioritizes comprehension: Universe/time identity, Interfaces, a compact world tree with Character identity rows, recent canonical commits and pending reviews, then advanced editors. Character Instances should not be repeated in a separate active-character list; their linked World Nodes are the place to navigate and edit Universe-specific knowledge. Cross-tree relationships are better shown in a selected-node detail surface than drawn as an unreadable graph on a phone.

3. Current implementation, status, and known gaps

The current UI is Blazor WebAssembly over host HTTP APIs. It uses shared CSS, Lucide sprite icons, and the shared Avatar component. The global frame has a desktop rail and mobile bottom navigation; Universe workspaces additionally use a responsive sidebar/left drawer.

Implemented surfaces include:

• Library tabs for Installed cards, Chub, bounded Folder discovery, and Upload or manual creation, with the installed-card browser reused by the Universe add-character picker;
• editable Character Cards with clear deletion protection while instances reference them, plus a history-backed Remove from Universe action on Character world-node rows; removing an instance never deletes its reusable Library Card;
• Convo, the shared Roleplay workspace (durable or bounded Scene), Social Feed, summaries, tracker, import, Persona, and provider screens where their features supply client routes;
• a Convo transcript with Character avatars, settings, edit/generate controls, per-message timeline forks, a complete conversation-family tree, one persisted continued path, edited markers, and correctly distinguished non-selected, imported, shared-history, and legacy-frozen read-only rows;
• Universe time controls, Interface navigation, a containment tree whose Character rows open the shared World Node editor, Character placement, relationships, history links, and tracker review;
• imported Marinara attachment display with managed URLs and source metadata.

The current Convo domain allows one or more Characters despite the one-to-one DM product ideal. Attachments are import data; there is no general attachment authoring promise. Native response swipes are available only for the latest locally authored Character response on the selected, active, unwrapped timeline. There is no universal right drawer, extension topbar tool contract, Persona-grouped Interface list, complete active/inactive lifecycle, or complete persistent three-region shell.