QuranFlow — Apple Ecosystem Widget Exploration

Date: July 17, 2026 Status: Ideation — grounded concepts for review, not a committed spec Inputs: QuranFlow handoff docs (PRODUCT-SPEC, DATA-MODEL, DESIGN-SYSTEM, FEEDBACK-SYNTHESIS), faith-essentials-strategy widget decisions (FE App Spec v1/v1.1, Daily Practice Track 3), Apple developer documentation and WWDC24/25 sessions, competitive scan (Duolingo, Muslim Pro, Pillars, Streaks, Calm, Apple Fitness).

1. Why widgets, specifically for QuranFlow

The audit's top findings are all failures of reach between app opens:

1. Disorientation — students didn't know what week they were on or what to do today. "8 out of 15" never read as "Week 8."
2. Missed live sessions — the schedule was five clicks deep; students missed sessions they intended to attend.
3. Unnoticed feedback — coach feedback arrived and students never saw it; the notification carried no context.

A widget is the only surface that answers "what week is it, what's due, when is my session" before the student opens the app — which is exactly where all three failures happen. The redesign's organizing principle (Weekly Rhythm) is also, conveniently, the ideal shape for a glanceable surface: one number, one strip, one next action.

Faith Essentials names this whole surface set the ambient layer — see its design board at https://fe-reset-mockup.pages.dev/ambient (Ambient Layer v2, July 12). We adopt the same term and the same board format for the companion deliverable: QuranFlow-Ambient-Board-v1-2026-07-17.html in this folder — but where FE's board is one day lived without opening the app, QuranFlow's is one week, because the week is this program's unit of rhythm.

The competitive scan found that no cohort-learning app (Khan Academy, Coursera) ships a meaningful widget. The category default among Quran apps is a generic "daily verse + streak counter." A semester-aware, curriculum-tied widget set is genuinely differentiated — there is no pattern to copy here, only to invent.

2. Decisions inherited from Faith Essentials strategy

FE already litigated several of these questions (App Spec v1/v1.1, July 2026). We inherit rather than re-argue:

3. Widget design rules (derived, binding on every concept below)

These fall out of the mockup's 8 binding rules (AUDIT.md), the copy canon, and the research:

• W1 — One idea per widget. A widget is a forced R0–R2 exercise: only "what's next," one week-reference, at most one action. (Apple HIG says the same thing.)
• W2 — No streaks, no composite scores. No streak exists in the data model. Weekly obligations (Watch / Record / Feedback) render as discrete segments — the Apple Fitness rings lesson: 2-of-3 done must read as progress, never as 67% failure.
• W3 — Locked vocabulary. Submission states are exactly "In review" → "Feedback ready" → heard → practiced. "Feedback," never "Hear back." No diacritics in UI copy. No invented urgency — "Due Sunday 11:59 PM" is a fact; "Don't lose your progress!" is banned.
• W4 — Times are viewer-local, no per-item zone suffixes. A widget showing a session time follows the same one-canonical-timezone rule as the app.
• W5 — Live Activities only for genuinely bounded live events (a session happening, an upload in flight). Never as a disguised daily reminder — a known anti-pattern that reads as spam.
• W6 — Nothing sensitive on the Lock Screen. "Feedback ready" is fine; the coach's actual notes/marks are not.
• W7 — The week strip is the orientation visual. At sizes where the 15-segment strip can't render legibly (accessoryInline, circular), the text "Week 8 of 15" replaces it — never both (R1: one week-reference per surface).
• W8 — No mascot guilt, no streak-insurance mechanics. Duolingo's disappointed-owl escalation and streak-freeze upsells are tonally wrong for Quranic learning and criticized even by Duolingo's own users. Pillars' "pause without penalty" is the tonal reference instead.

4. Concepts, by angle

Angle 1 — Orientation: "Where am I?" 【the #1 audit finding】

A. The Week widget — systemSmall (+ StandBy + CarPlay + visionOS free)

The SakStrip, made ambient. Large serif numeral (Newsreader/Fraunces) — the same hero-numeral treatment as the Today screen — over the 15-segment strip, with one status line.

┌──────────────────┐
│ WEEK             │   eyebrow: sans caps 0.08em
│ 8                │   serif display numeral
│ ▮▮▮▮▮▮▮▯░░░░░░░  │   SakStrip: done · current(gold) · remaining
│ 2 videos left    │   one line, the next thing only (R0)
└──────────────────┘

