# 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.