We need an onboarding #31

New issue

Closed

opened 2026-09-01 12:58:11 +00:00 by uwayss · 2 comments

uwayss commented

2026-09-01 12:58:11 +00:00

Owner

Das problem

A nice and warm, welcoming onboarding would add a nice touch to the app's identity and would also give us a window to ask for the users' preferences (e.g. school of thought). We could use it to give users a nicer and more personal experience. Everything will stay simple and offline, of course.

Research: What we really need to ask? Gender? School of thought? what else?
Design the flow: The order of the screens and the whole onboarding mechanism.
Vectorize the mascot: We already needed that. It'll be needed for the alternate poses that'll be added
Design the alternate poses: We may need to animate and show other poses of the mascot

Notes

Mascot vectorization

Technically, i can use generative AI to just generate the alternative poses. But

i don't think it can pull it off cleanly. Especially the format it should output in.
It's just unprofessional. Vectorization is much cleaner and better long term

The onboarding

We need to specifically decide on:

How will we store the data and where can users edit it? should all of them be editable?
We need to keep it fast and simple by the way. We shouldn't force people to go through a full onboarding just to use the app.

## Das problem A nice and warm, welcoming onboarding would add a nice touch to the app's identity and would also give us a window to ask for the users' preferences (e.g. school of thought). We could use it to give users a nicer and more personal experience. Everything will stay simple and offline, of course. - [ ] Research: What we really need to ask? Gender? School of thought? what else? - [ ] Design the flow: The order of the screens and the whole onboarding mechanism. - [ ] Vectorize the mascot: We already needed that. It'll be needed for the alternate poses that'll be added - [ ] Design the alternate poses: We may need to animate and show other poses of the mascot ## Notes ### Mascot vectorization Technically, i can use generative AI to just generate the alternative poses. But 1. i don't think it can pull it off cleanly. Especially the format it should output in. 2. It's just unprofessional. Vectorization is much cleaner and better long term ### The onboarding We need to specifically decide on: 1. How will we store the data and where can users edit it? should all of them be editable? 2. We need to keep it fast and simple by the way. We shouldn't force people to go through a full onboarding just to use the app.

uwayss added the

enhancement

label

2026-09-01 12:58:11 +00:00

uwayss commented

2026-09-01 12:59:33 +00:00

Author

Owner

@claude brainstorm the design parts. be direct, clear and concise

claude-bot commented

2026-09-01 12:59:57 +00:00

Collaborator

Onboarding — design brainstorm

Grounded in what's already in the repo: AppSettings (src/core/store/appStore.ts) is a flat object persisted as one MMKV blob via storageService.ts, and Settings is a declarative list (settingsData.ts) already rendering toggles/modals/nav items. Onboarding should plug into these, not invent a parallel system.

1. What to actually ask (keep it to 2 questions, both settings-shaped)

School of thought (madhab) — affects Asr calculation / fiqh-dependent deed suggestions. This is a real functional input, not flavor — ask it.
Gender — only ask this if it changes something concrete (deed suggestions, pronoun/copy in i18n strings). If it's purely cosmetic, cut it. Don't ask questions whose answer doesn't change app behavior.
Everything else (name, reminder time, theme) — skip. Reminder time already has a sane default (20:00) and its own settings screen; don't duplicate it in onboarding.

Rule of thumb: if removing a question wouldn't change any code path, it doesn't belong in onboarding — it belongs in Settings where a curious user can find it later.

2. Flow

3 screens, max:

Welcome — mascot, one line of warmth, "Get Started" + a visible Skip (skip = defaults, same as fresh install today).
Madhab select (+ gender, if kept) — single-choice cards, not a form.
Done — straight into Home.

No progress dots, no account creation, no permissions prompts bundled in (notification permission should be requested contextually when the user enables reminders in Settings, not here).

3. Storage & editability

