# Roadmap: HoloHue

## Overview

HoloHue delivers a cyberpunk-aesthetic GUI framework for Rust developers through 7 phases following a strict dependency chain: foundation scaffold, then theme tokens (consumed by everything visual), then core components (animation targets must exist as DOM), then animation choreography (needs targets), then virtual window manager (needs choreography for spawn/close), then soundscape (cues embed in choreography sequences), and finally the remaining components plus the demo application that proves the whole system works. Each phase delivers a coherent, independently verifiable capability.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [ ] **Phase 1: Foundation and Project Scaffold** - Tauri monorepo, IPC bridge, asset pipeline, GPU acceleration, and cross-platform window chrome validation
- [ ] **Phase 2: Theme System** - CSS custom property token architecture, default cyberpunk theme, font pairing, and runtime theme application
- [ ] **Phase 3: Core Components** - Cyberpunk window chrome and the 8 fundamental UI components consuming theme tokens
- [ ] **Phase 4: Animation Choreography** - GSAP-based choreography engine with named presets, ambient effects, and reduced-motion support
- [ ] **Phase 5: Virtual Window Manager** - DOM-based overlay subwindows with drag, resize, z-order, and lifecycle animations
- [ ] **Phase 6: Soundscape System** - Howler.js audio engine with interaction sounds, volume control, and opt-out capability
- [ ] **Phase 7: Full Component Library and Demo Application** - Remaining components, layout primitives, and the showcase demo that proves v1

## Phase Details

### Phase 1: Foundation and Project Scaffold
**Goal**: A working Tauri+SolidJS monorepo where Rust code can communicate with the webview, assets embed into the binary, GPU acceleration is enabled, and the cyberpunk window chrome renders correctly on Windows
**Depends on**: Nothing (first phase)
**Requirements**: WIN-05, PLAT-01, PLAT-02, PLAT-03
**Success Criteria** (what must be TRUE):
  1. Running `cargo build` produces a single binary that launches a borderless, frameless window with a SolidJS frontend rendered inside
  2. A Rust function call triggers a visible change in the webview (IPC bridge works bidirectionally)
  3. CSS animations in the webview run at 60fps with GPU acceleration enabled (no jank on transform/opacity transitions)
  4. All rendered lines, text, and UI elements are anti-aliased (no jagged edges visible at 1x and 2x DPI)
**Plans**: 2 plans

Plans:
- [x] 01-01-PLAN.md — Scaffold Tauri+SolidJS monorepo with frameless window, custom titlebar, GPU acceleration, and bidirectional IPC bridge
- [x] 01-02-PLAN.md — Build visual test harness (CSS animations, typography, SVG geometry, FPS counter) and verify Phase 1 success criteria

### Phase 2: Theme System
**Goal**: A two-tier CSS custom property token system where switching themes instantly re-skins all themed elements with zero JavaScript re-renders
**Depends on**: Phase 1
**Requirements**: THEM-01, THEM-02, THEM-03
**Success Criteria** (what must be TRUE):
  1. A default cyberpunk theme (dark, neon-on-void) applies automatically on launch with no developer configuration
  2. Changing the theme via a Rust API call swaps all colors, glows, and accents across the entire UI instantly (no flicker, no re-render)
  3. A monospace font and a display font are loaded and applied to appropriate elements by default
**Plans**: 2 plans

Plans:
- [x] 02-01-PLAN.md — Build two-tier CSS custom property token system (primitives + semantics), Tailwind v4 @theme inline integration, Fontsource font bundling (Fira Code + Share Tech), glow/effect tokens, and theme entry point
- [x] 02-02-PLAN.md — Migrate existing UI to theme tokens, add Rust set_theme IPC command, build ThemeDemo showcase component, and verify Phase 2 success criteria

### Phase 3: Core Components
**Goal**: The 8 foundational UI components and cyberpunk window chrome exist as styled, interactive SolidJS components consuming theme tokens
**Depends on**: Phase 2
**Requirements**: WIN-01, WIN-02, WIN-03, WIN-04, COMP-01, COMP-02, COMP-03, COMP-04, COMP-05, COMP-06, COMP-07, COMP-08
**Success Criteria** (what must be TRUE):
  1. A window displays angled/notched corners with a glowing perimeter line 6-8px inside the edge, a semitransparent background, and an optional dot-grid overlay
  2. All 8 core components (button, text input, label, toggle, slider, dropdown, panel, table) render with cyberpunk styling and respond to hover, focus, active, and disabled states
  3. Switching the theme causes every component to update its colors and glow effects instantly
  4. Components are keyboard-navigable (Tab to focus, Enter/Space to activate, Escape to dismiss)
