System Requirements Document for widgets-couples

1. Introduction

Companion is a mobile-first social app for couples, best friends, and small friend groups. It turns matching iOS and Android home-screen widgets into a shared emotional space: one member’s actions—such as tapping a heart, updating a mood, logging an activity, or sharing a photo—are reflected for their linked members in near-real time. The app is the control room for configuring widgets, viewing widget-related history, and socializing around them.

The product must make every screen’s loading, empty, error, and populated states explicit before UI implementation. It must not leave users with undefined states, silent failures, or ambiguous empty states.

2. System Overview

Companion consists of a mobile app for iOS and Android, separate native home-screen widget modules, and a backend that synchronizes shared state. Its current accepted behavior includes a four-tab bottom navigation, a live-preview Home dashboard, friend relationships and requests, widget setup and management, and the Pets, Tracker, Sleep, Our Days, Miss You, and Status experiences.

The only active human persona is Companion user. Members establish or verify their identity using a phone number or Apple/Google OAuth. A linked friend or group is needed for paired previews and shared interactions. When no friend is linked, the specified “Add friend to unlock” state is shown.

The native widgets are separate from the cross-platform client. iOS uses WidgetKit and App Groups; Android uses Glance/App Widgets. Both read a shared local cache synchronized by the main app. Paired-user changes must propagate in under two seconds. FCM on Android and APNs on iOS trigger widget refreshes and social notifications.

The current scope does not define the detailed mechanics or data fields for each module beyond the named behaviors and constraints in this document. It does not authorize adding adjacent product features merely because they are suggested by the visual references or common in social apps.

2a. Product Interpretation and Delivery Boundary

The versioned page contract is the final ordered information architecture. It contains an anonymous Landing page, authenticated Home, Friends, Widgets, Profile/Me, Pets, Tracker, Sleep, Our Days, Miss You, and Status pages, and an anonymously reachable Login page. The four bottom-navigation destinations are Home, Friends, Widgets, and Profile/Me. The other contracted pages own their respective accepted flows; they do not add capabilities beyond those flows.

Landing is the anonymous first impression for Companion and its shared-widget experience. Login is the anonymous entry for returning-member verification. First-use enrollment is self-service using the accepted phone-number or Apple/Google OAuth options. Protected member and shared state is available only after identity is established or verified.

The five supplied Widgetable screenshots are supplemental visual and feature references only. They do not replace the accepted Companion requirements or authorize copying another product’s names, copy, or unaccepted capabilities. The project-wide creative direction governs visual design.

The current scope includes the named dashboard cards and quick-access labels, but does not define separate Shop, Pro, Games, or Garden destinations or their underlying feature behavior. The carousel’s rotating promo categories are games, seasonal events, and referral challenges; their detailed content and actions are not specified. No future requirements were supplied.

2b. Page Content and Component Coverage

Every page and screen state must be specified before UI implementation. For each page, loading, empty, error, and populated states are required. Where a particular state’s content is not specified below, implementation must provide a clear, non-silent state without inventing a new product capability. Errors must be visible and provide a way to retry or return to the relevant accepted context where retry is applicable.

Landing

• Information and state: Anonymous introduction to Companion, its intended users, and the shared-widget experience. Loading, empty/not-applicable, error, and populated states must be defined. The page must not expose protected member state.
• Primary actions: Continue to first-use enrollment or returning-member verification.
• Entities: Product introduction and identity-entry choice.
• Components: Public introduction, identity-entry actions, and the hero composition described in Section 7.
• States: Loading while the entry surface initializes; empty/not-applicable for member-specific content; visible error if the entry surface cannot load; populated public introduction when available. Recovery returns the user to the public entry or proceeds to Login.

Home

• Information and state: Authenticated, vertically scrolling dashboard with a rotating promo carousel; quick-access row labeled Shop | Pro | Pets | Games | Garden; and a two-column feature-card grid. Cards show live previews from actual user state, not placeholders.
• Primary actions: Open the accepted feature flows from their cards. The quick-access row and carousel are present as specified; their destinations and detailed actions are not defined.
• Entities: Member state, linked friend/group state, promo items, feature-card previews, streak counters, sleep comparison, recent photo memories and day counters, heart-meter state, and mood/activity state.
• Components: Hero carousel; horizontally scrollable quick-access capsule row; Pets card with “Co-parent pets with your besties” and HOT badge; Tracker card with “Record fun activities” and two streak counters per linked friend; Sleep card with “Track and compare sleep” and a “Half Dead vs Slept Like a Log” style comparison; Our Days card with “Cherish every memory together,” NEW badge, and two most recent photo memories with day counters; Miss You heart-meter preview; Status mood/activity preview.
• States: Loading while actual state is fetched; empty/unlinked state displays “Add friend to unlock” on paired previews; error state identifies unavailable preview data and does not silently substitute placeholder data; populated state shows actual available state. Recovery retries loading or opens Friends to establish a link.

