Mockup Build Prompt

QuranFlow Mockup Build Process

What This Is

A screen-by-screen mockup build process for the QuranFlow iOS app redesign. Each screen gets 6-10 design iterations, evolving from a bold first pass to a polished, implementation-ready mockup.

Model requirement: Always use Opus 4.6 (claude-opus-4-6).

Tech stack: shadcn/ui with React + Tailwind CSS. Mobile-first, iPhone viewport (390px wide). Interactive prototypes, not static images.

Brand: Purple is the primary brand color (see logo at /design-reference-images/quranflow-logo-color-2x.png). Purple and purple gradients are welcome — use them intentionally as brand elements, not as generic filler.

References

Reference	Path	Purpose
Architecture spec	`/reviews/v6-output/phase-4-architecture.md`	WHAT each screen contains (content, states, behaviors). Read the relevant section before each screen.
WWDC25 Field Guide	`/reviews/reference-docs/App-Redesign-Field-Guide-WWDC25.md`	Validation checklist (3 Questions Test, Squint Test, Screen Anatomy, Progressive Disclosure).

The architecture spec defines WHAT to build. It says nothing about HOW it looks. Visual design is what the iterations figure out.

Screen Order

Build in this order. Each screen builds visual vocabulary that carries forward.

#	Screen	Key Challenge
1	Today	Home screen. Sets the visual language for everything else.
2	Learn	Week cards, journey map, Lesson/Submission/Feedback segments.
3	Recording	Quranic text display + recording interface.
4	Schedule	Calendar view, session cards, timezone handling.
5	Profile	Settings hub, coach section, menu groups.
6	Notification Sheet	Modal overlay with notification list.
7	Onboarding	5-step first-launch flow (simpler — 1-2 iterations each).

Per-Screen Workflow

Step 1: Read the Spec

Open /reviews/v6-output/phase-4-architecture.md. Read the section for this screen: content, states, behaviors, connections. Re-read it fresh each time — don't rely on memory from previous screens.

Step 2: Iteration 1 — Invoke the `frontend-design` Skill

Invoke the frontend-design skill (via Skill tool). This skill will guide you through committing to a bold aesthetic direction before writing code — typography, color, spatial composition, motion, backgrounds.

After the skill is loaded, build the screen following its methodology. The skill handles the design thinking process. Your job is to feed it the project-specific context it doesn't have:

What you're building: The screen content from Step 1
Who it's for: Busy adults, many older, many not tech-savvy. Clarity over cleverness. Large touch targets. High contrast. Readable type.
The dominant element: "Week N of 15" must be the most prominent element on the Today screen. On other screens, temporal orientation should still be visible but secondary.
Platform: iOS iPhone app

After building, take a screenshot and run the Validation Gate (see below). If it fails, fix the failures before proceeding.

Step 3: Iterations 2-N — Launch the Design Iterator Agent

Launch the compound-engineering:design:design-iterator agent via Task tool. This agent runs autonomously — it takes screenshots, analyzes, makes one improvement per iteration, and repeats.

Launch template:

subagent_type: "compound-engineering:design:design-iterator"
model: "opus"
prompt: |
  Refine the [SCREEN NAME] screen mockup.

  URL: [dev server URL, e.g., http://localhost:3000]
  Iterations: [5-9, depending on how many remain after iteration 1]
  Viewport: iPhone (390px wide)

  Aesthetic direction established in iteration 1: [brief summary of
  the typography, color palette, and layout approach chosen]

  Project constraints (do not violate):
  - "Week N of 15" is the dominant visual element on Today screen
  - All times must include timezone
  - Submission and feedback always shown together, never split
  - Mushaf/Uthmanic script as default for Quranic text
  - iOS bottom tab bar for navigation (4 tabs: Today, Learn, Schedule, Profile)
  - No hamburger menus, no Inter/Roboto/Arial fonts, no purple gradients
  - Users are busy adults, many older — large touch targets, high contrast

  Priority states to cover by the final iteration:
  [list from State Coverage section below]

The agent handles its own screenshot-analyze-improve cycle. Don't prescribe what it should focus on in which iteration — it decides based on its own analysis.

Step 4: Final Validation

After the design iterator finishes, run the validation gate one more time on the final state.

Step 5: Move to Next Screen

Carry forward the visual vocabulary (colors, typography, spacing, component patterns) established in previous screens. Summarize the key design decisions made for this screen before starting the next one — the summary becomes part of the design iterator's context for the next screen.

Validation Gate

Run this after iteration 1 and after the final iteration. Reference the full WWDC25 Field Guide at /reviews/reference-docs/App-Redesign-Field-Guide-WWDC25.md for details on any item.

3 Questions Test (screen fails if any fails):

Question	Pass Criteria
Where am I?	"Week X of 15" and screen identity visible in <1 second
What can I do?	ONE action visually dominates; others clearly secondary
Where can I go?	Tab bar visible; back navigation clear; no dead ends

Squint Test: Blur your eyes. Can you identify the most important element and the page structure? If not, hierarchy needs work.

Screen Anatomy: Toolbar at top (context + local actions), content area in middle, tab bar at bottom (navigation only, no actions).

Progressive Disclosure: Not everything on screen at once. Collections, "See All" links, disclosure indicators for depth. Group by time or progress, not alphabetically.

QuranFlow-Specific:

"Week X of 15" visible where relevant
All times include timezone
Submission and feedback shown together
Mushaf script for Quranic text
Touch targets large enough for older users

State Coverage

By the final iteration of each screen, these states should be represented:

Screen	Must-Have States
Today	Default (active week) + Behind + Pre-Semester
Learn	Current week expanded + All Weeks view + Behind (multiple incomplete)
Recording	Ready to Record + Recording + Review (post-recording)
Schedule	Active week with sessions + Live Now state
Profile	Default (mid-semester student)
Notification Sheet	With notifications + Empty
Onboarding	All 5 steps

Hard Rules

These are project-specific constraints that the skills and agents don't know about. They apply to every iteration.

The one rule: "Week N of 15" on the Today screen must be the most prominent element in the app. Everything else is secondary to temporal orientation.

Navigation:

iOS bottom tab bar (4 tabs), never hamburger menus
No top tabs instead of bottom tabs
No hiding essential features in settings
No external links for core functionality
Schedule reachable in 2 taps or fewer from anywhere

Visual:

No Inter/Roboto/Arial/system fonts
No excessively centered layouts
No uniform rounded corners everywhere
No cookie-cutter component patterns

Information:

All times include timezone
Week number always calculated for the user (never make them count)
Submission and feedback always shown together, never split
Mushaf/Uthmanic script as default for Quranic text (not hidden in settings)
No walls of text without structure

Users:

Busy adults, many older, many not tech-savvy
Clarity over cleverness
Large touch targets, high contrast, readable type

What Done Looks Like

A finished screen:

Contains all content from the architecture spec
Passes the 3 Questions Test and Squint Test
Handles its priority states visibly
Uses specific data ("Week 8 of 15", not "Week X of N")
Feels like a real iOS app, not a wireframe
Has gone through 6-10 iterations