# Understand missing-state design brief

**Status:** Draft for one consolidated owner review. This is a continuation of the approved Ferrofluid / dark-field direction, not a new brand exploration.

## Project and task

- **Project:** Understand mobile listening companion.
- **Task:** Design every state not represented by the pinned Flow harness, then port only the approved states into Flutter.
- **Source:** `docs/design/mocks/brand-proof/flow.html`, pinned at `30503a4` for the active integration branch.
- **Canonical browser artifact:** `docs/design/brand/consolidated-state-package-05.html` (git-tracked; supersedes the untracked previews 01–04). Fleet synthesis and open owner decisions: `docs/design/brand/FLEET-SYNTHESIS.md`.
- **Contract:** `docs/DESIGN.md`.

## Audience and psychological target

The listener is holding difficult text at a distance: dense, archaic, technical, or foreign material. The visual must make the successful state available immediately: voice is active, the sentence is findable, and the next action is obvious. The target is calm continuity, not feature discovery or screen engagement.

## One job of this package

Make every reachable state honest and recoverable while preserving the same attention order: voice/matter first, the heard sentence second, controls third, settings last.

## Dimensions

- **Palette:** Flow dark field, field lift, matter, live, wake, quiet, line, spike, and danger roles from `docs/DESIGN.md`.
- **Accent:** spike for action/identity; live for heard text; danger only for destructive/error recovery.
- **Typography:** Flow’s Sora-like grotesk; Reader 20px normal and 26px large, 1.38 line height, sentence hierarchy by live/wake/quiet.
- **Layout:** centered listening surface; editorial single-column reading; focused bottom sheets; no dashboard grid.
- **Density:** spacious in onboarding and Reader; balanced in sheets; dense only in model/download detail.
- **Mood:** low light, neutral-warm color temperature, restrained energy; the user should feel able to keep listening with the screen unattended.
- **Motion:** use existing Flow timings; every animated state gets start, intermediate, and settled captures. Reduced motion keeps order and removes ornamental movement.

## Missing state inventory

### Intake and first run

1. Empty Library with no saved sessions.
2. Empty Reader before text exists.
3. Add-text intake sheet.
4. Clipboard paste success.
5. Replace-open-text confirmation.
6. Share handoff / returned-from-share state.
7. Onboarding welcome.
8. Onboarding how-it-works.
9. Voice/model setup idle, downloading, verifying, ready, error, retry, and cancel.
10. First-use local rewrite disclosure and local-first explanation.

### Listening and Reader

11. Loaded original idle.
12. Cold open: gather, synth start, first live sentence, chrome settle.
13. Original paused, seeking, completed, and error.
14. Retelling loading, ready, disclosure, quota/premium gate, and retry.
15. Large-text Reader at 2× scale, including long paragraphs, live sentence, scroll, dock reservation, and accessibility semantics.
16. Voice selector: ready voice, preview playing, unavailable/download, download progress, verify, failure, retry.
17. Contents available, unavailable, current chapter, and close.
18. Overflow menu: edit stub, report, clear.
19. Report-output confirmation and failure recovery.
20. Listening-view / reply transition and back-to-Reader state. **Out of scope for this package** — reply listening is post-vc25; the boundary is recorded here and in the IA (fleet F-13).

### Settings, access, and destructive states

21. Settings default, large text, reduced motion, and unavailable account/premium stub.
22. Premium/cloud rewrite explanation, purchase/cancel/error, and local fallback.
23. Clear-current-text confirmation, cancel, success, and failure.
24. Delete-history confirmation, success, and failure.
25. Delete/downloaded-model confirmation, progress, success, and failure.
26. Native share sheet contract, notification/lock-screen contract, and permission-denied recovery.

## Large-text Reader decision

The current production Reader has the correct binary 20/26sp token values but does not yet match Flow as a composition. The approved direction for the comp is:

- Keep the Reader body and dock in one measured vertical layout; never paint the dock over the reading text.
- Give the text body its own scroll viewport with the Flow 22px outer inset and 2px inner reading inset.
- Preserve the sentence hierarchy at large size: live sentence in `live`, past in `wake`, upcoming in `quiet`.
- Use 26px text with 1.38 line height and 16px paragraph rhythm; large text changes wrapping and viewport length, not the hierarchy or control order.
- Keep the `Large text` badge above the passage, not inside or over the dock.
- Treat the dock as a measured sibling: retelling/original, retelling settings, voice, speed, buffer, transport, then safe-area padding.
- Keep one playback control in the Reader dock: the matter orb with a visible play/pause glyph. The voice row opens the voice picker; voice preview belongs inside that sheet and must not look like Reader playback.
- Do not add a paused or seeking banner above the passage. Use the matter and transport states instead.
- Validate at 412×915, wide, 2× text scale, screen reader, and reduced motion.

## Copy rules

Use direct verbs and truthful state labels: `Paste`, `Continue`, `Try again`, `Download`, `Apply`, `Close`, `Clear`, `Keep local`. Never require phone verification. Never imply that local listening or local rewrite requires an account, payment, or network.

## Anti-patterns

No warm-paper redesign face, fake radio controls, book/radio imagery, neon gradients, hidden failure, disabled primary action with no explanation, stacked scrims, overlaid dock, or large text that silently clips the active sentence.

## Output contract

- State fixtures separate **view** (`original` / `retelling`) from **playback** phase (`idle / gather / synth / playing / paused / seeking / completed / error`); segment selection binds to view, and mode changes apply on the next play (`pux-03`).
- First preview: representative coded screens for Reader large text, intake, onboarding, and model recovery.
- Final package: one browser preview with every state above, grouped by flow, with state IDs and action transitions.
- After owner approval: port the approved Flow states into Flutter, seed canonical fixtures, add golden/semantic tests, replay on emulator, and update issue #192.