Nebula-OS/src/styles/shell-guidelines.md

Nebula Shell UI Guidelines (Dashboard Refresh)

Layout Structure

• Home uses a left-aligned horizontal tile rail (.tile-rail) with one primary row of large app tiles.
• Top bar is shared across shell views with brand left and time/profile right.
• Settings uses a horizontal category bar at top and card panel content below.
• Lock screen keeps immersive centered time/date and reveals PIN panel on first input.

Animation Guidelines

• Use cubic-bezier curves only:
  • --nebula-ease-console: focus travel and panel transitions.
  • --nebula-ease-standard: opacity and ambient motion.
  • --nebula-ease-snap: press pulse feedback.
• Focus transitions target 120ms–180ms (--nebula-duration-fast / --nebula-duration-nav).
• Use transform/opacity for movement and avoid layout-triggering transitions.
• Page changes use .view to .view-entered slide-in transitions.
• Press feedback uses .is-pressed and uiPressPulse keyframes.

Component Breakdown

TopBar

• Class roots: .shell-topbar, .shell-brand, .shell-status, .shell-time, .shell-avatar, .shell-accent-line.
• Purpose: persistent identity + status + navigation-reactive accent line.
• Reactive token: --nebula-accent-line-x updates from focus manager.

TileRow

• Class root: .tile-rail.
• Purpose: horizontal app rail with controller-first left/right travel and smooth scroll.
• Behavior: focus auto-centers via scrollTo and updates parallax variables.

Tile

• Class roots: .tile, .dashboard-tile, .tile-icon, .tile-label, .tile-meta.
• Focus state: .is-focused scales tile and adds cyan glow outline.
• Press state: .is-pressed triggers pulse animation and hook events.

BackgroundLayer

• DOM root: #nebula-background with .nebula-layer children (gradient, starfield, fog, vignette).
• Purpose: animated nebula depth stack with subtle star motion and fog drift.
• Parallax token: --bg-parallax-x supports focus-driven depth shift.

FocusManager

• Implementation root: src/core/nav.js.
• Responsibilities:
  • Maintain focused element and directional navigation.
  • Apply .is-focused state and aria-selected.
  • Publish focus telemetry events (nebula-focus-change).
  • Update CSS vars (--nebula-accent-line-x, --nebula-focus-strength).

UI Hook Contract (No Audio Implementation)

• window CustomEvent("nebula-ui-hook") details:
  • type: "focus" | "move" | "accept" | "back"
  • Optional metadata (target, action, focusKey)
• Intended use: external UI audio/haptics bridge without coupling shell visuals to playback.