System Requirements Document for voxlink-offline-communication

1. Introduction

VoxLink is an offline communication application for Android, built in Flutter. This document specifies Step 1 of the product: a complete, polished, premium UI/UX layer for the VoxLink app. The intent of this step is to establish the visual identity, design system, navigation architecture, and screen inventory of an offline-first peer-to-peer communication tool, so that future functional stages (Bluetooth discovery, mesh networking, encryption, local storage, voice transmission, file transfer, and emergency signalling) can be implemented against a stable, modular, reusable interface foundation.

The audience for this step is the product owner and the Flutter implementation engineer. The audience for the eventual product is a person who needs to communicate when conventional infrastructure is unavailable — hikers, festival attendees, disaster-zone responders, protest participants, and remote job-site workers — and who therefore expects the app to read as dependable hardware rather than a social application.

This step is explicitly UI/UX only. No Bluetooth, networking, encryption, database, login backend, mesh, voice, or file transfer is implemented. All data shown is sample/demo data, clearly separated from future real implementation and clearly marked as such in the interface.

2. System Overview

VoxLink Step 1 delivers a single Flutter application with twelve polished screens, a single shared design system, a reusable component library, and a navigation architecture ready to accept real functionality in a later stage.

Current delivery. The app launches into a branded Splash Screen, hands off to an anonymous Welcome Screen, and offers two entry paths: creating a VoxLink identity or unlocking an existing one. From the Home dashboard, the user reaches Chat, Nearby, Voice / Push-to-Talk, Files, Emergency / SOS, Profile, and Settings. Bottom navigation exposes Home, Chat, Nearby, and Profile as persistent destinations. Every screen renders realistic content states — empty states, demo device rows, PTT states, SOS presentation — without performing any real communication, discovery, transmission, or persistence.

Actors. The single active human role in this step is the VoxLink User. There are no system, provider, or external actors in the current delivery, because no networking, discovery, or transmission is implemented.

Accepted behavior and ownership. All twelve screens are first-party application surfaces owned by the application. All access requirements are none in this step: the Welcome Screen, Splash Screen, Create VoxLink Identity, and Login / Unlock are anonymous entry surfaces, and the remaining screens are reachable UI surfaces in a UI-only build with no real authentication backend. No differentiated permissions, roles, or visibility controls exist in this step.

Narrow exclusions. This step does not implement: Bluetooth or any radio discovery, networking of any kind, encryption, any database or persistence layer, any login or authentication backend, mesh routing, voice capture or playback, file selection or transfer, or actual emergency transmission. It also does not implement any account-management capability beyond the UI of the identity and unlock screens.

2a. Product Interpretation and Delivery Boundary

VoxLink is delivered as a first-party Flutter application for Android. In this step, the entire product is the interface: the app owns every screen, every transition, and every visual state. There is no provider-owned surface, no external destination, and no headless delivery in the current scope.

The delivery boundary is drawn deliberately. The interface presents the shape of offline communication — a connection status panel, a scanning ring, a push-to-talk dial, an SOS control, a serial-number-style VoxLink ID — but performs none of it. Where the interface shows devices, transfers, or signal strength, those values are demo data and are labelled as demo data in the interface itself. The Nearby screen states that scanning is not active; demo device rows carry a visible DEMO chip. Nothing in the UI claims a capability the build does not have.

Access in this step is anonymous throughout. The Welcome Screen, Splash Screen, Create VoxLink Identity, and Login / Unlock are entry surfaces with no access requirement. Because no login backend exists, the Login / Unlock screen presents its unlock UI without performing verification, and the Home, Chat, Nearby, Voice / Push-to-Talk, Files, Emergency / SOS, Profile, and Settings screens are reachable UI surfaces rather than protected destinations. Establishing real identity continuity, protected destinations, and session ownership is deferred to a later stage.

Future stages — real identity creation and unlock, Bluetooth discovery, mesh communication, encrypted messaging, voice transmission, file transfer, and emergency signalling — are explicitly out of scope here and are recorded in Section 11 as future requirements. They must not be implemented until the user says NEXT.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source; all product facts originate in the authoritative user requirement thread and the Planning Scope contract.

2c. Page Content and Component Coverage

The page inventory below is the closed, ordered page contract for this generation. Each page appears exactly once.

