Stakeholder Feedback & Solutions — v2

QuranFlow: Design Consultant Review & Implementable Recommendations (v2)

Builds on: lejla-feedback-and-solution-exploration.md (v1) Perspective: Apple expert design consultant reviewing v1's recommendations against HIG Goal: Move from exploration to specific, implementable changes

Part 1: What I Agree With (v1 Got Right)

1.1 "Design for the new user first" -- Correct

This is Apple's philosophy exactly. The HIG says the best onboarding is no onboarding -- your app should be intuitive enough that people understand it by experiencing it. If a design requires explanation for new users, the design has a problem, not the user.

1.2 Progress ring removal -- Correct, and HIG confirms it

Apple's HIG says progress indicators are for tasks with a known duration where users are waiting for something to complete. The QuranFlow progress ring (53% weekly completion) is neither -- it's a decorative summary of data already shown in the triptych. Apple's HIG: "Always report progress accurately. Do not display inaccurate progress information just to make your app appear busy."

The ring fails on multiple HIG criteria:

• It's not tracking an active, in-progress task
• The percentage formula is ambiguous (videos + submission + feedback?)
• It competes with the primary action card for visual attention
• At 0% it provides negative signal without value

Verdict: Remove permanently from Today screen. The Learn screen's progress ring (showing "2/3" for video progress) is different -- it tracks a specific, clear metric (videos watched out of total). That one earns its space.

1.3 Permanent label changes -- Correct, and HIG prescribes it

Apple HIG (Writing section): "Choose simple, plain language... avoiding jargon." Apple HIG (Inclusion): "Use you and your to address people directly."

"Submission" is program jargon. "Your Recording" is plain language. Apple would make this change without hesitation. Same for "Feedback" → "Coach Feedback" and "Lesson" → "Your Lesson."

These must be permanent changes, not temporary annotations. Apple never shows one label to new users and a different label to experienced users. Labels are part of the app's language -- they should be consistent from Day 1 to Day 365.

1.4 Self-explaining empty states -- Correct, this IS Apple's approach

Apple teaches through states, not through overlays or tutorials. The HIG and TipKit documentation both emphasize: show information at the moment it becomes relevant. An empty "Coach Feedback" card that says "After you submit, Coach Amina will send audio feedback" is exactly this -- it teaches the concept through its own empty state.

1.5 Reducing session cards to 2 -- Correct

On a 390pt-wide iPhone SE / Mini, 3 session cards push the third card below the fold. Showing 2 with "Full Schedule →" respects the HIG's guidance on glanceability while providing an obvious path to more.

Part 2: What v1 Got Wrong or Didn't Go Far Enough On

2.1 The Today tab IS the problem -- and v1 didn't say this clearly enough

WWDC22 "Explore navigation design for iOS" explicitly warns: Most "Home" tabs are "just buttons that switch tabs or show content of individual tabs twice." Apple calls "Home" a "lazy name for the app's first tab." Each tab should own a distinct content domain and not duplicate what other tabs show.

Look at what the Today screen currently shows:

• Lesson status (2 of 3 watched) → duplicated from Learn tab
• Submission status (Not submitted) → duplicated from Learn tab
• Feedback status (1 new) → duplicated from Learn tab
• Session cards (3 sessions) → duplicated from Schedule tab
• Week position (Week 8 of 15) → also shown on Learn tab hero

The Today screen is EXACTLY what Apple warns against: a dashboard that aggregates content from other tabs. The triptych is a miniature Learn tab. The session cards are a miniature Schedule tab.

This doesn't mean the Today tab is wrong. It means its PURPOSE needs to be sharper. Instead of "summarize everything," the Today tab should answer ONE question that no other tab answers: "What should I do right now?"

The Primary Action Card already does this perfectly. The state machine (lesson not started → in progress → ready to submit → awaiting feedback → feedback ready → all done) is the best element on the entire screen. It's the one thing that's NOT a duplication -- it's a synthesis.