Friends

• Information and state: Friend list, friend requests, and co-parenting invites.
• Primary actions: View the friend list, requests, and co-parenting invites; add a friend and participate in the corresponding request or invitation flow.
• Entities: Member, friend/link, friend request, and co-parenting invite.
• Components: Friend list, request presentation, and co-parenting invite presentation.
• States: Loading while relationship data is fetched; empty state when no friends, requests, or invites exist, with the relevant add-friend entry point; error state with visible recovery; populated state showing available relationships and requests. A successful friend-add is observable and recorded as an analytics event. The exact discovery, acceptance, and rejection mechanics are not specified.

Widgets

• Information and state: Manage installed widgets, reorder and configure them, and access widget setup, installation, history, and social interaction around widgets.
• Primary actions: Configure and set up a widget, install it through the relevant platform flow, reorder installed widgets, and view widget-related history and social interactions.
• Entities: Widget module, installation state, configuration, shared local cache, and widget-related history.
• Components: Installed-widget management, ordering and configuration controls, module setup entry, and platform-specific installation guidance.
• States: Loading while widget and installation state is read; empty state when no widgets are installed, with setup guidance; error state for unavailable synchronization or platform installation, with visible recovery; populated state showing installed widgets and their configuration. Installation events are recorded as analytics events. Platform permissions and installation are required for home-screen participation.

Profile/Me

• Information and state: Member account, pet avatar, and settings entry.
• Primary actions: View the account, pet avatar, and settings entry. Detailed settings operations are not specified.
• Entities: Member identity and pet avatar.
• Components: Account summary, pet avatar, and settings entry.
• States: Loading while member information is retrieved; empty/not-applicable state for unavailable optional avatar content; error state with visible recovery; populated state showing the member’s account and pet avatar when available.

Pets

• Information and state: Co-parenting pets with besties; the Home card carries the HOT badge. The page owns the pet interaction and state previewed from Home.
• Primary actions: Enter the pet experience and participate in the accepted co-parenting interaction. Specific pet-care actions and pet data fields are not defined.
• Entities: Pet, linked members, and shared pet state.
• Components: Pet state and co-parenting interaction presentation.
• States: Loading while shared pet state is retrieved; empty/unlinked state uses the specified “Add friend to unlock” treatment for paired previews; error state is visible and recoverable; populated state shows actual shared pet state. The supplied pet screenshot is visual/feature reference only and does not authorize its egg, shop, speed-up, or other unaccepted mechanics.

Tracker

• Information and state: Record fun activities and show two streak counters per linked friend.
• Primary actions: Record an activity and view the resulting shared streak state.
• Entities: Activity record, linked friend, and streak counters.
• Components: Activity recording control, activity state, and paired streak preview.
• States: Loading while activity and streak state is retrieved; empty/unlinked state shows “Add friend to unlock”; error state is visible and recoverable; populated state shows actual activity and two streak counters per linked friend. The source’s example “logging a poop” is an accepted example of an interaction, but does not specify additional tracker categories or fields.

Sleep

• Information and state: Track and compare sleep between linked members, including a “Half Dead vs Slept Like a Log” style VS comparison.
• Primary actions: Record sleep information and view the comparison with the linked member.
• Entities: Member sleep state and paired comparison.
• Components: Sleep input/presentation and VS comparison.
• States: Loading while sleep state is retrieved; empty/unlinked state shows “Add friend to unlock”; error state is visible and recoverable; populated state shows actual available sleep comparison. The exact sleep fields and measurement method are not specified.

Our Days

• Information and state: Cherish shared photo memories. Home shows the two most recent photo memories with day counters, such as “1234 days.”
• Primary actions: Add a photo memory and revisit shared memories.
• Entities: Photo memory, media object, day counter, and linked members.
• Components: Memory presentation and photo upload flow.
• States: Loading while memories are retrieved; empty/unlinked state shows “Add friend to unlock” for paired content; empty linked state clearly indicates that no memories are available; error state is visible and recoverable; populated state shows available memories and their day counters. Photos are compressed client-side to max 1080p and under 2 MB per photo before upload, and stored using signed URLs.

Miss You