Splash Screen

• Information and state: VoxLink wordmark in Saira Condensed 700 at 56px on the #0C0E10 ground; a single amber hairline rule beneath the wordmark; no other content.
• Primary action: None. The screen is a timed brand moment that hands off automatically.
• Supporting actions: None.
• Domain entities: Brand identity (app name, wordmark).
• Component responsibilities: SplashScreen composes the wordmark and the amber hairline; a fade-in of the wordmark over 400ms and a left-to-right sweep of the hairline; a 250ms fade-through handoff to the Welcome Screen.
• States: Loading — wordmark fading in, hairline sweeping. Success — wordmark fully visible, handoff begins. Empty / Error / Recovery — not applicable; the splash has no data dependency and no failure mode in this step.

Welcome Screen

• Information and state: Full-bleed dark instrument face. A 420px tall concentric gauge occupies the upper two-thirds: outer tick ring, mid signal-arc ring, inner solid disc. The VoxLink wordmark sits inside the inner disc in Saira Condensed 700 at 52px. The tagline "Connect. Communicate. Offline." sits directly beneath the wordmark inside the dial, in Fira Sans 15px, tracked +0.04em, muted #7A8288. A 1px amber rule runs the full viewport width between the gauge and the buttons.
• Primary action: "Create VoxLink ID" — a solid amber #D9A24B block, 56px tall, black text, full width.
• Supporting actions: "I already have an account" — a 1px #2A2F34 outlined block, 56px tall, #ECEEF0 text, full width, stacked beneath the primary button.
• Domain entities: Brand identity; entry path selection.
• Component responsibilities: WelcomeGauge renders the tick ring, signal-arc ring, and inner disc, and animates a single slow amber sweep on entry that then holds at roughly 70% like a resting needle. PrimaryButton and SecondaryButton render the two entry actions. BrandTagline renders the tagline inside the dial.
• States: Loading — gauge sweep animating on entry. Success — gauge holds at rest, both buttons enabled. Empty — not applicable. Error / Recovery — not applicable; no data dependency in this step.

Create VoxLink Identity

• Information and state: Screen title "Create your VoxLink identity" in Saira Condensed 600, uppercase, tracked +0.06em, 26px. A Display Name text field. A VoxLink ID preview rendered in Saira Condensed 700 with tabular figures at 34px, letter-spaced like an engraved serial, in the VX-XXXX-XXXX format, with a hairline rule above and below it. A DEMO chip in 11px uppercase tracked amber-outlined text accompanies the previewed ID.
• Primary action: "Create Identity" — solid amber block, 56px tall, black text.
• Supporting actions: Editing the Display Name field, which updates the previewed identity presentation.
• Domain entities: Display Name; VoxLink ID (preview only, demo data).
• Component responsibilities: IdentityForm composes the title, the Display Name field, and the ID preview. VoxLinkIdBlock renders the ID typographic furniture — hairline rules above and below, tabular figures, and the DEMO chip. PrimaryButton renders the Create Identity action.
• States: Loading — not applicable in this step. Empty — Display Name field empty, ID preview showing the demo placeholder pattern. Success — Display Name populated, preview reflecting the entered name. Error — not applicable; no validation backend exists in this step. Recovery — not applicable.

Login / Unlock

• Information and state: Screen title in Saira Condensed 600, uppercase, tracked +0.06em, 26px. An unlock input surface for a returning user. A DEMO chip indicating that no real authentication backend is present.
• Primary action: An unlock action presented as a solid amber block, 56px tall, black text.
• Supporting actions: A return path to the Welcome Screen.
• Domain entities: Returning-user unlock intent (UI only).
• Component responsibilities: UnlockForm composes the title, the unlock input surface, and the unlock action. DemoChip marks the screen as demo-only. SecondaryButton renders the return path.
• States: Loading — not applicable. Empty — unlock input surface presented with no value. Success — not reachable in this step; no verification is performed. Error — not applicable; no verification backend exists. Recovery — the return path to the Welcome Screen.

Home

