# Understand Design Contract

> Category: offline listening companion for difficult text.  
> Pitch: paste dense, archaic, technical, or foreign text and stay inside it while a chosen persona rewrites it for the ear.

**Status:** Drafted 2026-08-28 from the approved Ferrofluid direction and pinned Flow revision `30503a4`. The owner reviews changes to this contract through GitHub issue #192.

## 1. Visual Theme & Atmosphere

A low-luminance, dark field is the carrier medium: near-black space with sparse, deliberate energy. The emotional target is concentration and continuity for someone listening with hands or eyes elsewhere. Voice is the primary event; the screen joins only when the heard sentence earns attention.

Never use cream-paper/copper as the active redesign face, neon-on-void, radio or book cosplay, a flooding blob, decorative dashboards, or chrome that arrives before voice.

## 2. Color Palette & Roles

Use the pinned Flow roles:

- Field `#070806`: page and listening carrier.
- Field lift `#10110f`: quiet raised surfaces.
- Matter `#1a1510`: voice presence.
- Ink `#e7e1d4`: primary readable copy.
- Live `#f3ebd8`: heard sentence / active consequence.
- Wake `#9a9488`: spoken-behind copy and secondary controls.
- Quiet `#5c574e`: upcoming/meta copy.
- Line `#22211c`: hairlines and boundaries.
- Spike `#c4a574`: action/identity accent and matter edge.
- Danger `#c4785a`: destructive/error action only.

Accent roles are semantic: spike carries action/identity, live carries the current heard state, danger carries recovery/destruction. Do not add a second decorative accent.

## 3. Typography

Use the Flow reference’s Sora-like soft grotesk for reading, titles, and utility. Reading copy is large enough for read-along use (20px normal, 26px large in the Flow contract), with comfortable line height and clear word shapes. Titles and labels are sparse, tracked, and sentence case unless the Flow surface explicitly uses an uppercase eyebrow. Time/speed values use tabular numerals.

Weight changes are state signals: live is stronger than wake; upcoming stays quiet. Do not use display typography as decoration or make all copy equally loud.

## 4. Layout & Spacing

Library is the durable root; Reader is an entered listening surface, not a peer tab. The reading surface remains primary and scrollable. Use the Flow’s 22px horizontal phone inset, hairline separators, compact 10px dock rhythm, 16/22/28 sheet padding, and 20px top sheet radius.

One primary action per state. Sheets are focused, scrollable when necessary, and never stack duplicate backdrops. Preserve space for the dock rather than overlaying it on text.

## 5. Components

- **Field:** dark carrier, sparse hairlines, no fake instrument chrome.
- **Matter:** restrained voice-shaped presence; idle/gather/play/hold/end are stateful, never a mascot.
- **Live text:** one heard sentence owns the highest contrast; past text recedes but remains readable.
- **Cards/rows:** choice and memory surfaces with hairline borders, quiet metadata, and explicit secondary actions.
- **Buttons:** direct verbs, 48dp minimum touch target, visible pressed/focus state, no gratuitous fill.
- **Sheets:** `#0e0d0b`, hairline top, 20px top radius, 16/22/28 padding, tracked title, right-aligned pill actions.
- **Dialogs:** `#12110e`, 16px radius, 18/16/14 padding, direct Cancel + action pair; destructive actions use danger.

## 6. Motion & Interaction

Motion explains attention handoffs, not decoration:

| Handoff | Current Flow contract |
| --- | --- |
| View enter/exit | opacity/translate, about 420–450ms |
| Gather → synth | 520ms gather, then 900ms synthesis demo |
| Voice → chrome | 380ms after first live sentence in Flow; Flutter waits for real first voice then reveals |
| Sheet entrance | 350ms transform |
| Dialog entrance | 250ms opacity/scale |
| Matter morph | 450ms; continuous play pulse is restrained |

Capture start, intermediate, and settled frames for every motion state. Use transitions that can be interrupted; do not animate layout dimensions when opacity/transform is sufficient. Reduced motion preserves the order of introduction but removes ornamental movement and avoids retaining two competing semantics trees.

## 7. Iconography & Imagery

Prefer text glyphs and quiet line icons already specified by Flow. Matter is the only signature visual: voice made visible, subordinate to the live sentence when reading. Do not introduce bookshelves, open books, dials, VU meters, tubes, radios, mascot faces, or stock illustrations.

OS share sheets, notification controls, lock screens, and permission prompts are platform surfaces. Define their titles/actions and validate them; do not fake their native visuals in the app harness.

## 8. Voice & Tone

Name what the listener controls: paste, share, listen, retelling, original, voice, speed, contents, library. Use direct verbs: `Paste`, `Continue`, `Apply`, `Close`, `Retry`, `Clear`. Keep copy specific about what happens and whether text leaves the device.

Local listening and Local rewrite are the default and work offline after model readiness. Cloud is an explicit Premium choice. Never imply that a cloud account, phone verification, or payment is required for local hearing. Do not call a faithful rewrite a summary. New personas require owner approval in copy or UI.

## 9. Edge Cases & Variations

- Cold open: matter/gather first; text and full chrome arrive only after voice/ignite.
- Loading/error: explain the next action; preserve the saved session and original text where possible.
- Destructive actions: confirm, keep Cancel non-destructive, and provide retry/recovery for failures.
- Unsupported Contents/intake: say unavailable; never fabricate chapters or enable PDF/EPUB without a parser.
- Narrow, wide, 2× text scale, screen reader, and reduced motion are required variants.
- Empty Reader is secondary; Library owns primary intake and Continue.
- Wave 2 stubs (full editor, account/paywall depth) remain stubs until their Flow designs are added.
- The source-of-truth is the pinned Flow file in the active integration branch, not a stale copy in another dirty worktree.