• Data: Semester.state, current Week.number, VideoWatchProgress counts. All local-timeline computable — the entire 15-week timeline can be generated ahead of time; zero server, zero reload-budget pressure.
• States: pre_semester ("Starts Sep 8" — solves the "when does it start?" confusion), active (above), complete ("Semester complete · 15 of 15").
• Tap → Today screen.
• This is the flagship. It is literally the app's orientation device relocated to the Home Screen.

Lock Screen variant — accessoryRectangular: "Week 8 of 15" + status line (strip replaced by text per W7). accessoryInline: "Week 8 · Due Sunday".

Angle 2 — The weekly loop: "What's next?"

B. This Week widget — systemMedium, interactive

The Watch → Record → Feedback loop as three discrete segments (W2), plus one App Intent button for the next step (R2: one primary action).

┌────────────────────────────────────────┐
│ WEEK 8              Due Sunday 11:59 PM│
│ ● Watch    2 of 3 watched              │
│ ● Record   Attempt 1 of 2 available    │
│ ● Feedback —                           │
│            [ Continue lesson ▸ ]       │
└────────────────────────────────────────┘

• The button is computed: videos remaining → "Continue lesson"; watched but not submitted → "Record" (deep-links to recorder — recording itself needs the app); submitted → no button, status shows "In review"; feedback arrived → "Play feedback."
• Data: VideoWatchProgress, Submission.status + attempt_number, Feedback.reviewed_at.
• iOS 17 interactive widgets run the intent in-background where possible; here most actions deep-link, which is correct — HIG says multi-step flows belong in the app.

Angle 3 — The feedback moment: the relationship with the coach

C. "Feedback ready" — an event-driven state, not a separate widget

The strongest emotional beat in the whole program is your coach replied to your recitation. When Feedback.reviewed_at lands, widgets A and B flip state: the status line goes gold ("Feedback ready" — locked vocabulary, gold is the one-flourish color).

• Mechanism: WidgetKit push notifications (iOS 17+) — a widget push token lets the server reload the widget the moment the coach submits, bypassing the reload budget. QuranFlow already runs push for the feedback notification type, so this is incremental, not new infrastructure. (FE rejected push because it had none; our situation differs.)
• Fallback: reload on notification receipt / app open. Degrades gracefully.
• This directly attacks audit finding #3 (feedback going unnoticed) at zero additional Home-Screen real estate.

Angle 4 — Live sessions: the bounded events

D1. Next-session countdown — accessoryRectangular (Lock Screen) + row in widget B — v1