• Information and state: A stacked instrument panel. Greeting row reading "Hello, [Name]". The VoxLink ID rendered in Saira Condensed 700 with tabular figures at 34px in VX-XXXX-XXXX format, with hairline rules above and below and a small COPY ID action cut into the right end of the lower rule. A full-width connection status card at 28px radius showing the large state word OFFLINE, a 3-arc signal gauge, and NEARBY DEVICES 0 as a ruled data row. A 2-column grid of five function cards: Chat, Nearby, Voice, Files, and Emergency. Emergency spans both columns and is the only card carrying a red-orange #E4572E left rule. Bottom navigation with four items: Home, Chat, Nearby, Profile.
• Primary action: Tapping any function card navigates to its screen.
• Supporting actions: COPY ID on the VoxLink ID block; bottom-navigation tab selection.
• Domain entities: Display Name; VoxLink ID; connection status (Offline); nearby device count (0); function destinations.
• Component responsibilities: GreetingRow renders the greeting. VoxLinkIdBlock renders the ID with the COPY ID action. ConnectionStatusCard renders the state word, the 3-arc signal gauge, and the ruled NEARBY DEVICES 0 row, with a topographic contour texture at 6% opacity behind it. FunctionCard renders each of the five cards, with the Emergency variant carrying the red-orange left rule. BottomNavBar renders the four-item bar with a 2px amber indicator rail above the active item.
• States: Loading — not applicable. Empty — the connection status card shows OFFLINE and NEARBY DEVICES 0, which is the accepted resting state in this step. Success — the dashboard renders fully with all five function cards and the bottom navigation. Error — not applicable; no data dependency exists in this step. Recovery — not applicable.

Chat

• Information and state: Screen title in Saira Condensed 600, uppercase, tracked +0.06em, 26px. A search field. A realistic empty state reading "No conversations yet" with the supporting line "Find a nearby VoxLink user to start communicating." A DEMO chip indicating that no messaging backend is present.
• Primary action: "New Chat" button.
• Supporting actions: Typing into the search field.
• Domain entities: Conversation list (empty in this step); search query (UI only).
• Component responsibilities: SearchField renders the search input. EmptyState renders the "No conversations yet" headline and its supporting line. PrimaryButton renders the New Chat action. DemoChip marks the screen as demo-only.
• States: Loading — not applicable. Empty — the accepted and only content state: "No conversations yet" with the supporting line. Success — not reachable in this step; no messaging is implemented. Error — not applicable. Recovery — not applicable.

Nearby

• Information and state: Screen title "Nearby VoxLink" in Saira Condensed 600, uppercase, tracked +0.06em, 26px. A header line stating "Demo data — scanning not active". A scanning animation area built from two concentric arcs rotating continuously at 3s and 5s with opacity 0.5, plus a soft amber radial breathing at 4s. Nearby device cards presented as ruled rows: name and VoxLink ID on the left, a 5-bar signal column flush right, and a Connect pill. Every demo device row carries an amber-outlined DEMO chip in 11px uppercase tracked text.
• Primary action: "Connect" pill on each device row.
• Supporting actions: None beyond row interaction.
• Domain entities: Nearby device (name, VoxLink ID, signal strength) — demo data only; scanning state.
• Component responsibilities: ScanningRing renders the two concentric arcs and the amber radial breathing. DeviceRow renders name, VoxLink ID, the 5-bar signal column, and the Connect pill as a ruled row. SignalBars fills left-to-right in 90ms steps. DemoChip marks every demo row. DemoNotice renders the "Demo data — scanning not active" header line.
• States: Loading — the scanning ring rotates continuously, which is the accepted resting state in this step. Empty — the scanning area is shown with demo device rows present; the interface never claims these are real devices. Success — demo device rows render with name, ID, signal strength, and Connect. Error — not applicable; no discovery backend exists. Recovery — not applicable.

Voice / Push-to-Talk

• Information and state: Screen title in Saira Condensed 600, uppercase, tracked +0.06em, 26px. A fixed readout block above the dial. A single 176px PTT dial centred on the screen, built from concentric stroked circles with a 2px bezel line and a 6px tick band. A state legend below the dial listing the three states: Hold to Talk, Listening, Transmitting. A DEMO chip indicating that no voice capture or transmission is implemented.
• Primary action: Pressing and holding the PTT dial.
• Supporting actions: None.
• Domain entities: PTT state (Hold to Talk, Listening, Transmitting) — UI only.
• Component responsibilities: PttDial renders the 176px dial, scales it to 0.97 in 120ms on press, and lights a 3px amber ring. PttReadout renders the fixed readout block above the dial. PttStateLegend renders the three-state legend. DemoChip marks the screen as demo-only.
• States: Loading — not applicable. Empty — the dial rests in the Hold to Talk state. Success — pressing the dial transitions the presentation through Listening and Transmitting; the Transmitting state swaps the 3px ring to red-orange #E4572E with a 1.2s rotating arc. Error — not applicable; no capture or transmission backend exists. Recovery — releasing the dial returns the presentation to Hold to Talk.

