designmd-forge 1.2.0

package/dist/data/designs/ios-calm-swiftui.md

@@ -0,0 +1,327 @@
+# Calm (iOS) — SwiftUI Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file translates Calm's visual language into paste-ready SwiftUI code: `Color` extensions, `Font` extensions, `ViewModifier`s, and example views.
+
+## 1. Color Tokens
+
+```swift
+import SwiftUI
+
+extension Color {
+    // MARK: - Night-Sky Gradient
+    static let calmGradientTop    = Color(red: 0.165, green: 0.435, blue: 0.839) // #2A6FD6
+    static let calmGradientMid    = Color(red: 0.102, green: 0.290, blue: 0.561) // #1A4A8F
+    static let calmGradientBottom = Color(red: 0.043, green: 0.118, blue: 0.247) // #0B1E3F
+    static let calmScrimNavy      = Color(red: 0.035, green: 0.094, blue: 0.188) // #091830
+
+    // MARK: - Glass Surfaces
+    static let calmGlass        = Color.white.opacity(0.08)
+    static let calmGlassRaised  = Color.white.opacity(0.12)
+    static let calmGlassDivider = Color.white.opacity(0.12)
+    static let calmGlassHover   = Color.white.opacity(0.16)
+
+    // MARK: - Text
+    static let calmTextPrimary   = Color.white                                  // #FFFFFF
+    static let calmTextSecondary = Color(red: 0.722, green: 0.769, blue: 0.847) // #B8C4D8
+    static let calmTextTertiary  = Color(red: 0.529, green: 0.580, blue: 0.659) // #8794A8
+
+    // MARK: - Accent
+    static let calmBlue         = Color(red: 0.165, green: 0.435, blue: 0.839) // #2A6FD6
+    static let calmBluePressed  = Color(red: 0.122, green: 0.341, blue: 0.671) // #1F57AB
+    static let calmBlueSoft     = Color(red: 0.290, green: 0.522, blue: 0.878) // #4A85E0
+    static let calmStreakGold   = Color(red: 0.949, green: 0.812, blue: 0.298) // #F2C94C
+    static let calmGentleError  = Color(red: 0.878, green: 0.541, blue: 0.541) // #E08A8A
+    static let calmSuccess      = Color(red: 0.498, green: 0.722, blue: 0.627) // #7FB8A0
+}
+
+extension LinearGradient {
+    static let calmSky = LinearGradient(
+        stops: [
+            .init(color: .calmGradientTop,    location: 0.0),
+            .init(color: .calmGradientMid,    location: 0.45),
+            .init(color: .calmGradientBottom, location: 1.0),
+        ],
+        startPoint: .top, endPoint: .bottom
+    )
+}
+```
+
+## 2. Typography
+
+Lora (serif headlines) and Inter (sans body) are both open-source (SIL OFL). Bundle TTFs via `Info.plist` (`UIAppFonts`).
+
+```swift
+extension Font {
+    // Lora — serif, the brand voice
+    static let calmGreeting   = Font.custom("Lora-SemiBold", size: 30)
+    static let calmScreenTitle = Font.custom("Lora-SemiBold", size: 26)
+    static let calmDailyTitle = Font.custom("Lora-SemiBold", size: 24)
+    static let calmCardTitle  = Font.custom("Lora-SemiBold", size: 19)
+    static let calmBreatheCue = Font.custom("Lora-Regular",  size: 22)
+
+    // Inter — sans, supporting
+    static let calmSection    = Font.custom("Inter-Bold",     size: 16)
+    static let calmRowTitle   = Font.custom("Inter-SemiBold", size: 17)
+    static let calmBody       = Font.custom("Inter-Regular",  size: 17)
+    static let calmSubtitle   = Font.custom("Inter-Regular",  size: 15)
+    static let calmButton     = Font.custom("Inter-SemiBold", size: 17)
+    static let calmMeta       = Font.custom("Inter-Medium",   size: 13)
+    static let calmTab        = Font.custom("Inter-SemiBold", size: 11)
+    static let calmTimer      = Font.custom("Inter-Light",    size: 44)
+    static let calmLabelUpper = Font.custom("Inter-Bold",     size: 12)
+}
+```
+
+## 3. Signature Components
+
+### Night-Sky Background
+
+```swift
+struct CalmBackground<Content: View>: View {
+    @ViewBuilder var content: Content
+    var body: some View {
+        ZStack {
+            LinearGradient.calmSky.ignoresSafeArea()
+            content
+        }
+    }
+}
+```
+
+### Breathe Bubble (signature)
+
+```swift
+struct BreatheBubble: View {
+    @State private var diameter: CGFloat = 120
+    @State private var cue = "Breathe in"
+    private let base: CGFloat = 120
+    private let peak: CGFloat = 220
+
+    var body: some View {
+        ZStack {
+            Circle()
+                .fill(Color.white.opacity(0.9))
+                .frame(width: diameter, height: diameter)
+                .shadow(color: .calmBlueSoft.opacity(0.6), radius: 40)
+            Text(cue)
+                .font(.calmBreatheCue)
+                .foregroundStyle(Color.calmGradientBottom)
+                .animation(.easeInOut(duration: 0.6), value: cue)
+        }
+        .onAppear { runCycle() }
+    }
+
+    private func runCycle() {
+        // Inhale 4s
+        withAnimation(.easeIn(duration: 4)) { diameter = peak }
+        cue = "Breathe in"
+        // Hold 7s
+        DispatchQueue.main.asyncAfter(deadline: .now() + 4) { cue = "Hold" }
+        // Exhale 8s
+        DispatchQueue.main.asyncAfter(deadline: .now() + 11) {
+            cue = "Breathe out"
+            withAnimation(.easeOut(duration: 8)) { diameter = base }
+        }
+        DispatchQueue.main.asyncAfter(deadline: .now() + 19) { runCycle() }
+    }
+}
+```
+
+### Primary Play Pill
+
+```swift
+struct CalmPlayPill: View {
+    let title: String
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: action) {
+            HStack(spacing: 10) {
+                Image(systemName: "play.fill").font(.system(size: 16))
+                Text(title).font(.calmButton)
+            }
+            .foregroundStyle(.white)
+            .padding(.vertical, 16)
+            .padding(.horizontal, 40)
+            .background(Capsule().fill(Color.calmBlue))
+        }
+        .sensoryFeedback(.impact(flexibility: .soft), trigger: title)
+        .buttonStyle(CalmPressableStyle(scale: 0.97))
+    }
+}
+
+struct CalmPressableStyle: ButtonStyle {
+    var scale: CGFloat = 0.97
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label
+            .scaleEffect(configuration.isPressed ? scale : 1)
+            .animation(.easeOut(duration: 0.25), value: configuration.isPressed)
+    }
+}
+```
+
+### Daily Calm Hero Card (signature)
+
+```swift
+struct DailyCalmHero: View {
+    let title: String
+    let subtitle: String
+    let photo: Image
+    let onPlay: () -> Void
+
+    var body: some View {
+        ZStack(alignment: .bottomLeading) {
+            photo.resizable().aspectRatio(contentMode: .fill)
+            LinearGradient(
+                colors: [.clear, .calmScrimNavy.opacity(0.85)],
+                startPoint: .top, endPoint: .bottom
+            )
+            HStack(alignment: .bottom) {
+                VStack(alignment: .leading, spacing: 6) {
+                    Text("DAILY CALM")
+                        .font(.calmLabelUpper).tracking(1)
+                        .foregroundStyle(.white)
+                    Text(title).font(.calmDailyTitle).foregroundStyle(.white)
+                    Text(subtitle).font(.calmSubtitle).foregroundStyle(Color.calmTextSecondary)
+                }
+                Spacer()
+                Button(action: onPlay) {
+                    Image(systemName: "play.fill")
+                        .font(.system(size: 18)).foregroundStyle(.white)
+                        .frame(width: 44, height: 44)
+                        .background(Circle().fill(Color.white.opacity(0.16)))
+                }
+            }
+            .padding(20)
+        }
+        .frame(height: 220)
+        .clipShape(RoundedRectangle(cornerRadius: 20))
+    }
+}
+```
+
+### Sleep Story List Row
+
+```swift
+struct SleepStoryRow: View {
+    let title: String
+    let narrator: String
+    let duration: String
+    let thumb: Image
+
+    var body: some View {
+        HStack(spacing: 14) {
+            thumb.resizable().aspectRatio(contentMode: .fill)
+                .frame(width: 56, height: 56)
+                .clipShape(RoundedRectangle(cornerRadius: 12))
+            VStack(alignment: .leading, spacing: 4) {
+                Text(title).font(.calmRowTitle).foregroundStyle(.white)
+                Text("Narrated by \(narrator) · \(duration)")
+                    .font(.calmSubtitle).foregroundStyle(Color.calmTextSecondary)
+            }
+            Spacer()
+            Image(systemName: "arrow.down.circle")
+                .font(.system(size: 22)).foregroundStyle(.white.opacity(0.8))
+        }
+        .padding(.horizontal, 20).frame(height: 76)
+        .contentShape(Rectangle())
+        .overlay(alignment: .bottom) {
+            Rectangle().fill(Color.calmGlassDivider).frame(height: 1)
+        }
+    }
+}
+```
+
+### Glass Card
+
+```swift
+struct CalmGlassCard<Content: View>: View {
+    @ViewBuilder var content: Content
+    var body: some View {
+        content
+            .padding(20)
+            .background(.ultraThinMaterial.opacity(0.6))
+            .background(Color.calmGlass)
+            .overlay(RoundedRectangle(cornerRadius: 20)
+                .strokeBorder(Color.calmGlassDivider, lineWidth: 1))
+            .clipShape(RoundedRectangle(cornerRadius: 20))
+    }
+}
+```
+
+## 4. Tab Bar
+
+Use `TabView` with a custom `UITabBarAppearance` matching the deep-navy glass base of the gradient. **Active tint is Calm Blue.**
+
+```swift
+struct RootTabView: View {
+    init() {
+        let a = UITabBarAppearance()
+        a.configureWithTransparentBackground()
+        a.backgroundEffect = UIBlurEffect(style: .systemMaterialDark)
+        a.backgroundColor = UIColor(Color.calmGradientBottom).withAlphaComponent(0.72)
+        UITabBar.appearance().standardAppearance = a
+        UITabBar.appearance().scrollEdgeAppearance = a
+    }
+    var body: some View {
+        TabView {
+            HomeView().tabItem { Label("Home", systemImage: "house.fill") }
+            SleepView().tabItem { Label("Sleep", systemImage: "moon.stars.fill") }
+            MeditateView().tabItem { Label("Meditate", systemImage: "figure.mind.and.body") }
+            MusicView().tabItem { Label("Music", systemImage: "music.note") }
+            MoreView().tabItem { Label("More", systemImage: "ellipsis") }
+        }
+        .tint(.calmBlue)
+    }
+}
+```
+
+## 5. Motion
+
+```swift
+// Breathe bubble: 4s ease-in → hold 7s → 8s ease-out, looping (see BreatheBubble.runCycle)
+
+// Card tap
+.buttonStyle(CalmPressableStyle(scale: 0.97))  // 250ms ease-out
+
+// Screen transitions — Calm fades, never hard-slides
+.transition(.opacity.animation(.easeInOut(duration: 0.55)))
+
+// Session timer ring — linear sweep over duration
+withAnimation(.linear(duration: sessionLength)) { progress = 1.0 }
+
+// Session complete
+.sensoryFeedback(.success, trigger: didComplete)  // soft sage check fades in over 600ms
+```
+
+Haptics via `.sensoryFeedback` (iOS 17+): `.impact(flexibility: .soft)` on play, `.success` on session complete, `.selection` on mood-chip pick. Keep haptics gentle and rare — Calm is serene.
+
+## 6. SF Symbols Used
+
+| Component | Symbol | Size |
+|-----------|--------|------|
+| Play | `play.fill` | 16-24pt |
+| Pause | `pause.fill` | 24pt |
+| Favorite | `heart` / `heart.fill` | 22pt |
+| Download | `arrow.down.circle` / `.fill` | 22pt |
+| Share | `square.and.arrow.up` | 22pt |
+| Background sound | `slider.horizontal.3` | 22pt |
+| Timer | `timer` | 22pt |
+| Search | `magnifyingglass` | 16pt |
+| Streak | `flame.fill` | 18pt |
+| Settings | `gearshape` | 22pt |
+| Home (tab) | `house.fill` | 24pt |
+| Sleep (tab) | `moon.stars.fill` | 24pt |
+| Meditate (tab) | `figure.mind.and.body` | 24pt |
+| Music (tab) | `music.note` | 24pt |
+| More (tab) | `ellipsis` | 24pt |
+
+## 7. Minimum iOS & Accessibility Notes
+
+- Minimum target: iOS 16 (`.sensoryFeedback` needs iOS 17; fall back to `UIImpactFeedbackGenerator`)
+- Dynamic Type: scale greetings, titles, body, narrator (both Lora and Inter); pin tab labels (11pt), duration meta (13pt), and cap the session timer at 56pt
+- VoiceOver: the breathe bubble is decorative/ambient — mark it `.accessibilityHidden(true)` and instead announce the phase ("Breathe in", "Hold", "Breathe out") via an `.accessibilityLabel` on a hidden live element; label the play pill "Play Daily Calm"
+- Reduce Motion: replace the breathe-bubble scale animation with a static circle plus a text-only phase cue; replace cross-dissolves with instant cuts
+- Reduce Transparency: when enabled, swap glass surfaces (`rgba(255,255,255,0.08)`) for solid `#13294B` so cards stay legible without blur
+- Contrast: `#B8C4D8` on the mid-gradient passes AA at 15pt+; validate the 13pt meta over the lighter top of the gradient and darken the scrim if needed
+- Dark-only: do not provide a light `ColorScheme`; lock the app to `.dark`