"Qari circle · Today 7:00 PM" with WidgetKit dynamic-date text counting down — ticks live with zero refresh budget and zero server (the FE-resolved pattern). Within 15 minutes of start: "Starting soon · Join" (matches the app's soon state and the 15-minute student reminder timing). Times viewer-local per W4.

• Data: SessionOccurrence.starts_at_utc, zoom_join_url. Weekly-recurring sessions mean the timeline is fully precomputable.
• Directly attacks audit finding #2 (missed sessions — previously five clicks deep, now zero clicks).

D2. Session Live Activity + Dynamic Island — v2

A true bounded event, so a Live Activity is legitimate here (W5): starts at T−15 min, compact presentation shows the countdown, flips to "Live now · Join" during the session, ends when the session ends. Well inside the 8-hour cap. Push updates via ActivityKit (liveactivity push type). iOS 26 extends this to CarPlay and macOS for free.

• Sports-app data point from the scan: Live Activities correlate with materially higher session counts — and a live class is structurally identical to a game in progress.

E. Submission Live Activity — the revoke window (novel; no app in the scan does this)

When a student submits a recording, a short Live Activity covers the genuinely live part of the submission lifecycle:

1. Uploading — progress.
2. Revoke window — "Submitted · Revoke window ends in 4:32" (dynamic-date countdown against revoke_expires_at). No inline revoke button — accidental taps on the Lock Screen would be destructive; it deep-links to the revoke screen instead.
3. Window closes → activity ends with "In review." The 48-hour coach SLA is not a Live Activity (exceeds the 12-hour cap and isn't "live") — that's widget territory (concept C).

This makes the submission grace period — a designed-in safety feature students would otherwise never notice — visible exactly when it matters.

Angle 5 — The gift: spiritual-ambient presence

F. The week's verse — accessoryRectangular / accessoryInline / systemSmall (second small widget)

The FE flagship pattern, made curriculum-specific: this week's assigned ayah — Arabic + citation only, no translation (locked rule), citation in mono ("AL-MULK · 67:1"). No counter, no CTA, no state. Reading it on the Lock Screen and never opening the app is a success — the FE north star, inherited verbatim.

• What separates it from the generic verse-of-the-day category (Ayah Widget, Muslim Pro, et al.): it isn't random — it's the verse you are learning to recite this week. Ambient rehearsal of your actual assignment. The differentiation comes from the semester structure, which no verse-widget app has.
• Cheapest concept on this list; a static weekly timeline.

Angle 6 — Zero-UI entry points: App Intents everywhere

G. Intents, controls, Siri, Spotlight

One App Intents investment fans out to five surfaces (write once — WWDC25 direction):

• Control Center / Lock Screen control / Action button (ControlWidgetButton, iOS 18): "Record recitation" — press the Action button, land in the recorder. Hint text starts with a verb per the API's own convention.
• App Shortcuts / Siri: "Continue this week," "Play my feedback."
• Spotlight: "Continue Week 8" as a direct action in search.

Low design cost, high reach; these are plumbing for the same three actions widget B computes.

Angle 7 — The wrist

H. Watch complications + Smart Stack — not a watch app

The accessory-family widgets (A-lock, D1, F) are watch complications post-ClockKit — one codebase. Add Smart Stack relevance hints so the system surfaces the right one unprompted: session widget in the pre-session window, week widget at the student's habitual practice time. A full watch app is deferred (FE precedent; the HIG itself says complications first). The watch face is seen ~60–80×/day — the highest-frequency surface in the ecosystem, and QuranFlow gets it nearly free.

Angle 8 — The coach

I. Coach queue widget — systemSmall/accessoryCircular, role-gated

The Coach section's stat hero, relocated: "6 waiting · oldest 39h" as a gauge against the 48-hour SLA. accessoryCircular is literally a gauge template. One intent: "Start reviewing" → Queue tab (oldest-first, the existing default).

• Data: queue depth + oldest submitted_at — needs a server endpoint or push-updated widget; a stale SLA gauge is worse than none, so this ships only with push updates.
• Same role-gating as the Coach section of the app (admin-granted).

5. Considered and set aside

6. Recommendation — build order

P1 — ship with the app (all local-timeline, no new infra):

1. A — Week widget (small + accessory families) → StandBy, CarPlay, visionOS, watch complications free
2. B — This Week widget (medium, interactive)
3. D1 — Next-session countdown (Lock Screen, dynamic-date)
4. F — Week's verse (near-zero cost, the differentiator + the gift)
5. C — Feedback-ready state flip (piggybacks on existing feedback push; the one server touch worth doing in P1)

P2 — fast follows: 6. E — Submission/revoke Live Activity 7. G — App Intents fan-out (controls, Action button, Siri, Spotlight) 8. I — Coach queue widget (needs the push-updated endpoint)

P3 — later, evidence-gated: 9. D2 — Session Live Activity + Dynamic Island (ActivityKit push infra) 10. Smart Stack relevance tuning; macOS/iPadOS placement QA; Liquid Glass visual QA pass (widgets inherit the glass material automatically in iOS 26 — needs review against light/dark/tinted/clear backgrounds, one more state matrix for the design system).

Success framing (inherited from FE): the widget set is working if students arrive already oriented — session attendance and feedback-heard rates rise while "what week is it?" support questions disappear. For widget F specifically, being read and never tapped is success.

7. Sources

• Repo: handoff/docs/ (PRODUCT-SPEC, DATA-MODEL, DESIGN-SYSTEM, FEEDBACK-SYNTHESIS), handoff/mockup/AUDIT.md (rules R0–R8), reviews/QuranFlow-User-Capability-Map.md, reviews/reference-docs/App-Redesign-Field-Guide-WWDC25.md
• FE strategy: faith-essentials-strategy/initiatives/daily-practice/FE-App-Spec-v1.1-2026-07-10.md (§5.4 notification architecture, widget-over-LA decision, AlarmKit), FE-Daily-Practice-Track3-Full-Vision-2026-07-05.md (gift-not-hook rule)
• Apple: WidgetKit docs (timelines, reload budgets, push-updated widgets, accessory families, StandBy WidgetLocation), ActivityKit (8h/12h lifecycle, 4 KB payload, liveactivity push), ControlWidget (WWDC24 s10157), App Intents (WWDC25 s260), What's new in widgets (WWDC25 s278), HIG: Widgets / Complications / Designing for watchOS
• Competitive: Duolingo widget + notification-tiering teardowns; Muslim Pro lock-screen widget docs; Pillars (pause-without-penalty); Streaks 6 (MacStories); Calm/Headspace; Apple Fitness rings; OneSignal/Airship Live Activity retention data