• Information and state: Shared Miss You interactions and a heart-meter preview.
• Primary actions: Send a Miss You interaction and view the shared heart-meter state.
• Entities: Miss You interaction and shared heart-meter state.
• Components: Interaction control and heart-meter presentation.
• States: Loading while shared state is retrieved; empty/unlinked state shows “Add friend to unlock”; error state is visible and recoverable; populated state shows actual heart-meter state. The source does not specify a meter range or a send limit.

Status

• Information and state: Share and view mood/activity status between linked members.
• Primary actions: Update mood/activity status and view the linked member’s status.
• Entities: Member status, mood, activity, and linked member.
• Components: Status input/presentation and paired status preview.
• States: Loading while status is retrieved; empty/unlinked state shows “Add friend to unlock”; error state is visible and recoverable; populated state shows actual shared mood/activity state. Specific status choices and fields are not defined.

Login

• Information and state: Anonymous returning-member verification before access to private account and shared durable workflows.
• Primary actions: Verify using phone number or Apple/Google OAuth.
• Entities: Identity credential and authenticated session.
• Components: Accepted authentication choices and verification result.
• States: Loading during verification; empty state before a method is selected; error state explains verification failure and permits retry; populated/success state continues to the protected destination. Email/password alone is not an acceptable authentication option.

2c. Cross-Screen and Native Component Responsibilities

• Bottom navigation: Four destinations in this order: Home, Friends, Widgets, Profile/Me. Home uses the planet/blob icon, Widgets the sliders icon, and Profile/Me the smiley cloud icon.
• Widget modules: Each accepted module has an in-app screen, a home-screen widget variant, an onboarding/setup flow, and a data model. The named modules are Pets, Tracker, Sleep, Our Days, Miss You, and Status. Their data models must represent only the state needed for the accepted behavior; unspecified fields remain to be defined without adding adjacent capabilities.
• Native widget delivery: iOS WidgetKit with App Groups and Android Glance/App Widgets are separate native modules. They read a shared local cache synchronized by the main app. Platform permissions and installation are part of widget participation.
• Synchronization and notifications: Backend realtime synchronization propagates paired-user changes in under two seconds. FCM (Android) and APNs (iOS) trigger widget refreshes and social notifications.
• Analytics: Every widget install, friend-add, and interaction is an analytics event using PostHog or Amplitude.
• Media: Image/video storage uses cloud storage with signed URLs. Client-side photo compression is limited to max 1080p and under 2 MB per photo.
• Global state completeness: Every screen defines loading, empty, error, and populated states. A state that does not apply must be explicitly treated as not applicable rather than left undefined. Failures must be visible; paired previews without a linked friend use the exact “Add friend to unlock” state.

3. Functional Requirements

Each requirement below is a distinct accepted capability. Provenance is explicit unless marked otherwise. Required inferred identity and continuity mechanics are identified separately.

1. As a Companion user, I should be able to use Companion as a mobile-first social app for couples, best friends, and small friend groups, so that matching iOS/Android home-screen widgets form a shared emotional space. [explicit]
   Lifecycle and acceptance: A member establishes or verifies identity, links with another member through the Friends experience, and uses shared widget interactions. The other linked member sees the resulting shared state in the app/widget within the under-two-second propagation requirement. If no friend is linked, paired previews show “Add friend to unlock.” Synchronization failures are visible rather than silent; recovery retries synchronization or returns to the relevant shared flow.

2. As a Companion user, I should be able to configure widgets, view widget-related history, and socialize around widgets in the app, so that the app serves as the widgets’ control room. [explicit]
   Lifecycle and acceptance: From Widgets, the member sets up/configures a module, installs a widget through the platform flow, and can revisit widget-related history and social interaction. Installation and interaction results are observable. Platform or synchronization failures are shown with recovery; successful installation is recorded as an analytics event.

3. As a Companion user, I should be able to navigate Home, Friends, Widgets, and Profile/Me from a four-tab bottom navigation, with the specified icons for Home, Widgets, and Profile/Me. [explicit]
   Lifecycle and acceptance: The member selects a tab and sees its contracted destination. Loading, empty, error, and populated states are defined for each destination. A destination failure is visible and does not silently present stale or placeholder content as current.

4. As a Companion user, I should be able to view a vertically scrolling Home dashboard with a rotating promo carousel, whose promo categories are games, seasonal events, and referral challenges. [explicit]
   Lifecycle and acceptance: Home loads the carousel and presents its available promo content. Loading and error are visible; no promo content has a clear empty state. The source does not define promo actions or detailed promo content, so none are assumed.

5. As a Companion user, I should be able to see the Home quick-access row labeled Shop | Pro | Pets | Games | Garden. [explicit]
   Lifecycle and acceptance: The row is horizontally scrollable as specified by the creative direction and its items remain readable as they pass. The source does not define separate destinations or behavior for Shop, Pro, Games, or Garden; this requirement does not create them.

