---
name: nexus-ui-engine
description: Design System & Component rules for Blazor
---
# UI Standards

- **Atomic Design:** 
  - Build reusable components in `NexusReader.UI.Shared/Components`.
  - `Atoms`: Base elements (`NexusButton`, `NexusIcon`, `NexusTypography`).
  - `Molecules`: Small groups (`AiAssistantBubble`, `KnowledgeCheck`).
  - `Organisms`: High-level sections (`KnowledgeGraph`, `ReaderCanvas`).

- **Styling & Isolation:** 
  - Mandatory use of scoped CSS (`.razor.css`).
  - Strict compliance: Zero inline `<style>` tags are allowed in `.razor` files.
  - No global CSS except for design tokens in `app.css`.
  - Use `::deep` only when absolutely necessary to style child components.

- **Design System (Nexus Neon):**
  - **Color Palette:**
    - Primary Accent: `--nexus-neon` (`#00ff99`) - Used for borders, highlights, and icons.
    - Neon Glow: `--nexus-neon-glow` / `--nexus-primary-glow` (`rgba(0, 255, 153, 0.3)`).
    - Dark Mode: `--nexus-bg` (`#0a0a0a`), `--nexus-card` (`#141414`).
    - Light Mode: `--nexus-bg` (`#f8f9fa`), `--nexus-card` (`#ffffff`).
    - **No Brand Splitting:** Strict ban on custom purple/indigo/cyan elements or hardcoded accent colors (like `#7c3aed`, `#4c1d95`, `#00b3ff`) on dashboard pages. Neutral/glass surfaces (`rgba(255, 255, 255, 0.05)`) must be used for secondary elements to preserve contrast and ensure the AI/neon-green elements are the focal point.
  - **Buttons:**
    - Must inherit from the global `.btn-nexus` class in `app.css`.
    - Primary Button: `.btn-nexus-primary` (background: `var(--nexus-neon)`, text color: `#000`).
    - Secondary Button: `.btn-nexus-secondary` (background: `rgba(255, 255, 255, 0.05)`, border: `1px solid rgba(255, 255, 255, 0.1)`, text color: `#fff`).
    - Hover Interaction: `transform: translateY(-2px)`, increased brightness, and a signature primary neon glow shadow.
  - **Typography:**
    - UI Elements: `Inter` (Sans-Serif) for controls, menus, and labels.
    - Reading Content: `Merriweather` (Serif) with `line-height: 1.65` and `letter-spacing: -0.01em` for high readability.
  - **Effects:**
    - Subtle neon glows (`box-shadow: 0 0 15px rgba(0, 255, 153, 0.3)`).
    - Glassmorphism for overlays and modals.

- **Adaptive Layouts:**
  - Support `.platform-mobile` and `.platform-desktop` context classes.
  - Handle safe-area insets (`--safe-area-inset-*`) for mobile devices.
  - **Immersive Reader (Zen Mode):**
    - Centered content flow: `max-width: 800px`, `margin: 0 auto`.
    - Paper-white background: `#F9F9F9` for light mode reader canvas.
    - Dedicated Scrollbars: Custom styled, thin scrollbars with `--nexus-neon` accents.
    - Reachability: Large `padding-bottom` (e.g., `15rem`) to ensure comfortable reading of end-of-page content.

- **Accessibility (A11y):**
  - Touch Targets: Min `44x44px` on mobile (enforced via CSS variables).
  - Contrast: Minimum ratio of 4.5:1.
  - Semantic HTML: Use appropriate tags (`<button>`, `<article>`, `<nav>`).

- **Interactive Flow:**
  - AI Assistant interactions must be non-blocking and smoothly transition using CSS animations.
  - Interactive elements must have clear `:hover`, `:active`, and `:focus` states.
  - **Glass Panel Standard:** All primary data panels (`.glass-panel`) must implement the following global parameters from `app.css` (only local modifiers like padding and hover offsets should live in scoped CSS):
    - Background: `rgba(20, 20, 20, 0.85)` (fallback) / `rgba(255, 255, 255, 0.03)` with `backdrop-filter: blur(10px)` when supported.
    - Border: `1px solid rgba(255, 255, 255, 0.05)`.
    - Border Radius: `var(--radius-xl)`.
    - Transition: `all 0.3s cubic-bezier(0.4, 0, 0.2, 1)`.
    - `:hover` state: `transform: translateY(-4px)` (or local offset) and highlight accent `border-color: rgba(0, 255, 153, 0.2)`.