package/dist/data/designs/ios-calm.md

@@ -0,0 +1,356 @@
+# Design System Inspiration of Calm (iOS)
+
+## 1. Visual Theme & Atmosphere
+
+Calm's iOS app is a night sky you can fall asleep inside. The defining surface is a full-screen vertical gradient that runs from a deep twilight blue (`#2A6FD6`) at the top down to a near-black navy (`#0B1E3F`) at the bottom — the color of dusk just after the sun has gone. Over that gradient, almost everything is glass: cards are translucent white (`rgba(255,255,255,0.08)`) so the sky shows through them. The result is an interface that feels less like an app and more like a calm physical space — a planetarium, a lakeside at night — where nothing is sharp, nothing is loud, and the eye is never asked to work.
+
+The accent system is a single, quiet blue. Calm Blue (`#2A6FD6`) is the only saturated color, and it is used sparingly: the primary "Play"/"Start" pill, the active tab, the progress arc on the breathing exercise. Everything else is white at varying opacities — full white for headlines, ~72% white (`#B8C4D8`) for supporting copy. There are no reds, no greens, no semantic traffic lights in the main experience; even errors are stated softly. Photography does the emotional work: full-bleed nature imagery (forests, rain on glass, slow waves) sits behind the content, gently darkened so type stays readable.
+
+Typography is a deliberate pairing. Headlines are set in **Lora**, a contemporary serif with a literary, bedtime-story warmth — "Daily Calm", a sleep story title, the greeting "Good evening". Body and UI text are **Inter**, a clean humanist sans that disappears into the background. The contrast between the two is the brand's voice: the serif speaks (calm, human, narrative), the sans supports (functional, quiet). Sizes are generous and airy — a 30pt serif hero, 17pt body — with weights kept soft (400 / 600 / 700, never heavier). The single most expressive moment is the breathe bubble: a soft white circle that expands and contracts on a 4-7-8 cycle, the type around it fading "Breathe in… Hold… Breathe out…" in time.
+
+**Key Characteristics:**
+- Full-screen night-sky gradient (`#2A6FD6` → `#0B1E3F`) as the canvas — dusk, not pure black
+- Glass cards — translucent white (`rgba(255,255,255,0.08)`) so the sky shows through
+- Calm Blue (`#2A6FD6`) as the single accent — primary actions, active tab, progress arc
+- Full-bleed, gently-darkened nature photography behind content
+- Serif/sans pairing — **Lora** for headlines (bedtime-story warmth), **Inter** for body
+- The breathe bubble — a soft circle that scales on a 4-7-8 breathing loop (signature)
+- Daily Calm hero card — the day's featured meditation, large and photographic
+- Sleep Story list rows — narrator + duration, designed to be read in the dark
+- Bottom tabs (Home / Sleep / Meditate / Music / More) — soft, glass-backed
+- Motion is slow and continuous — nothing snaps; everything eases over 600ms+
+
+## 2. Color Palette & Roles
+
+### Primary
+- **Calm Blue** (`#2A6FD6`): The single accent — primary "Play"/"Start" pill, active tab icon/label, breathing progress arc, selected state.
+- **Calm Blue Pressed** (`#1F57AB`): Pressed/active state for the blue pill and controls.
+- **Calm Blue Soft** (`#4A85E0`): Lighter blue used for secondary highlights and the breathe-bubble glow.
+
+### Canvas (Night-Sky Gradient)
+- **Gradient Top** (`#2A6FD6`): The twilight-blue top of the full-screen background gradient.
+- **Gradient Mid** (`#1A4A8F`): The transitional mid-band of the gradient (~45% down).
+- **Gradient Bottom** (`#0B1E3F`): The deep near-black navy at the base — behind the tab bar.
+- **Scrim Navy** (`#091830`): Photo-darkening overlay applied beneath text on imagery.
+
+### Surfaces (Glass)
+- **Glass Surface** (`rgba(255,255,255,0.08)`): Standard card fill — translucent so the sky shows through.
+- **Glass Surface Raised** (`rgba(255,255,255,0.12)`): Higher-elevation cards, the Daily Calm hero, pressed list rows.
+- **Glass Divider** (`rgba(255,255,255,0.12)`): Hairline separators between list rows.
+- **Glass Hover** (`rgba(255,255,255,0.16)`): Pressed state on glass surfaces.
+
+### Text
+- **Text Primary** (`#FFFFFF`): Headlines, card titles, primary copy — pure white for maximum readability on the dark sky.
+- **Text Secondary** (`#B8C4D8`): Narrator names, durations, descriptions, supporting copy (~72% white, cool-toned).
+- **Text Tertiary** (`#8794A8`): Very low-emphasis metadata, disabled labels, timestamps.
+
+### Semantic (Used Sparingly)
+- **Progress Blue** (`#2A6FD6`): Session progress arc / scrubber fill (same as accent).
+- **Streak Gold** (`#F2C94C`): Streak flame and "X-day streak" emphasis — the only warm accent, rare.
+- **Gentle Error** (`#E08A8A`): Soft desaturated rose for the rare error message — never harsh red.
+- **Success Calm** (`#7FB8A0`): Soft sage for "Session complete" confirmation.
+
+### Light Mode
+Calm's iOS app is effectively dark-only — the night-sky gradient is intrinsic to the brand and the product is used primarily before sleep. There is no shipped light variant. (A daytime reference would invert to Canvas `#EAF1FB`, Text `#0B1E3F`, but it is not part of the product.)
+
+## 3. Typography Rules
+
+### Font Family
+- **Headline / Display**: `Lora` — a contemporary serif with literary, bedtime-story warmth
+- **Body / UI**: `Inter` — a clean humanist sans that recedes
+- **Fallback (serif)**: `Georgia, 'Times New Roman', serif`
+- **Fallback (sans)**: `-apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Segoe UI', Roboto, sans-serif`
+
+### Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|------|--------|-------------|----------------|-------|
+| Greeting Hero | Lora | 30pt | 600 | 1.25 | -0.2pt | "Good evening, Sam" on Home |
+| Screen Title | Lora | 26pt | 600 | 1.3 | -0.2pt | "Sleep", "Meditate" screen heads |
+| Daily Calm Title | Lora | 24pt | 600 | 1.3 | -0.1pt | The featured-session title on the hero card |
+| Card Title | Lora | 19pt | 600 | 1.35 | 0pt | Sleep-story / meditation card titles |
+| Section Header | Inter | 16pt | 700 | 1.3 | 0.2pt | "Sleep Stories", "Featured" labels |
+| List Row Title | Inter | 17pt | 600 | 1.35 | 0pt | Sleep-story row name |
+| Body | Inter | 17pt | 400 | 1.55 | 0pt | Descriptions, session intros |
+| Subtitle / Narrator | Inter | 15pt | 400 | 1.4 | 0pt | "Narrated by Tamara · 32 min" |
+| Button (Primary) | Inter | 17pt | 600 | 1.0 | 0.1pt | "Play", "Start session" pill text |
+| Meta / Duration | Inter | 13pt | 500 | 1.3 | 0.2pt | "10 min", "Day 214" |
+| Tab Label | Inter | 11pt | 600 | 1.0 | 0.2pt | Bottom tab bar labels |
+| Breathe Cue | Lora | 22pt | 400 | 1.2 | 0.5pt | "Breathe in" / "Hold" / "Breathe out" |
+| Timer (large) | Inter | 44pt | 300 | 1.0 | 0pt | The countdown during a session (light weight, airy) |
+| Label (UPPER) | Inter | 12pt | 700 | 1.2 | 1.0pt | "DAILY CALM", "NEW" tags |
+
+### Principles
+- **Serif speaks, sans supports**: Lora carries every emotional/narrative string (greetings, titles, breathe cues); Inter carries every functional one (buttons, meta, navigation). Never swap them.
+- **Generous leading**: Body runs at 1.55 — this is a calm reading surface, not a dense feed.
+- **Soft weights only**: Lora at 400/600, Inter at 400/500/600/700. The session timer uses Inter 300 (Light) deliberately — it should feel weightless.
+- **Whitespace is the typography**: large type, lots of air, short lines. Nothing is cramped.
+- **Color is structural**: text is white or cool-grey; Calm Blue is never used for body text emphasis (use the serif or weight instead).
+
+## 4. Component Stylings
+
+### Buttons
+
+**Primary Play / Start Pill**
+- Shape: Full pill, height 52pt
+- Background: `#2A6FD6`
+- Text: `#FFFFFF`, Inter 17pt weight 600, with a leading `play.fill` SF Symbol 16pt
+- Padding: 16pt vertical, 40pt horizontal
+- Pressed: background `#1F57AB`, scale 0.97, soft haptic
+- Used for: "Play", "Start session", "Begin", "Continue"
+
+**Glass Secondary Button**
+- Background: `rgba(255,255,255,0.12)`
+- Text: `#FFFFFF`, Inter 16pt weight 600
+- Border: 1pt `rgba(255,255,255,0.16)`
+- Padding: 14pt vertical, 28pt horizontal, corner radius 26pt (full pill)
+- Pressed: background `rgba(255,255,255,0.16)`
+- Used for: "Add to favorites", secondary CTAs on cards
+
+**Icon Actions (Favorite, Download, Share, Background-sound)**
+- Size: 22pt glyph, 44pt hit area
+- Default: `#FFFFFF` at 80% opacity
+- Active: `#2A6FD6` (favorite saved, downloaded)
+- Spacing: 28pt between icons in the player action row
+
+**Text Button ("See all", "Skip")**
+- Font: Inter 15pt weight 600
+- Color: `#B8C4D8`
+- No background, 44pt hit area
+
+### Cards & Containers
+
+**Daily Calm Hero Card** *(signature)*
+- Height: ~220pt, full content width
+- Background: full-bleed nature photograph, darkened with a `#091830` → transparent bottom-up gradient (so text is legible)
+- Overlay content (bottom-left): "DAILY CALM" label 12pt w700 letter-spaced `#FFFFFF`, then Lora 24pt w600 title, then Inter 15pt `#B8C4D8` subtitle "Today · 10 min"
+- Trailing: a 44pt circular glass play button (`rgba(255,255,255,0.16)`, `play.fill` 18pt white)
+- Corner radius: 20pt
+- Pressed: scale 0.98, subtle brightness lift on the photo
+
+**Sleep Story / Meditation Card (Shelf tile)**
+- Width: 160pt, photographic top (1:1 or 4:3), text below
+- Background: glass `rgba(255,255,255,0.08)` behind the text zone
+- Corner radius: 16pt on the image
+- Structure: image → Lora 19pt w600 title (2-line clamp) → Inter 13pt w500 `#B8C4D8` "32 min · Sleep"
+- Gap between tiles: 14pt
+- Tap: scale 0.97 with soft haptic
+
+**Sleep Story List Row**
+- Height: 76pt
+- Layout: 56pt rounded thumbnail (12pt radius) → stacked title/narrator → trailing duration + download glyph
+- Background: transparent over the gradient; pressed → `rgba(255,255,255,0.12)`
+- Title: Inter 17pt w600 white; Narrator: Inter 15pt w400 `#B8C4D8`
+- Divider: 1pt `rgba(255,255,255,0.12)` between rows
+
+**Glass Card (generic container)**
+- Background: `rgba(255,255,255,0.08)` with a 20pt backdrop blur (the sky blurs through it)
+- Border: 1pt `rgba(255,255,255,0.12)`
+- Corner radius: 20pt
+- Padding: 20pt
+
+### Navigation
+
+**Bottom Tab Bar**
+- Height: 56pt + safe area
+- Background: `rgba(11,30,63,0.72)` with `.regularMaterial` blur (the deep navy base of the gradient, glassed)
+- Tabs: Home, Sleep, Meditate, Music, More
+- Icon size: 24pt
+- Active color: `#2A6FD6` (icon + label both pick up Calm Blue)
+- Inactive: `#FFFFFF` at 60% opacity
+- Labels: Inter 11pt w600, always shown
+- Active icon: filled SF Symbol; inactive: outlined
+- A hairline `rgba(255,255,255,0.12)` top border
+
+**Top Bar**
+- Height: 44pt + safe area, transparent (the gradient runs behind it)
+- Left: profile avatar (30pt circular) or greeting
+- Right: streak flame (`#F2C94C`) with day count, then a settings glyph 22pt white
+- No solid background — it floats on the sky; content scrolls beneath
+
+**Player Screen (Full)**
+- Full-bleed scene photo or animated gradient, scrim-darkened
+- Centered: Lora 24pt w600 title, Inter 15pt narrator
+- Large circular scrubber arc (Calm Blue progress) around a central 64pt play/pause
+- Below: background-sound selector, timer, favorite — glass icon row
+- A soft "x min remaining" caption in Inter 13pt `#B8C4D8`
+
+### Input Fields
+
+**Search Field**
+- Background: `rgba(255,255,255,0.10)`
+- Height: 46pt, corner radius 23pt (full pill)
+- Leading `magnifyingglass` SF Symbol 16pt `#B8C4D8`
+- Placeholder: "Search meditations, sleep stories", 16pt `#8794A8`
+- Text: `#FFFFFF`
+- Focus: border `rgba(255,255,255,0.20)`, no color shift
+
+**Mood Check-in Chip**
+- Background: `rgba(255,255,255,0.10)` / `#2A6FD6` selected
+- Text: `#FFFFFF`
+- Padding: 12pt vertical, 20pt horizontal, corner radius 24pt
+- Examples: "Calm", "Anxious", "Tired", "Grateful"
+
+### Distinctive Components
+
+**Breathe Bubble** *(signature)*
+- A soft white circle, base diameter ~120pt, on the night-sky gradient with a subtle outer glow (`#4A85E0` blur)
+- Animation cycle (4-7-8 default): expand to ~220pt over **4s** (inhale), hold at full for **7s**, contract to 120pt over **8s** (exhale)
+- The Lora 22pt cue text crossfades in time: "Breathe in" → "Hold" → "Breathe out"
+- Concentric faint rings ripple outward on each inhale
+- Motion easing is `easeInOut`, continuous, never linear — it must feel like breath
+
+**Daily Calm Streak**
+- A `#F2C94C` flame glyph + "214-day streak" in Inter 13pt w500
+- On milestone, a gentle particle shimmer (no confetti — Calm stays serene)
+
+**Session Timer Ring**
+- Circular progress arc around the player play button
+- Track: `rgba(255,255,255,0.16)`, 3pt; Progress: `#2A6FD6`, 3pt, rounded cap
+- Sweeps clockwise over the session length; the center shows `pause.fill` 24pt white
+
+**Soundscape Mixer**
+- A glass sheet with horizontal sliders (rain, waves, fire, white noise)
+- Slider track `rgba(255,255,255,0.16)`, fill `#2A6FD6`, 22pt white thumb
+- Each row: icon + label (Inter 15pt) + slider
+
+## 5. Layout Principles
+
+### Spacing System
+- Base unit: 4pt
+- Scale: 4, 8, 12, 16, 20, 24, 28, 32, 40, 56
+- Standard horizontal margin: 20pt (more generous than typical — Calm breathes)
+- Section spacing: 32pt between shelves
+
+### Grid & Container
+- Single column, full device width with 20pt horizontal margins
+- Horizontal shelves: 14pt gaps, peek the next tile at the right edge
+- Daily Calm hero: full content width, the visual anchor at the top of Home
+- Player: fully centered, vertically balanced
+
+### Whitespace Philosophy
+- **Air is the brand**: large margins (20pt+), generous leading (1.55), 32pt section gaps. The interface should never feel busy — busyness is the opposite of calm.
+- **Photography breathes too**: hero imagery is given full width and never crowded by chrome.
+- **The player is a sanctuary**: it uses the whole screen for one scene and a few large controls.
+
+### Border Radius Scale
+- Soft (12pt): List-row thumbnails
+- Standard (16pt): Shelf tiles, glass buttons (when not full-pill)
+- Comfortable (20pt): Daily Calm hero, generic glass cards, sheets
+- Pill (26pt / full): Primary play pill, glass secondary buttons, search field, chips
+- Circle (50%): Play buttons, avatars, the breathe bubble, timer ring
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Sky (Level 0) | The gradient itself; no shadow | The full-screen background canvas |
+| Glass (Level 1) | `rgba(255,255,255,0.08)` + 20pt backdrop blur | Standard cards, list-row press states |
+| Glass Raised (Level 2) | `rgba(255,255,255,0.12)` + blur + `rgba(0,0,0,0.25) 0 8px 24px` | Daily Calm hero, featured cards |
+| Sheet (Level 3) | `rgba(11,30,63,0.94)` + blur + `rgba(0,0,0,0.4) 0 -16px 48px` | Soundscape mixer, settings sheets |
+| Tab Bar Material | `rgba(11,30,63,0.72)` + `.regularMaterial` | Floats above scrolling content |
+| Scrim | `#091830` → transparent gradient | Darkens photos beneath text |
+
+**Shadow Philosophy**: Calm avoids hard shadows almost entirely — depth comes from translucency and blur, not from cast shadows. The sky shows through every glass surface, which is what makes the app feel layered yet weightless. The only real shadows are soft, very diffuse (24-48pt blur, low opacity) under the raised hero card and sheets, just enough to lift them off the gradient. Photography uses a scrim gradient (not a shadow) to keep type readable.
+
+### Motion
+- **Breathe bubble**: scale 120 → 220pt over 4s ease-in (inhale), hold 7s, 220 → 120pt over 8s ease-out (exhale); continuous loop
+- **Card tap**: scale 0.97 → 1.0 over 250ms ease-out, soft haptic
+- **Play pill tap**: scale 0.97, background → `#1F57AB`, `.impactOccurred(.soft)`
+- **Screen transitions**: cross-dissolve 500-600ms (never a hard slide — Calm fades)
+- **Timer ring**: continuous clockwise sweep, linear over session length
+- **Photo parallax**: hero imagery shifts ~8pt on scroll for gentle depth
+- **Session complete**: soft sage check fades in over 600ms with a single gentle haptic
+- **Streak shimmer**: slow particle drift, ~2s, no sharp motion
+
+## 7. Do's and Don'ts
+
+### Do
+- Use the night-sky gradient (`#2A6FD6` → `#0B1E3F`) as the canvas — dusk, not pure black
+- Make cards glass — `rgba(255,255,255,0.08)` with backdrop blur so the sky shows through
+- Reserve Calm Blue (`#2A6FD6`) for primary actions, the active tab, and progress
+- Set headlines in Lora (serif) and body/UI in Inter (sans) — never swap the roles
+- Give the layout generous air — 20pt margins, 1.55 body leading, 32pt sections
+- Animate the breathe bubble on a true 4-7-8 ease-in-out cycle — it must feel like breath
+- Scrim-darken photography with a navy gradient so white type stays readable
+- Keep motion slow and continuous — 500ms+ cross-dissolves, nothing snaps
+- Use the soft session timer in Inter Light (300) — it should feel weightless
+
+### Don't
+- Don't use pure black `#000000` as the canvas — Calm is a twilight gradient, not a void
+- Don't add saturated accent colors beyond Calm Blue (gold streak is the only rare warm)
+- Don't set headlines in a sans — the Lora serif is the brand's voice
+- Don't use hard drop shadows — depth is translucency and blur, not cast shadow
+- Don't crowd the layout — busyness is the opposite of calm
+- Don't animate fast or bouncy — no spring overshoot; everything eases gently
+- Don't use harsh red for errors — use the soft desaturated rose, stated quietly
+- Don't put solid opaque cards on the gradient — the sky must show through the glass
+- Don't make the breathe bubble linear or mechanical — it has to breathe
+
+## 8. Responsive Behavior
+
+### Device Sizes
+| Device | Width | Key Changes |
+|--------|-------|-------------|
+| iPhone SE (3rd gen) | 375pt | 140pt shelf tiles; breathe bubble base 104pt |
+| iPhone 13/14/15 | 390pt | Standard 160pt tiles; breathe bubble base 120pt |
+| iPhone 15/16 Pro | 393pt | Dynamic Island clears the floating top bar |
+| iPhone 15/16 Pro Max | 430pt | 180pt tiles; breathe bubble base 136pt; hero 240pt tall |
+| iPad | 768pt+ | 3-column shelves; player centers with max 600pt content width |
+
+### Dynamic Type
+- Greetings, titles, body, narrator: full scale (Lora and Inter both)
+- Tab labels, duration meta: fixed (layout-sensitive at 11-13pt)
+- Session timer: scales modestly, capped at 56pt
+- Breathe cue: scales but the bubble geometry stays fixed
+
+### Orientation
+- Home / Sleep / Meditate / Music: **portrait-locked** (the gradient is vertical by intent)
+- Player: **portrait-locked** — the scene composition assumes vertical
+- iPad: **rotates** — landscape widens shelves; the player keeps a centered column
+
+### Touch Targets
+- Primary play pill: 52pt tall — generous
+- Card play buttons: 44pt circular
+- List rows: full 76pt height tappable
+- Tab icons: 24pt glyph, 44pt effective hit
+- Breathe bubble: not a button (it is ambient) — controls sit below it
+
+### Safe Area Handling
+- Top: floating bar respects the notch / Dynamic Island; gradient runs to the top edge
+- Bottom: tab bar floats above the home indicator; gradient runs to the bottom edge
+- Sides: 20pt content insets
+- Player: full-bleed scene ignores safe area for the background; controls inset
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Gradient top: `#2A6FD6`
+- Gradient mid: `#1A4A8F`
+- Gradient bottom: `#0B1E3F`
+- Glass surface: `rgba(255,255,255,0.08)`
+- Glass raised: `rgba(255,255,255,0.12)`
+- Divider: `rgba(255,255,255,0.12)`
+- Text primary: `#FFFFFF`
+- Text secondary: `#B8C4D8`
+- Calm Blue (accent): `#2A6FD6`
+- Calm Blue pressed: `#1F57AB`
+- Streak gold: `#F2C94C`
+
+### Example Component Prompts
+- "Create a SwiftUI Calm background: a full-screen vertical LinearGradient from #2A6FD6 (top) through #1A4A8F (45%) to #0B1E3F (bottom), ignoring safe area. All content sits on top of this."
+- "Build the Daily Calm hero card: ~220pt tall, full width, a full-bleed nature photo darkened by a #091830-to-transparent bottom-up gradient. Bottom-left overlay: 'DAILY CALM' in Inter 12pt weight 700 letter-spacing 1pt #FFFFFF, then a Lora 24pt weight 600 white title, then Inter 15pt #B8C4D8 'Today · 10 min'. Trailing a 44pt circular glass play button (rgba(255,255,255,0.16), play.fill 18pt white). 20pt corner radius; pressed scales 0.98."
+- "Design the breathe bubble: a soft white circle base diameter 120pt on the night-sky gradient with a #4A85E0 outer glow. Animate scale to 220pt over 4s ease-in (inhale), hold 7s, contract to 120pt over 8s ease-out (exhale), looping. A Lora 22pt cue ('Breathe in' / 'Hold' / 'Breathe out') crossfades in time. Concentric faint rings ripple outward on each inhale."
+- "Create a Sleep Story list row: 76pt tall, a 56pt rounded thumbnail (12pt radius) leading, stacked title in Inter 17pt weight 600 #FFFFFF and 'Narrated by Tamara · 32 min' in Inter 15pt weight 400 #B8C4D8, trailing a download glyph 22pt white at 80% opacity. Transparent over the gradient; pressed background rgba(255,255,255,0.12); 1pt rgba(255,255,255,0.12) divider below."
+- "Build the primary play pill: full pill 52pt tall, background #2A6FD6, leading play.fill SF Symbol 16pt, label in Inter 17pt weight 600 #FFFFFF, padding 16pt vertical / 40pt horizontal. Pressed: background #1F57AB, scale 0.97, soft haptic."
+
+### Iteration Guide
+1. Canvas is the night-sky gradient `#2A6FD6` → `#0B1E3F` — never pure black
+2. Cards are glass — `rgba(255,255,255,0.08)` + backdrop blur; the sky must show through
+3. Calm Blue `#2A6FD6` is the only accent — primary actions, active tab, progress
+4. Headlines are Lora (serif), body/UI is Inter (sans) — never swap the two roles
+5. Give everything air — 20pt margins, 1.55 body leading, 32pt section gaps
+6. The breathe bubble must breathe — a true 4-7-8 ease-in-out cycle, never linear
+7. Photography is scrim-darkened with navy, not shadowed — keep white type readable
+8. Motion is slow and continuous — 500ms+ cross-dissolves, no spring bounce
+9. Calm is dark-only — do not surface a daytime light theme