6. As a Companion user, I should be able to see a Pets feature card labeled “Co-parent pets with your besties” with a HOT badge. [explicit]
   Lifecycle and acceptance: The card links to Pets and shows actual available pet state or the required “Add friend to unlock” state. Loading and errors are explicit. The linked member’s shared pet state is observable in the Pets experience.

7. As a Companion user, I should be able to record fun activities in Tracker and see two streak counters per linked friend. [explicit]
   Lifecycle and acceptance: The initiating member records an activity; the shared activity/streak state updates and is visible to linked members. The Home Tracker preview shows actual current streak state, not a placeholder. With no linked friend, it shows “Add friend to unlock.” Failed writes or synchronization are visible and recoverable. Each interaction is an analytics event.

8. As a Companion user, I should be able to track and compare sleep with a linked member using a “Half Dead vs Slept Like a Log” style VS comparison. [explicit]
   Lifecycle and acceptance: A member records sleep information and views the paired comparison; the linked member can view the shared comparison. No linked friend produces “Add friend to unlock.” Loading, empty, and error states are explicit. Failed updates are visible and recoverable.

9. As a Companion user, I should be able to cherish shared photo memories in Our Days, with the Home card showing the two most recent photo memories and day counters. [explicit]
   Lifecycle and acceptance: A member adds a photo memory; the linked member can see it in the shared memory experience and Home preview. Photos are compressed client-side to max 1080p and under 2 MB per photo and uploaded to cloud storage using signed URLs. Upload or synchronization failure is visible and recoverable; successful shared memory state is observable.

10. As a Companion user, I should be able to send and view Miss You interactions represented by a heart-meter preview. [explicit]
    Lifecycle and acceptance: The initiating member sends an interaction; the linked member sees the resulting shared heart-meter state. No linked friend produces “Add friend to unlock.” Failed writes or synchronization are visible and recoverable. Each interaction is an analytics event.

11. As a Companion user, I should be able to share and view mood/activity status with linked members. [explicit]
    Lifecycle and acceptance: A member updates status; linked members can view the resulting status in the app and widget preview. No linked friend produces “Add friend to unlock.” Failed updates or synchronization are visible and recoverable. Each interaction is an analytics event.

12. As a Companion user, I should be able to co-parent pets with besties. [explicit]
    Lifecycle and acceptance: A member enters Pets and participates in the shared pet experience; linked members can observe the resulting shared pet state. The Home card preview reflects actual state. No linked friend produces “Add friend to unlock” for paired previews. Loading, empty, and error states are explicit. Specific pet-care actions are not defined.

13. As a Companion user, I should be able to add friends and view friend lists, requests, and co-parenting invites. [explicit]
    Lifecycle and acceptance: The initiating member adds a friend; the friend’s request/invitation state is observable in Friends, and the resulting link unlocks paired previews and shared interactions. Friend-add is recorded as an analytics event. The exact discovery and response mechanics are unspecified; failures are visible and recoverable.

14. As a Companion user, I should be able to install matching widgets on iOS and Android home screens. [explicit]
    Lifecycle and acceptance: The member selects a module in Widgets, completes its setup, and follows the platform installation/permission flow. The native widget reads the shared local cache synchronized by the main app. The linked member’s actions are reflected in the widget after synchronization. Installation failure is visible and recoverable; each install is an analytics event.

15. As a Companion user, I should be able to use each named module through an in-app screen, home-screen widget variant, onboarding/setup flow, and data model. [explicit]
    Lifecycle and acceptance: This applies to Pets, Tracker, Sleep, Our Days, Miss You, and Status. Setup leads to the module’s accepted interaction; resulting state is visible in the app and widget where applicable. Loading, empty, error, and populated states are defined. The data model contains only fields needed for accepted behavior.

16. As a Companion user, I should be able to see live Home previews based on my actual state rather than placeholders. [explicit]
    Lifecycle and acceptance: Home loads actual module state for Tracker, Sleep, Our Days, Miss You, and Status, and pet state for Pets. It shows two Tracker streak counters per linked friend, the specified Sleep comparison, two recent Our Days photo memories with day counters, the Miss You heart-meter preview, and the Status mood/activity preview. If no friend is linked, paired previews show “Add friend to unlock.” Data errors are visible and do not silently become fabricated values.

17. As a Companion user, I should be able to establish a Companion identity on first use using phone number or Apple/Google OAuth. [required_inference]
    Lifecycle and acceptance: The anonymous Landing entry leads to self-service identity establishment using an accepted method. Successful establishment continues to protected member work; failure is visible and permits retry. Email/password alone is not acceptable.

