# State package review

**Review target:** `consolidated-state-package-01.html`  
**Scope:** 78 coded states in the project-scoped browser preview.  
**Review stage:** pre-approval. The package is a design proposal, not Flutter acceptance.

## Method

This pass uses the installed `design-critique`, `interaction-design`, `information-architecture`, `design-system`, `frontend-design`, `emil-design-eng`, and `unslop` guidance against `docs/DESIGN.md` and `MISSING-STATES-BRIEF.md`.

The review checks five things:

1. Does the first thing on screen match the listening job?
2. Does every state say what happened and what to do next?
3. Do related states use the same words, placement, and action order?
4. Does large text remain readable without hiding the dock?
5. Can the design become real Flutter behavior without inventing platform surfaces?

## Verdict

**Conditionally ready for one owner approval.** The representative direction is coherent and the package covers the missing state inventory. Do not port it into Flutter until the owner approves the complete package. The production Reader still needs the large-text composition change after approval.

## Overall impression

The package keeps the right attention order. Matter and the heard sentence lead. Controls follow. Settings and recovery stay quieter. The dark field is consistent, the copy is direct, and the local path stays visible when cloud or downloads fail.

The main risk is not the visual direction. It is state wiring. The package shows all states, but the final Flow source must connect every primary action and the Flutter implementation must prove those paths with real state changes.

## Usability

| Finding | Severity | Recommendation |
| --- | --- | --- |
| Large-text Reader is shown as a body-plus-dock composition. | Works | Keep the dock as a measured sibling. Never overlay it on the reading text. |
| Add text names paste, share, and unsupported imports separately. | Works | Keep this order. Paste is the fastest path. |
| Error states keep the text and provide a next action. | Works | Preserve this rule in every network, model, and report failure. |
| The 78 cards are navigable by group and state, but the cards do not yet play each action into the next state. | Moderate | Add a transition matrix and wire the highest-value actions in the canonical Flow before implementation. |
| `Not now` appears in model setup. | Moderate | Decide whether skipping setup is allowed when no installed voice exists. If it is allowed, the next screen must make the unavailable playback state explicit. |
| Premium details are clear, but purchase success/cancel/error need real entitlement outcomes in Flutter. | Moderate | Keep local fallback visible in every outcome and test entitlement changes without losing the current text. |

## Visual hierarchy

- **What draws the eye first:** the matter or the live sentence. This is correct for a listening companion.
- **Reading flow:** field, state title, live content, then control or recovery action. This matches the contract.
- **Emphasis:** live text is brighter than past and upcoming text. Error uses danger only for recovery. This is correct.
- **Large text:** the proposed Reader uses 26px copy, 1.38 line height, and a separate scroll viewport. This is the right direction for the mismatch the owner identified.

## Consistency

| Before | After | Why |
| --- | --- | --- |
| Production Reader treats large text as a size token inside the existing text display. | Reader body gets its own measured viewport and remains a sibling of the dock. | Increasing text must change wrapping and scroll length, not cause the dock to cover content. |
| Some production Reader layout paths still use legacy fixed dock reservations. | Ferrofluid Reader uses real Column measurement for body plus PlayerStrip. | A fixed overlay height cannot stay correct across 2× text, safe-area, and voice-row changes. |
| Flow and production had different text insets and paragraph treatment. | Use Flow’s 22px outer view inset, 2px inner reading inset, 20/26px scale, and 16px paragraph rhythm. | The visual reference and app need the same geometry, not just the same font number. |
| Error and empty states can become generic messages. | Every state has a named reason, a direct verb, and a recovery path. | Listening users should not have to interpret system language. |
| Platform surfaces can be imitated in a mockup. | Share sheet, notification, lock screen, and permission states are contracts only. | The OS owns those visuals; the app should validate titles/actions instead of faking them. |

## Accessibility

- The visual hierarchy supports high contrast: `live` and `ink` are reserved for primary reading, while `wake` and `quiet` carry secondary context.
- The Flow package needs final contrast measurement in the browser and Flutter, especially `quiet` text on `field` and `wake` text inside sheets.
- Every visible action needs a 48dp target in Flutter, even when the visual glyph is small.
- State changes need one screen-reader announcement, not duplicate banners plus live regions.
- Reduced motion must preserve order: matter, text, controls. It should remove blob pulse, sheet travel, and decorative fades.
- Large text must be checked at 2× with long titles, long paragraphs, sheets, and error copy. The reader must scroll; it must not clip or shrink the body to keep everything visible.

