nexus/docs/NEXUS_DESIGN_SYSTEM.md

Nexus authenticated UI contract

/dashboard is the visual authority for authenticated Nexus surfaces. This contract keeps the remaining routes aligned without coupling presentation to stores, services, API contracts, route behavior, or domain state.

Sources of truth

• frontend/src/assets/nexus-tokens.css is the only source for Nexus color, surface, typography, radius, focus, status, and page-geometry tokens.
• frontend/src/assets/nexus-components.css is the shared presentation layer for the authenticated legacy shell and route families.
• components/layout/AppSidebar.vue is the single authenticated navigation component. Both frontend/src/App.vue and frontend/src/layouts/NexusLayout.vue render it.
• frontend/src/App.vue with components/layout/AppHeader.vue and frontend/src/layouts/NexusLayout.vue with components/layout/Topbar.vue own the two content shells around that shared navigation.
• /dashboard and /login retain their standalone content implementations; the dashboard no longer owns a separate sidebar implementation.

Do not add raw color values to migrated views. Add or reuse a semantic token in nexus-tokens.css, then consume that token from the component or shared layer. Legacy variables must resolve to V2 tokens rather than introduce a second palette.

Visual foundation

Concern	Contract
Background	Galaxy background over --space-0 for authenticated routes
Sidebar	248px desktop; overlay navigation at 900px and below
Topbar	62px, glass surface, persistent above route content
Body type	Manrope, 12px minimum for interface copy
Page title	Space Grotesk, 24px / 30px, weight 700
Metadata	JetBrains Mono, 11px minimum
Page inset	20px desktop, 14px mobile
Panel	--glass, --line, 14px radius, controlled blur
Standard page	1180px maximum
Workspace	1440px maximum
Reading/form surface	880px maximum
Focus	Visible :focus-visible outline using --a-blue and --focus-ring

Blue-to-violet gradients and glows are reserved for active navigation, primary actions, and meaningful operational states. Neutral cards, inputs, metadata, empty states, and destructive confirmation surfaces use plain glass and semantic status colors.

Navigation contract

• Every authenticated sidebar presents the categories Operations, Knowledge, Infrastructure, and Governance in that order.
• Render components/layout/AppSidebar.vue; do not introduce another authenticated sidebar component or duplicate its navigation data.
• Settings remains a persistent footer destination below the scrollable category list on every authenticated route.
• Use semantic RouterLinks for registered destinations and aria-current for the active item. Agent, Project, and Task details activate their parent navigation destination.
• Keep counts, labels, permissions, registered route targets, and logout behavior owned by AppSidebar and its existing stores/props.

Shared presentation vocabulary

• Use .nexus-page for standard route roots.
• Add .nexus-page--workspace only for horizontally or spatially dense work surfaces such as Task Board and Chat.
• Add .nexus-page--reading for detail, form, and notification surfaces.
• Use .nexus-page-header for route identity and local actions.
• Use .glass-panel or the route-family rules in nexus-components.css for panels.
• Keep loading, empty, error, warning, and success feedback inside the route frame. Existing copy and state guards remain authoritative.
• Use Lucide icons already present in the project. Do not use emoji, text glyphs, handcrafted SVGs, or icon-like CSS drawings.

Dashboard orchestration contract

• Live-Orchestrierung is the primary dashboard surface and owns the remaining workspace after the 62px topbar.
• Iris Chat is closed by default. Open it only through the topbar Iris Chat action and render it as a modal dialog; do not restore a persistent rail.
• Preserve the existing chat store, polling lifecycle, messages, send handler, error state, and thinking state when changing presentation.
• Keep operational status in one compact row and prioritize active, planning, and blocker signals on narrow layouts.
• Keep focus tasks in one compact row. Priority, state, title, and owner must remain visible or programmatically available.
• At 680px and below, agent nodes use the compact card variant. Auto-layout must not overlap or clip nodes at the supported breakpoints.
• Modal close by pointer and Escape must restore focus to the connected Iris trigger.

Responsive and accessibility rules

• At 900px and below, the sidebar becomes a keyboard-operable overlay and the topbar exposes the navigation toggle.
• At 1024px and below, multi-column detail and settings layouts collapse presentationally without changing source order.
• At 767px and below, headers and action rows stack and the page inset becomes 14px.
• The document must never overflow horizontally at 375, 768, 1024, 1440, or 1920px.
• Internal horizontal scrolling is allowed only for a domain-horizontal work surface, currently the Task Board columns.
• Every icon-only control needs an accessible name. Interactive cards must use link/button semantics and offer Enter/Space keyboard equivalence as appropriate.
• Preserve existing v-model, handlers, emits, navigation destinations, permissions, and state transitions.

Route-family mapping

Family	Routes
List/detail	Memory, Docs, Incidents, Calendar, Security
Grid/overview	Agents, Projects, Models, Activity, Notifications
Detail/form	Agent Detail, Project Detail, Task Detail, Settings
Workspace	Task Board, Chat

When adding a route, choose the closest family, apply the shared root class, verify loading/empty/error states, and test the registered destination at all required breakpoints before adding navigation.