# Refrain Garden UX Architecture ## UX goal The interface must make one difficult truth feel obvious: every committed current remains active and combines with the new one. The board is always the visual priority. Decorative garden atmosphere lives behind the rules, never over cells, vectors, seeds, flowers, gates, or the four-beat preview. ## Screen Inventory - `SCR-ONBOARDING`: one real 3×4 board with a circle seed, circle flower, two anchors, and one valid short ribbon. A hand trace demonstrates press-and-drag once, then disappears. Preview positions stay visible before Commit. After the bloom, level two begins with an old numbered ribbon already present so the player sees it replay when drawing a new one. Skip and Accessibility are visible from the start; there is no carousel. - `SCR-HOME`: Refrain Garden mark, Continue, current bed and board, restored herbarium diorama, Bed Map, Settings, Legal, and an offline badge only when useful. `UI-UNLOCK` may appear as one quiet home card only after the first six boards; it cannot dominate or appear after failure. - `SCR-BED-SELECT`: five named beds in a vertical herbarium path: First Breath, Crosscurrent, Quiet Stone, Timed Petals, Full Chorus. Each bed contains six numbered boards with completion, up to three dew seals, current marker, and honest locks. No energy, countdown, streak, daily reward, or artificial scarcity. - `SCR-GAMEPLAY`: top safe-area status, four-beat timeline, complete fixed garden, enabled anchors, numbered committed ribbons, draft ribbon, seed/flower glyphs, vector composition, ribbon budget, rule hint, Commit/Cancel, Retry, and Pause. No UI crosses an anchor path or cell. - `SCR-PAUSE`: 68% indigo scrim over the frozen last stable board, with Resume, Restart, Settings, and Home. A draft is cancelled before opening; a preview may be preserved only if its state is deterministic and no resolution has begun. - `SCR-SUCCESS`: unobstructed final garden replay first, then a compact result sheet with blooms, ribbons used, optional dew seals, restored herbarium detail, Next as primary, Replay, and Home. Controls enable only after the replay or explicit Skip Animation. - `SCR-FAILURE`: frozen decisive beat, highlighted cells/entities, one plain rule such as “Circle and triangle tried to share row 4, column 3,” Retry as primary, Inspect Timeline, and Home. There is no purchase, ad, countdown, or shame language. - `SCR-SETTINGS`: music, night ambience, effects, haptics, tutorial replay, accessibility route, restore purchase when applicable, consent/data controls, support, legal, and reset progress behind confirmation. - `SCR-ACCESSIBILITY`: live preview for glyph labels, high contrast, reduced motion, 100/125/150% type, stepped timeline controls, haptics, screen-reader summaries, music, and effects. Every option is independent and Reset is reversible. - `SCR-LEGAL`: cached privacy, terms, credits, licenses, support, purchase/consent details, and last-updated labels. External links are clearly marked and failure leaves the cached local page available. ## State Inventory - `ST-FRESH`: every authored item is visible; no player ribbon exists unless the tutorial intentionally supplies an old numbered current. - `ST-DRAWING`: snapped candidate cells use a bright outline, direction chevrons, and valid/invalid endpoint state. Seeds never move while drawing. - `ST-PREVIEW`: the timeline exposes Start, 1, 2, 3, 4. Every seed has a projected trail, each block or gate shows its beat, collisions show both intents, and a fatal preview remains committable only with an explicit warning because preview fidelity is exact. - `ST-RESOLVING`: input locks for the deterministic four-beat playback. All seeds calculate intent together, move together, and settle together. Pause waits for the next stable snapshot except an OS interruption, which restores the prior stable state. - `ST-ACTIVE`: the new ribbon receives its chronological number, all previous ribbons remain, moved/bloomed seeds settle, and the next legal anchors reactivate. - `ST-PAUSED`: animation, audio beat, and input freeze; modal focus stays inside pause. - `ST-SUCCESS`: no seeds remain and every required bloom/order rule passed. - `ST-FAILURE`: the fatal beat and cause remain inspectable; retry reloads the exact authored fresh state. - `ST-ERROR`: local data, save, entitlement, or optional network failure is named honestly with Retry when useful and Return Home. A network failure never fabricates success or blocks owned offline play. - `ST-LOADING`: a non-interactive garden skeleton shown only while local board data decodes before entry. - `ST-DISABLED`: unavailable controls use opacity plus lock/slash shape and an explanatory label, never color alone. - `ST-INTERRUPTED`: draft cancels; resolving state restores its previous stable snapshot; the game returns paused. ## Transitions and Back Behavior First launch enters onboarding. Completing or skipping it goes home; the tutorial remains replayable. Returning launch goes home. Continue opens the current board in `ST-FRESH`; Bed Map opens `SCR-BED-SELECT`; selecting an unlocked board opens gameplay. A valid drag release opens `ST-PREVIEW`; Commit enters `ST-RESOLVING`; Cancel returns to the last stable active state. Resolution ends in active, success, or failure. Gameplay Pause or Android back opens pause. Back from pause resumes. Restart asks for confirmation only after a committed ribbon; Home saves the last stable state. Success Next loads the next board; failure Retry always loads the authored fresh board. Settings, accessibility, and legal push onto a simple stack and return to their caller. Back from home uses the native exit confirmation. Every overlay closes before a screen is popped. ## Overlays, Loading, and Errors `UI-MODAL` uses one title, one concise reason, one primary action, and no more than three secondary actions. It traps focus and returns focus to its opener. Opening any modal cancels `ST-DRAWING`. It never interrupts a beat midway. Levels decode before entering fresh state. Loading never overlays a board that appears playable. Optional analytics/cloud failures are silent except a small home status; entitlement uncertainty preserves already verified owned content and defers new access until verification. Corrupted level data quarantines that board and returns home. Save corruption restores the newest checksum-valid stable snapshot and says what could not be recovered. ## Orientation and Safe Areas Portrait is the only supported orientation. At 360×800, the top safe inset is `max(device inset, 16)`, status occupies approximately y=24–76, timeline y=76–124, garden y=132–636, and the lower action band y=648–784. At 430×932, the garden grows until cells reach 72 logical pixels; remaining height divides above and below it. Side insets are `max(device inset, 12)`. No camera crop, scroll, or hidden cell is allowed. Rotation while open preserves portrait and the same logical board mapping. Notches, dynamic islands, navigation bars, and home indicators only change the reserved safe inset. Decorative foliage may bleed under unsafe areas; text, controls, anchors, and board cells may not. ## Touch and Reachability All controls are at least 48×48 logical pixels with 8 pixels separation. Border anchors are at least 56×56 with a 12-pixel invisible inward extension. A drag begins only on an enabled anchor, snaps to orthogonally adjacent cells after a 10-pixel hysteresis threshold, and never relies on a system-edge swipe. Invalid self-repeat or endpoint state is shown immediately. Either thumb can draw; no gameplay uses pinch, long press, two-finger chords, tilt, or precise angles. Commit and Cancel remain in the lower thumb zone and cannot be triggered by releasing the path itself. Pause is bottom-right during play with a 56×56 target so the top safe area remains dedicated to status and timeline. Retry requires one tap after a resolved failure. ## Accessibility Matrix - `A-COLOR`: every seed and flower share a glyph and outline; ribbons carry chronological seals and chevrons; thorns have spikes/hatch; stones use solid weight; gates use aperture and beat numeral; all failure families have distinct symbols. - `A-MOTION`: four 100 ms stepped highlights replace flowing pulses, garden drift and bloom expansion are removed, and before/after states remain available. Nothing flashes more than three times per second. - `A-TEXT`: 100, 125, and 150% UI type. HUD may wrap but never cover the garden. Essential body and failure text is at least 17 logical pixels at 100%. - `A-HAPTIC`: optional independent patterns for snap, commit, bloom, thorn/edge, collision, order, and failure. Visual and text information remains complete when haptics are off. - `A-PREVIEW`: Start, 1, 2, 3, 4 buttons allow exact frame inspection without dragging the timeline. - Screen-reader focus follows heading → status → garden summary → anchors → timeline → primary action → secondary actions → navigation. Each cell exposes row, column, occupant, vector, target, gate schedule, and projected consequence. Accessibility is reachable before the first gesture and from Settings. Tutorial can skip and replay. Every modal returns focus to its opener. Reduced motion, high contrast, glyph labels, type size, haptics, screen reader summaries, music, and effects are independent so one assist never forces another. ## Visual-reference obligation The Art Bible must depict every screen above plus fresh, drawing, preview, resolving, active, paused, success, each failure family, error, loading, disabled, interrupted/recovery, high-contrast, large-text, and reduced-motion variants. Its first structural implementation board must explain the full gameplay flow and its final board must map every screen, HUD element, icon, entity, effect, state, safe area, and source reference. These boards are structural references; generated game imagery must follow Refrain Garden's own GDD-defined visual identity.