5kmrun-bg / 5kmrun-bg/fivekmrun-app
Branded launch splash screen (circular logo with impulse) — replace the white screen
- 主要語言
- Dart
- 星號
- 8
- 分支
- 7
- 平均合併
- 2 天 8 小時
- 30 天內合併 PR
- 30
描述
## 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.
貢獻指南
這個儲存庫沒有索引到貢獻指南
研究方向
先檢查目前的啟動畫面檔案:android/app/src/main/res/drawable/launch_background.xml 和 ios/Runner/Base.lproj/LaunchScreen.storyboard。品牌色彩定義在 lib/main.dart 中。等待維護者提供圓形 logo 資產。接著決定使用 flutter_native_splash package,或手動編輯平台檔案,並確保 Android 12+ 與 legacy 路徑都涵蓋在內。在 Android 和 iOS 模擬器/裝置上測試,確認 logo 沒有被裁切,且背景與強調色一致。
由索引模型根據 Issue 內容生成。
評估
- 技術堆疊
- android, ios
- 領域
- mobile, mobile-dev
- Issue 類型
- 功能
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 活躍度
- 冷清
- 描述清晰度
- 基本清楚
- 新手友好度
- 55/100