Design Decisions

QuranFlow Design Decisions

Purpose: Living document capturing all design decisions made during implementation. Last Updated: 2026-02-26

How to Use This Document

This document grows as the mockup is built. Each decision not covered by the Architecture Proposals spec gets documented here.

Entry format:

### [Date] - [Brief Title]
**Gap**: What was missing
**Decision**: What we decided
**Rationale**: Why

For full template, see .claude/skills/quranflow-design/templates/decision.md

Global Decisions

Decisions that apply across all screens.

(No decisions yet - document as they arise)

Tab Bar

Decisions about the bottom navigation.

(No decisions yet)

Today / Home Screen

Decisions about the primary landing screen.

(No decisions yet)

Learn / Lessons

Decisions about lesson content and submission flow.

(No decisions yet)

Schedule / Live

Decisions about session scheduling and live content.

(No decisions yet)

Progress / Feedback

Decisions about progress tracking and feedback display.

(No decisions yet)

Profile / More

Decisions about user profile and settings.

2026-02-26 - Profile screen visual anchor is avatar, not hero typography

Gap: The spec didn't define what the visual anchor (squint test target) should be for the Profile screen. Every other tab uses 58pt hero typography ("Week 8 of 15"). Decision: The profile card with 72px circular avatar is the visual anchor. Profile is the one tab that does NOT use the hero typography pattern. Rationale: Profile answers "who am I?" not "what week is it?" The student's identity (not the week number) is the question being answered. This matches Apple Settings (Apple ID card is the anchor).

2026-02-26 - Week indicator as pill badge (not plain text)

Gap: The spec says to show "Week 8 of 15" but gives no visual treatment for it on this screen. Decision: Render "Week 8 of 15" as a purple-tinted pill badge (oklch(0.95 0.025 285) background, oklch(0.40 0.15 285) text, rounded-full) inside the profile card. Rationale: Makes the temporal info read as a meaningful status indicator rather than caption text. Visually separates it from the name/level hierarchy above.

2026-02-26 - Quick Stats use display font (Fraunces) for numbers

Gap: No typography spec for the Quick Stats row. Decision: Stat values use font-display (Fraunces) at 22px bold. Stat labels use 11px semibold uppercase tracking-wider, matching the Section Header Pattern weight. Rationale: Branded numbers are consistent with the Today screen's numerical hierarchy. The display serif gives the numbers visual weight without increasing size.

2026-02-26 - Coach section uses gradient card (not standard Card Pattern)

Gap: Spec says "visually prominent — bordered card with slight elevation" but gives no specific treatment. Decision: Coach card uses linear-gradient(135deg, oklch(0.97 0.012 285), oklch(0.985 0.005 80)) background with a purple-tinted border and subtle shadow (0 2px 12px oklch(0.44 0.22 285 / 0.06)). Coach name uses Fraunces display serif at 16px. Rationale: The gradient differentiates it from standard menu group cards below. The subtle purple tint reinforces the relationship with the primary brand color without being heavy. Coach name in display font gives it warmth and importance.

2026-02-26 - Menu row icons use color-coded tinted backgrounds

Gap: Spec lists menu groups but gives no icon treatment. Decision: Each icon sits in a w-8 h-8 rounded-lg container with a section-specific tinted background:

• Account: purple tint (oklch(0.94 0.03 285), icon oklch(0.44 0.22 285))
• Settings: amber tint (oklch(0.94 0.04 75), icon oklch(0.50 0.12 65))
• Support: green tint (oklch(0.94 0.04 160), icon oklch(0.45 0.12 160))
• Sign Out: red tint (oklch(0.95 0.04 27), icon destructive red) Rationale: Color-coded icon backgrounds follow the iOS Settings pattern for section differentiation. Improves scannability — users can identify which section they're in by color alone.

2026-02-26 - Menu rows are 48px minimum height (above 44pt HIG)

Gap: Spec says 44pt minimum touch targets. No specific row height given. Decision: Menu rows use min-h-[48px] for comfortable touch targets. Rationale: 48px provides a more comfortable tap area for the target demographic (busy adults, many older). The extra 4px over the HIG minimum costs negligible vertical space.

Component Library

Decisions about shared/reusable components.

(No decisions yet)

Typography & Spacing

Decisions about type scale and spacing system.

(No decisions yet)

Color & Theme

Decisions about color palette and theming.

(No decisions yet)

States & Feedback

Decisions about loading, error, empty, and success states.

(No decisions yet)

Decision Index

Quick reference of all decisions by date.