Add the new fields to AppSettings (same object, same saveData/loadData — no new storage mechanism needed).
Add hasOnboarded: boolean to AppSettings. AppNavigator/root checks this once at initialize() — same place isInitialized is already gated — to decide Onboarding stack vs. Tab.Navigator.
Every value set in onboarding must be editable afterward in Settings — add a "School of thought" modal item to getSettingsData identical in shape to the existing theme/language ModalSettingsItems. No write-once fields. This also means onboarding is just "Settings with a welcome screen wrapped around it," not a separate data model.

4. Fast & skippable

Skip button on screen 1, always visible, never buried.
Skipping sets hasOnboarded: true with defaults — identical end state to answering, just unset preferences. No "resume onboarding" flow needed since everything's editable in Settings anyway.
No blocking network/permission calls — everything offline, consistent with the rest of the app.

5. Mascot poses

Not a blocker for shipping v1 — ship onboarding with the single existing mascot pose (static, in the Welcome screen) and layer in alternate poses later once vectorized. Don't let asset production gate the flow/data-model work, which is the part with real design decisions.

No files changed — this was a design discussion only, nothing pushed.

## Onboarding — design brainstorm Grounded in what's already in the repo: `AppSettings` (`src/core/store/appStore.ts`) is a flat object persisted as one MMKV blob via `storageService.ts`, and Settings is a declarative list (`settingsData.ts`) already rendering toggles/modals/nav items. Onboarding should plug into these, not invent a parallel system. ### 1. What to actually ask (keep it to 2 questions, both settings-shaped) - **School of thought (madhab)** — affects Asr calculation / fiqh-dependent deed suggestions. This is a real functional input, not flavor — ask it. - **Gender** — only ask this if it changes something concrete (deed suggestions, pronoun/copy in i18n strings). If it's purely cosmetic, cut it. Don't ask questions whose answer doesn't change app behavior. - Everything else (name, reminder time, theme) — skip. Reminder time already has a sane default (`20:00`) and its own settings screen; don't duplicate it in onboarding. Rule of thumb: if removing a question wouldn't change any code path, it doesn't belong in onboarding — it belongs in Settings where a curious user can find it later. ### 2. Flow 3 screens, max: 1. **Welcome** — mascot, one line of warmth, "Get Started" + a visible **Skip** (skip = defaults, same as fresh install today). 2. **Madhab select** (+ gender, if kept) — single-choice cards, not a form. 3. **Done** — straight into Home. No progress dots, no account creation, no permissions prompts bundled in (notification permission should be requested contextually when the user enables reminders in Settings, not here). ### 3. Storage & editability - Add the new fields to `AppSettings` (same object, same `saveData`/`loadData` — no new storage mechanism needed). - Add `hasOnboarded: boolean` to `AppSettings`. `AppNavigator`/root checks this once at `initialize()` — same place `isInitialized` is already gated — to decide Onboarding stack vs. Tab.Navigator. - **Every value set in onboarding must be editable afterward in Settings** — add a "School of thought" modal item to `getSettingsData` identical in shape to the existing `theme`/`language` `ModalSettingsItem`s. No write-once fields. This also means onboarding is just "Settings with a welcome screen wrapped around it," not a separate data model. ### 4. Fast & skippable - Skip button on screen 1, always visible, never buried. - Skipping sets `hasOnboarded: true` with defaults — identical end state to answering, just unset preferences. No "resume onboarding" flow needed since everything's editable in Settings anyway. - No blocking network/permission calls — everything offline, consistent with the rest of the app. ### 5. Mascot poses Not a blocker for shipping v1 — ship onboarding with the single existing mascot pose (static, in the Welcome screen) and layer in alternate poses later once vectorized. Don't let asset production gate the flow/data-model work, which is the part with real design decisions. --- No files changed — this was a design discussion only, nothing pushed.

uwayss referenced this issue from a commit

2026-09-04 12:59:18 +00:00

feat(onboarding): add first-run onboarding flow

uwayss closed this issue

2026-09-04 14:41:50 +00:00