2.2 Solution Space D ("What's Next") was dismissed too quickly

v1 called the "What's Next" approach "too radical" and "what Jony Ive would do." But it's actually what Apple's HIG recommends for a first tab. Apple says the first tab should represent your app's primary, most-used content area -- not a summary of everything.

For QuranFlow, the primary interaction is: "What should I do next in my weekly cycle?" That's the Primary Action Card. The triptych and session cards are secondary reference information that already lives in dedicated tabs.

The real question isn't "Should the Today screen show one thing?" -- it's "Should the Today screen show anything that the Learn and Schedule tabs already show?"

2.3 The onboarding video recommendation contradicts Apple's approach

Apple's HIG: design "a brief, enjoyable experience that doesn't require people to memorize or provide a lot of information." Apple prefers interactive onboarding over passive content.

More importantly, Apple's TipKit (introduced WWDC23) is their official answer to progressive feature discovery. TipKit's principles:

• Contextual, not front-loaded. Tips appear when relevant.
• Stretched over time. "Slowly introduce returning users to your app's full functionality, instead of choosing to overload them with tips upfront."
• Dismissable. Tips don't reappear once dismissed.

A 45-second video is passive, front-loaded, and unrepeatable. TipKit-style contextual tips are active, stretched over time, and appear at the moment of relevance. Apple would choose the latter.

However -- Lejla's insight that "people are used to short format videos" is real for this audience. The recommendation: keep the video as an optional orientation (in the pre-semester state, where it already lives), but don't make it the onboarding mechanism. The onboarding should be the 3-5 screen interactive flow. The video is supplementary.

2.4 The countdown timer analysis was too gentle

v1 said "questionable" and "remove or make subtle." After reviewing Apple's guidance, the answer is clearer:

Apple says time-remaining displays are for user-initiated, actionable contexts (deliveries, workouts, flights). "3 days until Week 9 unlocks" is:

• Not user-initiated (the student didn't start a timer)
• Not actionable (they can't speed up time)
• Potentially anxiety-inducing (pressure without purpose)

Remove it. If students need to know when new content unlocks, that information belongs in the Learn tab's week view ("Week 9 unlocks Saturday"), not as a permanent countdown on the Today screen.

Part 3: Specific Implementable Changes

These are ordered by confidence level -- what to implement now vs. what needs testing.

Tier 1: Implement Now (High confidence, HIG-aligned, low risk)

Change 1: Remove the progress ring from Today screen

File: mockups/qf-mockup-v2/src/screens/today.tsx What: Delete the ProgressRing component call in the week header section (line ~449). Remove the flex layout that positions the ring opposite the level subtitle. Why: Redundant with triptych. Not an Apple-sanctioned use of progress indicators. Competes with primary action card for attention. Keep: The ProgressRing in learn.tsx (showing "2/3" for videos watched) -- that's a clear, specific metric within its content domain.

Change 2: Remove the countdown timer line

File: mockups/qf-mockup-v2/src/screens/today.tsx What: Remove the "3 days until Week 9 unlocks" line with the Clock icon (lines ~443-446). Result: The week header becomes:

Week 8 of 15
Level 2 — Reading with Fluency

Two lines instead of three. Cleaner, calmer.

Change 3: Rename triptych labels permanently

File: mockups/qf-mockup-v2/src/screens/today.tsx What: Change the StatusCard labels:

• "Lesson" → "Your Lesson"
• "Submission" → "Your Recording"
• "Feedback" → "Coach Feedback" Also change the section header from "This Week" to leave as-is (it's a good grouping label). Why: Apple HIG prescribes plain language and second-person ("your") address. "Submission" is program jargon. "Your Recording" is what the student actually does.

Change 4: Rename session section header

File: mockups/qf-mockup-v2/src/screens/today.tsx What: Change "Today's Sessions" → "Today's Live Sessions" Why: "Sessions" is ambiguous (could mean lesson sessions, app sessions). "Live Sessions" immediately communicates these are real-time events with other people. Apple's writing guidance: be specific.

Change 5: Reduce session cards to 2

File: mockups/qf-mockup-v2/src/screens/today.tsx What: Show maximum 2 session cards. Keep the "Full Schedule →" link. Why: Third card is below fold on smaller devices. Two cards + link = same information, less density.

Change 6: Simplify level subtitle

File: mockups/qf-mockup-v2/src/screens/today.tsx What: Change "Level 2 — Reading with Fluency" → "Level 2" Why: "Reading with Fluency" is a level description that doesn't change all semester. It adds 3 extra words to every single screen visit for information the student memorized in Week 1. The full level name can live in the Profile screen and Learn screen hero. The Today screen needs only the level number for orientation.

Tier 2: Implement Now, Design Carefully (Medium confidence, requires copywriting)

Change 7: Design self-explaining empty states for triptych cards

File: mockups/qf-mockup-v2/src/screens/today.tsx What: When a triptych card has no meaningful data, show explanatory text instead of a bare status.

Your Lesson (when 0 videos watched):

Your Lesson
2 short videos this week
Start anytime

Your Recording (when not submitted):

Your Recording
Record this week's passage
Coach Amina will review it

Coach Feedback (when no feedback yet):

Coach Feedback
Arrives after you submit
Audio from Coach Amina

Note: These are compact -- 2 lines of 13pt text per card. They fit the existing card dimensions. When the student has data (e.g., "2 of 3 watched"), the explanatory text is replaced by the real value. The empty state IS the explanation; the filled state IS the proof of progress.

Why: Apple's approach is teaching through states. Each card becomes self-documenting. A Week 1 student reading "Record this week's passage — Coach Amina will review it" understands the entire submission concept from two lines. No onboarding screen needed for this.

Change 8: Design empty state for sessions section

File: mockups/qf-mockup-v2/src/screens/today.tsx What: When no sessions today, show:

Today's Live Sessions          Full Schedule →
No sessions today. Next: Tuesday 6 AM EST

Single line, muted text. Not an elaborate empty state graphic -- just a concise redirect.

Tier 3: Explore in Mockup, Test Before Committing (Needs validation)

Change 9: Consider triptych-into-action-card consolidation

Current state: The Primary Action Card and the Status Triptych are two separate zones.

Proposed exploration: Merge the triptych into the bottom of the Primary Action Card as a compact status footer:

┌─────────────────────────────────────┐
│  Continue Your Lesson                │
│  Idgham with Ghunnah                 │
│  Video 2 of 3 remaining             │
│                                      │
│  [▶ Continue Lesson]                 │
│─────────────────────────────────────│
│  Lesson 2/3  ·  Recording ○  ·  Feedback 1 new  │
└─────────────────────────────────────┘

What this solves: Reduces attention zones from 5 to 3 (header, card, sessions). The triptych data is preserved but as secondary detail inside the primary card, not as 3 competing attention zones.

What this risks: Losing the tap targets (currently, tapping "Lesson" navigates to Learn > Lessons, etc.). The consolidated status row is read-only text, not three tappable cards.

Recommendation: Build this as an alternative mockup state. Show both versions to test users. The WWDC22 guidance about not duplicating tab content supports consolidation -- but the loss of tap targets is a real cost that needs user validation.

Change 10: Rethink the Today tab's purpose

This is the most significant change and should NOT be implemented in the mockup yet. But it should be discussed:

Current purpose: Dashboard summarizing Learn + Schedule + status Apple-aligned purpose: "What should I do right now?" with a path to do it

If the Today tab became purely "What's Next":

• Week header (orientation)
• Primary Action Card (the one thing to do)
• Next live session if happening today (time-critical information)
• That's it. Everything else lives in its dedicated tab.

This aligns with Apple's guidance that the first tab should be a focused content area, not a summary. But it's a significant philosophical shift that needs stakeholder alignment and user testing before implementing.

Part 4: The Onboarding Recommendation (Revised)

v1 recommended a 45-second video as the core of Step 5. After reviewing Apple's guidance, here's the revised recommendation:

Keep the interactive onboarding flow (3-5 screens)

Apple says: brief, benefit-oriented, skippable. The current spec's 5 steps are fine:

1. Welcome (benefit-oriented: "Your personal Quran learning journey")
2. Your Level (personalized: "You've been placed in Level 2")
3. Choose Your Font (mandatory, P0 fix)
4. Meet Your Coach (personalized: coach photo, name)
5. Your Week (the rhythm: "Each week: watch, record, get feedback")

Step 5 should be one screen with a simple visual (3 icons showing the weekly cycle: video → mic → speech bubble), NOT a video. Apple prefers interactive over passive. The visual should be glanceable -- scannable in 2 seconds even if the student doesn't read the text.

Move the video to pre-semester (where it already lives)

The orientation video card in the pre-semester Today screen is the right place for a longer explanation. It's optional, it's there when the student has time, and it doesn't block the onboarding flow. Label it clearly: "Watch Your Orientation — Learn how the semester works (2 min)."

Use TipKit-style contextual tips for feature discovery

Instead of front-loading feature explanations in onboarding, use contextual tips that appear the FIRST time a student encounters a feature:

• First visit to Learn tab: Inline tip above the submission section: "This is where you'll record and submit your weekly recitation."
• First visit to Schedule tab: Inline tip above session type filters explaining QRC / Level Class / Office Hours (already specified in Schedule Amendment 8).
• First time feedback arrives: Inline tip in the Learn tab feedback section: "Your coach has reviewed your recording. Tap play to listen."

These tips appear once, are dismissible, and follow Apple's TipKit pattern of "contextual, not front-loaded."

Part 5: What Still Needs User Testing

These questions should be answered by Lejla's proposed user testing sessions before making further design changes:

1. Does the simplified Today screen (Tier 1 changes applied) feel right? Show users the mockup with progress ring removed, countdown removed, labels renamed, 2 session cards. Is it clearer? Or does it feel too sparse?

2. Do the self-explaining empty states work? Show a Week 1 student the triptych cards with empty state text. Do they understand what "Your Recording" means from reading "Record this week's passage — Coach Amina will review it"?

3. Triptych: 3 cards or consolidated row? Show both versions. Which do students prefer? Do they use the tap targets on the current triptych cards?

4. Session labels: do students know what "QRC" means? If not, should the card always show the expanded label ("Reading Practice" instead of "QRC")?

5. Is "Week 1 of 15" self-explanatory? Or do students need the week header to say something more like "Your first week — 15 weeks total"?

Part 6: Summary — What to Implement Before Sharing with Team

Do now (code changes to mockup):

Build as alternative to compare (mockup variant):

Discuss before implementing:

Out of scope for now:

• Learn screen simplification (separate review needed)
• Schedule screen changes (already addressed in amendments)
• Profile screen changes (already simple)

Appendix: Apple HIG Sources Referenced

• Progress Indicators: HIG says use for tasks with known duration. Not for decorative summaries.
• Writing/Labels: "Choose simple, plain language... use you and your to address people directly."
• Tab Bars (WWDC22): First tab should not be a dashboard duplicating other tabs. "Home is a lazy name."
• Onboarding: Brief, benefit-oriented, 3-5 screens. Tutorials should be optional and skippable.
• TipKit (WWDC23): "Stretch tutorials over a period of days to slowly introduce returning users to your app's full functionality, instead of overloading them with tips upfront."
• Countdown/Timers: Appropriate for user-initiated, actionable contexts only. Avoid pressure without purpose.
• Empty States: Teach through states, not overlays.