Avelia — UI/UX Design Specification

Date: 2026-03-18 Source: Functional mock (docs/avelia-mock/) Purpose: Definitive visual and interaction reference for native Flutter implementation

---

Table of Contents

1. Design Philosophy
2. Design System
3. Navigation Architecture
4. Onboarding Flow
5. Home Screen
6. Log Screen
7. Journal Screen
8. Guide Screen
9. Us (Partner) Screen
10. Settings / Account Screen
11. Hospital Bag Checklist
12. Context Switching
13. Stage-Adaptive Behavior
14. Privacy UI Patterns
15. Animations & Transitions
16. Accessibility
17. Platform Considerations
18. Solo Mode Behavior
19. Edge Cases & Empty States
20. Unspecified Flows (Design Required)

---

1. Design Philosophy

Aesthetic direction: "Botanical Journal" — warm, organic, intimate. The app should feel like a beautiful keepsake journal, not a clinical health tracker.

Guiding Principles

• Warm over cold — cream backgrounds, rose accents, warm shadows. Never cold grays or stark whites.
• Editorial typography — serif display font for headings creates an intimate, magazine-like quality. Sans-serif body text for readability.
• Generous space — content breathes. Cards have comfortable padding. Sections have clear visual separation.
• Understated motion — gentle fade-ins, subtle hover lifts. Never flashy or distracting.
• Stage-aware, not stage-gated — the UI adapts to surface relevant content, but nothing is hidden or locked.
• Privacy is visible — the shared/private toggle is always present and obvious. The user always knows who can see what.

---

2. Design System

2.1 Color Palette

Primary Colors

Token	Value	Usage
primary	#e6194c	Primary actions, active states, brand accent, logo
primary-light	#FDEAEF	Selected card backgrounds, icon containers, hover states
primary-dark	#C0153F	Button gradient end, pressed states
primary-glow	rgba(230, 25, 76, 0.15)	Focus rings, card selection glow, button shadows

Neutral Colors

Token	Value	Usage
secondary	#2A2438	Primary text, headings, dark UI elements
bg	#F7F3EE	Page/screen background
surface	#FFFCF8	Card backgrounds, input backgrounds, overlays
muted	#6B6678	Secondary text, labels, placeholders
border	#E8E2DC	Card borders, dividers, input borders
border-light	#F0EBE5	Subtle dividers, section separators

Accent Colors

Token	Value	Usage
success	#5A8F62	Toggle ON state, positive indicators
accent	#B8864F	Warm gold for highlights, decorative elements
accent-light	#F5EDE3	Warm gold backgrounds

Semantic Colors (Quick Log Icons)

These are per-category colors used on Quick Log icon items. They are intentionally varied to create visual distinction between log types:

Category	Color	Used in stages
Temperature/BBT	#ef4444	Trying
Fertility/Test	#ec4899	Trying
Cycle/Calendar	#8b5cf6	Trying, Pregnant
Mood	#eab308	Considering, IVF
Medication	#e6194c (primary)	IVF
Clinic/Event	#3b82f6	IVF, Pregnant
Feed	#3b82f6	Birth, First Year
Sleep	#8b5cf6	Birth, First Year
Diaper	#f59e0b	Birth, First Year
Milestone	#eab308	Growing Up
Activity	#10b981	Growing Up
Memory	#8b5cf6	Growing Up
More/Generic	#6b7280	All stages

2.2 Typography

Font Families

Role	Family	Fallback	Weight Range
Display	Fraunces (variable, optical size)	Georgia, serif	300–900
Body	Outfit (geometric humanist)	-apple-system, sans-serif	300–900

Type Scale

Element	Font	Size	Weight	Letter-spacing	Line-height
Screen title (H1)	Fraunces	1.5rem (24px)	700	-0.01em	1.2
Section heading (H2)	Fraunces	1.1rem (17.6px)	600	normal	1.3
Greeting text	Fraunces	1.8rem (28.8px)	700	-0.02em	1.15
Onboarding title	Fraunces	2rem (32px)	800	-0.02em	1.1
Body text (.p)	Outfit	0.9rem (14.4px)	400	normal	1.5
Small label	Outfit	0.75rem (12px)	600	normal	1.4
Tiny label (caps)	Outfit	0.65rem (10.4px)	800	0.1em	1.2
Button text	Outfit	0.9rem (14.4px)	700	0.05em	1.0
Nav label	Outfit	0.65rem (10.4px)	600	normal	1.0
Stage badge	Outfit	0.7rem (11.2px)	700	0.05em	1.0

Usage Notes

• All headings (screen titles, card titles, greeting, onboarding) use Fraunces
• Everything else (body, labels, buttons, inputs, nav) uses Outfit
• The Fraunces font has an optical size axis — at large sizes (headings), it renders with more contrast and character. At small sizes, it becomes more readable. Use font-variation-settings or the opsz axis when available in Flutter.

2.3 Spacing

The app uses an 8px base grid:

Token	Value	Usage
xs	4px	Tight gaps (step dots, icon-label gaps)
sm	8px	Compact spacing (between stage cards, inline gaps)
md	12px	Card internal gaps, list item spacing
base	16px	Card padding, standard content margins
lg	20px	Content area horizontal padding
xl	24px	Section spacing, content area top/bottom padding
2xl	32px	Onboarding section spacing
3xl	40px	Onboarding subtitle-to-content gap

Screen-level padding

• Content area: 20px horizontal, 24px top, 100px bottom (clears nav bar)
• Onboarding screens: 24px horizontal, 60px top, 40px bottom

2.4 Elevation & Shadows

All shadows use the warm charcoal base rgba(42, 36, 56, x) — never cold black.