18. As a Companion user, I should be able to verify my identity when returning before accessing private account and shared durable workflows. [required_inference]
    Lifecycle and acceptance: A returning member uses Login and an accepted authentication method. Successful verification resumes access to protected work; failure is visible and permits retry. Login remains anonymously reachable; protected state is unavailable until verification succeeds.

19. As a Companion user, I should be able to see paired previews and use shared interactions only when a linked friend or group is available. [required_inference]
    Lifecycle and acceptance: When no link exists, paired previews show “Add friend to unlock.” After a friend link is established, the relevant shared state becomes available. The friend’s request/invitation state is visible in Friends. No additional relationship-management capability is implied.

20. As a Companion user, I should be able to see paired changes propagated in under two seconds. [explicit]
    Lifecycle and acceptance: A member action updates backend shared state and the linked member’s app/widget state within the stated bound. Native widget refresh is triggered through FCM on Android and APNs on iOS. If propagation or refresh fails, the failure is surfaced; the system must not silently claim the remote state is current.

21. As a Companion user, I should be able to use native widgets that read a shared local cache synchronized by the main app. [explicit]
    Lifecycle and acceptance: The main app synchronizes shared state into the local cache; WidgetKit/App Groups on iOS and Glance/App Widgets on Android read that cache. Cache or synchronization errors are visible in the app and do not present fabricated state as current.

22. As a Companion user, I should be able to share photo memories with client-side compression and signed-URL storage. [explicit]
    Lifecycle and acceptance: Before upload, each photo is compressed to max 1080p and under 2 MB. The photo is stored in cloud storage using a signed URL and becomes part of the shared Our Days state. Compression, upload, or synchronization failure is visible and recoverable.

23. As a Companion user, I should be able to have every widget install, friend-add, and interaction recorded as an analytics event using PostHog or Amplitude. [explicit]
    Lifecycle and acceptance: The event is recorded for each of those actions. Analytics failure must not silently be represented as a successful event record; it must not prevent the underlying accepted user action unless required by the selected provider’s operation. No additional analytics event taxonomy is specified.

24. As a Companion user, I should be able to see explicit loading, empty, error, and populated states on every screen. [explicit]
    Lifecycle and acceptance: Each screen defines all four states before UI implementation. A non-applicable state is explicitly identified as such. Errors are visible; empty states are unambiguous; no screen silently fails or displays a broken/blank preview.

4. User Personas

Companion user

Provenance: Explicit active-human persona from the Planning Scope contract. The persona covers members who are couples, best friends, or part of a small friend group.

Product context: Uses Companion on iOS or Android to configure and install matching home-screen widgets, connect with friends, and share lightweight emotional or activity state. The app is the control room for widget setup, history, and social interaction.

Primary goal: Make shared actions feel present across members’ home screens and in the app, with live previews that reflect actual shared state.

Distinct accepted responsibilities: Establish or verify identity; add friends and participate in friend/request and co-parenting-invite flows; configure and install widgets; record activities and sleep information; share photo memories, Miss You interactions, and mood/activity status; participate in pet co-parenting; view shared state and widget-related history.

Relevant inputs and decisions: Chooses an accepted authentication method; selects widget modules and configuration; provides the accepted module interaction or photo; and decides whether to add a friend or continue without paired features.

Interactions with other accepted participants: Shares state with linked Companion users. A friend’s request/invitation state is visible in Friends; linked members observe shared module state and widget updates. No additional active-human persona is defined.

Observable success: The member sees actual shared state in the app and matching widgets, with paired changes propagated in under two seconds. Without a linked friend, paired previews clearly show “Add friend to unlock.”

5. Core User Flows

1. First use and identity establishment

1. The Companion user opens Landing anonymously and sees the public introduction to Companion and its shared-widget experience.
2. The user chooses first-use enrollment and establishes identity using a phone number or Apple/Google OAuth.
3. On success, the user enters protected member work. On failure, the error is visible and the user can retry.
4. The user can continue to Friends to add a friend, or use the app without paired previews; paired previews remain in the specified “Add friend to unlock” state until a link exists.

2. Returning member verification

1. A returning Companion user opens Login anonymously.
2. The user verifies identity using phone number or Apple/Google OAuth.
3. On success, the user resumes access to protected account and shared workflows.
4. On failure, Login shows a clear error and permits retry; protected state remains unavailable until verification succeeds.

3. Add a friend and establish shared access