Files

• Information and state: Screen title "Send Files" in Saira Condensed 600, uppercase, tracked +0.06em, 26px. A "Recent Transfers" section header. An empty state for recent transfers. A DEMO chip indicating that no file selection or transfer is implemented.
• Primary action: A send-files action presented as a solid amber block, 56px tall, black text.
• Supporting actions: None.
• Domain entities: Recent transfer (empty in this step); file selection intent (UI only).
• Component responsibilities: SectionHeader renders "Send Files" and "Recent Transfers". EmptyState renders the recent-transfers empty state. PrimaryButton renders the send-files action. DemoChip marks the screen as demo-only.
• States: Loading — not applicable. Empty — the accepted and only content state for Recent Transfers. Success — not reachable in this step; no transfer is implemented. Error — not applicable. Recovery — not applicable.

Emergency / SOS

• Information and state: Screen title in Saira Condensed 600, uppercase, tracked +0.06em, 26px. The text "Emergency communication" and "Send an SOS to nearby VoxLink devices." A 168px SOS dial built from concentric stroked circles with a 2px bezel line, a 6px tick band, and a hazard-tick bezel, carrying the red-orange #E4572E. This screen is the single exception in the system: it is the only screen permitted to use #E4572E. A DEMO chip indicating that no emergency transmission is implemented.
• Primary action: Pressing the large SOS button.
• Supporting actions: None.
• Domain entities: SOS intent (UI only).
• Component responsibilities: SosDial renders the 168px dial with the hazard-tick bezel in #E4572E. EmergencyCopy renders "Emergency communication" and "Send an SOS to nearby VoxLink devices." DemoChip marks the screen as demo-only.
• States: Loading — not applicable. Empty — the SOS dial rests in its idle presentation. Success — not reachable in this step; no transmission is implemented. Error — not applicable. Recovery — not applicable.

Profile

• Information and state: A profile photo placeholder rendered as a machined disc with the user's initials in Saira Condensed 700. Display name. VoxLink ID rendered in Saira Condensed 700 with tabular figures at 34px in VX-XXXX-XXXX format, with hairline rules above and below and a COPY ID action cut into the right end of the lower rule. A DEMO chip indicating that the profile is demo data.
• Primary action: "Edit Profile".
• Supporting actions: "Copy ID" button.
• Domain entities: Display name; VoxLink ID; profile photo placeholder.
• Component responsibilities: ProfileDisc renders the machined disc with initials. VoxLinkIdBlock renders the ID with the COPY ID action. PrimaryButton renders Edit Profile. DemoChip marks the profile as demo data.
• States: Loading — not applicable. Empty — the profile disc renders initials from the demo display name. Success — display name and VoxLink ID render fully. Error — not applicable. Recovery — not applicable.

Settings

• Information and state: Grouped ruled rows with uppercase section headers in Saira Condensed 600, tracked +0.06em, and a 1px #2A2F34 rule between groups. The groups are: Account, Security, Notifications, Appearance, Bluetooth, and About VoxLink. A DEMO chip indicating that no settings are persisted.
• Primary action: Tapping a settings row.
• Supporting actions: None.
• Domain entities: Settings group (Account, Security, Notifications, Appearance, Bluetooth, About VoxLink).
• Component responsibilities: SettingsGroup renders an uppercase section header and its ruled rows. SettingsRow renders a single row with a 1.5px stroke line icon, a label, and a trailing affordance. DemoChip marks the screen as demo-only.
• States: Loading — not applicable. Empty — not applicable; all six groups are always present. Success — all six groups render with their ruled rows. Error — not applicable. Recovery — not applicable.

3. Functional Requirements

