M03: Scripture Reader — `v0.3.0-alpha`

Version tag: web/v0.3.0-alpha Phase: P1: Core Reader Target: Weeks 9–14 Sprints: S4 (tail), S5, S6

Phase Context

Goal: A web app where users can read all LDS scriptures, navigate by book/chapter, search, and annotate (highlights, notes, bookmarks). The free tier of MVP.md § Free Tier.

Key constraint: This must be "genuinely better than Gospel Library" — the free tier IS the acquisition funnel.

ZenHub Configuration

Field	Value
Milestone	M03: Scripture Reader
Due Date	2026-06-14
Default Pipeline	Product Backlog
Primary Epic(s)	Scripture Reader Core, UI Foundation, Reader Interaction

Prerequisites

M02: Content API — content API serving passage data
M02: Shared Types — @gospelib/sdk wired to content endpoints

Epic: Scripture Reader Core

Story Area	Scope	Spec Reference
App shell	Layout, navigation sidebar, responsive breakpoints	DESIGN-SYSTEM.md § Navigation
Route structure	`(marketing)/` and `(app)/` route groups	TECH-SPEC.md § Next.js Apps
Scripture text display	`ScriptureText`, `VerseNumber`, `ChapterHeader` components	DESIGN-SYSTEM.md § P1 Components
Chapter navigation	Book selector → chapter list → verse display	DESIGN-SYSTEM.md § Navigation
Typography controls	Font size, 3 density modes (spacious/comfortable/compact)	MVP.md § Feature #9, DESIGN-SYSTEM.md § Reader
Dark mode	Light / Study Dark / Blackout themes	DESIGN-SYSTEM.md § Dark Mode
Reading modes	Reading mode (default) — Study and Interlinear modes deferred	DESIGN-SYSTEM.md § Render Modes
Responsive layout	Desktop, tablet, mobile breakpoints — web only	MVP.md § Platform

Issues