1. The Companion user opens Friends and views the friend list, requests, and co-parenting invites.
2. The user initiates a friend-add action.
3. The other Companion user sees the resulting request/invitation state in Friends and participates in the relationship flow. Exact response mechanics are not specified.
4. When a link is established, paired previews and shared interactions become available. Friend-add is recorded as an analytics event.
5. If the operation fails, the initiating user sees an error and can recover or retry. Until a link exists, paired previews show “Add friend to unlock.”

4. Configure and install a widget

1. The Companion user opens Widgets and selects one of the accepted modules: Pets, Tracker, Sleep, Our Days, Miss You, or Status.
2. The user completes that module’s onboarding/setup flow and configuration needed for its accepted behavior.
3. The user follows the platform’s installation and permission flow to add the native widget to the home screen.
4. The native widget reads the shared local cache synchronized by the main app. Installation is recorded as an analytics event.
5. The user can return to Widgets to manage installed widgets, reorder or configure them, and view widget-related history and social interaction.
6. If setup, permission, installation, or synchronization fails, the failure is visible and recovery is offered in the relevant context.

5. Record a Tracker activity

1. The Companion user opens Tracker from Home or Widgets.
2. The user records a fun activity.
3. The shared activity state and streak counters update; Home shows actual current streak state and two counters per linked friend.
4. Linked members can see the resulting shared state in the app and widget after synchronization.
5. The interaction is recorded as an analytics event. If there is no linked friend, the paired preview shows “Add friend to unlock.” If the write or synchronization fails, the user sees an error and can retry.

6. Track and compare sleep

1. The Companion user opens Sleep from Home or Widgets.
2. The user records sleep information.
3. The linked member can view the resulting paired comparison, presented in the “Half Dead vs Slept Like a Log” style.
4. Home shows the actual comparison when available; without a linked friend it shows “Add friend to unlock.”
5. If loading or saving fails, the error is visible and the user can retry. Specific sleep fields and measurement mechanics are not defined.

7. Share a photo memory in Our Days

1. The Companion user opens Our Days from Home or Widgets.
2. The user selects a photo memory to share.
3. The client compresses the photo to max 1080p and under 2 MB, then uploads it to cloud storage using a signed URL.
4. On success, the memory and its day counter become visible in Our Days to linked members; Home shows the two most recent photo memories with day counters.
5. If compression, upload, or synchronization fails, the user sees an error and can retry. With no linked friend, paired previews show “Add friend to unlock”; with a link but no memories, the page shows a clear empty state.

8. Send a Miss You interaction

1. The Companion user opens Miss You from Home or Widgets.
2. The user sends a Miss You interaction.
3. The linked member sees the resulting shared heart-meter state in the app/widget; Home shows the actual heart-meter preview.
4. The interaction is recorded as an analytics event.
5. Without a linked friend, the paired preview shows “Add friend to unlock.” A failed write or synchronization is visible and recoverable.

9. Share a mood/activity status

1. The Companion user opens Status from Home or Widgets.
2. The user updates mood/activity status.
3. Linked members see the resulting status in the app and widget; Home shows the actual mood/activity preview.
4. The interaction is recorded as an analytics event.
5. Without a linked friend, the paired preview shows “Add friend to unlock.” A failed update or synchronization is visible and recoverable.

10. Co-parent a pet

1. The Companion user opens Pets from Home or Widgets.
2. The user participates in the shared pet experience with linked members.
3. The resulting shared pet state is observable to linked members and reflected in the Home Pets preview.
4. Without a linked friend, paired previews show “Add friend to unlock.”
5. Loading, empty, and error states are explicit. Specific pet-care actions are not defined and are not assumed.

11. View the Home dashboard

1. The Companion user opens Home and sees the vertically scrolling dashboard.
2. The user views the rotating promo carousel, the Shop | Pro | Pets | Games | Garden quick-access row, and feature cards.
3. Each feature card shows actual available state: Pets, Tracker streak counters, Sleep comparison, two recent Our Days photo memories with day counters, Miss You heart-meter, and Status mood/activity.
4. If no friend is linked, paired previews show “Add friend to unlock.” If data is loading or unavailable, the state is explicit and not replaced with fabricated values.
5. The user selects an accepted feature card to continue to its dedicated page.

12. Native widget synchronization

1. A Companion user performs an accepted shared interaction in the app.
2. The backend synchronizes the paired state in under two seconds.
3. The main app updates the shared local cache; the native iOS WidgetKit or Android Glance/App Widget reads the cache.
4. FCM on Android or APNs on iOS triggers widget refresh and social notifications.
5. The linked member sees the updated state in the app/widget. If synchronization or refresh fails, the app surfaces the failure rather than claiming the remote state is current.

6. Visuals Colors and Theme

