docs(openspec): add SDD artifact trail for recent alarm and EQ changes

Persist the exploration, proposal, spec, design, tasks, and verify/archive reports produced during the multi-device EQ, alarm-countdown, and notification-visual-polish SDD cycles.
2026-07-04 12:42:11 +02:00
parent e5b6d8acb3
commit bccc5c48b8
64 changed files with 6020 additions and 0 deletions
@@ -0,0 +1,43 @@
+# Exploration: Notification Visual Polish
+
+## Current State
+
+All 3 native alarm notifications use generic Android system drawables, none have brand color:
+- Pre-notice (30-min): `android.R.drawable.ic_dialog_info` — `PluriWaveAlarmReceiver.kt:184`
+- Snooze countdown: `android.R.drawable.ic_lock_idle_alarm` — `AlarmScheduler.kt:580` (shares channel `pluriwave_alarm_pre_notice` with pre-notice)
+- Ringing/fire: `android.R.drawable.ic_lock_idle_alarm` — `PluriWaveAlarmService.kt:390` (own channel `pluriwave_alarm_fire_v2`)
+
+Audio/media notification (`lib/main.dart:17-23`, `configuracionAudioService`): has `notificationColor` (`#21D4D9`) but no `androidNotificationIcon` — defaults to `audio_service` package's `'mipmap/ic_launcher'` fallback, which is the full-color multi-gradient launcher icon. Android will auto-silhouette this into an illegible blob in the status bar.
+
+## Design Decision: Icon Glyph
+
+No SVG source exists anywhere in the repo (`**/*.svg` → 0 matches); `assets/icons/`/`assets/generated/` are raster PNGs only. No image-generation tooling available. **Hand-author a vector drawable.**
+
+**Chosen glyph: equalizer bars** (Material Design's open-source "graphic_eq" icon shape — 5 vertical bars of alternating heights). Rationale:
+- The app's centerpiece feature IS the equalizer — strong brand fit
+- Simple bold shapes read correctly at tiny status-bar rendering sizes (unlike detailed/gradient art)
+- Material Icons is Apache 2.0 licensed — safe to adapt path data without an artist
+- Well-established pattern (similar to Spotify/media-app waveform icons)
+
+## Technical Approach
+
+- New file: `android/app/src/main/res/drawable/ic_stat_pluriwave.xml` — `VectorDrawable`, 24x24dp viewport, single `<path>` with `android:fillColor="#FFFFFF"` (vector drawables need no density-specific PNG variants)
+- `androidNotificationIcon` in `audio_service`'s `AudioServiceConfig` resolves via `"type/name"` string → `getResources().getIdentifier()`; `'drawable/ic_stat_pluriwave'` is correct (not `mipmap`)
+- Wire into all 4 call sites: 3 Kotlin `.setSmallIcon(...)` + 1 Dart `androidNotificationIcon` field
+- Add `.setColor(...)` to the 3 alarm notifications (currently none have color) — use the SAME cyan brand color as the audio notification (`#21D4D9`) rather than introducing coral as a second meaning, since pre-notice/snooze already share a channel (reinforces existing grouping, avoids scope creep)
+
+## Scope
+
+IN: one new vector icon asset, wiring into all 4 notification builders, `.setColor()` brand theming on the 3 alarm notifications.
+
+OUT (deferred to a later change): action-button icons, BigTextStyle, fallback artwork for stations without favicons, NotificationChannelGroup.
+
+## Testability
+
+- `test/tema/notification_color_test.dart` already asserts directly on `configuracionAudioService` fields — same pattern extends to a new `androidNotificationIcon` field assertion
+- No Kotlin test harness exists — `.setSmallIcon()`/`.setColor()` verification is manual/on-device QA only, must be called out explicitly in tasks
+
+## Risks
+
+- Hand-authored vector glyph must be verified visually on-device (status bar rendering at small size) — not verifiable via static analysis or unit test
+- `NotificationCompat.setColor()` is advisory across Android versions/styles — best-effort, not guaranteed pixel-exact