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.