Muse: Karim Rashid. The visual language is sensual pop minimalism: a candy-gloss widget playground for two. It should feel affectionate, silly, optimistic, intimate, and tactile—not corporate or clinical.

Color tokens

• Light background: #FFF4F7 warm blush.
• Surface: #FFFFFF glossy white.
• Primary: #FF4FA3 bubblegum magenta-pink for paired hearts, active states, and primary actions.
• Accent: #B4FF3D acid lime for streak wins, live indicators, and friend-online pulses; do not use as a large fill.
• Text: #1F1230 deep aubergine for headings and body text.
• Muted text: #8E7FA8 lilac for secondary labels and metadata.
• Supporting widget-art colors only: tangerine #FF8A3D and sky-mint #7DE3D2.
• Approximate proportion: 62% blush/white, 20% ink text, 12% pink, 6% lime/tangerine accents.
• No blue, indigo, or violet in the chrome. Mint is limited to decorative widget art.

Typography

• Headings and widget titles: Unbounded, weight 700–800, tight tracking -0.02em, sentence case with occasional all-caps badges.
• Body, labels, and data: Manrope, weights 400–600.
• Scale: 64 / 48 / 36 / 27 / 20 / 16 / 13 / 11.
• Hero headline: clamp(34px, 8vw, 64px); section titles: clamp(24px, 5vw, 36px); body 16px; metadata 13px.
• Card titles: 20px/16px. Widget numerals: 28–44px, with tabular numerals.

Shape, spacing, and layout

• Use continuous-curve capsules and squircles, with 24–40px radii; avoid hard 4px corners.
• Buttons are pill-shaped with a 2px glossy top highlight.
• Widget previews are rounded device tiles with soft drop shadows and subtle inner glow.
• Use a 16px mobile grid gutter and 20px card padding.
• At 375px, use a mobile-first single-column page composition with a two-column feature-card grid and horizontally scrollable quick-access capsules.
• At 768px, retain a two-column card grid and allow a secondary preview tile beside the hero.
• At 1280px, center content in a 1120px maximum-width container, use a three-column card grid, and compose the hero as two panels.
• Readable text and controls must remain fully inside the viewport and their containers at 375px, 768px, and 1280px. Decorative imagery may bleed, crop, rotate, or overlap as directed, but must not cover readable text or controls.

Imagery and component style

Use glossy blob and capsule props in pink, lime, tangerine, and mint with soft studio lighting and visible specular highlights for hero decoration, empty-state art, and section dividers. Do not use stock photography of people, flat clip-art hearts, or emoji as primary illustration. Our Days photos, when present, sit in rounded capsule frames with a pink 2px border and soft inner shadow. Feature cards are capsule-squircles with a glossy top highlight and a live preview strip, or the explicit “Add friend to unlock” capsule. Use curved pink capsule waves or soft blob edges for section transitions, not straight rules.

Motion

• Capsule buttons squash to 0.96 on press and spring back over 320ms with cubic-bezier(0.34, 1.56, 0.64, 1).
• The paired heart pulses once every four seconds with a lime halo when a partner action arrives.
• Home card items scale in from 0.94 with a 60ms stagger on first paint.
• Widget preview tiles tilt toward cursor/touch by at most 4 degrees.
• A gentle pink-to-blush gradient drifts behind the hero at 0.02 opacity.
• Respect reduced motion: replace pulses with a static lime ring, collapse staggers to a single 200ms fade, stop the drift, and show whole items in rows or a horizontally scrollable row.

7. Signature Design Concept

The anonymous Landing hero is a blush-ground composition built from the accepted shared-widget concept. Set the oversized, flush-left Unbounded headline “TWO PHONES. ONE HEARTBEAT.” in a stacked nine-column composition, with “HEARTBEAT” in bubblegum pink and the remaining words in aubergine. Place a large glossy pink blob off-center behind the headline, bleeding off the right edge without covering text or controls.

Overlap the blob’s lower-left with two glossy white widget device tiles, tilted 4° and 7°. Their content must be real paired state when available, such as a heart count and a live streak; when no linked state is available, use the explicit “Add friend to unlock” treatment rather than fabricated values. Beneath the headline, show the lime capsule CTA “Pair your first widget” and the muted line “No friend yet? See how it works”. The CTA proceeds only into accepted identity and widget setup flows; it does not imply a new feature. Keep the composition tactile and product-specific, with no stock people photography, blue button, or unrelated decorative imagery.

8. Interaction Model & Motion Direction

