pluriwave/openspec/changes/premium-award-ui-icons-code-review/spec.md

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