**Plans**: 3 plans

Plans:
- [ ] 03-01-PLAN.md — Window chrome (angular corners, glow perimeter, dot-grid, scrollbar), shared component CSS foundation (interaction states, size system, color variants), install clsx
- [ ] 03-02-PLAN.md — Core UI components batch 1: Button, TextInput, Label, Toggle, Slider, Panel with full interaction states and keyboard accessibility
- [ ] 03-03-PLAN.md — Dropdown (solid-floating-ui + Portal), Table (sortable columns), ComponentDemo showcase, visual verification checkpoint

### Phase 4: Animation Choreography
**Goal**: A declarative choreography engine that plays multi-step animation sequences on components, with named presets for common interactions and ambient effects
**Depends on**: Phase 3
**Requirements**: ANIM-01, ANIM-02, ANIM-03, ANIM-04, ANIM-05, ANIM-06, ANIM-07, ANIM-08, ANIM-09, ANIM-10
**Success Criteria** (what must be TRUE):
  1. Opening a window plays a choreographed spawn animation (scale expand + glow line sweep + content flicker), and closing reverses it
  2. Clicking a button plays a visible double-blink + glow-fade sequence; hovering an interactive element shows a holographic shimmer
  3. Ambient effects (breathing glow on window edges, periodic ripple/splash) run continuously without user interaction
  4. Enabling "prefers-reduced-motion" in OS settings causes all animations to be replaced with instant static transitions
  5. An optional scanline/CRT overlay effect can be toggled on any window
**Plans**: TBD

Plans:
- [ ] 04-01: TBD
- [ ] 04-02: TBD

### Phase 5: Virtual Window Manager
**Goal**: Users can open, drag, resize, and close floating overlay subwindows within the main application window, with full lifecycle animations
**Depends on**: Phase 4
**Requirements**: WIN-06
**Success Criteria** (what must be TRUE):
  1. A developer can programmatically open overlay subwindows that float above the main content with proper z-order (clicking a panel brings it to front)
  2. Subwindows can be dragged by their title bar and resized by their edges, with smooth pointer tracking
  3. Opening and closing subwindows plays the choreographed spawn/close animations from Phase 4
**Plans**: TBD

Plans:
- [ ] 05-01: TBD

### Phase 6: Soundscape System
**Goal**: UI interactions produce audio feedback (clicks, hovers, transitions, errors) that can be globally muted or volume-adjusted, and the entire sound system can be disabled by the developer
**Depends on**: Phase 4
**Requirements**: SND-01, SND-02, SND-03
**Success Criteria** (what must be TRUE):
  1. Clicking buttons, hovering interactive elements, opening/closing windows, and encountering errors each produce distinct, thematic sound effects
  2. A global volume slider and mute toggle control all sound output; muting silences everything immediately
  3. A developer can disable the sound system entirely with a single configuration flag, and no audio code loads or executes
**Plans**: TBD

Plans:
- [ ] 06-01: TBD

### Phase 7: Full Component Library and Demo Application
**Goal**: The complete component set and layout system exist, and a demo application showcases every feature of HoloHue working together
**Depends on**: Phases 5 and 6
**Requirements**: COMP-09, COMP-10, COMP-11, COMP-12, COMP-13, COMP-14, COMP-15, LAYO-01, LAYO-02, LAYO-03, LAYO-04, LAYO-05, DEMO-01
**Success Criteria** (what must be TRUE):
  1. All remaining components (modal, tooltip, progress bar, tabs, breadcrumbs, notification toast, image frame) render with full cyberpunk styling and animations
  2. A grid-based layout with split panes, resizable panels, a status bar, and styled scroll containers can compose components into a dashboard
  3. The demo application displays a multi-panel dashboard with subwindows, theme switching, sound effects, animations, and every component type visible and interactive
  4. A new Rust developer can clone the repo, run `cargo build && cargo run`, and see the full demo without additional setup
**Plans**: TBD

Plans:
- [ ] 07-01: TBD
- [ ] 07-02: TBD
- [ ] 07-03: TBD

## Progress

**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7
(Phases 5 and 6 could execute in parallel; Phase 7 depends on both.)

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation and Project Scaffold | 2/2 | Complete | 2026-02-25 |
| 2. Theme System | 2/2 | Complete | 2026-02-28 |
| 3. Core Components | 0/? | Not started | - |
| 4. Animation Choreography | 0/? | Not started | - |
| 5. Virtual Window Manager | 0/? | Not started | - |
| 6. Soundscape System | 0/? | Not started | - |
| 7. Full Component Library and Demo Application | 0/? | Not started | - |