ID	Title	Status	Notes
M03-001	App Shell — Layout, Navigation Sidebar, Responsive Breakpoints	✅ Done	AppShell component with BottomTabBar, SidebarNav, responsive top bar
M03-002	Route Structure — `(marketing)/` and `(app)/` Route Groups	✅ Done	Route groups: (app)/reader/[...slug], (app)/study, (app)/explore, (marketing)/, (auth)/sign-in, (auth)/sign-up
M03-002a	Tailwind CSS v4 Setup, Preliminary Brand Theme & Lucide Icons	✅ Done	globals.css uses `@import 'tailwindcss'`; brand palette extended; Icon component wrapper in packages/ui
M03-002b	UI Infrastructure — TanStack Query, `cn()` Utility, React Native Web Alias	✅ Done	Providers/Providers.tsx with QueryClientProvider; packages/ui/src/utils/cn.ts; React Native Web configured
M03-003	Scripture Text Display — `ScriptureText`, `VerseNumber`, `ChapterHeader`	✅ Done	packages/ui: ScriptureText, VerseNumber, VerseBlock, ChapterHeader with all variants and tests
M03-004	Chapter Navigation — Book Selector → Chapter List → Verse Display	✅ Done	BookNavigator.tsx (testament groups → books → ChapterGrid), 220ms slide + crossfade transition, prev/next in ReaderChrome
M03-005	Typography Controls — Font Size, 3 Density Modes	✅ Done	Zustand store + TypographyProvider + CSS custom properties; 20 unit tests passing (PR #901)
M03-006	Dark Mode — Light / Study Dark / Blackout Themes	✅ Done	ThemeProvider in apps/web + packages/ui/src/theme with light/dark/blackout/night-warm mode store
M03-007	Reading Modes — Reading Mode (Default)	✅ Done	Reading mode default in navigation store; section headings 0.8em small-caps; SDK-fetched passage data
M03-008	Responsive Layout — Desktop, Tablet, Mobile Breakpoints	✅ Done	AppShell: md:hidden BottomTabBar, sidebar breakpoints; SplitPaneLayout; responsive margins in ScripturePage
M03-009	Design Token System — Full Implementation	✅ Done	packages/ui/src/theme/tokens.ts with color scales, spacing, radii, elevation, motion; validated by tokens.test.ts
M03-010	Typography Infrastructure — Font Loading, Type Scale, Scripture Rendering Rules	✅ Done	apps/web/app/scripture-typography.css + globals.css; TypographyProvider with runtime CSS custom properties
M03-011	Paper & Chrome Surface System	✅ Done	packages/ui/src/components/: Surface with paper/chrome variants; noiseTexture.ts; elevation-aware shadows
M03-012	Shape & Geometry System	✅ Done	packages/ui/src/theme/shape.ts with corner radius constants per surface type
M03-013	Custom Icon Set (P1 Subset)	✅ Done	12 custom SVG icon components (GlReaderIcon…GlCorpusPogpIcon) with line/filled variants; SidebarNav + BottomTabBar updated
M03-014	Motion & Animation System	✅ Done	useReducedMotion.ts hook + motion tokens (4 easing curves, 5 durations) + animation utilities in globals.css
M03-015	Theme Provider — 3 Modes + Night Warm	✅ Done	packages/ui/src/theme/ThemeProvider.tsx + store.ts with mode cycling and CSS custom property resolution
M03-016	Core Primitives — Button, Icon, Text, Card, Badge	✅ Done	packages/ui/src/components/: Button, Badge, Card, Text — all implemented with token integration
M03-017	Scripture Display Components — `ScripturePage`, `VerseBlock`, `ChapterHeader`	✅ Done	packages/ui/src/components/: ScripturePage, VerseBlock, VerseNumber, ScriptureText, ChapterHeader, OriginalLanguageText, RedLetterText
M03-018	Layout Components — `BottomTabBar`, `SideRail`, `ReaderChrome`, `SplitPaneLayout`	✅ Done	packages/ui/src/components/: BottomTabBar, SideRail, ReaderChrome, SplitPaneLayout — all implemented
M03-019	Loading & Skeleton States	✅ Done	packages/ui/src/components/: ScripturePageSkeleton (shimmer animation), FirstLoadBreathing (icon animation)
M03-020	Empty & Error State Patterns	✅ Done	packages/ui/src/components/: EmptyState + ErrorCard with amber error card styling and tests
M03-021	Accessibility Foundation	✅ Done	AccessibilityProvider, useAccessibility.ts hook; accessibility.test.ts, touchTargets.test.ts, contrastRatio.test.ts
M03-022	Component Playground — Storybook	✅ Done	packages/ui/.storybook/ configured; 8 story files (Button, Text, Card, Badge, ScripturePage, VerseBlock, ChapterHeader, Icon)

Progress: 23 Done · 0 Partial · 0 To Do (100% ✅)

Epic: UI Foundation

Build foundational @gospelib/ui components. Ref: DESIGN-SYSTEM.md § Component Priority.

Story Area	Scope	Spec Reference
Design token system	Full token implementation: color scales (navy, tan, white), doctrinal colors, corpus colors, semantic colors, functional colors, personal highlight colors, Night Warm tints. Spacing, radii, elevation shadows, motion curves/durations, layout constants, density presets — all from `tokens.ts`	DESIGN-SYSTEM.md § Design Tokens Reference
Typography infrastructure	Font loading/serving: Gentium Plus (scripture), Inter (UI), SBL Hebrew (Hebrew). Type scale (xs–3xl). Scripture text rendering rules (`font-feature-settings`, verse number styling, chapter drop caps, red-letter toggle). Original language text rules (RTL direction, sizing, line height)	DESIGN-SYSTEM.md § Typography
Paper & chrome surface system	Two surface personalities: paper (warm texture, `white-200`, noise pattern, warm shadows) vs chrome (clean, flat, cooler). 6-level elevation scale with warm `rgba(20,16,10)` shadows	DESIGN-SYSTEM.md § Elevation & Surface Language
Shape & geometry system	Corner radius philosophy: 12px paper, 8px chrome, 4px chips, 50% circular. Border usage rules. Horizontal rule styling	DESIGN-SYSTEM.md § Shape & Geometry
Custom icon set (P1 subset)	Stroke-based 1.5px icon system. P1 icons: `reader`, `explore`, `study`, `search`, `profile`, `settings`, corpus icons (`corpus-ot`, `corpus-nt`, `corpus-bom`, `corpus-dc`, `corpus-pogp`). Line default / filled active state convention	DESIGN-SYSTEM.md § Iconography
Motion & animation system	Easing curves (spring-snappy, smooth-in-out, decelerate, accelerate). Duration scale (instant→slow). Reduced motion support (`prefers-reduced-motion` crossfade fallbacks)	DESIGN-SYSTEM.md § Motion & Animation
Theme provider (3 modes)	Light / Study Dark / Blackout modes with semantic token resolution. Night Warm independent overlay. CSS custom properties or RN theme context for all tokens	DESIGN-SYSTEM.md § Dark Mode & Theming
Core primitives	Button, Icon, Text, Card, Badge — using token system	DESIGN-SYSTEM.md § Component Catalog P5
Scripture display components	`ScripturePage` (paper surface, scroll, gesture detection), `VerseBlock` (number + text + layers), `ChapterHeader` (drop cap, corpus bar, 3 styles)	DESIGN-SYSTEM.md § Component Catalog P1
Layout components	`BottomTabBar`, `SideRail`, `ReaderChrome` (auto-hide/summon with 3s timeout), `SplitPaneLayout` (tablet/web)	DESIGN-SYSTEM.md § Component Catalog P5, DESIGN-SYSTEM.md § Layout & Navigation
Loading & skeleton states	Scripture page shimmer (tan gradient, 1.8s), verse-number placeholders, content-shaped skeletons matching scripture text metrics. Optimistic UI pattern. First-load breathing icon animation	DESIGN-SYSTEM.md § Loading & Waiting States
Empty & error state patterns	Inline amber error cards (Elevation 1, never modal). Wordless success confirmations (visual change + haptic only). Empty state template (icon mark + one sentence + action)	DESIGN-SYSTEM.md § App-Wide Polish & Tone
Accessibility foundation	System font size scaling + in-app slider. 44×44px minimum touch targets. WCAG 2.1 AA contrast in default modes, AAA in Blackout. Screen reader labels. `lang` attributes for Hebrew/Greek	DESIGN-SYSTEM.md § Accessibility
Component playground	Storybook-based internal playground (`packages/ui/.storybook/`). All components in all states. Mode/density/font toggles. Visual regression baseline	DESIGN-SYSTEM.md § Design System Governance

Issues

(Issues for this epic are numbered as part of the main M03 issue list above)

Epic: Reader Interaction

Reader interaction patterns and gesture system needed for the P1 reading experience.

Story Area	Scope	Spec Reference
Reader chrome behavior	Auto-hide after 3s, single-tap margin summon, scroll-reveal (configurable). Minimal top bar (book/chapter nav) + bottom bar (progress + tools)	DESIGN-SYSTEM.md § Reader Chrome Behavior
Quick Settings Tray	Half-swipe-up invocation. Font size slider (12–28px, live preview), line spacing slider, brightness, density chips, mode chips, font dropdown. Bottom sheet (280px resting height)	DESIGN-SYSTEM.md § Quick Settings Tray
Reading density modes	Spacious / Comfortable / Compact. Line height, paragraph spacing, font size delta. Animated transitions (300ms smooth-in-out) with scroll position preservation	DESIGN-SYSTEM.md § Reading Density
Context panel (tablet/web)	Right-side 360px persistent workspace. State-driven content (empty → word → verse → AI → topic → search). History navigation. Remembers last content on chapter switch	DESIGN-SYSTEM.md § Contextual Panel System

Issues

(Issues for this epic are numbered as part of the main M03 issue list above)

Document References

Doc	Contains	Use When Writing Stories For
MVP.md	Feature scope, tier breakdown, success criteria, budget	Acceptance criteria, scope boundaries
TECH-SPEC.md	Architecture, service boundaries, data stores, API catalog	Technical implementation details
DESIGN-SYSTEM.md	Visual identity, component catalog, reader modes, tokens	UI component stories
DESIGN-SYSTEM.md §§ 13, 21–23	Footnotes (§13), subscription boundaries (§21), sharing (§22), onboarding (§23)	UX flow stories
GOSPELIB-SCHEMAS.md	All 7 schema families, node/edge types, validation rules	Data models, Pydantic models, graph schema
Deployment & Operations	Environments, K8s, CI/CD, migrations, secrets, DR	Infrastructure and deployment stories
REPO-MAP.md	Directory structure, naming conventions, dependency rules	All stories (coding standards)
Business	LEGAL.md, POLICY-TERMS.md, executive summary, market research, GTM	Launch readiness, legal/compliance stories

Sprint Mapping

Sprint	Weeks	Primary Focus
S4 (tail)	9–10	M02 content service + gateway complete; M03 work begins as API is available
S5	11–12	Design token system, typography infrastructure, paper/chrome surfaces, icon set (P1), motion system, theme provider, core primitives, app shell, route structure
S6	13–14	Scripture display components, reader chrome, Quick Settings Tray, density modes, dark mode, loading/skeleton states, empty/error patterns, accessibility, component playground

Sprint Load Warnings

⚠️ S5 (Weeks 11–12) packs the entire design token system + typography + surfaces + icons + motion + theme + primitives + app shell + routes into 2 weeks. Consider splitting: tokens + typography + theme in S5; icons + motion + primitives + app shell in S6.

⚠️ S6 (Weeks 13–14) compounds with scripture display + reader chrome + Quick Settings + density + dark mode + loading states + error patterns + accessibility + playground. May need to push some items to S7.

Release Info

Release	Tag	Contains
`v0.3.0-alpha`	`web/v0.3.0-alpha`	Scripture reader — text display + chapter navigation + typography controls + dark mode + responsive layout

Relevant Risks

Risk	Impact	Mitigation
Custom icon set scope creep	Delays P1 reader delivery	Ship P1 with minimum viable icon set (navigation + corpus only); expand in P2. Consider temporary placeholder icons
Design token system complexity	Over-engineering slows initial delivery	Implement tokens incrementally: colors + typography first (S5), then elevation + motion + density (S6). Keep token API simple
Solo founder velocity	38-week plan too aggressive	Founding users at Week 22 provide feedback before full scope; cut P3 scope if needed

Cross-Cutting Concerns

Testing

Layer	Framework	When	Spec Reference
TypeScript unit	Vitest	Every PR	TECH-SPEC.md § Testing
Component visual	Storybook or playground	P1+	DESIGN-SYSTEM.md § Governance
Visual regression	Playwright + pixelmatch	P1+ (any `packages/ui/` or `apps/*/src/` change)	DESIGN-SYSTEM.md § Visual Regression CI

Documentation

Doc	Update Trigger
API OpenAPI specs	Each service milestone
ADRs	Each major technical decision

CI/CD

Addition	Detail
Nx affected test execution	Vitest workspace already configured; needs per-project configs
Visual regression screenshots	Playwright renders component playground; `pixelmatch` diff blocks PRs exceeding 0.5% threshold

Dependencies

Upstream (what M03 needs)

M02: Content API — content API serving passage data via HTTP
M02: Shared Types — @gospelib/sdk wired to content service endpoints; @gospelib/types with scripture types

Downstream (what depends on M03)

M04: Annotations — depends on reader shell (verse anchoring for annotations)
M05: Search & Staging — search UI lives in the web app built here
M06: Interlinear & Lexicon — interlinear mode extends the reader built here
M09: AI Study Assistant — AI panel lives in the web app built here

Issue Dependency Graph

M03-009 (tokens) ──────────────────────────────────────────────────────────────┐
    ├──► M03-010 (typography) ──► M03-003 (scripture text) ──► M03-005 (typo controls)
    │                         └──► M03-017 (scripture UI)  ──► M03-007 (reading mode)
    ├──► M03-011 (surfaces) ──► M03-003                        M03-008 (responsive)
    │                       └──► M03-019 (loading)
    │                       └──► M03-020 (errors)
    ├──► M03-015 (theme) ───► M03-006 (dark mode)
    │                    └──► M03-016 (primitives) ──► M03-018 (layout) ──► M03-023*
    │                    └──► M03-017              └──► M03-022 (playground)
    │                    └──► M03-021 (a11y)
    ├──► M03-013 (icons) ──► M03-016
    │                    └──► M03-018
    ├──► M03-014 (motion) ──► M03-018
    │                     └──► M03-019
    │                     └──► M03-020
    │                     └──► M03-021
    └──► M03-012 (shape)

M03-001 (app shell) ──► M03-002 (routes) ──► M03-004 (chapter nav) ──► M03-007
                    └──► M03-004
                    └──► M03-008

M03-003 ──► M03-005 ──► M03-024*
        └──► M03-006 ──► M03-024*
        └──► M03-007 ──► M03-023*
        └──► M03-008 ──► M03-026*

Legend: A ──► B means A blocks B (B is blocked by A). * = issue not yet defined in this milestone.

Summary

Metric	Count
Total Issues	23 (incl. M03-002a, M03-002b)
Sub-Issues	19
Total Estimate (pts)	122
Sprints	S5–S6
Completed	23/23 (100%) — 2026-04-03
Dependencies (blocking)	42
Dependencies (blocked by)	42

Phase Context​

ZenHub Configuration​

Prerequisites​

Epic: Scripture Reader Core​

Issues​

Epic: UI Foundation​

Issues​

Epic: Reader Interaction​

Issues​

Document References​

Sprint Mapping​

Sprint Load Warnings​

Release Info​

Relevant Risks​

Cross-Cutting Concerns​

Testing​

Documentation​

CI/CD​

Dependencies​

Upstream (what M03 needs)​

Downstream (what depends on M03)​

Issue Dependency Graph​

Summary​

Phase Context

ZenHub Configuration

Prerequisites

Epic: Scripture Reader Core

Issues

Epic: UI Foundation

Issues

Epic: Reader Interaction

Issues

Document References

Sprint Mapping

Sprint Load Warnings

Release Info

Relevant Risks

Cross-Cutting Concerns

Testing

Documentation

CI/CD

Dependencies

Upstream (what M03 needs)

Downstream (what depends on M03)

Issue Dependency Graph

Summary