feat(ui): add premium PluriWave redesign

2026-05-20 18:42:22 +02:00
parent f95a8290ae
commit c707fc9911
30 changed files with 2218 additions and 954 deletions
@@ -0,0 +1,98 @@
+# Spec: Premium award UI, icons, and code-review hardening
+
+## Requirement: Hardening before premium UI
+
+The system MUST correct lifecycle and state-integrity defects before premium visual work is considered complete.
+
+### Scenario: hardening gate precedes visual rollout
+- GIVEN premium UI work starts
+- WHEN implementation tasks are planned
+- THEN tests for listener lifecycle, favorite consistency, reorder persistence, playback state, timer cancellation, and error reporting MUST be written first
+- AND premium UI tasks SHALL NOT be marked complete until those tests pass with `flutter test`
+
+### Scenario: failures are observable
+- GIVEN an async operation fails in playback, favorites, or loading
+- WHEN the failure reaches app state
+- THEN the system MUST expose a user-visible or test-observable error path
+- AND it MUST NOT silently swallow the failure without state feedback
+
+## Requirement: Lifecycle-safe subscriptions
+
+The system MUST own and cancel every stream subscription/listener created by widgets or app shell.
+
+### Scenario: app error stream is subscribed once
+- GIVEN dependencies change more than once
+- WHEN one error message is emitted
+- THEN the app MUST show at most one SnackBar for that message
+
+### Scenario: visualizer disposes cleanly
+- GIVEN an audio visualizer or playback indicator is removed
+- WHEN `estadoStream` emits later
+- THEN no disposed widget SHALL call `setState`
+- AND its subscription MUST be cancelled
+
+## Requirement: Consistent favorites and ordering
+
+The system MUST derive favorite UI from global state and persist complete ordering after reorder.
+
+### Scenario: reorder persists full list order
+- GIVEN favorites `[A, B, C]`
+- WHEN the user moves `A` after `C`
+- THEN persisted favorites MUST reload as `[B, C, A]`
+- AND every item SHALL have a deterministic order
+
+### Scenario: favorite state stays in sync
+- GIVEN the same station appears in card and player surfaces
+- WHEN favorite is toggled from either surface
+- THEN all visible favorite icons MUST reflect the updated global state
+
+## Requirement: Playback source of truth
+
+The player MUST reconcile route input with `EstadoRadio` current playback state and MUST NOT keep acting on stale station snapshots.
+
+### Scenario: active station changes while player is open
+- GIVEN the player was opened for station `A`
+- AND global playback changes to station `B`
+- WHEN controls or favorite actions render
+- THEN they MUST target the effective current station
+- AND labels/artwork/actions SHALL remain consistent
+
+## Requirement: Premium visual system
+
+The system MUST define reusable visual tokens for “Ondas vivas globales”: deep violet, electric magenta, warm coral, dark glass surfaces, subtle neumorphism, controlled glow, radius, spacing, and motion.
+
+### Scenario: screens consume tokens
+- GIVEN a premium screen is rendered
+- WHEN colors, surfaces, shadows, or motion are applied
+- THEN they MUST come from shared tokens or theme extensions
+- AND one-off hardcoded styling SHOULD be avoided
+
+## Requirement: Premium icon system
+
+The app MUST use custom PluriWave iconography for primary navigation, playback, favorite, search, settings, live/error/loading, and radio fallback states.
+
+### Scenario: icon states are coherent
+- GIVEN an icon supports inactive, selected, and active playback states
+- WHEN each state is displayed
+- THEN outline, filled, and glow variants MUST preserve the same rounded wave geometry
+- AND tappable icons MUST keep accessible labels
+
+## Requirement: Five-screen premium refresh
+
+Inicio, Buscar, Reproductor, Favoritos, and Ajustes MUST share the premium language, with Reproductor as the strongest reference composition.
+
+### Scenario: mockup scope is implemented coherently
+- GIVEN the five primary screens are reviewed together
+- WHEN navigation moves between them
+- THEN tokens, icon style, hierarchy, empty states, and loading states SHALL feel like one product
+- AND no primary screen SHOULD fall back to generic Material-only presentation
+
+## Requirement: Accessibility and verification
+
+The system MUST preserve accessibility while adding premium visuals.
+
+### Scenario: premium visuals remain usable
+- GIVEN large text, reduced motion, or high-contrast needs
+- WHEN premium UI is rendered
+- THEN content MUST remain readable and controls MUST remain reachable
+- AND verification MUST use `flutter test`, never `flutter build`