Phase 4 — Learn Screen Amendments

Phase 4 — Learn Screen Spec Amendments

Version: 1.0 Date: February 26, 2026 Input: Phase 1 Problem Brief, Phase 2 Design Principles, Phase 3 Learnings, Phase 4 Architecture, WWDC25 Field Guide, User Capability Map, Implementation Experience (3+ mockup iterations) Status: Applied — Integrated into Phase 4 Architecture v1.2 on February 26, 2026

Why These Amendments Are Needed

Three rounds of mockup implementation revealed that the Phase 4 Learn screen specification produces designs that consistently fail visual quality standards, despite correct structural intent. The root causes trace to specific spec decisions that contradict the project's own design principles established in Phase 2.

This document proposes targeted amendments to the Learn screen section of the Phase 4 architecture (lines 240-338). Each amendment cites the specific principle it enforces and the specific problem it resolves.

Amendment 1: Replace Internal Segmented Control with Vertical Sections

Current spec (line 276):

"When expanded, the week card contains an internal segmented control: Lesson | Submission | Feedback"

Problem:

This creates 4 levels of navigation depth on a single mobile screen:

Screen → [This Week / All Weeks] toggle → Week accordion → [Lesson | Submission | Feedback] tabs → Content

This violates three Phase 2 principles:

• "Clarity over density" (Priority Stack #3): Tabs within cards add cognitive overhead without reducing information — they hide information behind taps.
• "Standard platform patterns over custom ones" (Priority Stack #4): Internal segmented controls within collapsible cards are not a standard iOS pattern. The WWDC25 Field Guide's "Anatomy of a Perfect Screen" shows Toolbar → Content → Tab Bar. There is no precedent for nested tab controls inside accordion sections.
• Content Principle 2 ("Items belonging to the same week must be co-located"): The internal tabs actually split the week's content into three hidden panes. Only one is visible at a time. The student must actively discover that their feedback is behind a tab, inside a card.

Amendment:

When the current week is displayed (in "This Week" view or expanded in "All Weeks"), its three content areas — Lesson, Submission, and Feedback — are laid out as vertically stacked sections in a continuous scroll. Each section has a labeled header using the established section header pattern (uppercase, letter-spaced, muted foreground) and its content below.

The vertical layout means:

• All three areas are discoverable by scrolling — no hidden panes
• The natural reading flow (top to bottom) mirrors the weekly workflow sequence (learn → submit → receive feedback)
• The same section header pattern used on the Today screen (e.g., "THIS WEEK", "TODAY'S SESSIONS") creates visual consistency across tabs

What this changes in the spec:

• Remove: "internal segmented control: Lesson | Submission | Feedback" (line 276)
• Replace with: "The week's content is presented as three vertically stacked sections — Lesson, Submission, and Feedback — in a continuous scroll. Each section has a labeled header matching the Today screen's section header pattern."
• Remove: "When expanded, the week card contains..." framing. The current week is not "inside a card" — it IS the page content.

Amendment 2: Define Visual Hierarchy (Matching Today's Specificity)

Current spec:

The Learn screen has no visual hierarchy guidance. Compare to the Today screen spec:

Today (line 158-164): "Week Header (dominant visual element)... Line 1 (Large Title size, bold): 'Week 8 of 15'... This header is the visual anchor of the screen. It is the largest text element."

The Learn screen (line 269) says only: "Each week card is a collapsible container with a header showing: 'Week [N]: [Topic Name]'"

This gap is why every implementation defaults to a generic layout. Without visual hierarchy guidance, the implementer treats all content equally, producing a flat, monotonous scroll.

Amendment — Add to spec:

Visual Hierarchy (Learn Screen — "This Week" View):

The Learn screen mirrors the Today screen's visual hierarchy pattern, adapted for its workspace purpose:

Above-the-fold rule: On first load in "This Week" view, the student must see: the week number and "of 15", the topic name, and the beginning of the Lesson section (first 1-2 video rows) — without scrolling. Submission and Feedback sections are below the fold.

Squint Test target (Phase 2, C2): When the screen blurs, the week number ("Week 8") remains identifiable as the dominant element. The progress ring is the second identifiable element. The video list card is the third.

Visual Hierarchy (Learn Screen — "All Weeks" View):

Amendment 3: Video Thumbnail Requirements

Current spec (lines 282-286):

"Video list: Each video as a row with: Checkbox (filled if watched, empty if not), Video title (e.g., 'Introduction to Madd Rules'), Duration (e.g., '4:32'), Tap target: opens Video Player screen"

Problem:

The User Capability Map, Task 3A.3, explicitly identifies "Generic thumbnails, not descriptive" as a current-app problem. The spec does not address this — it describes a text-only list. A video list without thumbnails looks like a file browser, not a learning experience. Every major learning platform (Coursera, Khan Academy, YouTube, Apple TV+) uses visual thumbnails.

Amendment — Replace video list spec with:

Video list: Each video as a row within a single grouped card (separated by subtle dividers). Each row contains:

• Thumbnail (52×38pt, rounded corners, 8pt radius): A small visual preview representing the video content. Displays a centered play icon overlay on a topic-appropriate background.

  • For mockup: Use varied gradient backgrounds (shifting hue per video within the purple family) to create visual distinction between videos.
  • For production: Replace gradients with actual video preview frames or topic-appropriate illustrations.
  • Watched state: Thumbnail background desaturated (reduced chroma) to indicate completion.

• Title and metadata:

  • Line 1: "Video [N]: [Title]" — 14pt, semibold for unwatched / medium weight + muted color for watched
  • Line 2: Duration + watched indicator — 12pt, muted secondary text (e.g., "3:45 · Watched")

• Status indicator:

  • Watched: Filled green checkmark circle (24pt diameter)
  • Unwatched: Right chevron indicating tappability

• Progress footer (inside the card, below the last row): A thin progress bar showing videos watched out of total, with a "2/3" counter. This mirrors the progress ring in the hero section but in a linear format appropriate for the detail level.

Amendment 4: Quranic Text Visual Treatment

Current spec (lines 292-293):

"Quranic text display: The assigned passage rendered in mushaf font (Amiri Quran), RTL, with proper Arabic typography. Font is mushaf by default -- no settings change required."

Problem:

This one-line description provides zero visual design guidance for the most culturally significant and visually distinctive element on the screen. The result is implementations that render Arabic text as plain body text — no visual distinction, no reverence, no breathing room. This is equivalent to specifying a music player as "audio plays when you tap the button" without describing the player UI.

Amendment — Replace with:

Quranic Text Display:

The assigned passage is presented in a dedicated display card that signals its sacred nature through visual treatment:

• Container: A distinct card with warm, slightly elevated background — using a subtle warm tint (e.g., oklch(0.97 0.01 75)) that differs from the standard card background. Rounded corners (16pt radius). No hard border — instead a very subtle shadow or soft border to create gentle separation. Generous internal padding (20pt horizontal, 24pt vertical).

• Typography: Amiri Quran font at 26-30pt (large enough for comfortable reading with diacritical marks). RTL text direction. Line height of 1.8-2.0× to accommodate Arabic marks (tashkeel) without overlap. Text centered horizontally within the card.

• Passage reference: Below the Arabic text, separated by 12pt of space: Surah name and ayah range in the body font at 13pt, muted foreground (e.g., "Surah Al-Mulk, Ayat 1-4"). Left-aligned (LTR) since this is transliterated text.

• Minimum card height: 120pt, to ensure the sacred text has visual prominence and breathing room even for short passages.

• Relationship to Record button: The Quranic text card sits directly above the Record CTA, creating a clear visual flow: read the passage → record your recitation. The text card and button should feel like one unit.

Rationale: The Quranic text is what distinguishes QuranFlow from a generic learning app. Proper visual treatment of the Arabic calligraphy elevates the entire design and signals respect for the content. Users are reading sacred text — the visual environment should reflect that.

Amendment 5: Clarify Screen Purpose — Workspace Primary, Overview Secondary

Current spec (line 242):

"Purpose: Show the student's complete learning journey organized by week, with the current week expanded and ready for action."

Problem:

This purpose statement serves two competing goals equally:

1. "Complete learning journey" = overview mode (macro, 15 weeks, where am I in the semester)
2. "Current week expanded and ready for action" = workspace mode (micro, watch videos, record, review feedback)

The Today screen succeeds because it has ONE clear purpose: dashboard. It surfaces status and routes the student to action. The Learn screen tries to be both a journey map AND an interactive workspace. Every implementation has struggled with this tension — either the overview elements dominate and the workspace feels cramped, or the workspace dominates and the overview is an afterthought.

Phase 2 Priority Stack #3: "Clarity over density. When in doubt, show less and disclose progressively."

Amendment — Replace purpose statement with:

Purpose: Provide the student's weekly learning workspace — the place where they watch lesson videos, read the assigned Quranic passage, submit their recording, and review coach feedback. The current week's content is the default view and primary focus.

The complete learning journey (all 15 weeks with statuses) is a secondary view for navigation, review, and catch-up — accessed via the "All Weeks" toggle.

Two distinct modes with distinct purposes:

The student's mental model: "I tap Learn to do my weekly lesson." Not "I tap Learn to see a map of my semester."

Amendment 6: Journey Map — Simplify and Relocate

Current spec (lines 250-262):

"A compact horizontal visualization of the 15-week semester: A horizontal track of 15 circles (one per week), connected by a line... Tapping any completed week circle scrolls to and expands that week card below"

Problem:

15 interactive circles on a 390px-wide screen. Each circle gets approximately 20px of space including gaps. This is:

• Below Apple's 44pt minimum tap target guideline
• Visually cramped — the circles cannot display meaningful status indicators at this size
• Competing with the week content below for the student's attention

Phase 3 Learnings note that the journey visualization from Proposal C should be considered. But Proposal C used a vertical journey map in a dedicated Progress tab — not a horizontal cramped bar above content.

Amendment:

In "This Week" view: The journey map is not shown. The hero section (week number at 58pt + "of 15" + topic name + progress ring) provides complete temporal context — exactly as the Today screen does. Adding a 15-circle visualization above this creates visual competition and pushes the video list below the fold, violating the above-the-fold rule from Amendment 2.

In "All Weeks" view: A simplified horizontal progress indicator appears at the top:

• A thin horizontal track (2pt height) connecting 15 small status dots
• Completed weeks: small filled circles (8-10pt) in primary accent color
• Current week: slightly larger filled circle (20pt) with week number, accent color, subtle glow/ring
• Behind weeks: filled circles in amber with alert indicator
• Upcoming weeks: hollow circles in muted color
• Graduation icon at the end of the track
• Below the track: summary text — "Week 8 of 15 — 4 completed, 2 behind"

Critical change: The dots are visual status indicators, not interactive tap targets. The week list below serves as the interactive navigation. This solves the 44pt tap target problem and eliminates the need for scroll-to behavior (which added implementation complexity without clear user value — the list is right below).

If interactive week selection is needed in a future iteration, it should use the week list rows as tap targets (which are full-width, comfortably tappable), not the tiny dots.

Amendment 7: Past Week Rows — Grouped Card with Progressive Disclosure

Current spec (lines 271-274):

"Each week card is a collapsible container with a header showing: 'Week [N]: [Topic Name]', Status badge, Chevron to expand/collapse"

Problem:

"Collapsible container" implies each week is its own card. In "All Weeks" view, this means 15 separate cards stacked vertically. Expanding one to show full content (with internal padding, video lists, Quranic text) creates visual disruption — the expanded card is dramatically larger than its collapsed neighbors, and the content inside has its own padding rules that conflict with the card's padding.

Phase 2 Content Principle 1 (Progressive Disclosure): "Show the top 5 items in a collection, add a disclosure indicator, let the user tap through to the full list."

Amendment:

In "All Weeks" view, past and future weeks are displayed as compact rows within a single grouped card:

Row layout:

• Left: Week number (bold, tabular, fixed width)
• Center: Topic name (regular weight, truncated if needed)
• Right: Status badge + chevron

Card container: All rows grouped in one card (bg-card rounded-xl border border-border/60) with dividers between rows. This matches the video list card pattern and the Today screen's session card pattern.

Expansion behavior (progressive disclosure): When a row is tapped, it expands inline to show a compact status summary — three mini-cards in a horizontal row:

Plus a "View Full Week" action that loads the complete week content in the workspace layout (replacing the current view).

Why not full inline expansion: Expanding a past week to show its complete content (video list + Quranic text + feedback audio player) inside a card row creates extreme layout disruption. The expanded state is 5-10× the height of the collapsed row, breaking the visual rhythm of the list. The compact summary provides the information the student needs (status at a glance) and the "View Full Week" action provides the escape hatch for full content.

Amendment 8: Submission Section — Visual Prominence Matching Today's Primary Action

Problem:

The spec describes the submission CTA as "Record Submission button (large, centered, mic icon)" but provides no visual treatment guidance. The Today screen's Primary Action Card is specified with rich detail:

Today (line 166-168): "A single prominent card that changes based on the student's state... colored left border (accent color), a title, a subtitle, and a single action button"

The submission recording is the single most important weekly action — it's the output that gets graded. It deserves the same visual prominence as Today's Primary Action Card.

Amendment — Add visual treatment guidance:

Submission section visual treatment by state:

The Quranic text card (from Amendment 4) appears above the CTA in the "Not yet submitted" state, creating the visual flow: sacred text → record button. When the submission has been sent, the Quranic text card can be collapsed or hidden (the student no longer needs to reference it actively).

Amendment 9: Add "Learning Objectives" Spec

Current spec (line 281):

"Learning objectives: Blue info box with 2-4 bullet points describing what the student will learn"

Problem:

This element is specified in the Lesson segment but has no visual treatment guidance and was omitted from every mockup iteration because it competed for space with the video list. It needs either a clear visual spec or a decision about whether it's necessary.

Amendment:

Learning objectives appear as a subtle info block between the week header and the video list:

• Treatment: Not a separate card. Instead, a muted text block with a small icon (e.g., a lightbulb or book icon) and 2-3 short bullet points in 13pt body text. Background: transparent or very subtle tint. No border.
• Purpose: Orient the student to what they'll learn this week. Brief — each bullet is one line.
• Progressive disclosure: Collapses to a single line ("3 learning objectives") with expand chevron after the first visit. The student sees it fully once, then it gets out of the way.

Example:

📖  This week you'll learn:
    · When to apply Idgham with nasal resonance
    · The difference between Idgham with and without Ghunnah
    · How to hold the Ghunnah for exactly 2 counts

If this element is deemed unnecessary for the mockup phase, it can be deferred — but the spec should explicitly state "deferred to implementation" rather than leaving it ambiguous.

Summary of All Amendments

Broader Spec Gap: Missing "Visual Design Language" Section

Beyond the Learn screen, the Phase 4 architecture would benefit from a new section (perhaps 4.3.5 or an appendix) that defines the shared visual design language across all screens:

• Hero typography pattern: Display serif, 58pt, font-black — used for week numbers on both Today and Learn
• Section header pattern: 11pt, bold, uppercase, tracked, muted — used for all section labels
• Card pattern: bg-card, rounded-xl, border with 60% opacity — used for all content containers
• Gradient CTA pattern: linear-gradient with subtle border and shadow — used for primary actions
• Status badge pattern: colored pill with uppercase label — used for week and submission statuses
• Progress ring pattern: SVG ring with percentage — used for completion indicators
• Touch interaction pattern: active:scale-[0.97], touch-manipulation — used for all tappable elements

Defining these once prevents the visual inconsistency that occurs when each screen spec re-describes (or fails to describe) the same patterns.

What These Amendments Do NOT Change

The following Phase 4 decisions are preserved:

• The [This Week / All Weeks] segmented control (correct and functional)
• The week-as-unit grouping principle (the core insight from Proposal A)
• The co-location of Lesson + Submission + Feedback within each week (Quality Bar C3)
• The accordion behavior in "All Weeks" view (one expanded at a time)
• All 8 states defined in the states table (lines 314-324)
• All behaviors (lines 326-334)
• All connections to other screens (lines 336-338)
• The tab bar structure (Today | Learn | Schedule | Profile)

These amendments refine HOW the Learn screen presents its content, not WHAT content it presents.