Interaction Model: Animated
Motion Tempo: expressive
Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject: The paired glossy widget tiles and their shared heart/streak state, composed over the off-center pink blob.
• Input → transformation → outcome: A member’s accepted shared action updates the paired state; the heart receives its specified lime-halo pulse when a partner action arrives, and the widget tiles present the resulting real shared state. No fabricated state or additional interaction is introduced.
• Motion vocabulary: Soft expressive motion; capsule press squash and spring; subtle tile tilt up to 4°; the specified low-opacity hero drift. The hero uses layered 2D, not required WebGL.
• First frame: Blush ground, flush-left stacked headline, pink blob behind it, and two overlapping glossy white widget tiles with real state or the explicit unlinked state. CTA and supporting line remain fully readable.
• Reduced-motion state: Stop the drift; replace the pulse with a static lime ring; collapse first-paint stagger to a single 200ms fade; stop tilt and ensure scrollable items remain fully reachable.

9. Non-Functional Requirements

1. Mobile platforms — explicit: The product targets iOS and Android and is mobile-first.
2. Paired propagation — explicit: Realtime paired-user propagation is a hard requirement and must be under two seconds.
3. Native widget boundary — explicit: WidgetKit/App Groups and Glance/App Widgets are separate native modules, not built directly in Flutter or React Native; they read a shared local cache synchronized by the main app.
4. Authentication — explicit: Use phone number or Apple/Google OAuth. Email/password alone is not acceptable.
5. Screen-state completeness — explicit: Every screen defines loading, empty, error, and populated states before UI implementation. No undefined states, silent failures, or ambiguous empty states.
6. Photo constraints — explicit: Client-side photo compression must produce max 1080p and under 2 MB per photo; image/video storage uses signed URLs.
7. Analytics coverage — explicit: Every widget install, friend-add, and interaction is an analytics event using PostHog or Amplitude.
8. Readable responsive content — explicit creative direction: Readable text and controls remain whole at 375px, 768px, and 1280px. Decorative imagery may be cropped or bleed only when it does not cover readable content.
9. Failure visibility — explicit: Synchronization, upload, installation, and data failures must be visible and recoverable where retry is applicable; the system must not claim remote state is current when propagation has failed.

10. Tech Stack

• Client: Flutter, single codebase for iOS and Android.
• State management: Riverpod.
• iOS widgets: WidgetKit in Swift, using App Groups for shared local-cache access.
• Android widgets: Glance/App Widgets in Kotlin, using the shared local cache.
• Backend: Firebase: Firestore, Cloud Functions, and FCM. This is an accepted backend option for MVP speed and supports the required paired realtime synchronization; the implementation must meet the under-two-second propagation requirement.
• Push: FCM on Android and APNs on iOS for widget-refresh triggers and social notifications.
• Analytics: PostHog. Every widget install, friend-add, and interaction is recorded.
• Media storage: Cloud Storage with signed URLs; client-side photo compression to max 1080p and under 2 MB per photo.
• Repository note: If implementation deviates from the selected client stack, the repository must include a comment block at its top justifying the deviation.

11. Assumptions and Constraints

• [required_inference] First-use self-service identity establishment and returning verification are required for private account and shared durable workflows. Use only phone number or Apple/Google OAuth.
• [required_inference] A linked friend or group is required for paired previews and shared interactions. Without one, show “Add friend to unlock.”
• [required_inference] Platform permissions and installation are required for native home-screen widget participation.
• [explicit] The versioned page contract is closed and ordered: Landing, Home, Friends, Widgets, Profile/Me, Pets, Tracker, Sleep, Our Days, Miss You, Status, Login. No additional page is introduced.
• [explicit] The five supplied screenshots are supplemental visual and feature references; they do not authorize unaccepted product behavior.
• [explicit] The source names Shop, Pro, Pets, Games, and Garden in the Home quick-access row but does not define separate destinations or their detailed behavior.
• [explicit] The source names carousel promo categories but does not define their content or actions.
• [explicit] Module-specific data fields and detailed setup mechanics are not specified; define only what is necessary for accepted behavior.
• [explicit] No future requirements were supplied.
• [Default — not specified by user] Use accessible contrast, scalable text, and touch targets suitable for a mobile-first consumer app, without changing accepted product behavior.

12. Glossary

• Companion user: The sole accepted active-human persona; a member who uses Companion as part of a couple, best-friend pair, or small friend group.
• Linked friend/group: A relationship that enables paired previews and shared interactions.
• Shared local cache: Device-local state read by native widgets and synchronized by the main app.
• Widget module: One of the accepted Pets, Tracker, Sleep, Our Days, Miss You, or Status experiences, with an in-app screen, home-screen widget variant, setup flow, and data model.
• Paired propagation: Synchronization of a member’s shared action to linked members, required in under two seconds.