QuranFlow · Redesign handoff
Guided Walkthrough · Decision Log
Built Jul 13, 2026 · Kamran away from keyboard; decisions taken autonomously per his instruction
and logged here. Orchestration: Opus 4.8 as orchestrator, advisor, reviewer and verifier;
Sonnet 5 as the content analyst and four screen implementers.
Location: handoff/walkthrough/.
Modeled on the Faith Essentials "40 Day Reset" hi-fi mockup pattern Kamran pointed to as the reference.
Status: delivered. All 20 screens built (four Sonnet implementers against a locked contract),
screenshot-verified one by one by the orchestrator, and the 20-chapter guided walkthrough runs end to
end (verified: boots at chapter 1, advances correctly, reaches chapter 20, no console errors).
Deliverable: QuranFlow-Walkthrough.html — one 1.7 MB self-contained file that opens by
double-click over file:// (confirmed). Dev source in app/. Nothing committed
to git without Kamran's ask (standing rule).
What this is, and why it is different from the existing mockup
The handoff already contains the Sakīna artboard mockup (handoff/mockup/): 40+
screens on one scrolling design canvas, the source of truth for design intent. It answers
"what should each screen look like." It does not answer "what is it like to use the app," and
it needs a local web server to view. This walkthrough is the complementary artifact: a single,
double-clickable file that you tap through like the real app, with a guided story rail for a
PM/developer discussion. Same design language; different job.
Product & scope decisions
| # | Decision | What & why |
|---|
| 1 | Deliverable = one interactive, double-clickable file with a guided tour | Mirrors the reference (FE "40 Day Reset"). A single self-contained HTML that opens by double-click (no server), with a dismissible walkthrough rail (‹ › through ~20 chapters) drawn as demo chrome, never as app UI. Solves the artboard mockup's two gaps for a stakeholder meeting: it is navigable, and it needs no toolchain to open. |
| 2 | 20-screen curated scope, organized by Weekly Rhythm | Five acts: Getting oriented (2) · The weekly rhythm (7) · Sessions & coaching (4) · Learn & progress (5) · The coach app (2). Flow-completeness over coverage: every tap lands somewhere and the core loop (watch → recite → submit → hear back) is whole, rather than 40 screens where half are dead ends. |
| 3 | Reuse the Sakīna design system, single theme | Plum palette, light mode only — honoring the standing accessibility ask to "reduce color variety, single theme" (FEEDBACK-SYNTHESIS.md). Tokens copied verbatim from DESIGN-SYSTEM.md; kit primitives ported from the mockup's sak-base.jsx. |
| 4 | Both apps represented | The student app is the spine; the coach app gets a two-screen glimpse (review queue + reviewing a recitation) so the discussion can cover both sides and the async-feedback loop end to end. |
| 5 | Real content, one coherent world | Student Sarah Ahmed (Level II, Toronto/EDT, Week 8 of 15); coach Ustadha Amina (Cairo/EEST); group coach Ust. Radwa; passage Al-Mulk 67:1–3; the coach's real feedback notes — all extracted from the mockup's own fixtures (see build-notes/02-fixtures.md). Invented strings are flagged [FIXTURE] there. |
| 6 | newTwo screens designed where no source existed | onboarding-notify (opt-in reminders — the mockup's onboarding never asks; the principle is "reminders you choose, never default-on") and week-detail (a single-week drilldown — Learn only had multi-week "Parts"). book-confirm added as an explicit "just booked" state (the source folded confirmation into the ongoing appointment detail). |
| 7 | Normalized the source's term-label inconsistency | The mockup says "Spring 2026" everywhere (term ends Jun 22) except the Year-2 booking screens, which say "Fall 2026 · Year 2." The walkthrough uses Spring 2026 throughout. The mockup's own inconsistency is flagged for that workstream, not reproduced here. |
Technical decisions
| # | Decision | What & why |
|---|
| T1 | Vite + React 19 + TypeScript + Tailwind v4 + Motion | The reference stack. React for stateful navigation + motion; Tailwind v4 @theme for the shell; Motion for the iOS push/pop/sheet transitions. |
| T2 | Single-file build via vite-plugin-singlefile | JS, CSS and fonts inline into one index.html (~1.7 MB). Opens by double-click, sends as one attachment, works offline. This is the whole reason it beats the artboard canvas for a meeting. |
| T3 | Reused the reference app-shell, adapted | The custom stack navigator, device shell (iPhone frame on desktop, full-bleed on phone), tour rail and in-memory store are ~90% app-agnostic; ported and re-skinned to Sakīna rather than rebuilt. Hash deep-links (#/screen?param=x) + a ?shell=0&safe=ios review harness make every screen state directly addressable for screenshots. |
| T4 | Self-hosted fonts, inlined | Newsreader (display), DM Mono (numbers), Amiri (Arabic) via @fontsource — no network at runtime. Amiri carries the Qur'anic glyphs; the Amiri Quran variant was not pinned, to keep the dependency set minimal and the build reproducible. |
| T5 | Build is vite build only; type-check is separate | So a stray type error during a multi-agent build never blocks the single-file output. bun run typecheck runs tsc when wanted. |
| T6 | Demo state in memory only | Reload = fresh story. Nothing persisted; no localStorage. A plain open starts the guided tour at chapter 0; a deep-link open starts in free exploration with no tour chrome. |
Process decisions
| # | Decision | What & why |
|---|
| P1 | Model roles | Opus 4.8 orchestrated and built the shared foundation + the reference screen directly (the highest-risk, most-shared code), then reviews and verifies. Sonnet 5 ran the spec/fixtures recon and the four screen implementers, each with hard file ownership (one set of screen files, no shared-file edits) to avoid conflicts. |
| P2 | Central screenshot verification | Implementers do not run the build or a browser (a shared-directory build race would waste work); the orchestrator builds once, screenshots every screen headlessly via the deep-link harness, and looks at each before calling it done. "Compiles" is not "done." |
| P3 | A locked contract before fan-out | The design tokens, kit API, screen list, routing ids, business rules and the reference screen were all fixed before any implementer started, captured in build-notes/03-implementer-brief.md. Implementers execute the contract; they don't invent it. |
| P4 | Uncommitted until asked | Nothing committed to git without Kamran's ask. Everything lives under handoff/walkthrough/. |
Open items
| Item | Note |
|---|
| O1 | for Kamran / SOKContent sign-off | All copy traces to the mockup's fixtures, but the one English translation gloss and any [FIXTURE] strings (per-week theme names, notification labels) want a content/SOK review before this file is shown outside the team. |
| O2 | contentSource inconsistency upstream | The Spring/Fall 2026 mismatch (decision 7) still lives in the artboard mockup itself; normalize it there in a later pass. |
| O3 | for KamranHosting (optional) | The build is one HTML file, so it needs no hosting for the meeting (open it locally). If a shareable link is wanted later, it drops onto any static host (e.g. a Cloudflare Pages project) unchanged. |