Each requirement below is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Branded launch. As a VoxLink User, I should see a branded Splash Screen when the app launches, so that the product identity is established before any entry path is offered. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = app launch, observable result = VoxLink wordmark fades in over 400ms with a single amber hairline sweeping left-to-right beneath it, continuation = 250ms fade-through handoff to the Welcome Screen; failure/recovery = not applicable, no data dependency.)

FR-2 — Welcome entry. As a VoxLink User, I should see the VoxLink name, the tagline "Connect. Communicate. Offline.", and two entry buttons on the Welcome Screen, so that I can choose how to enter the app. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = arrival from Splash, observable result = the concentric gauge holds at rest with the wordmark and tagline inside the dial, and both "Create VoxLink ID" and "I already have an account" are presented as full-width 56px buttons; continuation = selecting either button; failure/recovery = not applicable.)

FR-3 — Create VoxLink identity. As a VoxLink User, I should be able to enter a Display Name and see a VoxLink ID preview with a Create Identity button, so that I can establish my identity presentation. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = selecting "Create VoxLink ID", observable result = the "Create your VoxLink identity" screen with a Display Name field, a VX-XXXX-XXXX ID preview in Saira Condensed 700 with tabular figures, and a Create Identity button; continuation = the identity presentation is established for the demo session; failure/recovery = not applicable, no validation backend exists in this step.)

FR-4 — Demo data separation on identity. As a VoxLink User, I should see that the identity preview uses sample/demo data, so that I am never misled into believing a real identity was created. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = viewing the identity preview, observable result = a DEMO chip in 11px uppercase tracked amber-outlined text accompanies the previewed ID; continuation = the user proceeds knowing the data is demo-only; failure/recovery = not applicable.)

FR-5 — Unlock presentation. As a VoxLink User, I should see an unlock UI when I indicate I already have an account, so that the returning-user path is represented. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = selecting "I already have an account", observable result = the Login / Unlock screen with an unlock input surface and an unlock action; continuation = the user can return to the Welcome Screen; failure/recovery = the return path to Welcome is always available; no verification is performed in this step.)

FR-6 — Home dashboard. As a VoxLink User, I should see a premium dashboard with my greeting, my VoxLink ID, a connection status card, and five function cards, so that I can orient myself and reach any part of the app. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = arriving at Home, observable result = "Hello, [Name]", the VoxLink ID in VX-XXXX-XXXX format, a connection status card showing OFFLINE and NEARBY DEVICES 0, and cards for Chat, Nearby, Voice, Files, and Emergency; continuation = selecting any card or bottom-navigation item; failure/recovery = not applicable.)

FR-7 — Bottom navigation. As a VoxLink User, I should see a four-item bottom navigation bar with Home, Chat, Nearby, and Profile, so that I can move between the primary destinations. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = selecting a bottom-navigation item, observable result = a 2px amber indicator rail slides between items in 180ms above the active item on a #16191C bar with a 1px top rule; continuation = the selected destination is displayed; failure/recovery = not applicable.)

FR-8 — Chat empty state. As a VoxLink User, I should see a realistic empty state on the Chat screen, so that I understand no conversations exist yet and how to start one. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = opening Chat, observable result = "No conversations yet" with the supporting line "Find a nearby VoxLink user to start communicating.", plus a search field and a New Chat button; continuation = the user can search or select New Chat; failure/recovery = not applicable; no actual messaging is implemented.)

FR-9 — Nearby discovery presentation. As a VoxLink User, I should see a discovery interface with a scanning animation area and nearby device cards, so that the discovery experience is represented. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = opening Nearby, observable result = "Nearby VoxLink" with two concentric arcs rotating at 3s and 5s, a soft amber radial breathing at 4s, and device cards showing Name, VoxLink ID, Signal strength, and a Connect button; continuation = the user can select Connect on a row; failure/recovery = not applicable; no real discovery is implemented.)

FR-10 — Demo device honesty. As a VoxLink User, I should see that nearby device rows are demo data and that scanning is not active, so that I am never told these are real devices. (provenance: explicit; lifecycle: initiator = VoxLink User, trigger = viewing the Nearby screen, observable result = the header states "Demo data — scanning not active" and every demo device row carries an amber-outlined DEMO chip in 11px uppercase tracked text; continuation = the user proceeds knowing the rows are demo-only; failure/recovery = not applicable.)