5kmrun-bg / 5kmrun-bg/fivekmrun-app
Branded launch splash screen (circular logo with impulse) — replace the white screen
- Linguagem predominante
- Dart
- Estrelas
- 8
- Forks
- 7
- Merge médio
- 2d 8h
- PRs com merge (30d)
- 30
Descrição
## Problem
The app's launch splash is a **plain white screen**. It is dull, unbranded, and reads as a loading stall rather than as part of the product. Every cold start — including the one before every Saturday race — opens on blank white.
This is the first thing a user sees, and right now it says nothing about 5kmRun.bg.
## Goal
Replace it with a branded splash: the **circular version of the 5kmRun logo with the impulse/pulse line coming out of it**, on a brand-coloured background.
Brand accent is already defined in `lib/main.dart:24`:
```dart
final appAccentColor = Color.fromRGBO(218, 3, 56, 1.0); // #DA0338
```
Use that as the single source of truth for the splash background rather than hardcoding a new red.
## Required input — asset is not in the repo ⚠️
**This is blocking the visual work.** The circular-logo-with-impulse artwork does **not** exist anywhere in this repository. The only logo assets present are:
- `assets/logo.png` — the square red app icon (the "5" drawn as a route with node markers and a map pin). Not the circular version.
- `assets/logo_strava_icon.svg` — Strava branding, unrelated.
@etabakov needs to supply the circular logo, ideally as **SVG or a high-resolution transparent PNG** (≥1024×1024). Everything else below can be scaffolded before the asset lands, but the splash cannot be finished without it.
## Current state
**Android** — `android/app/src/main/res/drawable/launch_background.xml` is the untouched Flutter template:
```xml
```
with the example bitmap block still commented out. `android/app/src/main/res/values/styles.xml` sets only `windowBackground` on `LaunchTheme`.
**iOS** — `ios/Runner/Base.lproj/LaunchScreen.storyboard` has a white `backgroundColor` (`red="1" green="1" blue="1"`) and a `LaunchImage` imageView. The images in `ios/Runner/Assets.xcassets/LaunchImage.imageset/` are the default Flutter placeholders at 168×185.
There is no `flutter_native_splash` config in `pubspec.yaml` — only `flutter_icons` for launcher icons.
## Technical constraints — read before starting
1. **Android 12+ ignores `launch_background.xml`.** From API 31 the system SplashScreen API takes over, driven by `windowSplashScreenBackground` and `windowSplashScreenAnimatedIcon` on the theme. We target `compileSdk`/`targetSdk` 36, so editing only `launch_background.xml` will appear to do nothing on most modern devices while still mattering for `minSdkVersion 26` devices. **Both paths must be handled.**
2. **The Android 12+ splash icon is masked to a circle** and the outer ~1/3 of the canvas is clipped. A circular logo suits this well, but the impulse line must be positioned so it is not cut off. Budget time to test the safe zone.
3. **"Impulse coming out of it" — animation is only partly possible.**
- Android 12+: can animate via `windowSplashScreenAnimatedIcon` with an `AnimatedVectorDrawable` (≤1000 ms).
- Android 8–11 (`minSdk 26`): static only.
- iOS: the launch storyboard **cannot animate**. Static only.
Decide early whether the impulse is a **static graphic** (consistent everywhere, much simpler) or **animated where supported** (nicer on modern Android, inconsistent across platforms). **Recommendation: ship static first**, then consider a Flutter-side animated transition as a follow-up — the native splash is visible for only a few hundred milliseconds on a warm start, so an animation there is easily missed.
4. **There is a second, longer loading phase worth branding.** In `lib/main.dart`, `main()` awaits `Firebase.initializeApp()` and `authRes.loadFromLocalStore()` **before** `runApp()`. The native splash covers that window. Whether to also add a Flutter-side branded loading screen for slow starts is a judgement call — mention it in the PR, but do not scope-creep into it without asking.
5. **Dark mode.** There are no `values-night` resources. Decide whether the splash background stays brand red in dark mode (recommended — it is a brand surface, not a content surface) and note the decision.
## Suggested approach
`flutter_native_splash` is the standard solution and handles the Android 12+ API, the legacy drawable, and the iOS storyboard from one `pubspec.yaml` block. **It is a new dependency, so confirm with @etabakov before adding it** (per CLAUDE.md). If it is rejected, the same result is achievable by hand-editing `styles.xml`, `launch_background.xml`, the storyboard, and the imageset — more work, more files, but no new dependency.
## Acceptance criteria
- [ ] No white flash on cold start on either platform.
- [ ] Branded splash verified on **Android 12+** (SplashScreen API path) **and** on an **Android 8–11** device/emulator (legacy `launch_background.xml` path, `minSdk 26`).
- [ ] Branded splash verified on iOS, including a notched device.
- [ ] The impulse element is not clipped by the Android 12+ circular icon mask.
- [ ] Splash background matches `appAccentColor` (#DA0338) — no drifted second red.
- [ ] Transition from native splash into the first Flutter frame has no visible colour jump.
- [ ] Checked in both light and dark system theme.
- [ ] Screenshots from all tested configurations in the PR.
- [ ] `flutter test` passes and CI is green.
## Notes for whoever picks this up
- Branch `claude-feat/branded-splash-screen`.
- **Do not start the visual work until the circular logo asset is supplied** — scaffolding and platform config can begin, but do not substitute `assets/logo.png` and call it done; it is the wrong logo.
- Do not add `flutter_native_splash` without explicit confirmation.
- If generated files are used, keep the generator config in `pubspec.yaml` committed so the splash can be regenerated rather than hand-patched later.
- Screenshots are the deliverable; this is not verifiable from tests.
Guia de contribuição
Nenhum guia de contribuição indexado para este repositório
Direção de pesquisa
Comece examinando os arquivos atuais da tela de inicialização: android/app/src/main/res/drawable/launch_background.xml e ios/Runner/Base.lproj/LaunchScreen.storyboard. A cor da marca está definida em lib/main.dart. Aguarde o maintainer fornecer o asset do logotipo circular. Em seguida, decida se deve usar o pacote flutter_native_splash ou editar manualmente os arquivos da plataforma, garantindo que tanto o Android 12+ quanto os caminhos legacy sejam contemplados. Teste em emuladores/dispositivos Android e iOS, verificando se o logotipo não está cortado e se o plano de fundo corresponde à cor de destaque.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- android, ios
- Domínio
- mobile, mobile-dev
- Tipo de issue
- Funcionalidade
- Dificuldade
- 4/5
- Tempo estimado
- 3-5 dias
- Status de atividade
- Pouca atividade
- Clareza
- Razoavelmente clara
- Facilidade para iniciantes
- 55/100