## Interaction and motion

| State change | Purpose | Direction |
| --- | --- | --- |
| Library → Reader | Preserve the selected text while changing context. | Short fade/translate; no delay before the first matter state. |
| Matter → first live sentence | Show that audio has started. | Gather, then reveal text, then settle chrome. |
| Reader → sheet | Keep the reader in place while focusing a choice. | Sheet rises from its bottom edge; backdrop is one layer. |
| Model/download progress | Show work and allow cancellation. | Determinate progress; never fake completion. |
| Retelling switch | Explain that wording changed while ideas remain. | Brief recast, then stable live sentence. |
| Error → retry | Confirm that the same task is being attempted again. | Button feedback only; no celebratory motion. |

Keep existing Flow timings unless a device probe proves they feel slow. Use custom ease-out/ease-in-out curves for new motion, keep routine feedback under 300ms, and make every long operation interruptible.

## Copy review

Works:

- `Paste`, `Continue`, `Download`, `Try again`, `Apply`, `Close`, `Clear`, and `Keep using local` are concrete.
- `Same ideas. Different wording.` explains retelling without calling it a summary.
- `Your text is safe.` is useful in model and destructive failures.
- `PDF or EPUB — Not available yet` is honest.

Keep watching:

- Use one term for the voice: `voice` in user-facing copy, `model` only when describing the download work.
- Use `cloud rewrite` consistently. Do not alternate between `cloud processing`, `hosted voices`, and `premium` without explaining the difference.
- Never add phone verification, account requirements, or payment language to local paths.

## What works well

- The package is organized by real user paths rather than by a component gallery.
- The large-text Reader directly addresses the important production mismatch.
- The failure states protect the user’s text and listening position.
- The premium states leave a local path visible.
- Unsupported platform/import features are named without pretending they work.

## Priority recommendations

1. **Approve or change the large-text Reader composition.** This is the main visual decision. Once approved, use it as the geometry contract for Flutter.
2. **Add the transition matrix to the canonical Flow source.** The browser package currently lets the reviewer inspect states, but the source must also prove the important actions between them.
3. **Resolve model setup bypass behavior.** Pick one rule for `Not now` when there is no installed voice, then use it in onboarding, Reader error, and voice download states.
4. **Run the accessibility pass on the approved package.** Measure contrast, 48dp targets, screen-reader order, 2× text, reduced motion, and one-announcement-per-state-change.
5. **Only then port the package into Flutter and compare seeded emulator states.**

## Owner feedback applied in preview 04

The first package made the Reader dock ambiguous. The revision follows the approved Flow meaning:

- The matter orb is the only playback control in the Reader dock. It now has a visible play or pause glyph and will map to `Play` / `Pause` semantics.
- The voice row is a voice picker. It no longer contains a second play-looking button.
- Voice preview lives inside the Voice sheet and is labeled `Preview voice`, changing to `Stop preview` while active.
- Paused and seeking do not add a banner above the reading text. The matter state and transport state carry that information without covering the passage.

This is a correction to the preview, not an app implementation yet. The same rule must be used in the canonical Flow source and Flutter dock.

## External skill candidates

No external skill was installed during this review. The current local skills are enough for this pass. If the owner wants additional review depth, the strongest candidates found were:

| Skill | Evidence | Use |
| --- | --- | --- |
| `alirezarezvani/claude-skills@a11y-audit` | 872 installs; source repo 25.1K stars, MIT, active | Accessibility audit of the approved mobile state set. |
| `kylezantos/design-motion-principles@design-motion-principles` | 8.6K installs; source repo 997 stars, MIT, active | Motion timing and transition review. |
| `community-access/accessibility-agents@mobile-accessibility` | 291 installs; source repo 403 stars, MIT, active | Mobile-specific accessibility cross-check. |
| `coreyhaines31/marketingskills@copy-editing` | 116.8K installs; source repo 46K stars, MIT, active | Copy editing, but it is marketing-oriented and is not needed for the core app review. |

The project already has a mechanical visual comparator, so I do not recommend adding another visual-regression skill yet.

## Addendum: superseded by revision 05

This review targeted `consolidated-state-package-01.html`. The fleet pass that followed produced five focused reviews and one synthesis; their corrections are applied in the tracked canonical artifact `docs/design/brand/consolidated-state-package-05.html` (previews 01–04 remain untouched history). Read `FLEET-SYNTHESIS.md` for the reconciled findings, the checks run against revision 05, and the open owner decisions D-1…D-8 before any Flutter port.