Token	Value	Usage
shadow-sm	0 1px 3px rgba(42,36,56,0.04), 0 1px 2px rgba(42,36,56,0.03)	Cards, input fields
shadow-md	0 4px 12px rgba(42,36,56,0.06), 0 2px 4px rgba(42,36,56,0.04)	Elevated cards, profile images
shadow-lg	0 12px 32px rgba(42,36,56,0.08), 0 4px 8px rgba(42,36,56,0.04)	Context menus, popups
shadow-xl	0 20px 50px rgba(42,36,56,0.12)	Phone frame (mock only)

2.5 Border Radii

Token	Value	Usage
radius-sm	12px	Input fields, small cards, icon containers, checkboxes
radius-md	16px	Standard cards, settings items
radius-lg	24px	Large cards, setup option cards, popups, profile images
radius-pill	100px	Buttons, stage badges, toggle switches

2.6 Icons

• Icon system: Material Symbols Outlined (variable weight, no fill)
• Default settings: FILL: 0, wght: 400, GRAD: 0, opsz: 24
• Icon sizes: 20px (small/nav), 24px (standard), 32px (profile), 40px (large profile), 48px (onboarding photo placeholder)

Key icons by function

Function	Icon name	Context
Home tab	home	Navigation
Journal tab	book	Navigation
Guide tab	info	Navigation
Family context	groups	Navigation
Settings / Profile	person	Header, settings
Back	arrow_back_ios	Overlay/screen navigation
Close	close	Full-screen overlays
Share	share	Invite code
Child	child_care	Context menu, child cards
Partner/Heart	favorite	Context menu, partner mode
Edit	edit	Profile photo, child edit
Add photo	add_a_photo	Child photo placeholder
Add	add	Quick log "More" button
Check	check_circle	Stage selection confirmed
Chevron	chevron_right	List item disclosure

---

3. Navigation Architecture

3.1 Tab Bar

Fixed at the bottom of the screen. Always visible on dashboard screens. Hidden during overlays (Log, Settings, Hospital Bag, Onboarding).

Structure: 4 tabs, equally spaced

Position	Label	Icon	Behavior
1	Home	home	Shows Home screen
2	Journal	book	Shows Journal screen
3	Guide	info	Shows Guide screen
4	(Dynamic)	groups	Toggles context switcher popup. Label shows active profile name

Visual states:

• Inactive: muted color (#6B6678)
• Active: primary color (#e6194c) with a 4px dot indicator below the icon

Tab 4 special behavior:

• Label is always primary color and weight: 800
• Label text changes dynamically: "Us" when parent context active, child name ("Leo", "Mia") when child context active
• Tapping toggles the context switcher popup (see section 12)
• When no children exist, the popup still appears but shows only the "Us (Partner)" option. The native app may choose to navigate directly to the Us screen instead when there is only one context available.

3.2 Screen Layers

The app uses a layered screen model (not route-based navigation for overlays):

Layer 0: Dashboard (Home / Journal / Guide / Us) — tab bar visible
Layer 1: Full-screen overlays (Settings, Log, Hospital Bag) — tab bar hidden
Layer 2: Sub-pages (Profile Edit, Sharing Settings, Device Management, etc.)

Transition pattern: Overlays slide in from bottom or right. Sub-pages push from right (standard iOS/Android pattern).

3.3 Header

Present on all dashboard screens. Hidden during onboarding and full-screen overlays (which have their own overlay header).

Layout: Row, space-between

• Left: Logo SVG (32x32) + "AVELIA" text (Outfit, 1.2rem, weight 900, letter-spacing 1px, secondary color)
• Right: Profile photo trigger (36x36 rounded square, primary-light background, person icon in primary color)

Styling: Background: surface (#FFFCF8), bottom border: 1px solid border-light (#F0EBE5).

Profile photo trigger: Tapping opens the Settings/Account screen as a full-screen overlay.

3.4 Overlay Header

Used by Log, Hospital Bag, and sub-page screens.

Layout: Row, space-between, vertically centered

• Left: Close button (close icon) or Back button (arrow_back icon), 40x40 touch target
• Center: Screen title (H1, Fraunces)
• Right: 40px spacer (maintains centering)

---

4. Onboarding Flow

4.1 Overview

A multi-step guided setup that runs before the user enters the main app. Total steps depend on partner mode:

• Together path: Welcome → Partner Mode → Stage → Invite Partner → Children = 5 steps
• Solo path: Welcome → Partner Mode → Stage → Children = 4 steps

4.2 Shared Layout

All onboarding steps share:

• Background: Warm cream (bg) with subtle radial gradients for depth:
  • Top-right: warm gold glow at 4% opacity
  • Bottom-left: primary rose glow at 4% opacity
• Padding: 60px top, 24px horizontal, 40px bottom
• No header or tab bar — clean, focused experience
• Back button: Present on steps 2–6. arrow_back_ios icon, positioned absolutely at top: 44px, left: 12px, 40x40 touch target. Returns to the previous step.
• Footer area: Sticks to bottom via flex margin-top: auto

4.3 Step Indicator

Appears on steps 2–5 (not on Welcome or Child Details sub-screen).

Visual: A row of dots, 6px gap between

• Inactive dot: 8px wide, 8px tall, border color (#E8E2DC)
• Active dot: 28px wide, 8px tall, gradient from primary to primary-dark, with a subtle glow shadow

Current mock behavior: Always renders 3 dots. All reached steps use the active style (no visual distinction between current and completed steps). The native app should implement a proper indicator:

• Solo path: 3 dots (Partner Mode → Stage → Children)
• Together path: 4 dots (Partner Mode → Stage → Invite → Children)
• Previous steps should use a completed style: 8px wide, primary at 40% opacity

4.4 Step 1: Welcome

Content (top to bottom):

1. Logo: Avelia SVG logo, centered, scaled to 1.5x (48px rendered), with a primary-glow drop shadow
2. Spacing: 48px below logo
3. Title: "Your journey to family, together." — Fraunces 2rem/800, secondary color
4. Subtitle: "A zero-knowledge sanctuary for tracking, journaling, and curated guidance." — Outfit 1rem/400, muted color
5. Spacing: flex grows to push footer down
6. Footer:
   • Primary button: "GET STARTED"
   • Below button: "I HAVE AN ACCOUNT" text link (Outfit, 0.75rem, 800 weight, centered, cursor pointer)

Behavior: GET STARTED advances to step 2. "I HAVE AN ACCOUNT" would navigate to login (not implemented in mock).

4.5 Step 2: Partner Mode

Content:

1. Step indicator (dot 1 active)
2. Title: "How are you starting?"
3. Subtitle: "You can link a partner now or at any time in the settings."
4. Option card: Together (pre-selected by default)
   • Icon: favorite in primary color on primary-light background (48x48, radius 14px)
   • Title: "Together" — Fraunces 1.1rem/600
   • Description: "Link with a partner to share logs, milestones, and your journey feed."
5. Option card: Solo
   • Icon: person in muted color on #f3f4f6 background
   • Title: "Solo"
   • Description: "Focus on your personal tracking. All features are fully available to you."
6. Footer: "CONTINUE" button

Card states:

• Default: surface background, 2px transparent border (becomes border-light on hover), 24px radius (radius-lg)
• Hover: border color changes to border, subtle shadow appears
• Active/Selected: primary border, primary-light background, 3px primary-glow ring

Behavior: Tapping a card selects it (deselects the other). CONTINUE advances to step 3.

4.6 Step 3: Stage Selection

Content:

1. Step indicator (dot 2 active)
2. Title: "Where are you on the journey?"
3. Subtitle: "The app adapts its fields and content to your current stage."
4. Scrollable stage list (7 items):

Stage	Icon	Label	Subtitle
Considering	💭	Considering	Values, readiness, check-ins
Trying naturally	✨	Trying naturally	Cycle tracking, fertile window
IVF / Assisted	🔬	IVF / Assisted	Meds, retrieval, clinics
Pregnant	🤰	Pregnant	Development, symptoms, plans
Birth & Beyond	👶	Birth & Beyond	Story, timer, hospital bag
First Year	🍼	First Year	Feeding, sleep, growth
Growing Up	🏠	Growing Up	Milestones, activities

5. Footer: "CONTINUE" button (with gradient fade overlay above it to indicate scrollable content)

Stage card layout: Row — emoji (22px) + column (label bold 0.9rem + subtitle 10px 60% opacity) + check icon (only on selected)

Card states: Same as option cards (default/hover/active with glow ring).

Default selection: "Considering" (first item).

4.7 Step 4: Invite Partner (Together path only)

Content:

1. Step indicator (dot 3 active)
2. Title: "Invite your partner"
3. Subtitle: "Parenting is a team sport. Send this code to your partner to link your accounts."
4. Invite code card: Centered card with:
   • Code display: AV-284-910 in monospace (Courier, 1.8rem, weight 900, 4px letter-spacing)
   • Background: gradient from primary-light to accent-light, dashed 2px border border, 16px radius
5. Share button: Secondary button with share icon, "SHARE INVITE CODE"
6. Info callout card: Blue-tinted card with info icon
   • Message: "Your partner will be able to see logs and milestones that you explicitly mark as 'Shared'. Everything else stays private."
7. Footer:
   • "CONTINUE" button
   • "I'LL DO THIS LATER" text link below (50% opacity)

4.8 Step 5: Children

Content:

1. Step indicator (final dot active)
2. Title: "Your children"
3. Subtitle: "Add your children to track their individual milestones and growth."
4. Children list (if any added): Each child shown as a card with:
   • Left: 4px primary left border accent
   • Avatar placeholder (32x32 circle, child_care icon)
   • Name (bold, secondary) + metadata (gender + DOB, tiny text)
   • Right: edit icon in muted
   • Tapping opens child edit form
5. Add child button: Full-width, 2px dashed border border, transparent background, add icon + "ADD A CHILD"
6. Footer: Button label is "FINISH SETUP" if kids exist, "SKIP FOR NOW" if none

Behavior: ADD A CHILD opens the child details form (step 6). SKIP/FINISH completes onboarding and enters the main app.

4.9 Step 6: Child Details Form

Reached from: ADD A CHILD or tapping an existing child card on step 5.

Layout (distinct from other steps):

• Back button: Top-left, absolute positioned. arrow_back_ios icon.
• Extra top padding: 20px added to prevent back button / title overlap
• Title: "Child Details"
• Subtitle: "Tell us more about your little one."

Form elements:

1. Photo placeholder: Centered, 100x100, primary-light background, rounded 50%, add_a_photo icon. Small primary edit badge (32x32 circle) at bottom-right.
2. Form card: Contains all fields in a column with 16px gaps: Each field has an uppercase label above it: 10px, extra-bold (800), muted color, wide letter-spacing (0.1em), 1px horizontal padding.
   • Name: Text input, placeholder "Name"
   • Birth Date: Date picker input
   • Gender: Row of 3 toggle buttons ("Girl", "Boy", "Other"). No default selection — user must explicitly choose.

Gender button states:

• Default: btn-secondary style (outline)
• Selected: primary background, white text

3. Footer:
   • "SAVE CHILD" primary button
   • "REMOVE" danger button — only visible when editing an existing child, hidden when creating a new one

Behavior: SAVE validates that name is non-empty (no visual error shown in mock — implement inline validation in native). Returns to step 5 with child added/updated.

---

5. Home Screen

5.1 Layout Structure

[Header]
[Content Area — scrollable]
  [Greeting Container]
  [Quick Log Section]
  [Stage-Specific Cards]
  [Kid Profile Section — child context only]
  [Partner's Shared Log]
  [Quick Log Button]
[Nav Bar]

5.2 Greeting Container

Parent context (activeProfile = "parent"):

• Line 1: "Good morning," — Fraunces 1.8rem/700, secondary
• Line 2: "Sarah & Mark" — Fraunces 1.8rem/700, primary color
• Below: Stage badge

Child context (activeProfile = child):

• Line 1: "Sarah & Mark," — Fraunces 1.1rem/600, 70% opacity
• Line 2: "How is Leo today?" — Fraunces 1.8rem/700, child name in primary
• Below: Stage badge showing child's age (e.g., "STAGE: 6 Months")

5.3 Stage Badge

A pill-shaped label showing the current stage context.

• Background: Linear gradient 135deg from primary to primary-dark
• Text: White, Outfit 0.7rem, weight 700, letter-spacing 0.05em
• Padding: 5px vertical, 14px horizontal
• Radius: pill (100px)
• Shadow: 0 2px 8px primary-glow
• Margin: 12px above, 8px below

Content by stage:

• Considering: "STAGE: Considering"
• Trying: "STAGE: Trying"
• IVF: "STAGE: IVF - Day 14"
• Pregnant: "STAGE: Pregnant - Week 12"
• Birth: "STAGE: Postpartum - Day 3"
• First Year: "STAGE: 6 Months"
• Growing Up: "STAGE: Toddler"

5.4 Quick Log Section

Title: "Quick Log" — Outfit 1.125rem (text-lg), bold, secondary color. Note: this heading does not use the .h2 class — it uses inline Tailwind classes directly.

Grid: 4 columns, 8px gap. Each item is a QuickLogItem:

QuickLogItem anatomy:

• Icon container: 56x56, centered, rounded-xl (12px), white background, 1px border-light border, subtle shadow
• Icon: Material Symbol, 24px, colored per semantic category
• Label: Below icon, 10px, semibold, #6b7280 (Tailwind gray-500 — slightly different from the muted token)

The items shown depend on the active stage (see section 13). The 4th item is always "+ More" in muted gray.

Tap behavior: Opens the Log screen (full-screen overlay).

5.5 Stage-Specific Cards

Cards that appear between Quick Log and Partner's Shared Log. Content varies by stage:

Considering

• Readiness Check-in card: Title "Readiness Check-in", prompt question, "Open Conversation Guide" secondary button

Trying Naturally

• Fertile Window card: Title "Fertile Window" in #ec4899 (pink), status message

IVF / Assisted

• Today's Medication card: Title "Today's Medication", checklist of medications with:
  • Each item: Row — medication name (bold) + time (small) | checkbox
  • Checkbox: 24x24, 2px primary border, 8px radius. Checked: filled primary, white checkmark

Pregnant

• Hospital Bag card (tappable): Row — title "Hospital Bag" + "65% READY" label. Progress bar below (primary fill on gray-100 track). Hint text: "Next: Pack baby's first outfit". Tapping opens Hospital Bag overlay.
• Baby Size card: Title "Baby is the size of a...", row with fruit emoji (lime-100 circle background) + name + development note

Birth & Beyond / First Year

• Last Feeding card: Title "Last Feeding", relative time + details

Growing Up

• Recent Milestone card: Title "Recent Milestone", milestone description + relative time

5.6 Kid Profile Section (child context only)

Shown when the active context is a child (not "parent"). Two cards:

1. Child info card: Row — avatar placeholder (60x60 circle, child_care icon) + name (H2) + age/DOB
2. Appointments card: event icon in primary + "Appointments" title + appointment item (name, date/time, doctor)

5.7 Partner's Shared Log Card

Always present on Home (in both parent and child context).

Title: "Partner's Shared Log" — Fraunces H2 Content: Styled quote with primary left border (3px), italic text, attribution line (name + relative time)

5.8 Quick Log Button

Full-width primary button at the bottom of the scrollable area: "+ QUICK LOG"

---

6. Log Screen

6.1 Structure

Full-screen overlay with overlay header.

Header: Close button (X) | "Log for {profileName}" | spacer

profileName is the literal string "Us" when in parent context, or the child's name when in child context.

6.2 Content Sections

Current Mood

• Title: "Current Mood" — H2
• Card: Row of 5 mood face icons (Material Symbols), evenly spaced:
  1. sentiment_very_dissatisfied
  2. sentiment_dissatisfied
  3. sentiment_neutral
  4. sentiment_satisfied
  5. sentiment_very_satisfied
• Default state: All icons in gray-200 color
• Selected state: Icon changes to primary color
• Hover state: Icon changes to primary color

Details

• Title: "Details" — H2
• Card: Contains stage-specific input fields (see section 13.2)
• All inputs use the .log-input style:
  • 12px 16px padding
  • 1px border border
  • 12px radius
  • surface background
  • secondary text color
  • On focus: primary border + 3px primary-glow ring
  • Placeholder: #B0AAB8

Sharing Toggle

• Card: Row — label column + toggle switch
  • Label: "Shared with Partner" (bold) + "Visible to {partnerName}" (small, muted)
  • Toggle: 44x24, border when off, success (#5A8F62) when on
  • Toggle knob: 20x20 white circle with shadow, slides with spring animation

Save Button

• Full-width primary button: "SAVE ENTRY"
• 20px top margin

6.3 Stage-Specific Fields

See section 13.2 for the complete field mapping per stage.

---

7. Journal Screen

7.1 Layout

Standard dashboard screen with header and tab bar.

Title: "Journal: {contextName}" — where contextName is "Us" (parent) or child name

7.2 Entry Cards

Each journal entry is a card with:

• Top row: Entry type badge (left) + timestamp (right)
  • Badge: Uppercase, 0.7rem, bold. Color varies by type (fertility = primary, feeding = #3b82f6)
  • Timestamp: 0.7rem, muted color, format "Today, 08:30 AM"
• Body: Entry text, secondary color

7.3 Context Awareness

The journal content adapts to the active profile:

• Parent context: Shows fertility/pregnancy logs. Badge: "FERTILITY LOG"
• Child context: Shows child-specific logs. Badge: "FEEDING LOG"

7.4 Implementation Notes

The mock shows only one entry per context. In the native app, this should be a vertically scrollable list of all entries, with:

• Date section headers (grouped by day)
• Visual distinction between own entries and partner's shared entries (partner entries use the italic left-border style from Partner's Shared Log)
• Filter chips at top: All / Shared / Private
• Empty state: Illustration + "No entries yet" + prompt to create first entry

---

8. Guide Screen

8.1 Layout

Standard dashboard screen with header and tab bar.

Title: "Guide" — H1 Subtitle: "Library ({stageName})" — H2, stage name in parentheses

8.2 Article List

Each article is a card with:

• Row layout: Article title (left, bold secondary) + chevron › (right, #ccc)
• Full-width tappable area

8.3 Implementation Notes

The mock shows 2 static articles. In the native app, this should include:

• A featured/hero article card at the top (larger, possibly with illustration)
• Topic filter chips (Development, Wellness, Partners, Nutrition)
• Stage-specific article content that actually changes per stage
• Article detail view when tapped

---

9. Us (Partner) Screen

9.1 Layout

Standard dashboard screen, accessed by selecting "Us (Partner)" from context menu or tapping the family tab when in parent context.

9.2 Content

1. Title: "Us (Partner View)" — H1
2. Stats card (centered text):
   • "You've been using Avelia for" — body text
   • "42 Days" — Fraunces 2.5rem, primary color
   • "Partner: Sarah & Mark" — body text
3. Partner Account card (tappable):
   • Title: "Partner Account" — H2
   • Subtitle: "Manage linking, invites, and sharing."
   • Right: chevron_right icon
   • Tapping navigates to partner management sub-page (with add-partner flow)
4. Shared Moments card:
   • Title: "Shared Moments" — H2
   • Partner quote with left-border styling (same as Partner's Shared Log on Home)

---

10. Settings / Account Screen

10.1 Structure

Full-screen overlay with overlay header.

Header: Back button (‹) | "Account" | spacer

10.2 Content

1. User summary card (centered):

   • Profile image placeholder: 80x80, primary-light background, 28px radius, person icon in primary, 4px white border, medium shadow
   • Name: "Sarah Miller" — body bold
   • Email: "sarah.miller@example.com" — body muted
   • Card: surface background, 24px radius, 28px padding, subtle border

2. Settings menu list: Vertical stack, 12px gap between items

Icon	Label	Subtitle	Navigates to
person	My Profile	Edit name, email, and avatar	Profile edit sub-page
share	Sharing & Privacy	Manage access for partners & doctors	Sharing settings
devices	Device Management	2 devices connected	Device list
settings	Settings	Notifications, units, and appearance	App settings
info	Imprint	Legal information	Legal page
policy	Privacy Policy	How we protect your data	Privacy page

Settings item card anatomy:

• Row: Icon container (40x40, primary-light bg, primary icon, 12px radius) + column (label bold + subtitle small muted) + chevron_right
• Card: surface background, 16px radius, 16px padding, 1px border-light border
• Hover: border darkens to border, subtle shadow appears

3. Logout button:
   • Full width, 16px padding, 16px radius
   • Background: #fce4e4, text: #c53030, weight 700
   • Icon: logout (from Material Symbols)

---

11. Hospital Bag Checklist

11.1 Access

Only available during the Pregnant stage. Accessed by tapping the Hospital Bag card on the Home screen.

11.2 Structure

Full-screen overlay with overlay header.

Header: Close button (X) | "Hospital Bag" | spacer

11.3 Content

1. Progress card:

   • Row: "Completion" label + percentage
   • Progress bar: 12px height (h-3), gray-100 track, primary fill, full radius, animated width transition (500ms)

2. Category sections (3 categories: "For Mum", "For Baby", "Essentials"):

   • Category header: Uppercase tiny label (10px, extra-bold, muted, wide letter-spacing)
   • Items within each category, 8px gap

3. Checklist item card:

   • Row: Checkbox + label + info button
   • Checkbox (20x20): primary border, 8px radius. Checked: filled primary + white ✓
   • Label: Body text. When checked: line-through + 50% opacity
   • Info button: info icon in gray-300, hover changes to primary. Tapping opens item detail.
   • Tapping the checkbox area toggles checked state
   • Tapping the info icon opens the item detail view

11.4 Item Detail View

A sub-overlay (z-index 400) with:

• Header: Back arrow + "Item Details"
• Content: Icon card (centered, primary bg icon) + item name (H2) + description text + "Avelia Tip" card
• Action button: "MARK AS PACKED" or "MARK AS UNPACKED" (toggles)

---

12. Context Switching

12.1 Concept

The app supports multiple "contexts" — one parent context (the couple) and one per child. The context determines:

• Which stage badge and greeting to show
• Which quick log items to display
• What journal entries to filter
• What stage-specific content to render

12.2 Context Switcher Popup

Triggered by: Tapping the 4th tab (family icon) in the nav bar.

Visual: Floating card, 190px wide, anchored to bottom-right of screen (15px from right, 85px from bottom — above nav bar).

Animation: Slides up with spring animation (0.25s, cubic-bezier(0.34, 1.56, 0.64, 1)) from 8px below with 5% scale-down.

Content:

• Header: "SELECT CONTEXT" — uppercase tiny label
• Menu items (one per context):
  • "Us (Partner)" — favorite icon + label
  • One entry per child — child_care icon + child name
• Active item: primary-light background, primary color, bold text
• Hover: primary-light background

Behavior:

• Tapping "Us (Partner)": Sets activeProfile to "parent", switches to Us tab, closes popup
• Tapping a child: Sets activeProfile to child ID, switches to Home tab, closes popup
• Tapping the tab again: Closes the popup

12.3 Tab Label Update

When context changes, the 4th tab label updates:

• Parent context: "Us"
• Child context: Child's name (e.g., "Leo")

The label is always rendered in primary color with 800 weight.

---

13. Stage-Adaptive Behavior

13.1 Quick Log Items by Stage

Stage	Item 1	Item 2	Item 3	Item 4
Considering	Mood (mood, yellow)	Talk (chat_bubble, blue)	Decision (check_circle, green)	More
Trying	BBT (thermostat, red)	Test (bloodtype, pink)	Cycle (calendar_today, purple)	More
IVF	Med (medication, primary)	Clinic (event, blue)	Mood (psychology, yellow)	More
Pregnant	Symptom (sick, purple)	Kicks (child_care, pink)	Weight (monitor_weight, blue)	More
Birth / First Year	Feed (water_bottle, blue)	Sleep (bedtime, purple)	Diaper (baby_changing_station, amber)	More
Growing Up	Milestone (star, yellow)	Activity (sports_soccer, green)	Memory (auto_stories, purple)	More

13.2 Log Screen Fields by Stage

Considering

• text: "Conversation Topics (e.g. Finances)"
• text: "Decisions Reached"

Trying Naturally

• Row: text "BBT (°C)" + text "Cycle Day"
• select: Cervical Mucus Type (Dry / Sticky / Creamy / Egg White)
• text: "Ovulation Test Result"

IVF / Assisted

• text: "Medication & Dose"
• time: Time input
• text: "Clinic Visit Notes"

Pregnant

• Row: text "Kicks (last 1hr)" + text "Weight (kg)"
• text: "Blood Pressure (e.g. 120/80)"
• text: "Physical Symptoms"

Birth & Beyond / First Year

• Row: select Feeding Type (Breast Left/Right, Bottle Milk/Formula) + text "Volume (ml)"
• Row: text "Sleep Duration (min)" + select Diaper Status (Wet/Dirty/Both/Dry)

Growing Up

• text: "Milestone Achieved"
• text: "Activity (e.g. Playground)"
• textarea: "Special memory or note..." (80px height)

13.3 Home Screen Cards by Stage

See section 5.5 for the complete breakdown.

---

14. Privacy UI Patterns

14.1 Core Rule

Every log entry has a private/shared toggle. The toggle is:

• Always visible on the Log screen
• Positioned after the form fields, before the Save button
• Default state: private (toggle OFF)

The private default is a core product principle — nothing crosses the privacy boundary without explicit intent.

14.2 Toggle Visual

• Card container: Full width, surface background
• Left column: "Shared with Partner" (bold) + "Visible to {partnerName}" (small muted)
• Right: Toggle switch
  • OFF: border track color (#E8E2DC), knob on left
  • ON: success track color (#5A8F62), knob slides right with spring easing
  • Knob: 20x20 white circle with shadow-sm

14.3 Journal Privacy Indicators

In the native Journal implementation:

• Own private entries: Standard card style
• Own shared entries: Add a small share icon or "Shared" label
• Partner's shared entries: Italic text with primary left border (3px), partner attribution line

14.4 Info Callout (Onboarding)

On the Invite Partner screen, a blue-tinted card communicates the privacy model:

• info icon in blue
• Message explaining that only explicitly shared content is visible to the partner

---

15. Animations & Transitions

15.1 Page-Level Animations

Staggered Card Reveal

When the Home screen content loads, cards animate in sequence:

• Animation: fadeInUp — opacity 0→1, translateY 16px→0
• Duration: 500ms, ease timing
• Stagger: 50ms per item (1st at 50ms, 2nd at 100ms, 3rd at 150ms, etc.)

Onboarding Step Transitions

Each step's content animates in with the same staggered fadeInUp:

• Duration: 400ms, ease timing
• Stagger: 50ms per element

15.2 Micro-Interactions

Button Hover/Press

• Hover: translateY(-1px), shadow intensifies
• Active/Press: translateY(0), scale 0.98

Quick Log Item Tap

• Hover: translateY(-3px), spring easing (cubic-bezier(0.34, 1.56, 0.64, 1))
• Active: translateY(0), scale(0.92), 80% opacity

Toggle Switch

• Track color transition: 300ms ease
• Knob translation: 300ms spring (cubic-bezier(0.34, 1.56, 0.64, 1))

Context Switcher Popup

• Enter: menuSlideUp — opacity 0→1, translateY 8px→0, scale 0.95→1
• Duration: 250ms, spring easing
• Exit: reverse (implement in native)

Card Selection (Onboarding)

• Border color, background, and glow ring transitions: 250ms ease

Step Indicator Dots

• Width and color transitions: 400ms spring easing

Checkbox Toggle

• Background fill: 200ms ease
• Checkmark appearance: scale-in

15.3 Reduced Motion

When prefers-reduced-motion: reduce is active (or the Flutter equivalent):

• All animation durations reduce to near-zero (0.01ms)
• No motion-based transitions — instant state changes only
• This respects users with vestibular disorders

---

16. Accessibility

16.1 Color Contrast

All text/background combinations meet WCAG AA (4.5:1 for normal text, 3:1 for large text):

Combination	Ratio	Result
primary (#e6194c) on surface (#FFFCF8)	~4.8:1	AA pass
secondary (#2A2438) on bg (#F7F3EE)	~13.6:1	AAA pass
muted (#6B6678) on bg (#F7F3EE)	~4.5:1	AA pass
White on primary (#e6194c)	~4.8:1	AA pass
White on primary-dark (#C0153F)	~5.7:1	AAA pass

16.2 Focus Indicators

All interactive elements show a visible focus ring when navigated via keyboard/assistive technology:

• outline: 2px solid primary
• outline-offset: 2px

16.3 Touch Targets

Minimum touch target sizes:

• Buttons: Full width, minimum 48px height
• Nav items: Flex-1 width, 75px height
• Close/Back buttons: 40x40 minimum
• Checkboxes: 24x24 visual, but wrap in 44x44 touch area
• Quick Log items: 56x56 icon area + label

16.4 Screen Reader Considerations

• All icons should have semanticsLabel in Flutter (e.g., the favorite icon should read "Partner mode: Together")
• Toggle switches need value announcements ("Shared with partner: on/off")
• Stage badges should be announced with full context ("Current stage: Pregnant, Week 12")
• Context switcher: announce selected profile on change
• Mood icons: label each ("Very unhappy", "Unhappy", "Neutral", "Happy", "Very happy")

---

17. Platform Considerations

17.1 Flutter Implementation

Font Loading

• Use google_fonts package or bundle Fraunces and Outfit as assets
• Fraunces is a variable font — use FontVariation in Flutter for weight and optical size axes
• Fallback fonts: Georgia (serif), system sans-serif

Color System

• Define all tokens in a ThemeExtension<AveliaColors> for type-safe access
• Support potential dark mode (not in current mock, but design tokens make it straightforward to derive)

Component Mapping

Mock Component	Flutter Widget
.card	Custom AveliaCard widget (Container with BoxDecoration)
.btn-quick-log	Custom PrimaryButton widget with gradient
.btn-secondary	OutlinedButton with custom theme
.log-input	TextFormField with OutlineInputBorder
.toggle-switch	Switch.adaptive with custom colors
.stage-badge	Custom StageBadge widget with gradient
.nav-bar	BottomNavigationBar or custom implementation
.check-btn	Custom AveliaCheckbox widget
QuickLogItem	Custom QuickLogItem widget (Column: icon container + label)
Stage card	Custom StageOptionCard with selected animation
Context switcher	showMenu or custom popup positioned above nav

Navigation

• Use go_router (already in the project) for tab-based navigation
• Full-screen overlays: Use showModalBottomSheet with full height, or push a full-screen route
• Sub-pages: Standard context.push() navigation

17.2 iOS vs Android

Aspect	iOS	Android
Status bar	Light content on dark phones, integrate with safe area	Standard Material status bar
Navigation	iOS-style back swipe gesture	System back button
Scroll physics	Bouncing scroll	Clamping scroll with overscroll glow
Fonts	Fraunces + Outfit (custom)	Same
Date picker	CupertinoDatePicker	showDatePicker (Material)
Toggle	Custom styled (same on both)	Custom styled (same on both)

17.3 Safe Areas

• Top: Account for notch/dynamic island — the header already includes 44px top padding
• Bottom: Account for home indicator — the nav bar includes 15px bottom padding
• In Flutter, wrap with SafeArea or use MediaQuery.of(context).padding

---

18. Solo Mode Behavior

When a user has no linked partner, the app adapts across all screens:

Screen	With Partner	Solo Mode
Home — Partner's Shared Log	Shows partner's latest shared entry	Hidden entirely, or replaced with a "Link a partner" prompt card
Home — Greeting	"Good morning, Sarah & Mark"	"Good morning, Sarah" (individual name)
Log — Sharing toggle	Shows toggle with partner name	Hidden (all entries are private by nature)
Journal — Shared filter	Shows own + partner shared entries	"Shared" filter is disabled or hidden
Us screen	Shows partner stats, shared moments	Shows invite-only content: "Invite your partner" card with code generation
Context switcher	Shows "Us (Partner)" + children	Shows only children (if any), no "Us" option
Settings — Sharing & Privacy	Per-partner sharing controls	Shows "Link a partner" prompt

Principle: Solo mode should never feel like a degraded experience. All tracking, journaling, and guidance features work identically. Only partner-specific UI elements are hidden or replaced with gentle prompts.

---

19. Edge Cases & Empty States

19.1 Empty States

Context	Empty State
Journal — no entries	Warm illustration + "Your journal starts here" + "Create your first entry" button
Journal — Shared filter, no shared entries	"Nothing shared yet" + contextual message (solo: "Link a partner to share", with partner: "Mark as shared when logging")
Home — no recent logs	"Today's Snapshot" card shows "No logs today" with a Quick Log prompt
Guide — no articles for stage	Should not happen (content is pre-loaded), but fallback: "Content coming soon"
Us — partner not linked	"Invite your partner" card with invite code generation
Children list (onboarding) — no children added	Dashed "ADD A CHILD" button with subtitle: "You can always add children later from Settings"
Hospital Bag — all items packed	Celebration state: "You're all set!" with confetti/checkmark illustration

19.2 Confirmation Dialogs

Action	Dialog
Close Log with unsaved changes	"Discard this entry?" — "Discard" (destructive) / "Keep Editing" (primary)
Remove child	"Remove {name}? Entries associated with this child will be kept but unlinked." — "Remove" / "Cancel"
Unlink partner	"Unlink from {name}? You won't see each other's shared entries anymore. This can be reversed with a new invite." — "Unlink" / "Cancel"
Delete account	"Delete your account? All data will be permanently removed. This cannot be undone." — "Delete Account" (destructive) / "Cancel"
Change stage	"Switch to {stage}? Your home screen and quick log will adapt. All existing entries are preserved." — "Switch" / "Cancel"

19.3 Validation

Field	Rule	Error display
Child name	Required, non-empty	Red border + "Name is required" below field
BBT	Numeric, range 35.0–42.0	Red border + "Enter a value between 35.0 and 42.0"
Blood pressure	Format "systolic/diastolic"	Red border + "Use format like 120/80"
Weight	Numeric, positive	Red border + "Enter a valid weight"
Volume (ml)	Numeric, positive, max 500	Red border + "Enter a value between 0 and 500"
Email (registration)	Valid email format	Red border + "Enter a valid email address"
Password (registration)	Min 8 chars	Red border + "Password must be at least 8 characters"

Validation is inline — errors appear below the field on blur or on submit attempt. The field border changes to #dc2626 (red-600) and the error message uses the same color at 0.75rem.

---

20. Unspecified Flows (Design Required)

These flows are required by the product spec but not yet designed. They must be specified before implementation.

20.1 Account Creation & Login

Account creation should occur between Welcome (step 1) and Partner Mode (step 2):

• Fields: Name, Email, Password, Confirm Password
• Validation: inline (see 19.3)
• On success: advance to Partner Mode
• "I HAVE AN ACCOUNT" on Welcome opens a Login screen: Email + Password fields, "Forgot password?" link, biometric unlock for returning users

20.2 Journal Entry Detail View

Tapping a journal entry card opens a full-screen overlay:

• Header: Back button | entry type badge + date | Edit icon
• Content: Full entry data (mood, all fields, notes)
• Sharing toggle: Editable — user can change private/shared status retroactively
• Metadata: Created date/time, last modified, entry type

20.3 Log Entry Edit Mode

When editing an existing entry (from Journal detail view):

• Header title: "Edit Entry" (instead of "Log for {name}")
• Fields pre-populated with existing values
• Mood pre-selected
• Sharing toggle reflects current state
• Save button: "UPDATE ENTRY"
• Add "DELETE ENTRY" text button (destructive, with confirmation dialog)

20.4 Stage Change from Settings

Accessible from Settings → a "Current Stage" menu item (to be added to the settings list):

• Opens a screen reusing the stage selection cards from onboarding (section 4.6)
• Current stage is pre-selected
• On change: show confirmation dialog (see 19.2)
• Update takes effect immediately — Home screen adapts

20.5 Partner Invite Code Entry (Receiving Partner)

The receiving partner's flow during their own onboarding:

• On the Partner Mode step (step 2), add a link: "I have an invite code"
• Tapping opens a code entry screen: 6-character input field (grouped as AV-XXX-XXX)
• States: validating (spinner), success (checkmark + partner name), invalid code (error message), expired code
• On success: accounts link and onboarding continues

20.6 Cloud Sync & Recovery

Not in current mock. Design needed for:

• Sync toggle in Settings (enable/disable)
• Sync status indicator (last synced, syncing, error)
• E2E encryption key generation UX during first sync setup
• Recovery Kit: QR code/passphrase generation screen, prompted during onboarding or first sync
• Partner Recovery: request/approval flow
• Login screen: "Restore from iCloud/Google" button for platform backup

20.7 Settings Sub-Pages

The mock implements three sub-pages that need formal specification:

Device Management: List of linked devices (icon, device name, ID, "THIS DEVICE" badge for current), "ADD NEW DEVICE" flow with QR code.

Sharing & Privacy: Linked partners list, per-partner per-category sharing toggles (Journal, Logs, Calendar, Docs), "One-Time Medical Access" emergency QR, "REMOVE ACCESS" button.

Add Partner: Two-path flow ("I want to invite someone" → shows invite code / "I have an invite code" → 6-digit entry). Reached from Us screen → Partner Account card.

---

Appendix A: File Reference

Resource	Path
Functional mock (source of truth)	docs/avelia-mock/src/App.tsx
Design tokens (CSS)	docs/avelia-mock/src/App.css
Product specification	docs/avelia-product-spec.md
Mock dev server	cd docs/avelia-mock && npm run dev

Appendix B: Known Gaps Between Mock and Spec

The mock is a functional prototype, not a complete implementation. Items are grouped by priority.

Critical (blocks core flows)

1. Account creation / login flow — no registration or login screens exist (see 20.1)
2. Cloud sync settings & E2E encryption setup — core architecture feature with no UI (see 20.6)
3. Recovery Kit / Partner Recovery / Platform Backup — product spec's "Critical Risk" section, no design (see 20.6)
4. Partner invite code entry (receiving partner side) — partner linking cannot be completed (see 20.5)

High (product spec requirements)

5. Home screen: "Today's Snapshot" card — product spec lists this as a Home component, not mocked
6. Home screen: "This Week" guidance section — product spec lists this, not mocked
7. Journal entry detail view — product spec requires tap-to-open with sharing status edit (see 20.2)
8. Journal filters (All / Shared / Private) — spec requires, mock shows single entry
9. Stage change from Settings — product spec says "can be updated at any time", no path in settings (see 20.4)
10. Birth & Beyond stage — currently conflated with First Year; should have its own quick log items (contraction timer, birth story) and stage-specific cards
11. IVF protocol timeline — spec describes a visual step-by-step cycle view
12. IVF embryo count tracker — spec describes a progression display
13. IVF appointment tracker — spec requires structured fields (clinic, type, date), mock only has free-text
14. IVF medication reminders — spec requires per-medication reminders and missed-entry flagging

Medium (important for completeness)

15. Solo mode behavior — affects every screen for solo users, design guidance in section 18 but not mocked
16. Us screen: partner avatars and connection status — product spec requires, not shown
17. Us screen: shared entry count and stage milestone stats — product spec requires, only "days" is shown
18. Guide content that varies by stage — mock shows same 2 articles for all stages
19. Guide article detail view — tapping an article has no destination
20. Log entry edit mode — no way to edit existing entries (see 20.3)
21. Settings sub-pages — Profile, Sharing & Privacy, Devices are partially mocked but not spec'd (see 20.7)
22. Notification/reminder settings UI — no notification design
23. Contraction timer (Birth stage) — mentioned in spec, not designed
24. Birth story recording — mentioned in spec, not designed
25. Birth plan builder (Pregnant stage) — mentioned in spec, not designed
26. Growth tracking / vaccine schedule (First Year) — mentioned in spec

Low (polish)

27. Biometric app lock — spec requires Face ID / fingerprint
28. Data export — spec requires full JSON export
29. Account deletion — spec requires permanent deletion option
30. Dark mode — not designed, but token system supports it
31. School preparation (Growing Up) — mentioned in spec
32. Family memory archive (Growing Up) — mentioned in spec
33. Journal date navigation — timeline view with date grouping

Appendix C: Mock-Only Controls

The mock includes a sidebar control panel (.stage-selector) visible to the left of the phone frame. This is a development tool only — it does not represent any in-app UI. It allows:

• Toggling between onboarding and dashboard states
• Switching parent stages without going through settings
• Toggling family mode (showing/hiding children)

This sidebar should be ignored when implementing the native app. All equivalent functionality should be accessed through Settings (stage change) and the context switcher (family/child selection).