23 KiB
StemEngine Web UI Redesign — MetroUI Plan
Redesign the StemEngine React frontend using the
MetroUI (@olton/metroui) component framework,
replacing the current Tailwind CSS utility-class approach with MetroUI's Metro Style
design language (flat, tile-based, high-contrast, strongly typographic).
Current Stack
| Layer | Current |
|---|---|
| Build | Vite 5 + TypeScript |
| Framework | React 18 |
| Styling | Tailwind CSS 3 + custom CSS variables (--brand-*) |
| Icons | lucide-react |
| Query | TanStack React Query 5 |
| Audio | Tone.js, @tonejs/midi, abcjs |
The Tailwind dependency is removed; everything else stays.
Why MetroUI
- Zero external dependencies — one CSS + one JS bundle, no tree-shaking puzzle.
- Metro Style matches the tool's technical, editor-like aesthetic better than a generic utility framework.
- Built-in dark theme —
data-theme="dark"on<html>, no custom variable juggling. - Rich component set already covers every current UI pattern: panels, tiles, appbar, sidenav, progress bars, sliders, dialogs, toasts, accordions, tabs, badges, activity indicators.
- Live Tiles — ideal for the project browser grid: each project tile can show job-status colour and animated activity indicator natively.
- CSS-class driven — React keeps all interactivity; MetroUI JS is only needed for a handful of overlay components (dialog, toast, window). No framework conflict.
Installation
npm install @olton/metroui
In main.tsx (replaces Tailwind imports in index.css):
import '@olton/metroui/dist/css/metro.css'
import '@olton/metroui/dist/css/icons.css'
// MetroUI JS (for dialog/toast/tooltip JS API)
import '@olton/metroui/dist/js/metro.js'
Remove from package.json:
tailwindcss,autoprefixer,postcsstailwind.config.js,postcss.config.js
The index.css file is reduced to:
- Custom scrollbar overrides
KaraokeEditorcanvas variables (these are purely internal and not Tailwind)- Any one-off layout rules not covered by MetroUI
Design Language Decisions
| Decision | Choice |
|---|---|
| Theme | Dark (data-theme="dark") by default; user can toggle to Light |
| Accent | Six Metro accent colours matching current set: Blue, Violet, Rose, Emerald, Amber, Cyan — applied via data-accent on <html> and MetroUI's built-in accent palette |
| Typography | Keep current font selection feature (Archivo, Inter, Poppins, etc.); MetroUI's font stack is overridden with the user's chosen font |
| Border radius | Metro default (minimal rounding, ~2–4 px) |
| Spacing | MetroUI grid (12-column) + flexbox utilities |
| Icons | Replace lucide-react with MetroUI icon font (<span class="mif-...">) or keep lucide SVGs as-is (both work) |
Layout Shell (App.tsx)
Current
Flex column: fixed header → flex row (collapsible sidebar + main content) → fixed footer.
Tab navigation (Separator / ProjectDetail / Settings) via activeTabId state.
MetroUI Redesign
┌─────────────────────────────────────────────────────┐
│ AppBar [≡ StemEngine] [GPU status] [⚙ Settings] │ ← metro appbar
├───────────┬─────────────────────────────────────────┤
│ │ │
│ SideNav │ Main content panel │
│ │ (routed view) │
│ Project │ │
│ list │ │
│ (tiles) │ │
│ │ │
├───────────┴─────────────────────────────────────────┤
│ GlobalAudioBar (fixed bottom strip) │
└─────────────────────────────────────────────────────┘
Key class mappings:
| Old | MetroUI |
|---|---|
fixed top-0 header div |
<div data-role="appbar"> |
| Sidebar div | <div data-role="sidenav-m3"> or custom vertical nav panel |
| Main content flex area | <div class="container-fluid"> with MetroUI grid |
| Footer credits | <div class="app-footer"> |
Navigation moves from tab buttons to AppBar action buttons + sidenav so the main content area is maximised.
Page: Separator
Current
Long vertical form: file upload zone → model accordion → format options → output settings → submit button.
MetroUI Redesign
Use a two-column panel layout:
┌──────────────────────┬────────────────────────────┐
│ Drop Zone │ Configuration Panel │
│ │ │
│ [Metro drop-zone │ ┌─ Model ──────────────┐ │
│ with dashed border │ │ accordion (closed) │ │
│ and icon] │ └──────────────────────┘ │
│ │ ┌─ Output Format ──────┐ │
│ Imported files list │ │ radio tiles │ │
│ (metro listview) │ └──────────────────────┘ │
│ │ ┌─ Stems ──────────────┐ │
│ │ │ slider group │ │
│ │ └──────────────────────┘ │
│ │ [Separate ▶] │
└──────────────────────┴────────────────────────────┘
MetroUI components:
| UI element | MetroUI |
|---|---|
| File drop zone | data-role="drop-zone" |
| Accordion sections | data-role="accordion" |
| Model radio tiles | Metro tile grid with data-role="radio" |
| Format select | data-role="select" |
| Level sliders | data-role="slider" with custom track labels |
| Job status | data-role="progress" + data-role="activity" spinner |
| Submit | <button class="button large primary"> |
| Toast notification | Metro toast API on job queue |
Page: ProjectDetail
Current
Vertical stack: stem file list → job action buttons → KaraokeEditor → DynamicMixPlayer → LyricsLivePreview — all in one scrollable column.
MetroUI Redesign
Resizable window panels — each major feature area is a collapsible Metro
data-role="panel" with a title bar, independently collapsible. Power users can
collapse all but the one they're working in.
┌── Project: "Song Title" ─────────────────────────── [↑ actions] ┐
│ │
│ ┌─ Stems ──────────────────────────────────── [▼] ────────────┐│
│ │ [stem tiles with colour-coded job badges] ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ Karaoke Editor ─────────────────────────── [▼] ────────────┐│
│ │ WaveformCanvas + TimingTable (unchanged internally) ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ Dynamic Mix ────────────────────────────── [▼] ────────────┐│
│ │ DynamicMixPlayer sliders + master gain ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ Lyrics Preview ─────────────────────────── [▼] ────────────┐│
│ │ LyricsLivePreview (unchanged internally) ││
│ └─────────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────────┘
MetroUI components:
| UI element | MetroUI |
|---|---|
| Panel sections | data-role="panel" with data-collapsible="true" |
| Stem tiles | Metro tile grid — colour indicates stem type |
| Job status badges | <span class="badge ..."> |
| Action buttons (transcribe, align, etc.) | <button class="button"> + data-role="dropdown" for multi-action |
| Job progress | data-role="progress" bar inside stem tile |
| File download links | <a class="button flat"> with icon |
Page: Settings
Current
Horizontal tab strip (Appearance / Models / Subsonic / Maintenance / Power / AutoPipeline) with tab panel content below.
MetroUI Redesign
Keep tabs but use MetroUI data-role="tabs" with a left-side vertical pill list
on desktop and collapsing to a data-role="select" dropdown on narrow viewports.
Appearance tab:
- Theme radio tiles (Dark / Light / System) — Metro style tiles with check mark
- Font select →
data-role="select"with preview label - Accent colour — a horizontal row of Metro colour tiles
Models tab:
data-role="listview"with group rows and expand/collapse- Progress bars inside each model row for download status
- Action buttons (Download / Pause / Cancel / Remove) inline
Subsonic tab:
- Metro form layout with
data-role="input"fields data-role="treeview"for the library browser
Maintenance tab:
data-role="accordion"grouping related cleanup actions- Each action: button + status badge + result count
Power tab:
- Metro form grid with labelled inputs and toggle switches
(
data-role="switch")
AutoPipeline tab:
- Step-builder as a sortable
data-role="listview"withdata-role="accordion"detail panels per step
Sidebar: Project Browser
Current
Fixed-width div with search input, filter checkboxes, and a flat list of project cards.
MetroUI Redesign
┌─────────────────────────────┐
│ 🔍 [Search input] │
│ Filter: [All ▼] │
├─────────────────────────────┤
│ ┌── Live Tile ─────────────┐│
│ │ Artist — Title ││ ← Metro medium tile
│ │ ████░░░░ Separating… ││ ← job progress strip at bottom
│ └──────────────────────────┘│
│ ┌── Tile ──────────────────┐│
│ │ Artist — Title ✓ ││
│ └──────────────────────────┘│
│ ... │
├─────────────────────────────┤
│ ▶ Imported Files │ ← metro accordion section
│ ▶ Subsonic Browser │
└─────────────────────────────┘
MetroUI components:
| UI element | MetroUI |
|---|---|
| Project tiles | Metro tile grid (tile, tile-medium) |
| Search | data-role="input" with search icon |
| Filter | data-role="select" |
| Imported files | data-role="accordion" > data-role="listview" |
| Subsonic tree | data-role="accordion" > data-role="treeview" |
Live Tile behaviour: tile background colour reflects job state —
bg-blue— separatingbg-amber— transcribing / aligningbg-green— completebg-red— error- Animated
data-role="activity"spinner appears while any job is running.
GlobalAudioBar
Fixed bottom strip, unchanged in function. Reskin with MetroUI:
<div class="app-bar bottom fixed">container- Metro-style playback buttons (
<button class="button cycle">) data-role="slider"for seek bar and volume<span class="badge">for current stem label
KaraokeEditor
Internal rendering is NOT reskinned. It is a custom canvas + DOM timing-table
component with its own internal colour constants and inline styles.
It will be wrapped in a MetroUI data-role="panel" shell (title bar + collapse toggle)
but its internals remain unchanged. This is explicitly called out because it must not
be broken by the migration.
LyricsLivePreview
LyricsLivePreview has two distinct layers with different treatment:
Lyrics display canvas — NOT reskinned with MetroUI
The animated lyrics rendering area (scrolling lines, word-fill gradient, glow/blur
effects) is driven by a custom RAF loop with direct DOM/style mutations (and per the
Karaoke Renderer (Two JS).md plan, will be replaced by a Two.js SVG scene). MetroUI
does not touch this area.
UI shell — reskinned with MetroUI
All the surrounding controls and panels are standard HTML UI and are fully reskinned:
┌─ Lyrics Preview ─────────────────────────────────────── [⛶] [▼] ┐
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ [lyrics display canvas — Two.js / custom RAF, unchanged] │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Transport ──────────────────────────────────────────────────┐ │
│ │ [◀◀] [▶] [▶▶] ══════════════●══════ 0:32 / 3:47 🔊 ─● │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Style ──────────────────────────────────────── [▼] ─────────┐ │
│ │ [scroll] [fade] [karaoke] [glow] [blur] ← Metro radio tiles│ │
│ │ Font [select ▼] Size [──●──] Align [L] [C] [R] │ │
│ │ Highlight ■ Word fill ■ Text ■ Bg ■ │ │
│ │ [•] Stroke width [─●─] color ■ │ │
│ │ [•] Shadow x [─●─] y [─●─] blur [─●─] color ■ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Speakers ───────────────────────────────────── [▼] ─────────┐ │
│ │ ● SPEAKER_00 [name input] │ │
│ │ ● SPEAKER_01 [name input] │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ LRC Editor ─────────────────────────────────── [▼] ─────────┐ │
│ │ [textarea] [Apply] [Reset] │ │
│ └──────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘
MetroUI components:
| UI element | MetroUI |
|---|---|
| Outer panel shell | data-role="panel" with data-collapsible="true" |
| Visual style selector | Metro tile grid with data-role="radio" (one tile per style mode) |
| Transport play/pause | <button class="button cycle primary"> |
| Seek bar | data-role="slider" |
| Volume slider | data-role="slider" with mute toggle button |
| Time display | <span class="badge"> |
| Font family | data-role="select" |
| Font size | data-role="slider" with numeric readout |
| Text alignment | Three-button <button class="button"> group (L / C / R) |
| Colour pickers (highlight, fill, text, bg) | data-role="color-picker" or data-role="input" data-type="color" |
| Stroke / shadow toggles | data-role="switch" |
| Stroke width, shadow x/y/blur | data-role="slider" |
| Speaker list | data-role="listview" — each row has a colour swatch + editable name input |
| Speaker colour assignment | Metro accent colour tile row |
| LRC text editor | <textarea class="metro-input" rows="8"> |
| Editor apply/reset buttons | <button class="button primary"> / <button class="button"> |
| Timing shift slider | data-role="slider" (−15 s … +15 s) with numeric readout |
| Fullscreen toggle | <button class="button square"> with mif-expand icon |
Style picker as collapsible panel (default collapsed):
The full style picker is wrapped in a data-role="panel" with data-collapsible="true"
and data-collapsed="true" so it doesn't dominate the view. A single gear icon button
in the lyrics panel title bar expands it. The transport controls remain always visible
below the canvas.
ThemeContext
Currently manages light | dark | system and applies a dark class to <html>.
Replaces the class toggle with MetroUI's data-theme attribute:
// was: document.documentElement.classList.toggle('dark', isDark)
document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light')
Accent colours: set data-accent attribute on <html> exactly as now, but map to
MetroUI's built-in accent palette names (blue, violet, crimson, green,
amber, cyan).
Migration Phases
Phase 1 — Install & Shell (App.tsx)
npm install @olton/metroui; remove Tailwind packages.- Swap
index.cssimports; updatemain.tsx. - Rebuild
App.tsxAppBar + SideNav shell in MetroUI classes. - Verify dark/light theme toggle and accent switching still work.
- No page content changed yet — inner pages still render their existing JSX.
Phase 2 — Sidebar
- Project tile grid with job-status colour coding.
- Imported files + Subsonic accordion sections.
- Search input + filter select.
Phase 3 — Separator page
- Drop zone.
- Model accordion + format radio tiles.
- Slider group for stem levels.
- Job progress + toast notifications.
Phase 4 — ProjectDetail page
- Panel sections (Stems, Karaoke Editor, Dynamic Mix, Lyrics Preview outer shell).
- Stem tiles with badges + progress.
- Action button dropdowns. (KaraokeEditor internals and the LyricsLivePreview rendering canvas untouched.)
Phase 5 — Settings page
- Vertical tab nav.
- Appearance: theme tiles, font select, accent tiles.
- Models: listview with progress rows.
- Subsonic: form + treeview.
- Maintenance / Power / AutoPipeline panels.
Phase 6 — GlobalAudioBar + polish
- Reskin audio bar.
- Remove any remaining Tailwind class remnants.
- Audit icon usage — decide lucide SVG vs MetroUI icon font.
- Cross-browser / dark-mode QA pass.
Phase 7 — LyricsLivePreview UI shell
- Transport controls: play/pause cycle button, seek slider, volume slider + mute, time badge.
- Visual style selector: Metro radio tile row (scroll / fade / karaoke / glow / blur).
- Style picker panel: font select, size/alignment sliders, colour pickers, stroke/shadow switches + sliders.
- Speaker listview: colour swatch tiles + inline name inputs.
- LRC text editor: Metro textarea + apply/reset buttons.
- Timing shift slider.
- Fullscreen button (mif-expand icon).
- Verify the lyrics rendering canvas is visually unaffected (no MetroUI classes inside it).
What Does NOT Change
| Item | Reason |
|---|---|
KaraokeEditor.tsx internals |
Custom canvas engine; MetroUI-independent |
LyricsLivePreview.tsx — lyrics rendering canvas |
Custom RAF / Two.js scene; MetroUI-independent |
LyricsLivePreview.tsx — UI shell (transport, style picker, speakers, editor) |
Does change — reskinned with MetroUI in Phase 7 |
api/client.ts |
Pure data layer |
utils/ |
Pure logic |
ThemeContext.tsx logic |
Only the DOM attribute changes |
| TanStack React Query | Unaffected by styling |
| Tone.js / abcjs / midi | Audio/music — unaffected |
| Vite config | No changes needed |
| TypeScript types | Unaffected |
Risk Notes
- MetroUI JS and React event system: MetroUI's JS-initialised components (dialog,
dropdown, tooltip) bypass React's synthetic event system. Use MetroUI CSS classes
only for those components and implement open/close logic in React state, or use the
MetroUI JS API via
useEffectwith refs — never let both systems control the same element. data-roleauto-init: MetroUI scans the DOM on load fordata-roleattributes and initialises JS widgets. Components rendered after initial load (dynamically by React) needMetro.makePlugin(el, 'role-name')called in auseEffect— or switch to CSS-only for those elements.- Vite tree-shaking: Metro bundles are monolithic (CSS + JS). Ensure
metro.cssandmetro.jsare imported as side-effects ("sideEffects": truein package config or explicit import) so Vite doesn't exclude them. - SSR / hydration: Not applicable (Vite SPA mode, no SSR).