5kmrun-bg / 5kmrun-bg/fivekmrun-app

Branded launch splash screen (circular logo with impulse) — replace the white screen

未關閉
#219 1 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement up-for-claude
主要語言
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

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。