diff --git a/docs/presentation/SCREEN_AND_STATE_MAP.md b/docs/presentation/SCREEN_AND_STATE_MAP.md index 5d14ff7a..cb050b87 100644 --- a/docs/presentation/SCREEN_AND_STATE_MAP.md +++ b/docs/presentation/SCREEN_AND_STATE_MAP.md @@ -1,359 +1,369 @@ # Aetherbound Guild: Screen And State Map -> Authority: complete player-facing navigation, screen purposes, major states, -> onboarding surfaces, and chapter-specific presentation coverage. +> Authority: complete player-facing landscape navigation, page purposes, +> interaction states, onboarding, return paths, and endgame presentation. > -> Stage: pre-production design. This document specifies presentation; it does -> not claim an implemented or human-understood interface. +> Product source: `.agent-taskgraph/spec.md` revision `design-spec-r3`. +> +> Stage: design-only. This document specifies intended presentation; it does +> not claim implemented behavior, device validation, or human comprehension. -## 1. Screen Contract +## 1. Experience Contract -The game uses a landscape `16:9` reference canvas at `1920x1080`. The minimum -supported design viewport is `1280x720`; the large reference is `2560x1440`. -Critical controls remain inside a `96 px` reference safe margin on every edge. -Extra-wide displays reveal more world at the sides and never stretch the HUD. +Aetherbound Guild is operated through a repeatable decision path: -Every player-facing state must answer these questions without opening another -page: +`review pressure -> inspect offers -> recruit or dismiss -> equip -> reorder the +party line -> choose risk -> observe automatic battle -> diagnose -> resolve +losses and rewards -> adapt` -1. Where am I? -2. What changed since the previous state? -3. What is the current pressure, cost, or opportunity? -4. What is the one next action the page recommends without forcing? -5. How do I inspect the rule and how do I leave safely? +Every player-facing screen answers six questions in its first viewport: -The interface is a game scene with docked instruments, not a dashboard of -floating cards. Full-screen locations, characters, routes, and battle actors -carry the fantasy. Panels attach to screen edges or physical in-world surfaces. -Only repeated inventory entries, modal confirmations, and comparison tools use -bounded cards. +1. Where am I in the run? +2. What changed since I arrived? +3. What decision is available now? +4. What does that decision cost or expose? +5. Can it be reversed? +6. Where will Back return me? -## 2. Global Shells +The interface presents one primary action per decision region. Inspection is +always reversible. Purchases, dismissal, risk commitment, retreat, reward +selection, recovery expenditure, and destructive data actions show a review +before they change authoritative state. -### 2.1 Guild Shell +## 2. Integration Bindings -The Guild is a full-bleed, evolving illustrated yard. Restored services occupy -physical locations and animate when active. A shallow top status rail shows the -current chapter objective, Crowns, selected company readiness, and save state. -A bottom destination dock contains five persistent destinations: +Presentation uses named bindings for values and rules owned by the product or +content workstreams. A binding is displayed only after its source resolves; the +UI must not substitute a guessed number, price, formula, or probability. -`Yard | Company | Workshop | Records | World Map` +| Binding | Presentation use | Owning authority | Unresolved design state | +|---|---|---|---| +| `BIND:RUN_PHASE` | current loop step and legal destinations | core systems | named phase plus `Rules pending integration` in design fixtures | +| `BIND:DIFFICULTY_RULES` | run setup options, consequences, and postgame compatibility | difficulty/core systems | Begin remains disabled until resolved | +| `BIND:RUN_RESOURCES` | balances, deltas, affordability | economy | label and non-numeric placeholder | +| `BIND:SHOP_OFFERS` | available recruit and item offers | shop/content | structurally complete sample rows with no authoritative values | +| `BIND:SHOP_REFRESH` | refresh cost, limit, result policy | economy/shop | disabled action with binding name | +| `BIND:RECRUIT_TRANSACTION` | price, capacity effect, receipt | recruitment/economy | review skeleton with no commit | +| `BIND:DISMISSAL_OUTCOME` | retained, returned, or lost value | recruitment/economy | consequence field marked unresolved | +| `BIND:RECRUIT_SCHEMA` | name, profession, trait, attributes, equipment, level, history | content/core systems | field labels remain; missing fields show `Pending` | +| `BIND:EQUIPMENT_RULES` | slots, eligibility, conflicts, equip result | equipment/content | incompatible reason requires source data | +| `BIND:ARTIFACT_RULES` | active shared modifiers, acquisition, conflicts, and lifecycle | artifacts/core systems | ledger remains read-only until resolved | +| `BIND:PARTY_CAPACITY` | current simultaneous deployment and growth | progression/simulation | count area displays binding, never a guessed cap | +| `BIND:PARTY_ORDER_EFFECTS` | exposure, reach, protection, movement, replacement | battle/core systems | preview lists only sourced effects | +| `BIND:RISK_OPTIONS` | risk choices, entry costs, known outcomes | run/economy | choice remains unavailable until resolved | +| `BIND:BATTLE_SNAPSHOT` | actors, time, events, health, status, targets | deterministic battle | battle mock state is labeled non-authoritative | +| `BIND:BATTLE_SPEEDS` | available playback speeds and restrictions | battle/accessibility | control renders from supplied options | +| `BIND:RETREAT_OUTCOME` | timing, losses, retained state | failure/economy | review cannot commit while unresolved | +| `BIND:CASUALTY_OUTCOME` | death, survival, replacement, inventory handling | failure/recruitment | consequence list waits for receipt | +| `BIND:RESULT_CAUSALITY` | first collapse and downstream effects | battle validator | `Cause unavailable` is an error, not an empty success | +| `BIND:REWARD_OPTIONS` | choices, eligibility, claim receipt | reward/content | no generic fallback reward | +| `BIND:RECOVERY_OPTIONS` | legal recovery paths, costs, consequences | recovery/economy | disabled path explains missing rule source | +| `BIND:RUN_FAILURE` | run-ending condition and retained progression | failure/save | summary waits for authoritative transaction | +| `BIND:PROGRESSION` | unlocks, prerequisites, receipts | progression/content | unknown future nodes stay undisclosed | +| `BIND:POSTGAME` | postgame rules, eligibility, modifiers | difficulty/postgame | entry remains locked with sourced requirement | +| `BIND:SAVE_STATE` | slot health, resume point, migration, conflict | save | safe recovery path only | -The current destination is shown by a raised metal-and-cloth tab plus a text -label. Settings is a gear icon in the top-right safe area and is never hidden in -a destination overflow menu. +Binding failure is a presentation error with a safe exit. It never silently +turns into zero cost, no consequence, a default target, or a successful claim. -### 2.2 Expedition Shell +## 3. Navigation And Shells -The route fills the world surface. A left edge expedition strip shows company, -Supplies, Strain, and Command preparation. A right edge Cache strap shows -secured and unsecured value. The lower band contains the selected node's -threat/reward comparison and one primary commit action. Route nodes never look -like generic circles: each is a miniature place silhouette with a type marker. - -### 2.3 Battle Shell - -The battlefield occupies at least 68% of the reference frame. Six allied slots -sit in the left/lower half and enemy lanes in the right/upper half. HUD elements -attach to actors, lanes, or screen edges; they do not form a wall over the -action. At 1x speed, the visual priority is: - -1. next major enemy telegraph and affected lane; -2. allied unit at greatest immediate risk; -3. legal Directive and remaining Command charges. - -Pause, speed, event log, settings, Cache risk, and retreat remain available in -the safe area without competing with the three priority reads. - -### 2.4 Overlay Stack - -Overlays darken but do not blur the underlying state. Only the top overlay owns -input. Back/cancel closes one layer and restores prior focus. The stack order is: - -`base screen -> inspect drawer -> selection overlay -> review -> confirmation` - -No confirmation opens another confirmation. Destructive confirmation uses the -full effect statement, stable target name, and a hold or second explicit input; -cancel receives default focus. - -## 3. Complete Navigation Tree +### 3.1 Global Navigation ```text Boot -|- Accessibility primer (first launch) -|- Language and safe-area calibration (first launch) +|- First-launch setup `- Title - |- Continue -> Returning recap or current safe state - |- Campaign slots -> New campaign / slot actions - |- Second Weave -> Postgame slot selection - |- Records -> profile completion overview + |- Continue -> Resume review -> last safe state + |- Run ledger -> New run / Open run / Save recovery + |- Records + |- Postgame (when eligible) `- Settings / Credits / Licenses -Guild Yard -|- Company -| |- Roster -> Adventurer detail -> Profession / Skills / Equipment -| |- Formation workshop -> Company validation -| `- Presets / Reserves / Standing orders -|- Workshop -| |- Forge / Upgrade / Salvage -| |- Clinic / Strain recovery -| `- Service restoration / facility detail -|- Records -| |- Bestiary / Items / Professions / Characters -| |- Achievements / Collections / Guild history -| `- Tutorial and glossary archive -`- World Map - |- Chapter overview -> settlement -> expedition briefing - `- Second Weave laws and mastery hunts - -Expedition -|- Route graph -> node preview -> commit -|- Encounter preview -> company adjustment -> battle -|- Noncombat decision / camp / recruit / mastery trial -|- Reward draft -> Cache decision -|- Anchor -> bank / recovery / standing-order update -`- Withdrawal / defeat recovery -> Anchor or Guild +Guild desk +|- Forecast +|- Shop -> Offer detail -> Recruit review / Item review +|- Roster -> Recruit detail -> Dismissal review +|- Equipment -> Item comparison +|- Party line -> Readiness review +|- Active artifacts / Progression / Records +`- Risk board -> Risk review -> Battle opening Battle -|- Live battle -> telegraph/status/event inspect -|- Directive selection -> targeting -> review -> commit -|- Pause -> battle options / controls / retreat review -|- Victory -> diagnosis -> reward -`- Defeat -> cause -> loss review -> recovery choice +|- Live automatic battle -> Inspect +|- Pause and speed -> Settings / Retreat review +|- Background or suspend -> Resume review +`- Result diagnosis + |- Casualty resolution (when required) + |- Reward choice (when earned) + |- Recovery (when required) + |- Run end summary (when ended) + `- Guild desk / next risk choice + +Postgame +|- Rules review -> New postgame run +|- Challenges and records +`- Postgame result -> Postgame hub ``` -## 4. Screen Inventory +### 3.2 Shell Responsibilities -### 4.1 Boot, Title, And Campaign - -| ID | Screen | Three-second focal order | Primary action | Required variants and exit | -|---|---|---|---|---| -| `SYS-001` | Boot and studio marks | animated Waylamp line, product mark, loading state | none | first load, shader/content migration progress, recoverable load error; proceeds automatically | -| `SYS-002` | Accessibility primer | text size preview, contrast example, Continue | Apply recommended preset | 100/115/130%, reduced motion/flashes, captions; back is disabled only before a legal preset exists | -| `SYS-003` | Language and safe-area calibration | language pair, corner markers, Continue | Confirm language and safe area | English, zh_CN, controller overscan; can reopen later from Display settings | -| `SYS-004` | Title | working guild above a ruptured route, Continue, current slot summary | Continue | no save, resumable battle, postgame unlocked, offline service warning; Settings and slot select remain visible | -| `SYS-005` | Campaign slots | three named slot ledgers, last location, play time | Open selected slot | empty, healthy, recovered backup, migration required, conflict, deleted-in-trash; back to Title | -| `SYS-006` | New campaign setup | difficulty consequence comparison, accessibility inheritance, Begin | Begin Wayfinder campaign | difficulty review, slot overwrite review, seed disclosure; no character creator or randomized roster | -| `SYS-007` | Returning recap | illustrated last events, unresolved objective, one suggested inspection | Resume | 1-7 days, 8-30 days, 30+ days, post-failure, post-restoration; skip to safe state | -| `SYS-008` | Save recovery | valid lineage, exact lost interval, recovery options | Load recommended valid commit | corrupt active, all snapshots corrupt, migration fallback, cloud conflict; export diagnostics and return to slots | -| `SYS-009` | Profile completion | campaign, mastery, collection, challenge completion rings | Open incomplete category | first campaign, completed, 100% state; back to Title or Records | -| `SYS-010` | Credits, licenses, and data use | credits chapters, licenses, privacy/offline statement | Open section | text search, external link confirmation; back to Title | - -### 4.2 Guild And Company - -| ID | Screen | Three-second focal order | Primary action | Required variants and exit | -|---|---|---|---|---| -| `GLD-001` | Guild Yard | current objective in world, active service, ready company | Open World Map | chapter 1 broken yard through eight restoration states; idle, returning, facility alert, chapter complete | -| `GLD-002` | Objective board | next anchor objective, two optional goals, known consequence | Track objective | no optional goals, completed, blocked by route, postgame; close to Yard | -| `GLD-003` | Roster | six selected members, readiness issues, available recruits | Inspect adventurer | 30 owned, filtered, injured, no valid deployable, new recruit, 130% text; back to Company | -| `GLD-004` | Adventurer detail | full-body adventurer, current profession/talent, readiness | Edit loadout | recruited, locked silhouette with known route, three Strain, relationship scene ready, max mastery | -| `GLD-005` | Formation workshop | six-slot Weave Grid, predicted protection/targets, validation | Confirm company | empty slot, invalid role, reserves, drag and tap-select paths, compare preset, tutorial highlight | -| `GLD-006` | Company presets | named formation preview, legal differences, save/overwrite action | Apply preset | empty, invalid after content change, current, six saved presets; overwrite/delete review | -| `GLD-007` | Profession assignment | character silhouette, base/advanced tree, combat role preview | Assign profession | locked, mastery-ready, branch choice, respec, no compatible advanced branch; cancel preserves loadout | -| `GLD-008` | Skill loadout | four skill slots, timeline effect preview, point budget | Confirm skills | empty slot, over budget, invalid combination, refund, maxed, large text scroll | -| `GLD-009` | Equipment loadout | equipped silhouette layers, exact behavior delta, inventory candidates | Equip selected item | no item, unique-group dormant, comparison, attunement, locked route, salvage-protected | -| `GLD-010` | Standing orders | event-condition-action row, exception preview, mastery eligibility | Save order | no mastery, invalid condition, overlapping rules, disabled, training preview; back to Company | -| `GLD-011` | Recruit review | named character, motive and field proof, company impact | Recruit | roster full is not a blocker because reserves are persistent; decline defers, never deletes recruit | -| `GLD-012` | Relationship scene index | two-character scene illustration, unresolved relationship, reward type | Play scene | locked reason, ready, seen, consent-sensitive skip summary; back to Adventurer or Records | -| `GLD-013` | Guild history | chronological illustrated repair line, current consequence | Inspect event | empty first launch, filtered character/region, ending; back to Records | - -### 4.3 Workshop And Services - -| ID | Screen | Three-second focal order | Primary action | Required variants and exit | -|---|---|---|---|---| -| `WRK-001` | Workshop floor | working forge, selected recipe family, material shortage/surplus | Open Forge | broken, basic, selected chapter restoration, postgame; back to Yard | -| `WRK-002` | Forge and craft | output item, exact budget/effect, ingredient change | Craft one | affordable, insufficient, deterministic counter-item fallback, duplicate, inventory cap policy | -| `WRK-003` | Upgrade | before/after item, behavior preserved/changed, exact cost | Upgrade | at cap, chapter lock, insufficient, equipped item, unique behavior boundary | -| `WRK-004` | Salvage review | item to lose, returned materials, affected presets | Confirm salvage | locked/favorite/equipped/protected, bulk selection, no eligible items; destructive second confirm | -| `WRK-005` | Clinic | injured adventurers in scene, Strain, available recovery | Recover selected unit | no Strain, insufficient Supply only at Anchor, full Guild recovery, story scene ready | -| `WRK-006` | Service restoration | two physical service futures, world/economy consequences, preview | Choose restoration | eight chapter-specific decisions, consequence comparison, confirmation, completed permanent state | -| `WRK-007` | Facility detail | facility process animation, current capability, next unlock | Use service | locked, newly restored, upgrade-ready, fully complete; back to Yard | -| `WRK-008` | Training hall | fixed threat, selected counter hypothesis, no-reward label | Start training | tutorial, same-seed replay, custom formation, invalid company, completed analysis | - -### 4.4 Records And Collections - -| ID | Screen | Three-second focal order | Primary action | Required variants and exit | -|---|---|---|---|---| -| `REC-001` | Records atrium | illustrated category shelves, newest discovery, completion | Open category | first discovery, all complete, filtered; back to Yard | -| `REC-002` | Bestiary | enemy illustration/silhouette, known mechanic, counter evidence | Inspect identity | unseen, observed, researched, mastered, variant, boss; chapter/filter/search states | -| `REC-003` | Item catalog | item illustration, owned count, behavior summary | Inspect item | unknown source, known-unowned, owned, upgraded, attuned, collection-linked | -| `REC-004` | Profession atlas | 12-base radial branches, selected role, mastery proof | Inspect profession | locked advanced, eligible, mastered, character compatibility, comparison | -| `REC-005` | Character archive | 30 portrait ledger, selected arc state, relationship links | Inspect character | unknown, recruitable, recruited, arc complete, ending state | -| `REC-006` | Achievement ledger | achievement artwork, exact requirement progress, reward | Inspect achievement | hidden only when discovery is the mechanic; incomplete, claim-ready, complete, platform sync pending | -| `REC-007` | Collection room | physical collection display, missing evidence, regional consequence | Inspect collection | empty plinth, partial, complete, Second Weave variation | -| `REC-008` | Tutorials and glossary | current topic illustration, plain-language rule, replay link | Replay example | never seen, newly unlocked, completed, returning recommendation, search/no result | -| `REC-009` | Battle reports archive | encounter scene strip, first failure point, build snapshot | Open report | victory, defeat, retreat, training, missing old ruleset; compare two reports | - -### 4.5 World, Chapter, And Expedition - -| ID | Screen | Three-second focal order | Primary action | Required variants and exit | -|---|---|---|---|---| -| `WLD-001` | Concordance world map | active rupture, current settlement, chapter route | Enter chapter | chapter locked, available, active, restored, postgame remix; back to Yard | -| `WLD-002` | Chapter overview | settlement key art, learning goal, persistent choice | View expedition | new, in progress, confrontation ready, restored, unresolved objective, Reweave | -| `WLD-003` | Settlement hub | local service at risk, named contact, route exits | Open route board | chapter-specific before/after repair, optional scene, recruit ready | -| `EXP-001` | Expedition briefing | route objective, company readiness, difficulty losses | Begin expedition | invalid company, no counter tag, safe warning, resumed expedition, Reweave law | -| `EXP-002` | Route graph | next forks, route pressure, Cache/Supplies | Inspect node | hidden, forecasted, selected, completed, closed, reroute path, boss approach | -| `EXP-003` | Node comparison | two node scenes, threat/counter, reward/cache delta | Commit node | safe/elite/camp/story/recruit/mastery/boss, unknown bounded reward, inaccessible reason | -| `EXP-004` | Encounter preview | enemy formation, major telegraphs, projected first targets | Prepare company | ordinary, elite, sub-boss, boss, researched variant, surprise clause with legal preview | -| `EXP-005` | Between-node company | formation, health/Strain, reserve and limited changes | Continue | reserve swap, one free change, extra change costing Supply, no legal unit | -| `EXP-006` | Camp | recovery candidates, Supply cost, next pressure | Commit camp action | heal, clear Strain, field craft, relationship, leave unused; exact opportunity cost | -| `EXP-007` | Noncombat decision | illustrated situation, two or three consequences, affected records | Choose reviewed option | insufficient condition, defer, irreversible chapter flag, accessibility summary | -| `EXP-008` | Reward draft | three authored rewards, build interaction, Cache exposure | Accept reward | bad-luck guarantee, deterministic counter item, no inventory space policy, skip for Crowns | -| `EXP-009` | Cache management | unsecured physical satchel, exact risk lines, Anchor distance | Secure or continue | empty, mixed splittable/indivisible, difficulty preview, loss example, post-battle update | -| `EXP-010` | Anchor | banked reward transfer, persistent route state, three next plans | Commit next plan | bank, recover, update order, withdraw, chapter confrontation, corrupted save blocked | -| `EXP-011` | Withdrawal review | bank/discard comparison, Supply conversion, route consequence | Confirm withdrawal | three difficulty contracts, noncombat only, cancel, operation retry receipt | -| `EXP-012` | Chapter confrontation | boss scene, learned mechanics checklist, consequence allies | Begin confrontation | not ready, ready, alternate ally support, Reweave clauses | - -### 4.6 Battle, Result, And Recovery - -| ID | Screen | Three-second focal order | Primary action | Required variants and exit | -|---|---|---|---|---| -| `BAT-001` | Battle opening | lane matchup, first telegraph, greatest-risk ally | Start or inspect | 1x tutorial lock, normal, boss phase intro, resumed snapshot | -| `BAT-002` | Live battle | next telegraph, threatened ally, Directive state | Inspect or intervene | calm, busy, Break, Downed, Rescue Window, Fracture Clock, boss phase, low-power | -| `BAT-003` | Telegraph inspect | affected lane/targets, countdown, plain cause/counters | Close and act | known, partially researched, variant, non-counterable but mitigable; pauses at allowed speeds | -| `BAT-004` | Status and unit inspect | selected actor, current event timeline, exact derived values | Pin event or close | ally/enemy/device/decoy, hidden value explanation, screen-reader linear version | -| `BAT-005` | Directive selection | two prepared Directives, legal states, Command cost | Select Directive | zero charge, illegal target, cooldown/window, mastered standing-order interaction | -| `BAT-006` | Directive targeting | legal target/lane, outcome preview, cancel | Review target | tap-select and controller focus, no legal target, target changes before commit | -| `BAT-007` | Directive review | exact event insertion, one charge cost, changed forecast | Confirm Directive | duplicate confirm receipt, stale target rejection, cancel spends nothing | -| `BAT-008` | Battle event log | chronological icon/text rows, selected cause chain, jump-to-event | Inspect event | current, paused, post-battle, filtered actor/type, captions, 130% text | -| `BAT-009` | Battle pause | battlefield frozen, resume, current objective | Resume | settings overlay, controls, event log, retreat review; no hidden simulation progress | -| `BAT-010` | Retreat review | channel time, expected Cache/Supply/Strain transaction, risk | Start retreat channel | unavailable, interrupted, completed, difficulty variants, cancel before commit | -| `RES-001` | Victory tableau | surviving company, decisive rule, reward path | View diagnosis | ordinary, elite, boss, no Downed, rescued, challenge complete | -| `RES-002` | Battle diagnosis | predicted vs actual timeline, first divergence, counter options | Continue to reward | victory lesson, defeat cause, standing-order exception, no actionable error | -| `RES-003` | Defeat transaction | exact lost Cache lines, Strain/Supplies changes, cause | Accept committed result | three difficulties, operation retry receipt, all cache lost, no cache | -| `RES-004` | Recovery choice | first preventable event, three legal paths, retained state | Reconfigure at Anchor | train same seed, end at Guild, no Anchor fallback; never paid continue | -| `RES-005` | Chapter restoration result | transformed location, chosen service, new capability | Return to Guild | eight chapter-specific transformations, delayed consequence, Reweave change | -| `RES-006` | Campaign ending | working federation panorama, character outcomes, completion | Enter epilogue records | choice-reactive panels, credits, Second Weave offer, continue completed world | -| `RES-007` | Second Weave setup | carried accord, selectable law, visible changed route | Begin new weave | locked requirements, law conflict, difficulty review, completed challenge state | - -### 4.7 Settings And Diagnostics - -| ID | Screen | Three-second focal order | Primary action | Required variants and exit | -|---|---|---|---|---| -| `SET-001` | Settings index | categories, changed-value indicator, Reset category | Open category | title/guild/battle entry, unsaved input remap, safe defaults | -| `SET-002` | Display | UI scale preview, safe area, contrast | Apply display settings | 100/115/130%, high contrast, color cues, brightness, window/display modes | -| `SET-003` | Motion and effects | live sample, reduced motion/flashes, camera/hit stop | Apply effects | low power, particle density, shake 0-100%, photosensitivity preset | -| `SET-004` | Audio | master/music/ambience/voice/SFX sliders, live test | Apply audio | mute, output change, subtitles/captions, dynamic range, mono compatibility | -| `SET-005` | Controls | current device map, focus path sample, conflicts | Save mapping | touch options, mouse/keyboard, controller, hold timing, reset, disconnect | -| `SET-006` | Language and text | language preview, glossary sample, subtitle size | Apply language | English, zh_CN, 130%, dyslexia-friendly spacing option, pseudolocale developer-only | -| `SET-007` | Gameplay assists | pause behavior, speed defaults, forecast detail | Apply assists | no result-changing assist hidden as accessibility; changes explain scope | -| `SET-008` | Save and cloud | local commit health, cloud state, export | Manage save | offline, sync, divergence, conflict, backup recovered, diagnostics export | -| `SET-009` | Data and reset | exact scope summary, recoverable trash policy | Open review | campaign delete, profile reset, local diagnostics clear; destructive flow only | -| `SET-010` | Diagnostics | build/ruleset IDs, event/export summaries, copy action | Export diagnostic | redacted by default, no credentials, export success/failure | - -## 5. Chapter-Specific Visual Screen Families - -Each chapter requires at least three independently composed full-screen scenes. -They share HUD geometry but not background composition, palette, primary prop, -weather, route material, or boss silhouette. - -| Chapter | `A` Route/settlement scene | `B` representative battlefield | `C` restoration/choice scene | +| Shell | Persistent information | Primary surface | Persistent exits | |---|---|---|---| -| `CHV-01A/B/C` First Light, Broken Bell | Windmill basin and silent bell wave crossing farm pumps | Bright grass terraces, three wind lanes, armored scavengers bracing against dark wavefront | Clinic lamps or warning towers receive the recovered bell pulse; chosen service begins moving in Guild Yard | -| `CHV-02A/B/C` Voices in Glass | Flooded reed channels carrying visible voice ribbons toward ferry platforms | Translucent reed walls, rising water bands, delayed burst markers, recital-engine silhouette | Three ferry assemblies compare testimony; governance choice physically redirects clean water | -| `CHV-03A/B/C` The Heat We Owe | Furnace district split between mint pipes and worker heat lines | Vertical smelter lift, pressure gates, alternating hot/cool bands, ledger constructs | Foundry charter table between labor furnace and mint conduit; selected network gains stable flame | -| `CHV-04A/B/C` Leaves That Disagree | Living archive canopy with two incompatible charters growing as branches | Ink-leaf platforms where repeated action glyphs are visibly redacted | Canopy court preserves annotated disagreement or prunes a branch; the archive silhouette permanently changes | -| `CHV-05A/B/C` Two Tides, One Name | Moon-tide harbor with real and mirrored manifests traveling on separate piers | Reflective reef lanes with offset doubles, identity rim patterns, rescue beacons | Customs desk and rescue tower face the same manifest wall; chosen priority changes which lights answer | -| `CHV-06A/B/C` A Crown Made of Weather | Four floating wards orbiting the storm's calm eye | Layered aerial bridges, readable gust arrows, selective anchors, parallax rotation | Public weather mechanism is handed to central or rotating stewardship; ward paths visibly reorganize | -| `CHV-07A/B/C` The Market Beneath Names | Descending market ring with deliberately blank registry fields paired with living owners | Intimate lantern platforms, false-safe telegraphs, memory-map cords, relational tells | Anonymous maintainers decide reveal/protection at a circular registry; no person is rendered as an erased silhouette | -| `CHV-08A/B/C` A Concord of Many | Seven consequence rooms converging on the First Junction | Multi-region battlefield where three linked telegraphs require visibly different roles | Public plural charter is woven from eight region materials; final guild remains a working repair yard, not a throne | +| Title | active language, accessibility shortcut, save health | illustrated guild threshold and current run summary | Settings, run ledger, credits | +| Guild | run phase, sourced resources, save state | current preparation decision | Shop, roster, equipment, party line, risk board | +| Battle | objective, playback state, greatest current danger | actors and event projections | Inspect, pause; retreat only through review | +| Result | outcome, earliest causal event, unresolved transactions | causal timeline and affected recruits | next required resolution only | +| Records | filter, discovery state, selected entry | readable catalog or history | previous safe screen | +| Settings | changed values and current category | live preview or setting rows | Apply/Discard and exact caller | -Every `A` scene appears in `WLD-002` and `WLD-003`, every `B` scene supports -`EXP-004`, `BAT-001`, and `BAT-002`, and every `C` scene supports `WRK-006` and -`RES-005`. Boss confrontations add a unique boss layer to the chapter's `B` -scene rather than replacing it with an unrelated arena. +Back closes only the top overlay. From a base screen it returns to the named +parent in the inventory below. Back never commits, claims, purchases, equips, +reorders, dismisses, retreats, or starts a battle. -## 6. Common Component States +### 3.3 Overlay Order -Every actionable component implements the same semantic states. A screen cannot -invent a sixth meaning for disabled or selected. +Only the top layer owns input: -| State | Visual and text contract | Input result | -|---|---|---| -| Available | full silhouette, action verb, cost/effect visible | opens review or commits only when no review is required | -| Selected | physical raised edge, high-contrast outline, check marker | second input opens detail or confirms according to screen contract | -| Active | moving state marker and explicit `Active` label | does not restart or spend again | -| Unaffordable | required value and current shortfall shown | inspect remains legal; commit disabled with reason | -| Locked | named requirement and where it can be fulfilled | inspect requirement; never silent tap | -| Temporarily unavailable | reason plus event/time that restores it | inspect reason; no success feedback | -| Complete | final result and next consequence shown | opens result/history; does not claim again | -| Claimed | receipt/check marker and granted result | returns original receipt on duplicate input | -| Recoverable error | plain cause, safe retained state, Retry/Alternate | retry receives new attempt identity where required | -| Blocked | external or integrity boundary and safe exit | cannot proceed; export diagnostics when relevant | +`base screen -> inspect drawer -> selection surface -> transaction review -> +confirmation` -## 7. Loading, Empty, Error, And Interruption States +A confirmation may not open another confirmation. A system interruption closes +no layer until the operation result is known. When focus returns, it returns to +the invoking control or the nearest still-valid sibling. -- Loading longer than 300 ms shows the named operation, never a generic spinner - over an apparently tappable screen. -- A content list empty because of filters shows `Clear filters`; genuinely - undiscovered content shows its acquisition route when the design allows it. -- Network unavailability cannot block campaign play. Platform achievements and - cloud work enter a bounded outbox and show local completion separately. -- Input-device change during a target or confirmation pauses selection and - spends nothing. -- Backgrounding during battle saves the deterministic snapshot and returns to a - resume review, not directly into a running timeline. -- A stale preview is rejected before cost. The updated preview highlights the - exact value, target, or rule that changed. -- Fatal content/ruleset mismatch returns to Campaign Slots with diagnostic - export. It never offers to continue into a partially loaded campaign. +## 4. Input Profiles -## 8. Onboarding Surface Map +Each inventory row names one profile. Mouse and keyboard use the controller +focus order plus pointer shortcuts; no workflow depends on hover. -The first 20 minutes use the normal screens with temporary teaching layers. No -separate tutorial UI is allowed to teach a control that looks different later. +| Profile | Touch | Controller | Focus and cancel rule | +|---|---|---|---| +| `NAV` | tap destination; horizontal swipe is optional | directional focus; shoulder buttons change top-level destination | focus enters heading then primary content; Cancel returns to parent | +| `LIST` | tap row; drag scroll; long press opens the same inspect action | vertical focus; left/right changes defined filter or comparison target | virtualization preserves logical focus by stable item ID | +| `SELECT` | tap option then explicit action | focus option, South selects, South on primary commits review | selection is not commitment; Cancel clears selection first | +| `ORDER` | tap recruit then destination; drag is optional | select recruit, move focus, confirm destination; bumpers shift one place | undo is available until readiness commitment | +| `BATTLE` | tap actor/event to inspect; dedicated pause and speed controls | bumpers cycle actors/events; face buttons open inspect and pause | focus never enters moving world elements; closing inspect resumes prior playback state | +| `MODAL` | tap explicit action; destructive hold duration is setting-aware | focus starts on Cancel; destructive action requires second explicit input or hold | Cancel spends nothing and returns focus to invoker | +| `SETTINGS` | native toggle, segmented control, slider, menu, remap row | predictable row navigation; left/right adjusts; South activates | uncommitted changes prompt Apply/Discard on exit | -| Time | Base screen | Teaching layer | Removal condition | -|---:|---|---|---| -| 0:00-0:30 | `GLD-005` | highlights one Front slot and its protected Rear relation | valid tap-select/tap-destination placement | -| 0:30-2:00 | `BAT-001/002` | freezes at first intercept and labels source, protector, result | player opens or dismisses cause chain | -| 2:00-4:00 | `EXP-004` + `GLD-009/008` | presents guard-item and interrupt-skill counters side by side | either legal plan confirmed | -| 4:00-7:00 | `BAT-002` | no answer highlight; event log records changed first failure point | variant resolved or free training reset chosen | -| 7:00-10:00 | `EXP-003/009` | brackets reward, Unsecured Cache, and Anchor distance | player reviews and commits route risk | -| 10:00-14:00 | `BAT-005/006/007` | one legal Directive path plus preserved-charge comparison | Directive result or explained preserved charge | -| 14:00-18:00 | `EXP-006/005` | compares Supply recovery and reserve rotation | one reviewed option committed | -| 18:00-20:00 | `EXP-002..010` | objective pin remains; all action highlights removed | player completes node and names next pressure | +Input-device change during selection, ordering, remapping, or confirmation +freezes the transaction and shows the equivalent controls for the new device. +No resource is spent and no selection is lost. -After two failed independent attempts, `RES-002` offers the same-seed training -replay with no rewards. It explains the first preventable event but does not -equip or choose the answer. +## 5. Complete Screen Inventory -## 9. Responsive And Accessibility Matrix +The tables are normative. `Empty / loading`, `Error / confirmation`, and +`Interruption / return` are required for every listed screen, including pages +that are not expected to be empty during ordinary play. -Every screen family must be designed and later captured at: +### 5.1 Boot, Title, And Runs -| Axis | Required states | +| ID / screen / input | Purpose | Primary action and consequence | Empty / loading | Error / confirmation | Interruption / return | +|---|---|---|---|---|---| +| `SYS-001` Boot and verification / `NAV` | Verify rules, content, settings, and `BIND:SAVE_STATE` before exposing a run. | None; proceed only after all required sources are valid. | Empty install shows required local content status. Loading names the current verification step and progress. | Recoverable source failure offers Retry; unsafe mismatch offers diagnostics and Exit. No confirmation. | Suspend resumes verification from a safe checkpoint. Return exits to platform only before Title is legal. | +| `SYS-002` First-launch setup / `SETTINGS` | Establish language, safe area, 100/115/130% text, contrast, reduced motion/flashes, captions, and input prompts. | Apply settings; writes preferences only. | Missing locale falls back to sourced English text and names the missing pack. Loading renders the preview inline with text status. | Invalid safe area or unavailable output is explained. Apply review lists changed accessibility settings. | Device change refreshes prompts without reset. No Back until one usable preset has been applied; later visits return to caller. | +| `SYS-003` Title / `NAV` | Identify the game, current safe resume state, save health, and legal entry paths. | Continue; opens `SYS-006` and does not immediately advance simulation. | No run promotes New Run. Loading affects only the run summary and keeps Settings usable. | Save warning links to `SYS-007`; offline optional service warning does not block local play. No confirmation. | Suspend returns to the same selection. Back invokes platform exit review; child pages return here. | +| `SYS-004` Run ledger / `LIST` | Inspect run slots, last safe state, play time, difficulty, and health. | Open selected run; opens resume or recovery review. | No runs explains New Run. Loading uses per-slot skeletons with slot names retained. | Corrupt, incompatible, conflict, and migration states name their safe next action. Delete and overwrite require `SYS-005` or `SET-009` review. | Refresh or cloud interruption keeps the last verified local list. Back returns to Title. | +| `SYS-005` New run setup / `SELECT` | Choose sourced difficulty and initial options without making the opening plan for the player. | Begin run; creates a run then enters Guild desk. | Missing difficulty binding disables Begin with source reason. Loading previews locally. | Slot collision, unsupported ruleset, or write failure preserves choices. Begin review states difficulty, irreversible options, and slot. | Suspend saves the uncommitted form. Back returns to the run ledger with no run created. | +| `SYS-006` Resume review / `SELECT` | Explain current phase, last committed transaction, unresolved consequence, and resume destination. | Resume; enters the exact safe state from `BIND:SAVE_STATE`. | No active run offers Run Ledger. Loading shows the saved destination name. | Invalid snapshot routes to Save Recovery. Resuming battle requires explicit review of playback state. | Suspend changes nothing. Back returns to Title or Run Ledger, whichever invoked it. | +| `SYS-007` Save recovery / `SELECT` | Compare valid save lineage, migration, conflict, and known lost interval. | Load selected valid state; changes active lineage and records a receipt. | No valid recovery offers diagnostics and safe deletion path. Loading validates and names each candidate. | Failed recovery cannot overwrite the last valid source. Selection review lists timestamp, ruleset, lost interval, and reversibility. | Suspend retains candidates but makes no choice. Back returns to Run Ledger. | +| `SYS-008` Credits, licenses, and data notice / `LIST` | Present authorship, licenses, privacy, local/offline behavior, and external-link policy. | Open section; no run consequence. | No search result offers Clear Search. Loading long text retains the current local section. | Missing license is a blocking production defect with diagnostics. External links require destination confirmation. | Suspend preserves scroll position. Back returns to the invoking Title or Settings screen. | + +### 5.2 Guild, Shop, And Recruits + +| ID / screen / input | Purpose | Primary action and consequence | Empty / loading | Error / confirmation | Interruption / return | +|---|---|---|---|---|---| +| `HUB-001` Guild desk / `NAV` | Show current pressure, preparation readiness, latest outcome, resources, and all preparation destinations. | Open Risk Board when ready; navigation itself changes nothing. | First run uses a compact opening decision prompt. Loading each status region leaves destinations usable. | Missing mandatory binding blocks only its dependent destination and names the owner. No confirmation. | Suspend records no new transaction. Child pages return here with the changed field highlighted. | +| `HUB-002` Forecast / `LIST` | Explain upcoming known threats, opportunities, deadline, and information confidence. | Track pressure; changes the Guild desk summary only. | No optional forecast still shows the mandatory next pressure. Loading preserves last verified forecast with timestamp. | Stale or incomplete forecast labels uncertainty instead of inventing certainty. Tracking needs no confirmation. | Suspend preserves filters. Back returns to Guild desk. | +| `SHP-001` Shop / `LIST` | Compare `BIND:SHOP_OFFERS`, affordability, roster/equipment fit, and refresh consequence. | Inspect offer; purchase is never performed from the list row. | Sold out explains next sourced restock. No matching filter offers Clear Filters. Loading keeps balances visible and rows inert. | Stale, duplicate, or unavailable offers refresh before review. Refresh and any paid action require exact cost confirmation. | Suspend cancels no verified purchase and polls receipts on resume. Back returns to Guild desk. | +| `SHP-002` Recruit review / `SELECT` | Evaluate generated name, profession, trait benefit/cost, rolled attributes, equipment eligibility, level, survival history, price, and party impact. | Recruit; commits `BIND:RECRUIT_TRANSACTION` after review. | Missing roster comparison states which binding is pending. Loading shows stable recruit identity, never a substitute recruit. | Offer expired, insufficient value, invalid capacity, or duplicate receipt keeps the prior state. Confirmation states exact recruit, cost, capacity effect, and undo policy. | Suspend after commit checks receipt before retry. Cancel returns to Shop on the same stable offer ID. | +| `SHP-003` Item offer review / `SELECT` | Explain item behavior, eligible recruits, owned conflicts, price, and likely party effect. | Buy; adds the item according to sourced inventory rules. | No eligible recruit is informative, not an error. Loading retains item identity and offer price timestamp. | Expired, unaffordable, full-policy, or duplicate claim states preserve balance. Confirmation lists cost, destination, and conflict. | Suspend reconciles the transaction receipt. Cancel returns to Shop on the offer. | +| `REC-001` Roster / `LIST` | Scan all cumulative recruits, deployed status, profession, trait, readiness, equipment issue, and survival history. | Inspect recruit; changes nothing. | No recruits points to Shop. No filter match offers Clear Filters. Loading uses stable roster order. | Binding failure preserves last verified summary and blocks dependent edits. No confirmation. | Suspend preserves selection and filters. Back returns to Guild desk. | +| `REC-002` Recruit detail / `NAV` | Read one recruit's sourced identity, mechanical history, current role, equipment, position, and legal actions. | Open Equip or Party Line; navigation changes nothing. | Missing optional history states `No recorded battles`. Loading keeps name and stable ID. | Deleted/stale recruit returns to Roster with explanation. Dismiss opens a separate review. | Suspend preserves the selected tab. Back returns to Roster and its prior scroll position. | +| `REC-003` Dismissal review / `MODAL` | State exactly what leaves the run, what is retained, affected party/equipment references, and `BIND:DISMISSAL_OUTCOME`. | Dismiss recruit; permanently applies the sourced transaction. | If dismissal is illegal, show the reason and nearest legal next action. Loading must finish before the destructive action enables. | Stale dependencies refresh the full consequence. Confirmation uses generated name, stable ID, outcome, and an explicit destructive gesture. | Suspend before commit cancels nothing; after commit verifies receipt. Cancel returns to Recruit Detail. | + +### 5.3 Equipment And Party Preparation + +| ID / screen / input | Purpose | Primary action and consequence | Empty / loading | Error / confirmation | Interruption / return | +|---|---|---|---|---|---| +| `EQP-001` Equipment workbench / `LIST` | Equip a selected recruit while showing eligible inventory and sourced behavior changes. | Equip selected item; changes loadout only after comparison review. | No owned items points to Shop. No eligible item explains profession/slot requirements. Loading retains current loadout. | Incompatible, already used, stale inventory, or ruleset error blocks commit with reason. Confirmation states replaced item, conflicts, and before/after behavior. | Suspend before receipt keeps the old loadout; resume reconciles receipt. Back returns to Recruit Detail or Party Line caller. | +| `EQP-002` Item comparison / `SELECT` | Compare current and candidate item in the vocabulary used by party preview, battle, and results. | Apply candidate; returns to workbench with changed effects highlighted. | Empty candidate keeps current item and offers Choose Item. Loading never clears current values. | Unknown derived effect is labeled unresolved and blocks Apply when consequence-critical. Confirmation lists all sourced changes and affected saved plan references. | Suspend keeps comparison but performs no equip. Back returns to Equipment with selection intact. | +| `ART-001` Active artifact ledger / `LIST` | Inspect run-wide artifact rules, acquisition source, interactions, conflicts, and lifecycle without treating them as recruit equipment. | Inspect artifact; changes nothing unless `BIND:ARTIFACT_RULES` supplies a separate legal action. | No active artifacts explains their sourced acquisition route. Loading retains verified active rules. | Missing or conflicting artifact references identify stable IDs and block dependent commitment. Any lifecycle-changing action requires a separate sourced confirmation. | Suspend preserves selection. Back returns to Guild desk or the Reward caller. | +| `PTY-001` Party line / `ORDER` | Select simultaneous recruits and order them from first exposure to last, with sourced targeting, protection, reach, healing, movement, and replacement previews. | Save order; changes the prepared party snapshot but does not start battle. | No recruits points to Shop. No eligible deployable recruit points to recovery or roster reason. Loading preserves last committed order. | Invalid count, duplicate recruit, incompatible state, or stale capacity identifies the exact position. Confirmation is required only when removing a currently prepared recruit has a sourced consequence. | Suspend stores only the last committed order; uncommitted moves are offered to Restore or Discard. Back returns to Guild desk. | +| `PTY-002` Readiness review / `SELECT` | Summarize prepared recruits, order effects, equipment issues, known pressure coverage, reserve state, and `BIND:PARTY_CAPACITY`. | Accept preparation; records a reviewable battle-plan snapshot. | Empty party blocks acceptance and points to Add Recruits. Loading verifies all stable IDs. | Invalid or outdated effect opens the owning edit screen. Confirmation states warnings that are allowed but does not overstate outcome prediction. | Suspend preserves the last accepted snapshot. Back returns to Party Line. | +| `RSK-001` Risk board / `SELECT` | Compare sourced risk options by known pressure, uncertainty, entry cost, reward class, recovery exposure, and current party coverage. | Review selected risk; selection alone changes nothing. | No legal option explains whether preparation, progression, or recovery is required. Loading retains accepted party summary. | Unresolved or stale option cannot be committed. No confirmation until `RSK-002`. | Suspend preserves selection only locally. Back returns to Guild desk. | +| `RSK-002` Risk commitment / `MODAL` | Present the chosen option, known threats, uncertainty, cost, reward class, retreat implication, and frozen party snapshot. | Begin battle; commits the sourced risk transaction and opens Battle Opening. | Missing party snapshot or option returns to the owning screen. Loading verifies all dependencies. | Stale resources, changed recruit state, or invalid rule reopens the changed source. Confirmation is the page's purpose and names irreversible effects. | Suspend before receipt changes nothing; after receipt resumes at Battle Opening. Cancel returns to Risk Board. | + +### 5.4 Automatic Battle + +| ID / screen / input | Purpose | Primary action and consequence | Empty / loading | Error / confirmation | Interruption / return | +|---|---|---|---|---|---| +| `BAT-001` Battle opening / `BATTLE` | Establish objective, ordered party, enemy order, first known threat, playback speed, and inspection affordance. | Start observation; releases the deterministic timeline. | Missing actor data blocks start and names the binding. Loading shows verified actor silhouettes and progress. | Snapshot mismatch returns safely to Risk Commitment or Resume Review. Start needs explicit input only on first onboarding or resumed state. | Suspend preserves an unopened snapshot. Back is disabled after risk commitment; Pause offers legal exits. | +| `BAT-002` Live battle / `BATTLE` | Make automatic resolution readable: current objective, urgent cause, actor state, target relation, event sequence, pause, speed, inspect, and retreat access. | Inspect the highlighted cause; battle decisions are diagnostic controls only. | No current event shows `Waiting for next event`, not a blank field. Loading occurs only during safe resume and the timeline does not advance. | Invalid event data pauses and offers Retry Snapshot or Safe Exit. Speed change needs no confirmation; retreat is separated. | Backgrounding or device loss freezes according to save rules and routes to `BAT-006`. Closing inspect restores the prior legal playback state. | +| `BAT-003` Actor and event inspect / `BATTLE` | Explain selected actor, action, target, status source, order interaction, equipment contribution, and causal neighbors. | Pin event or close; changes no battle result. | No related event states why. Loading pauses inspect data at the selected event ID. | Hidden information states the discovery rule; missing required cause pauses with diagnostics. No confirmation. | Suspend routes to Resume Review with the selected event remembered. Back closes inspect to Live Battle. | +| `BAT-004` Pause and speed / `BATTLE` | Freeze observation where rules allow, expose playback options, settings, event log, controls, and retreat entry. | Resume; restores the selected legal speed. | No speed alternatives shows one sourced speed. Loading settings does not resume time. | Disallowed speed explains the rule. Applying settings may require its own Apply/Discard review. | App suspend remains paused. Back resumes only when the player explicitly chooses Resume; Settings returns here. | +| `BAT-005` Retreat review / `MODAL` | State `BIND:RETREAT_OUTCOME`, timing, interruption rule, affected recruits, losses, retained state, and next destination. | Begin retreat; commits only after the full consequence is sourced. | Unavailable retreat shows exact condition and Close. Loading keeps battle paused. | Stale outcome refreshes before confirmation; duplicate input returns the original receipt. Confirmation uses explicit `Begin retreat`. | Suspend before commit returns to Pause; after commit resumes the retreat resolution snapshot. Cancel returns to Pause. | +| `BAT-006` Battle resume review / `SELECT` | Explain saved time, playback state, pending events, latest committed receipt, and whether retreat resolution is active. | Resume from verified snapshot; never resumes in motion without review. | No resumable battle routes to the last safe Result or Guild state. Loading validates the snapshot. | Invalid snapshot uses save recovery and never starts a partial simulation. Resume confirmation states current speed and pause behavior. | Repeated suspend leaves the battle frozen. Back returns to Title without discarding the snapshot. | + +### 5.5 Result, Death, Reward, And Recovery + +| ID / screen / input | Purpose | Primary action and consequence | Empty / loading | Error / confirmation | Interruption / return | +|---|---|---|---|---|---| +| `OUT-001` Battle result and diagnosis / `LIST` | Show outcome, first meaningful divergence, decisive interaction, downstream costs, survivor state, and available next resolution. | Continue to the earliest unresolved consequence. | No preventable cause states `No actionable divergence` and still shows decisive events. Loading preserves outcome receipt. | Missing causal data is an explicit diagnostic error; transaction remains paused. No confirmation. | Suspend preserves the result receipt and scroll position. Back does not bypass unresolved consequences. | +| `OUT-002` Death and loss review / `SELECT` | Name each dead recruit, stable identity, profession, trait, level, survival history, equipment disposition, party gap, and sourced replacement implication. | Acknowledge resolved losses; advances to Reward, Recovery, or Run End. | No deaths skips this screen. Loading renders known identities before disposition details. | Incomplete casualty receipt blocks acknowledgement and offers Retry. Confirmation is acknowledgement of an already committed result, not a reversal offer. | Suspend preserves unresolved acknowledgement. Back returns to Result diagnosis but cannot alter battle outcome. | +| `OUT-003` Reward choice / `SELECT` | Compare `BIND:REWARD_OPTIONS` by changed decision, eligible target, conflicts, and run impact. | Claim selected reward; commits one sourced receipt. | No earned reward explains the result and offers Continue. Loading preserves result context. | Expired, ineligible, duplicate, or storage-policy state returns a deterministic next action. Confirmation names reward, target, conflicts, and skip outcome. | Suspend checks receipt before retry. Cancel returns to Result only if reward choice is not mandatory. | +| `OUT-004` Recovery / `SELECT` | Compare legal recovery paths by cost, time, recruit availability, replacement opportunity, and next planning state. | Commit recovery; changes the run according to `BIND:RECOVERY_OPTIONS`. | No recovery required offers Continue. No viable path exposes the run-ending route. Loading retains casualty and resource facts. | Unaffordable, stale, or illegal paths remain inspectable with reason. Confirmation lists full transaction and next destination. | Suspend before receipt spends nothing; after receipt resumes at its destination. Back returns to Result or Death Review. | +| `OUT-005` Run end summary / `LIST` | Explain `BIND:RUN_FAILURE` or clear, retained progression, losses, discoveries, decisions unlocked, and exact next choices. | Finish run; closes the run and applies the verified progression receipt. | No progression gain is stated plainly. Loading waits for all receipts before enabling Finish. | Duplicate or failed progression application preserves the run as unresolved. Finish confirmation is needed only if viewing unresolved optional pages would be lost. | Suspend preserves the unresolved summary. Back remains within summary tabs; Finish returns to Title or Progression. | + +### 5.6 Progression, Records, And Postgame + +| ID / screen / input | Purpose | Primary action and consequence | Empty / loading | Error / confirmation | Interruption / return | +|---|---|---|---|---|---| +| `PRO-001` Run progression / `LIST` | Show current level paths, profession changes, capacity growth, prerequisites, and decisions opened within the active run. | Inspect or apply a legal sourced choice. | No pending choice shows next prerequisite. Loading retains current applied state. | Stale prerequisite or invalid choice refreshes before commit. Irreversible branch or reset uses explicit comparison confirmation. | Suspend reconciles any receipt. Back returns to Guild desk or Result caller. | +| `PRO-002` Persistent progression / `LIST` | Show unlock breadth, new planning grammar, prerequisite evidence, and claimed receipts across runs. | Claim or inspect a sourced unlock. | First-run state explains when evidence can be earned. Loading uses stable unlock IDs. | Unknown future content remains undisclosed; duplicate claim returns receipt. Confirmation states how new runs change. | Suspend retains filters. Back returns to Title, Guild, or Run End caller. | +| `PRO-003` Records and compendium / `LIST` | Browse professions, traits, equipment, artifacts, enemies, bosses, regions, recruit histories, and battle reports without spoilers. | Inspect entry; changes no run result. | Category empty states discovery route when allowed. No search result offers Clear Search. Loading keeps category context. | Missing referenced entry reports stable ID and diagnostics. Inspection requires no confirmation and external links do not exist here. | Suspend preserves category, filter, and scroll ID. Back returns to caller. | +| `PST-001` Postgame hub / `NAV` | Present eligibility, sourced rules, open challenges, prior results, and the distinction from an ordinary run. | Open rules review; does not start immediately. | No eligible modifier states the next sourced requirement. Loading preserves ordinary New Run access. | Missing `BIND:POSTGAME` disables entry and names source. No confirmation. | Suspend preserves selected challenge. Back returns to Title. | +| `PST-002` Postgame run review / `SELECT` | Compare active postgame modifiers, known consequences, difficulty, save slot, and carried unlock breadth. | Begin postgame run; creates a new run with the reviewed rules. | No compatible selection blocks Begin with reason. Loading verifies every modifier ID. | Conflict, expired ruleset, or slot collision preserves selection. Confirmation lists every active modifier and irreversible setup choice. | Suspend saves the uncommitted form. Cancel returns to Postgame hub. | +| `PST-003` Postgame result / `LIST` | Explain challenge outcome, rules that mattered, record change, rewards, and next legal attempt. | Finish result; applies verified record and reward receipts. | No record change is stated without negative framing. Loading waits for receipts. | Duplicate or invalid score is separated from local clear status. Finish confirmation only when an unresolved claim exists. | Suspend preserves the result. Back stays within result tabs; Finish returns to Postgame hub. | + +### 5.7 Settings And Data + +| ID / screen / input | Purpose | Primary action and consequence | Empty / loading | Error / confirmation | Interruption / return | +|---|---|---|---|---|---| +| `SET-001` Settings index / `SETTINGS` | Navigate Display/Text, Motion/Effects, Audio/Captions, Controls, Language, Gameplay Information, Save/Data, and Reset. | Open category; no run consequence. | No changed settings shows current preset. Loading categories does not block Back. | Invalid stored setting uses documented safe default and identifies it. No confirmation. | Suspend preserves selected category. Back returns to exact caller: Title, Guild, or Pause. | +| `SET-002` Display and text / `SETTINGS` | Set safe area, brightness, contrast, color-independent cues, and 100/115/130% UI/text with live preview. | Apply display settings. | Unavailable display option remains visible with reason. Preview loading shows text sample. | Unsupported combination offers nearest supported result without auto-applying. Apply/Discard review appears on exit with changes. | Output change freezes preview and retains values. Return to Settings index. | +| `SET-003` Motion, flashes, and power / `SETTINGS` | Set reduced motion, reduced flashes, shake, hit pause, particle density, and low-power behavior with a non-combat sample. | Apply effects settings. | Unsupported effect control explains platform behavior. Sample loading never flashes. | Unsafe or unavailable combination reverts preview only. Apply/Discard on exit. | Backgrounding stops sample. Return to Settings index. | +| `SET-004` Audio and captions / `SETTINGS` | Set master/music/ambience/SFX/voice-when-present levels, mute, dynamic range, captions, event labels, and mono-compatible cues. | Apply audio settings. | Missing output or absent voice category is stated. Test loading is silent with visible status. | Output failure keeps captions and visual cues active. Apply/Discard is the exit confirmation. | Output change pauses test and retains settings. Return to Settings index. | +| `SET-005` Controls / `SETTINGS` | Inspect and remap touch, keyboard/mouse, and controller actions; set hold timing and vibration. | Save mapping. | No controller attached still permits mapping inspection. Loading keeps safe Cancel binding. | Conflict names both actions and requires resolve; essential actions cannot be left unbound. Save confirmation lists changed mappings. | Device loss pauses capture and spends no input. Return to Settings index after Apply/Discard. | +| `SET-006` Language and locale / `SETTINGS` | Select English or Simplified Chinese and preview mechanics, dates, numbers, and wrapping. | Apply language; reloads localized text without changing run state. | Missing optional locale pack names the fallback. Loading uses current language until complete. | Invalid string key shows stable diagnostic ID, not raw code in player copy. Apply confirmation appears when a reload is required. | Suspend resumes the reload safely. Return to Settings index in the applied language. | +| `SET-007` Gameplay information / `SETTINGS` | Set forecast detail, tutorial reminders, battle log density, default speed, and other information assists without hiding result-changing rules. | Apply information settings. | Unavailable option states dependency. Preview loading uses a fixed non-authoritative sample. | Disallowed combination explains the rule. Apply/Discard on exit. | Suspend stops preview only. Return to Settings index. | +| `SET-008` Save and data / `SETTINGS` | Inspect local save health, optional synchronization, conflicts, backups, export, and diagnostics. | Open selected management action; routine inspection changes nothing. | Offline state keeps local status and names queued optional work. Loading shows last verified timestamp. | Conflict and recovery use `SYS-007`; export failure retains local data. Replacing a lineage requires full comparison confirmation. | Suspend pauses external work and keeps a durable receipt. Return to Settings index. | +| `SET-009` Reset and deletion / `MODAL` | Separate run deletion, profile reset, settings reset, and diagnostics clearing with exact scope and recovery policy. | Execute reviewed destructive action. | No eligible data disables the action with reason. Loading inventory must finish before review. | Write failure preserves data. Confirmation names scope, stable target, retained data, recovery window, and explicit destructive gesture. | Suspend before receipt cancels nothing; after receipt verifies outcome. Cancel returns to Settings index. | + +## 6. Global State Rules + +### 6.1 Loading And Empty + +- Operations longer than `300 ms` show the named operation and whether input is + blocked. An apparently tappable control never sits under an unlabeled spinner. +- Lists retain stable headers, selected IDs, and known balances while rows load. +- Filter-empty and truly empty are distinct. Filter-empty always offers Clear + Filters; truly empty explains the legal way content becomes available. +- Unknown, undiscovered, unavailable, unaffordable, incompatible, full by a + sourced rule, and completed are distinct states with distinct next actions. + +### 6.2 Error And Receipt + +- Every commit has an operation ID and resolves to one receipt. Retry never + duplicates purchase, recruit, dismissal, equip, reward, progression, recovery, + retreat, or run completion. +- A stale review refreshes all changed values and requires a new explicit + confirmation. It never commits the old preview. +- A binding error states the affected feature and safe next action. Raw stack + traces, credentials, paths, and internal tokens are excluded from player copy. +- Offline optional services cannot block local run play. + +### 6.3 Interruption And Save + +- Backgrounding during battle produces or verifies a deterministic snapshot and + returns through `BAT-006`; time never advances behind an obscured app. +- Backgrounding during any transaction returns through receipt reconciliation. +- A low-memory restart returns to Title with the exact resumable state named. +- Clock rollback, cloud divergence, migration, corruption, duplicate claims, + rollback, and bounded offline behavior are presented through `SYS-007` or + `SET-008` using sourced save rules. + +## 7. Onboarding Map + +Onboarding uses production screens and can be replayed from Records. It teaches +one decision at a time and never completes a build choice for the player. + +| Moment | Base screen | Teaching focus | Completion evidence | Skip/return behavior | +|---|---|---|---|---| +| First launch | `SYS-002` | language, text preview, reduced motion/flashes, captions | one usable preset applied | cannot skip before usable settings; later returns to Title | +| Opening choice | `SHP-001/002` | compare a small sourced offer set by profession and trait tradeoff | player inspects then recruits one legal offer | skip hides callouts, never picks an offer | +| First preparation | `EQP-001/002` | one behavior-changing equipment comparison | player identifies before/after behavior | back returns to Recruit Detail | +| First order | `PTY-001` | move one recruit and read changed exposure/reach preview | tap-select/tap-destination or controller move completed | drag is never required | +| First risk | `RSK-001/002` | known pressure, uncertainty, cost, and recovery exposure | player reviews and commits a legal option | no recommended option is auto-selected | +| First battle | `BAT-001/002/003` | observe target choice, pause, inspect one cause | player opens a causal explanation | speed remains sourced; no combat action prompt | +| First result | `OUT-001` | locate earliest divergence and downstream consequence | player follows one cause chain | Continue remains available after review | +| First casualty | `OUT-002/004` | distinguish committed loss from the next recovery decision | player acknowledges receipt and inspects legal recovery | no loss is silently undone | +| First reward | `OUT-003` | compare changed decisions, not rarity alone | player claims one sourced option | skip only when product rules allow it | +| First adaptation | `HUB-001` | highlight what changed in Shop, Roster, Equipment, Party Line, and Risk | player opens any affected preparation page | all teaching highlights end after one independent loop | + +After repeated failure, Result may offer a replayable explanation or training +surface only if supplied by product rules. It may identify the earliest +preventable event, but it does not equip, recruit, reorder, or choose risk. + +## 8. Landscape, Localization, And Accessibility Matrix + +Every base screen and required overlay must be captured and reviewed across +these axes before a gallery can claim coverage: + +| Axis | Required design states | |---|---| -| Viewport | 1280x720, 1920x1080, 2560x1440; extra-wide reveal policy | -| Language | English, Simplified Chinese, longest localized string fixture | -| Scale | 100%, 115%, 130% UI/text | -| Input | touch-only, mouse/keyboard, controller; focus indicator always visible | -| Motion | normal, reduced motion, reduced flashes, camera shake 0 | -| Audio | normal, master mute, captions-only, mono-compatible information cues | -| Power | normal and low-power without changing simulation or decision timing | -| Vision | standard and high contrast; no state relies only on hue | +| Landscape phone | `1280x720` reference; short-height and wide-cutout fixtures; touch-safe edges | +| Landscape tablet | `1366x1024` and `2048x1536`; world expands without stretching controls | +| Large landscape | `1920x1080` and `2560x1440`; constrained HUD with lateral world reveal | +| Language | English (`en`), Simplified Chinese (`zh_CN`), and a longest-string fixture for every action and consequence | +| Text/UI scale | 100%, 115%, and 130%; no critical value, cost, state, or action truncated | +| Input | touch-only and controller required; keyboard/mouse parity; visible focus at all times | +| Motion | normal and reduced motion; no information conveyed only by travel, parallax, shake, or speed | +| Flashes | normal and reduced flashes; event geometry and text remain sufficient | +| Audio | normal, master mute, captions-only, output loss, and mono-compatible information cues | +| Power | normal and low-power; same decisions, simulation state, event order, and receipts | +| Vision | standard and high contrast; no state depends on hue, opacity, or image detail alone | -At 130%, secondary prose may move into an inspect drawer, but cost, state, -consequence, objective, and primary action remain in the first viewport. The -battle event log becomes a full-screen linear overlay at 130% instead of -shrinking the battlefield into an unreadable remainder. +At 130%, secondary explanation moves to an inspect drawer or full-screen detail. +Objective, current state, cost, consequence, primary action, Back, focus, and +transaction status stay in the first viewport. Battle inspection becomes a +pauseable full-screen linear view when a side drawer would make actors +unreadable. + +Simplified Chinese (`zh_CN`) may wrap actions to two lines. Components grow vertically +within bounded layout tracks; type never shrinks to force a one-line label. +Generated names support long Latin strings and multi-codepoint CJK without +using name length to resize surrounding controls. + +## 9. Endgame And Completion States + +The following are separate, player-readable states: + +1. Active run with ordinary preparation available. +2. Battle victory with unresolved casualty, reward, or recovery transaction. +3. Battle loss with the run still viable. +4. Retreat resolved with a changed preparation state. +5. Run ended by sourced failure, with progression receipt pending. +6. First clear, with newly eligible persistent and postgame decisions. +7. Completed run retained for records, not resumable as active play. +8. Postgame run setup with all active modifiers reviewed. +9. Postgame result with local clear, verified record, and reward receipt shown + independently. +10. Profile completion with no unclaimed transaction and ordinary New Run still + available. + +Credits, records, and postgame never trap the player. Each returns to Title or +its explicit caller, and ordinary run creation remains visible wherever legal. ## 10. Coverage Gate -The presentation package is incomplete until: +The screen authority is candidate-ready only when: -- every ID in Section 4 has one canonical layout and all listed variants; -- all 24 `CHV` scene families have a visual board or prototype frame; -- opening, first action, first choice, pressure, failure, recovery, reward, - transformation, ending, and Second Weave are visible at actual landscape - play size; -- every action has available, locked/unavailable, selected, committed, and - duplicate/retry behavior where applicable; -- navigation is proven with touch, keyboard/mouse, and controller semantics; -- English, zh_CN, 130%, reduced-motion, mute/captions, and low-power layouts are - represented; -- the interactive prototype can complete the first 20-minute flow as a - compressed click path without unexplained dead controls. - -This gate proves specification coverage only. Human visual quality, -comprehension, fun, device behavior, and release acceptance remain open. +- every ID in Section 5 has a canonical landscape composition; +- every row has purpose, primary action, consequence, empty, loading, error, + confirmation, interruption, and return behavior; +- Shop, recruit, dismiss, equip, compare, active artifacts, party ordering, risk commitment, + automatic battle, pause, speed, inspect, retreat, result, death, reward, + recovery, progression, Settings, and postgame form complete paths; +- all product values appear through Section 2 bindings or an integrated source; +- no interaction inserts a combat action into the automatic timeline; +- every destructive or costly action has a stale-preview and duplicate-receipt + path; +- landscape phone/tablet, touch/controller, English/Simplified Chinese, 130%, + reduced motion/flashes, mute, high contrast, and low-power states are covered; +- onboarding uses the real screens and ends with an independent player decision; +- no screen implies authored story leads; recruits remain generated run + participants; and +- design coverage is not described as implementation, device, comprehension, + fun, packaging, store, or release acceptance. diff --git a/docs/presentation/UI_AND_VISUAL_SYSTEM.md b/docs/presentation/UI_AND_VISUAL_SYSTEM.md index 069e21fe..0605f206 100644 --- a/docs/presentation/UI_AND_VISUAL_SYSTEM.md +++ b/docs/presentation/UI_AND_VISUAL_SYSTEM.md @@ -1,519 +1,734 @@ # Aetherbound Guild: UI And Visual System -> Authority: landscape composition, visual identity, semantic color, type, -> component behavior, motion, and canonical layout families. +> Authority: player-facing landscape composition, information hierarchy, +> reusable UI grammar, semantic color, type, input feedback, responsive +> behavior, and accessibility presentation. > > Companion: [SCREEN_AND_STATE_MAP.md](SCREEN_AND_STATE_MAP.md). > -> Evidence boundary: this is a production specification, not a rendered, -> human-reviewed, or device-verified result. +> Product source: `.agent-taskgraph/spec.md` revision `design-spec-r3`. +> +> Evidence boundary: this is a production specification, not rendered UI, +> final media, runtime proof, device acceptance, or human validation. ## 1. Visual Thesis -**A working magical expedition journal laid over a living hand-painted world.** +**A field guild making consequential plans at the edge of a vivid, unstable +fantasy world.** -In three seconds, a player should see named adventurers repairing a ruptured -magical route, not a medieval tavern, a gacha roster, an idle-game spreadsheet, -or a generic dark strategy dashboard. The art is authored 2D Japanese -hand-drawn fantasy with clear cel-shaped characters, painted environments, -selective ink texture, and restrained animation rigs. The interface uses the -guild's physical repair language: enamel labels, stitched field cloth, brass -Waylamp mechanisms, inked forecast acetate, ceramic status chips, and route -cords. +The first viewport presents the actual decision surface: generated recruits at +a muster table, physical equipment under comparison, an ordered expedition +line, a dangerous destination, or a battle already resolving. The world and +its actors remain the primary composition. UI surfaces attach to a desk edge, +tool rack, field ledger, route frame, or screen edge instead of floating as a +wall of panels. -The UI must feel maintained rather than luxurious. Surfaces show repair marks, -handwritten secondary notes, replaced screws, and faction additions, while -primary text and numbers remain clean engine-rendered typography. The player is -a strategist at a working table, not a monarch receiving ornate popups. +The visual language combines hand-painted 2D Japanese fantasy environments, +clean cel-shaped actors, dark ink structure, bright mineral pigments, cool +paper-white labels, enamel action plates, woven position markers, and precise +engine-rendered type. It feels practical and repaired, not royal, luxurious, +or collectible-first. -### 1.1 Experience Reads +Generated recruits read as individuals through their sourced name, modular +appearance, profession silhouette, one trait seal, equipment, condition, level, +and survival marks. Presentation never implies that one recruit is an authored +lead who must remain in the party. -| State | First read | Second read | Third read | Intended feeling | +### 1.1 Three-Second Reads + +| Moment | First read | Second read | Third read | Desired feeling | |---|---|---|---|---| -| Title/opening | ruptured route crossing a working guild | Mara and Oren repairing, not posing | one route pulse successfully relit | invitation and practical purpose | -| Guild | current physical repair/objective | named company preparing nearby | destination dock and next route | ownership without menu anxiety | -| Route | two materially different paths | reward versus exposed Cache | company readiness and Supplies | informed anticipation | -| Battle | telegraphed enemy action | threatened ally and protection relation | legal Directive / Command | readable pressure and trust | -| Failure | first preventable event | retained people/progress | credible reconfiguration path | diagnosis, not humiliation | -| Reward | behavior-changing object | build interaction and exact delta | Cache exposure / Anchor distance | curiosity with responsibility | -| Restoration | service visibly starts working | people affected by the choice | new route/profession possibility | earned transformation | -| Ending | eight local systems working together | 30 adventurers remain workers/mediators | a new route law, not a throne | plural accomplishment | +| Title | active guild threshold and distant unstable route | current safe run state | Continue and accessibility access | invited, not advertised to | +| Guild desk | next pressure or opportunity | what changed after the last result | available preparation destinations | purposeful freedom | +| Shop | materially different offers | cost and current fit | refresh or return consequence | constrained possibility | +| Recruit review | profession responsibility and trait tradeoff | rolled strengths and limitation | price and party effect | informed attachment without narrative obligation | +| Equipment | changed behavior and eligible wearer | conflict or replacement | cost and reversibility | deliberate construction | +| Party line | order from first exposure to last | protection, reach, movement, and target effects | validation and undo | readable planning | +| Risk choice | known pressure and uncertainty | reward class and recovery exposure | committed party snapshot | chosen tension | +| Battle | most urgent event and affected actors | why the current target or protection relation exists | pause, speed, and inspect | trust in automatic resolution | +| Result | earliest meaningful divergence | downstream losses and survivors | next adaptation | diagnosis, not spectacle alone | +| Death | who was lost and what capability disappeared | equipment and party gaps | legal recovery or replacement path | consequence with agency | +| Reward | which future decision changes | current build interaction | claim consequence | earned redirection | +| Postgame | active rule differences | eligibility and record | ordinary run remains available | mastery with transparency | ### 1.2 Anti-Goals -- No black/navy screen filled with detached translucent rectangles. -- No oversized title copy replacing the world or playable subject. -- No parchment-beige monoculture, faux medieval calligraphy, or ornamental - borders that reduce text space. -- No rarity rainbow dominating item purpose or behavior. -- No tiny chibi army whose profession and condition disappear at play size. -- No portrait cards as the main battle representation. -- No full-screen blur, decorative gradient orb, ambient bokeh, or particle fog. -- No unexplained icon-only resource, status, or destructive action. -- No animated decoration that resembles a telegraph, reward, hit, or legal - target. -- No font sizing tied to viewport width and no negative letter spacing. +- No detached dark rectangles covering a decorative background. +- No portrait-card wall as the primary roster, planning, or battle view. +- No oversized headings inside compact operational surfaces. +- No rarity color as the main argument for recruiting or choosing an item. +- No one-hue fantasy wash; semantic colors stay distinct from region art. +- No beige parchment monoculture, full-screen blur, ornamental glow spheres, + decorative gradients, or particle haze. +- No tiny actors whose profession, order, target, health, and death state vanish + at play size. +- No icon-only unfamiliar resource, trait, status, or destructive action. +- No animated decoration that resembles danger, a legal target, a reward, or a + successful transaction. +- No font sizing tied to viewport width, negative letter spacing, text baked + into art, or forced one-line localized controls. +- No nested decorative cards. Repeated offers and items may use bounded rows; + page sections remain unframed or edge-docked. -## 2. Canvas, Camera, And Safe Areas +## 2. Cross-Workstream Presentation Bindings -The design canvas is `1920x1080`, rendered responsively at a fixed landscape -aspect policy. +Gameplay values use the binding registry in the companion screen map. Media +identity uses the following named bindings until the art and audio authorities +are integrated: -| Target | Logical viewport | Safe area | Policy | +| Binding | Required presentation contract | Source authority | +|---|---|---| +| `BIND:ART_RECRUIT_PRESENTATION` | modular body, face, hair, garment, condition, and survival-mark layers | art/animation catalog | +| `BIND:ART_PROFESSION_PRESENTATION` | silhouette, tool/weapon, pose, emblem, and action-read vocabulary for each profession | art/animation catalog | +| `BIND:ART_EQUIPMENT_PRESENTATION` | inventory object, equipped read, comparison view, and conflict marker | art/animation catalog | +| `BIND:ART_REGION_PRESENTATION` | environment, route material, weather, and readable ground contrast per region | art/animation catalog | +| `BIND:ART_ENEMY_PRESENTATION` | identity, threat source, target projection, status, injury, and death/exit reads | art/animation catalog | +| `BIND:ART_EFFECT_LANGUAGE` | anticipation, target, impact, mitigation, status, death, reward, and recovery event roles | art/animation catalog | +| `BIND:AUDIO_EVENT_CATALOG` | UI commit, shop, order, battle, casualty, result, reward, recovery, and error cues | audio catalog | + +Design fixtures may use labeled geometric stand-ins. They may not invent final +silhouettes, asset counts, music, voice scope, prices, formulas, or content +identities. + +## 3. Canvas, Safe Areas, And Responsive Tracks + +The interface is designed in logical pixels. Layout changes by available height +and aspect, not by scaling the entire canvas. + +| Class | Required fixture | Safe area | Structural policy | |---|---:|---:|---| -| Small mobile/tablet split | 1280x720 | 56 px sides / 40 px top-bottom | preserve world center, collapse secondary drawers | -| Reference landscape | 1920x1080 | 96 px all edges | canonical composition | -| Large desktop/console | 2560x1440 | 128 px all edges | reveal lateral environment and wider lists; no stretched controls | -| Extra-wide | wider than 16:9 | reference safe-area width centered | reveal world only; HUD tracks remain max-width constrained | +| Short landscape phone | `1280x720` | `56` sides, `40` top/bottom plus device insets | compact top rail, full-height decision surface, bottom action dock; detail replaces secondary region | +| Wide landscape phone | `1560x720` | device insets plus `56` | keep short-height control sizes; reveal world laterally | +| Landscape tablet | `1366x1024` and `2048x1536` | `64` all edges plus device insets | main decision area plus persistent contextual rail when useful | +| Reference landscape | `1920x1080` | `96` all edges | canonical composition and two-region comparison | +| Large landscape | `2560x1440` | `128` all edges | constrained UI tracks; reveal environment and longer lists | -Environment cameras use a stable horizon between 38% and 46% of canvas height. -Battle is a shallow three-quarter side view, not top-down: bands are separated -by floor motifs and depth offsets while actor silhouettes remain mostly -upright. Formation tools use an elevated 30-degree table view because planning, -not spectacle, is the focal action there. +The major tracks are stable: -On-screen subjects have protected composition zones: +- top status rail: `56-72` high, one row at 100%, two bounded rows at 130%; +- main subject: at least `62%` of usable width and `68%` of usable height; +- context rail: `360-520` wide when docked, or a full-height replacement surface + on a short phone; +- bottom action dock: `72-96` high, with one primary action aligned to the + decision rather than centered by habit; +- inspect surface: up to `42%` of width on tablet/reference, full screen on a + short phone at 130%; and +- settings category rail: `224-272` wide when persistent; a top selector when + the scaled label set would narrow content below its minimum. -- left and center `68%`: world, formation, actors, route, or physical collection; -- right `22-28%`: context/inspect drawer only when open; -- top `7-9%`: compact objective and resource rail; -- bottom `10-14%`: destination/action dock when the screen family requires it. +Control and text dimensions do not stretch on large screens. Environment art, +world spacing, and list length absorb extra room. Cutouts and home indicators +may move the action dock inward but never cover a focus outline or consequence. -Drawers replace, slide over, or compress only secondary world space. They never -shrink battle below 68% or force a functional control under 48 logical pixels. +### 3.1 Responsive Priority -## 3. Semantic Palette +When height or text space is constrained, retain in this order: -The palette combines daylight pigments and dark ink structure. No single hue -family owns more than half of a normal scene. +1. objective or decision name; +2. current state and selected stable identity; +3. cost, consequence, and reversibility; +4. primary action and Back; +5. comparison delta or urgent causal explanation; +6. supporting history and flavor. -| Token | Color | Role | Non-color backup | +Items 1-5 remain in the first viewport. Item 6 may move to Inspect. No layout +solves overflow by reducing type below its token or actors below their minimum +readable silhouette. + +## 4. Information Hierarchy + +| Decision surface | Primary | Secondary | Deferred to inspect | |---|---|---|---| -| `ink-950` | `#171C22` | primary text, deep silhouettes | weight and solid edge | -| `ink-800` | `#2B333B` | docked panels, inactive mechanisms | inset contour | -| `paper-050` | `#F7F3E8` | readable labels, selected ledger surface | bright field and raised edge | -| `paper-200` | `#DDD4C2` | secondary physical surfaces | stitch or paper grain | -| `aether-cyan` | `#32B8C6` | route energy, legal flow, arcane action | continuous double-line motif | -| `repair-gold` | `#E5B445` | objective, repair, selected destination | key-notch motif | -| `ally-jade` | `#3F9E78` | ally health/recovery/safe commit | leaf-chevron motif | -| `danger-coral` | `#D95C55` | immediate danger, invalid destructive consequence | broken triangle and pulse | -| `command-blue` | `#477EC7` | player Directive and Command charge | four-point command seal | -| `strain-violet` | `#8C63A8` | Strain and unstable memory effects | three-knot mark | -| `cache-copper` | `#B86D3F` | unsecured value and risk | open-clasp icon | -| `secured-green` | `#287A5A` | banked/committed value | closed-clasp icon | -| `focus-white` | `#FFFFFF` | keyboard/controller focus edge | two-pixel outer+inner outline | +| Guild desk | upcoming pressure, latest change, preparation readiness | sourced resources and open decisions | complete run history | +| Shop | offer behavior, price, immediate fit | future eligibility and refresh consequence | full discovery provenance | +| Recruit review | profession responsibility, trait benefit/cost, rolled constraint | equipment eligibility, level, survival history | full attribute derivation | +| Equipment | changed behavior, wearer, replacement, conflict | secondary derived effects and acquisition | unrelated collection record | +| Party line | position, exposure, target/protection/reach change | alternate order and unresolved warning | cosmetic identity detail | +| Risk | known threat, uncertainty, entry cost, reward class | current coverage and recovery exposure | unrelated progression | +| Battle | urgent event, affected actor, objective, playback state | aggregate party condition | long-form build explanation | +| Result | first divergence, decisive interaction, deaths, next resolution | contribution and complete event list | collection celebration | +| Recovery | viable paths, full transaction, next planning state | longer-term replacement implications | unrelated records | +| Progression | newly opened decisions and prerequisites | path preview and reset consequence | unrelated catalog entries | -Semantic color appears on no more than 25% of a component surface. Large -surfaces use region/environment palettes; the semantic token appears in icons, -edges, lane markings, and state-changing light. Color is never the sole -difference between safe/risky, ally/enemy, active/disabled, or complete/open. +The same mechanical noun and icon must be used in preview, battle, result, and +records. A tooltip cannot rename a rule or hide a consequence behind flavor. -### 3.1 Chapter Palette Shifts +## 5. Semantic Palette -| Chapter | Dominant environment pigments | Aether interruption | Avoid | +Region art supplies local color. UI semantics use a small, stable set that is +readable over both bright and dark scenes. + +| Token | Color | Meaning | Required non-color cue | |---|---|---|---| -| CH-01 | grass green, sky cyan, windmill yellow, chalk white | silent charcoal wavefront with cyan fracture | idyllic beige farm | -| CH-02 | reed jade, flood blue, frosted glass, ferry red | white voice ribbons with patterned source marks | all-blue underwater wash | -| CH-03 | iron gray, furnace vermilion, worker cobalt, mint silver | alternating amber/cyan pressure seams | monochrome orange forge | -| CH-04 | leaf green, archive white, ink black, annotation magenta | missing ink cuts with cyan return stroke | generic enchanted forest | -| CH-05 | moon silver, harbor teal, rescue orange, customs indigo | offset mirrored rim patterns | indistinct blue reflection | -| CH-06 | storm gray, ward saffron, lift jade, clear-eye blue | directional coral/cyan wind arrows | dark blue storm everywhere | -| CH-07 | lantern coral, registry ivory, wet stone green, night black | blank fields paired with gold voice marks | purple-black mystery cliché | -| CH-08 | one retained material/color from every region | plural eight-color cadence with ink scaffolding | rainbow glow without structure | +| `ink-950` | `#182127` | primary text, deepest structural edge | solid weight | +| `ink-760` | `#34424A` | docked instrument and inactive surface | inset border | +| `mist-050` | `#F3F6F2` | primary text field and selected ledger surface | raised plane | +| `mist-180` | `#D7E0DD` | secondary surface and divider | woven grain | +| `route-teal` | `#13818A` | legal flow and navigation path | paired continuous lines | +| `work-gold` | `#D6A72E` | primary decision and selected destination | key-notch edge | +| `safe-jade` | `#27845E` | health, retained state, safe completion | upward leaf-chevron | +| `danger-coral` | `#C94E52` | urgent harm, invalid destructive consequence | split triangle | +| `focus-cobalt` | `#4169B1` | focus, inspect, information action | double square contour | +| `uncertain-plum` | `#855579` | uncertainty and incomplete forecast | broken ring | +| `neutral-silver` | `#88969B` | disabled or not applicable | cross-pin and text reason | +| `focus-white` | `#FFFFFF` | controller/keyboard outer focus | paired outer and ink inner line | -## 4. Typography And Numeric Display +Semantic color occupies no more than one quarter of a large component surface. +Health, danger, uncertainty, eligibility, selection, and completion use shape, +text, and pattern in addition to hue. Body text meets `4.5:1` contrast and +large text plus meaningful component boundaries meet `3:1` in all approved +region fixtures. -Display type uses a humanist Japanese/Latin-compatible sans with slightly -calligraphic terminals for location and chapter names. Functional UI uses a -high-legibility UI sans with tabular numerals. The implementation may select -licensed fonts later; font names are not part of this authority until license, -glyph, fallback, and platform rendering tests pass. +Rarity, when supplied by content, is secondary metadata. It may change a small +corner stamp or texture but never the size, brightness, or order of an offer. -Reference sizes at `1920x1080` and 100%: +## 6. Typography, Numbers, And Localization + +Display text uses a licensed Japanese/Latin-capable humanist sans only for the +product name, region arrival, and run ending. Functional UI uses a highly +legible Japanese/Latin sans with tabular numerals. Font selection remains +pending glyph, license, fallback, and device rendering review. + +Reference tokens at `1920x1080`, 100%: | Style | Size / line | Use | |---|---:|---| -| Display chapter | 48 / 58 | chapter arrival only, over world image | -| Screen title | 34 / 42 | docked heading, never a hero headline | -| Section title | 25 / 32 | panel/area heading | -| Body | 20 / 29 | explanations and narrative choices | -| UI label | 18 / 23 | buttons, tabs, fields | -| Caption | 16 / 21 | metadata that is not decision-critical | -| Battle number | 18 / 20 | HP changes, timers, event values | +| Display | `46 / 58` | product name or region arrival only | +| Screen title | `32 / 40` | page or major decision name | +| Section title | `24 / 32` | one bounded content region | +| Body | `20 / 29` | consequence and explanation | +| UI label | `18 / 24` | actions, tabs, fields, position markers | +| Caption | `16 / 22` | noncritical metadata | +| Battle label | `18 / 22` | attached event, value, timer, status | -All values use tabular numerals. A value that changes displays `old -> new`, -the signed delta, or a before/after bar according to context. The interface -never shows a green number without the affected stat or a percentage without -the absolute consequence. Compact battle labels expand on focus/tap and in the -event log. +Letter spacing is `0`. All numeric values use tabular numerals. A changed value +uses a named `before -> after`, signed delta, or before/after bar. A percentage +never appears without the affected rule and sourced base consequence. -At 115% and 130%, type and controls scale from a theme token, not viewport -width. Text may wrap to a second line. Functional labels never ellipsize unless -the same component exposes the complete accessible name on focus and the -truncated value is not a state/cost/consequence. +At 115% and 130%, font and control tokens increase independently of viewport. +Labels may wrap to two lines. Screen titles, buttons, tabs, generated names, +prices, consequences, and state labels do not ellipsize. Noncritical history +may truncate only when an adjacent Inspect action exposes the complete +accessible string. -## 5. Shape, Material, And Icon Grammar +English (`en`) and Simplified Chinese (`zh_CN`) share hierarchy and action order. Chinese +mechanical text remains engine-rendered, uses localized punctuation, and is +tested without inserting spaces between ideographs. Dates, numbers, and unit +order use locale formatting, while stable diagnostic IDs remain ASCII. -### 5.1 Structural Shapes +## 7. Shape, Material, And Icon Grammar -| Meaning | Shape language | +| Meaning | Shape/material | |---|---| -| Guild/navigation | squared enamel tab with one clipped repair corner | -| Character/company | upright cloth pennant and portrait medallion | -| Route/place | small landscape silhouette on a tied route cord | -| Threat | angular forecast acetate with one pointed time edge | -| Reward/item | physical object silhouette on a shallow inventory tray | -| Safe/secured | closed clasp and complete outer contour | -| Risk/unsecured | open clasp and dashed outer contour | -| Locked | physical cross-pin plus named condition; never padlock alone | -| Completed | repaired seam and stamped receipt, not confetti alone | +| Global navigation | squared enamel tab with one clipped corner | +| Recruit identity | upright woven marker plus unframed full or half figure | +| Profession | stamped tool silhouette backed by a square field | +| Trait | single hexagonal seal with benefit edge and cost notch | +| Equipment | physical object silhouette on a shallow metal tray | +| Artifact | shared-rule emblem on a full-width ledger strip, visually separate from equipment | +| Party position | numbered stitched marker joined to one horizontal cord | +| Known threat | angular forecast sheet with a pointed time edge | +| Uncertainty | broken outer contour and explicit confidence text | +| Safe completion | closed contour, receipt stamp, and named result | +| Destructive consequence | split edge and warning sentence; not a solid red fill | +| Locked | cross-pin plus named requirement; never an unexplained lock icon | -Cards use a maximum `8 px` reference corner radius. Panels are docked to an -edge, table, shelf, satchel, slate, or other physical parent. Cards never sit -inside decorative cards; nested detail uses dividers and sub-rows. +Cards have at most `8 px` corner radius. Cards are reserved for repeated shop +offers, repeated reward choices, and transaction reviews. A card contains rows +and dividers, not more cards. Page sections remain edge-docked or unframed. -### 5.2 Icons +Familiar tools use familiar symbols from the implementation's approved icon +library: Back, close, settings, pause, play, speed, inspect, compare, filter, +sort, search, undo, speaker, controller, download, and warning. Unfamiliar +profession, trait, status, resource, or threat icons always pair with localized +text and expose a tooltip or touch Inspect action. -The core icon set uses a consistent 24/32/48-pixel vector envelope, 2.25-pixel -reference stroke, squared rounded ends, and one internal negative-space motif. -Icons must remain recognizable in high contrast and grayscale. Each status has: +Icon envelopes are `24`, `32`, and `48` logical pixels with a consistent +reference stroke. Filled/outline alone may not distinguish two state meanings. -- silhouette icon; -- short localized name; -- one-line mechanical effect; -- source and remaining duration/stack when applicable; -- event-log form. +## 8. Core Components -Familiar actions use familiar symbols: back arrow, gear, pause, play/speed, -speaker, controller, compare, pin, search, filter, sort, undo where legal, and -close. Tooltips name unfamiliar icons; touch uses the same content through -tap-and-hold or inspect. +### 8.1 Action Control -## 6. Core Components +One primary action appears in each decision region. The label uses an explicit +verb and includes cost or outcome when sourced: `Recruit - [price]`, not +`Confirm`. -### 6.1 Action Control - -One primary action per decision region. Primary buttons combine an icon, action -verb, and cost/consequence when one exists: `Secure Cache - 1 Supply`, not -`Confirm`. Icon-only controls are reserved for universal tools and always carry -accessible labels/tooltips. - -| Variant | Surface | Example | +| Variant | Composition | Behavior | |---|---|---| -| Primary | repair-gold enamel, ink text, raised upper edge | Begin expedition | -| Tactical | command-blue mechanism with charge notch | Retune - 1 Command | -| Safe commit | ally-jade clasp and explicit result | Bank 180 Crowns | -| Risk commit | paper surface with coral/copper exposed edge | Press on - 180 at risk | -| Destructive | paper surface, coral broken edge; never filled red by default | Salvage item | -| Disabled | material remains, mechanism pin inserted, reason beside it | Requires 1 Supply | +| Primary | gold enamel edge, ink label, leading familiar icon | performs or opens the named decision | +| Inspect | mist surface, cobalt double contour | opens reversible detail | +| Safe commit | jade completion edge and closed contour | states retained result | +| Risk commit | mist surface with coral split and uncertainty mark | states exposure and next state | +| Destructive | neutral surface, coral split, full consequence nearby | requires explicit review gesture | +| Disabled | intact material with cross-pin and reason | remains inspectable; no press or success cue | +| Pending | stable width, progress label, controls locked to operation ID | cannot submit twice | -Press state begins within 50 ms. Legal commit feedback begins within 100 ms of -authoritative state. Disabled controls do not depress or play a success sound. +The touch target is at least `48x48`; primary and destructive actions target +`56` high on touch layouts. Press feedback begins within `50 ms`; confirmed +local feedback begins within `100 ms` of authoritative receipt. Pending state +does not change component dimensions. -### 6.2 Resource Rail +### 8.2 Status Rail -The top rail displays only resources relevant to the current shell. Guild: -Crowns, objective, selected company readiness, save. Expedition: Supplies, -Cache, Strain alert, Anchor distance. Battle: Command, Cache risk, objective, -speed/pause. Each item includes name on expansion and exact delta animation -bound to the committed transaction. +The top rail contains only information needed by the current decision: -### 6.3 Adventurer Representation +- Guild: `BIND:RUN_PHASE`, relevant `BIND:RUN_RESOURCES`, readiness, save health; +- Shop: spendable value, refresh status, offer validity; +- Party: capacity binding, validation, selected pressure; +- Battle: objective, playback state, urgent condition, save/snapshot state; and +- Result: outcome receipt and unresolved next transaction. -Each adventurer appears at three canonical scales: +Each resource has localized name on focus/tap, icon, exact value, recent delta, +and pending/confirmed state. Unknown and zero are visually and semantically +different. -- `portrait`: head/shoulders with signature garment and expression; -- `company figure`: full-body 220-320 px reference height for planning and hub; -- `battle actor`: full-body 150-230 px based on lane depth, preserving weapon, - profession overlay, face direction, and condition silhouette. +### 8.3 Shop Offer Row -Profession equipment augments a stable character base rather than replacing the -character with a generic class sprite. Selected, targeted, Downed, Strained, -Hushed, Anchored, and protected relationships change stance/markers in addition -to color. +Recruit offer order is: figure or portrait, generated name, profession, trait +benefit/cost, two decision-relevant rolled reads, price, and Inspect. Item offer +order is: object, name, behavior, eligibility/conflict, price, and Inspect. -### 6.4 Item Row +Rows share stable height per text scale. Selection adds an external contour and +comparison region; it does not push adjacent rows. Sold, expired, unaffordable, +and selected states keep the original stable ID visible. -An item row shows object art, name, slot/tier, owned/equipped state, one-sentence -behavior, and one exact relevant delta. Expanded comparison shows all derived -changes, affected skill/timing events, unique-group conflicts, acquisition, and -salvage consequences. Raw power score is never the primary sort or visual size. +### 8.4 Recruit Identity -### 6.5 Telegraph +The component has four canonical scales supplied by +`BIND:ART_RECRUIT_PRESENTATION`: -A telegraph is anchored to the acting enemy and projected onto the affected -lane/targets. It includes action icon/name, countdown wedge, target line, effect -value/status, and at least two counter tags or a named mitigation rule. At 1x, -the most urgent telegraph receives scale/contrast priority; additional -telegraphs stack along the event rail without covering actors. +| Scale | Required reads | +|---|---| +| Marker | stable portrait/silhouette, profession emblem, trait seal, condition | +| Roster | generated name, profession, trait tradeoff, readiness, deployed state | +| Planning figure | full silhouette, equipment read, order number, health/condition | +| Battle actor | profession/tool silhouette, target/protection relation, health, urgent status, death/exit | -### 6.6 Route Node +The generated name and stable ID are text. Profession is never inferred from +color alone. Trait shows exactly one benefit edge and one cost notch before its +expanded mechanical sentence. Survival history uses a small set of sourced +marks and never becomes a fixed personal-story track. -Node art shows the actual place type and its pressure. The marker contains: +### 8.5 Equipment Row And Comparison -- place silhouette; -- encounter type shape; -- forecast confidence; -- reward family; -- supply/cache consequence when known; -- objective/recruit/mastery marker if authored. +An item row shows object, name, equipment position from `BIND:EQUIPMENT_RULES`, +current wearer, one behavior sentence, eligibility, and relevant sourced delta. +Comparison aligns current and candidate by mechanical field; unchanged fields +remain visible but quiet. Conflicts name the other item or rule. -Selected nodes lift from the cord and extend the lower comparison band. A -completed node becomes a stamped travel note while the world art remains. +Apply does not enable until replacement, returned item, invalidated reference, +and reversibility are known. Raw power score, rarity, or price is never the sole +or largest comparison read. -### 6.7 Modal And Review +### 8.6 Party-Line Editor -Review surfaces are sheets physically attached to the current context, occupy -no more than 62% of the reference canvas, and preserve the affected subject. -They state `Before`, `After`, `Cost`, `Risk`, and `Can undo?` using the actual -transaction. Destructive reviews place Cancel left/default and the explicit -verb right after adequate separation. +One horizontal cord runs from `First exposed` at left to `Last` at right. Every +prepared recruit occupies a stable numbered marker joined to that cord. The +component renders the count from `BIND:PARTY_CAPACITY`; it never labels an +assumed maximum. -## 7. Canonical Layout Families +Each marker has a fixed aspect ratio and minimum size. At dense target widths, +all order markers remain visible while the selected recruit expands into the +context rail; nonselected figures use simplified but distinct silhouettes. If +future sourced capacity cannot fit at minimum size, the cord scrolls by whole +positions with sticky First/Last indicators and a full miniature order strip. -### 7.1 Title: `SYS-004` +Selecting a recruit then a destination previews only sourced changes: -- Full-bleed Aster Yard at dawn; broken route arcs behind workers at real scale. -- Product name occupies the upper-left but no more than 22% of frame height. -- Continue sits lower-left over clear ground, followed by current slot summary. -- Settings, slots, and accessibility occupy a compact vertical tool rail. -- Ambient action: Oren seats a Waylamp contact, Mara signals, the route pulse - travels into one working pump. This is a state-change vignette, not random - particle motion. +- expected exposure and likely targets; +- protection given or received; +- reach and healing access; +- movement behavior; and +- replacement behavior after death or exit. -### 7.2 Guild Yard: `GLD-001` +Changed relations draw direct shaped connectors above the cord and list the +same changes in text. Undo and Reset are familiar icon controls with tooltips. +Drag is optional; tap-select/tap-destination and controller move are complete. -- Physical yard is central; objective repair is the primary focal object. -- Current company occupies a preparation platform and reflects loadout/Strain. -- Restored services are reachable by world hotspot and bottom destination dock. -- Objective board is a compact banner tied to the repair, not a floating quest - card. -- Chapter completion changes architecture, workers, sound layers, and route - light permanently. +### 8.7 Active Artifact Ledger -### 7.3 Roster And Adventurer: `GLD-003/004` +Artifacts are presented as run-wide rule modifiers, never as equipment attached +to a recruit. Each ledger row shows sourced emblem, name, changed rule, +acquisition receipt, active/inactive state, interactions, conflicts, and +lifecycle from `BIND:ARTIFACT_RULES`. Inspect uses the same vocabulary in Shop, +Reward, Guild, Battle, Result, and Records. Missing rules block dependent +commitment instead of reducing an artifact to rarity or flavor. -- Left 62%: company line and scrollable roster figures/portraits on a guild - muster wall; selected character remains a full-body subject. -- Right 38%: identity, talent, profession, readiness, and one Edit Loadout. -- Filters are a horizontal icon+text toolbar; no pill cloud. -- Adventurer detail changes the left background to their working space and - keeps relationship/history as physical annotations. +### 8.8 Risk Choice -### 7.4 Formation Workshop: `GLD-005` +Risk options are aligned by known pressure, uncertainty, entry cost, reward +class, recovery exposure, and current coverage. Options use different threat +silhouettes and comparison rows rather than promotional art or rarity frames. -- Center 66%: large 3x2 Weave Grid on a field table with real party figures. -- Protection arcs, predicted first targets, reach, and invalid positions update - immediately after tap-select/tap-destination or drag. -- Left strip: available/reserve figures. -- Right slate: encounter pressure, validation, role diversity, first event. -- Bottom-right primary: `Confirm Company`; preset/undo are icon tools. +The selected option expands in place. The commitment surface remains attached +to it and displays the accepted party snapshot. Unknown information is a +sourced uncertainty state, not an empty value or hidden tooltip. -### 7.5 Profession, Skill, And Equipment: `GLD-007..009` +### 8.9 Battle Actor And Event Projection -- Character remains visible at left with profession/equipment silhouette layers. -- Center is one current decision: branch tree, four skill slots, or four gear - slots. It is never three equal nested panels. -- Right comparison slate shows the real timeline/stat/behavior difference. -- A branch choice previews signature pose, resource device, skill behavior, and - counter surface; it is not only a node name in a tree. +The battlefield owns at least `68%` of usable area. Party and enemy actors +occupy one readable horizontal encounter space with depth offsets and authored +staging from media bindings. Order remains legible through numbered ground +marks and target/protection connectors; the planning cord itself is not drawn +as a large HUD over combat. -### 7.6 World And Chapter: `WLD-001..003` +Actor-attached information is limited to: -- World map is an illustrated network, not a level-select grid. -- Restored route lines physically animate from local services to the First - Junction. Ruptures interrupt geography with a dark silent seam. -- Selected chapter opens a horizontal travel folio: full region art, learning - question, current transformation, characters, and Enter Chapter. -- The settlement screen brings named residents and the threatened service to - the foreground before route choices appear. +- health or other sourced survival state; +- urgent status icon and short label; +- current target relation when relevant; and +- order marker for allied recruits. -### 7.7 Expedition Route: `EXP-002/003` +Only the greatest immediate danger expands automatically. Other values remain +compact and are available through Inspect. Event projections originate at the +acting subject, name affected targets, include time/order, and keep actors +visible. -- Route cords traverse the region art and visibly converge at Anchors. -- Two prospective branches occupy distinct parts of the landscape so the player - can point to them before reading. -- Lower comparison band aligns threat, counter, reward, supply/cache impact, and - objective consequence column-for-column. -- `Commit node` appears only after selection; inspect never commits. +### 8.10 Playback And Inspect Tools -### 7.8 Encounter Preview: `EXP-004` +Pause, play, speed, and inspect use symbol-first controls with tooltips and +accessible labels. Speed is a segmented symbol control populated by +`BIND:BATTLE_SPEEDS`; changing it never looks like a combat action. Retreat is +inside Pause and separated from Resume by layout and review. -- Enemy group and battlefield occupy 62%; the actual first formation is visible. -- A forecast acetate overlays up to three major mechanics with timing and lanes. -- Bottom formation strip allows limited company changes without leaving preview. -- Right comparison shows `First target`, `First major threat`, `Counters in - company`, and `Missing coverage`. -- Start Battle is the only primary action. Research opens as a drawer. +Inspect freezes or preserves playback according to sourced rules and opens: -### 7.9 Live Battle: `BAT-002` +1. selected event and source; +2. target and order reason; +3. equipment, profession, trait, or status contribution; +4. immediately preceding cause; and +5. downstream event when already known. -- Actors and lane action remain unobstructed across at least 68% of the screen. -- Enemy telegraphs originate in the world. The next-event strip on top confirms - sequence but does not replace world projection. -- Ally HP/Guard/Ward bars are compact and attached to feet; only the greatest - immediate risk expands automatically. -- Two Directive mechanisms sit bottom-center at thumb reach with visible - charges and legality. They are not large text rectangles. -- Pause/speed/log sit top-right; retreat lives inside Pause to prevent accidents. -- Cache strap at far right shows secured/unsecured via closed/open clasp. +On short phones or at 130%, this becomes a full-screen linear view. Closing it +restores the exact prior playback state. -### 7.10 Directive Flow: `BAT-005..007` +### 8.11 Causal Timeline -- Selection slows/pauses according to rules and expands the two prepared - mechanisms; illegal one remains inspectable with reason. -- Targeting uses actor/lane outlines, not a cursor disconnected from the scene. -- Review draws one insertion on the visible event timeline and states cost and - changed forecast. -- Confirm uses the Directive symbol; Cancel returns to battle with zero spend. +Result uses a two-track timeline: expected responsibilities from the accepted +party snapshot above, actual events below. The first meaningful divergence has +the strongest contour and direct connectors to affected recruits, enemy event, +equipment, and order relation. Totals and rankings are secondary. -### 7.11 Diagnosis And Recovery: `RES-002..004` +Every event has a stable icon, timestamp/order, source, target, outcome, and +accessible text. `Cause unavailable` is an error state. A neutral result may +state that no preventable divergence was detected. -- Timeline fills the center, with predicted plan above and actual events below. -- The first divergence is physically linked to the involved actor, item/order, - and enemy telegraph. -- The page names `What happened`, `Why`, and two legal adjustments. It never - declares a universal best build. -- Failure transaction shows people retained before value lost. Recovery choices - use three distinct scene exits: reconfigure at Anchor, training ring, Guild. +### 8.12 Death And Party Gap -### 7.12 Reward And Cache: `EXP-008/009` +Loss presentation is quiet and explicit. The affected recruit remains visible +at a respectful readable scale with generated name, stable ID, profession, +trait, level, survival marks, equipment disposition, and committed receipt. +The adjacent party cord shows the new gap and sourced replacement behavior. -- Three rewards are actual illustrated objects on a field cloth, not equal - rarity cards. Relative scale is normalized so large weapons do not imply value. -- Selecting one shows which current character/skill/event changes and the exact - behavior. -- Accept visibly moves the object into the open Cache satchel; banked inventory - remains visually separate. -- Cache management displays real lines and deterministic loss examples rather - than only total percentage. +The Acknowledge action does not suggest reversal. Recovery and replacement are +separate next decisions supplied by their bindings. No celebratory particles, +rarity framing, or generic red overlay accompanies death. -### 7.13 Records: `REC-001..009` +### 8.13 Reward Choice -- Records atrium is a physical evolving guild room. Category selection uses - shelves, specimen tables, profession loom, portrait ledger, and collection - displays. -- List/detail screens preserve a large focal illustration and use a single - scroll track for entries rather than nested grids. -- Unknown content distinguishes `not encountered`, `observed but not - researched`, and deliberately undisclosed information. +Rewards appear as actual object, profession, recruit, or rule presentations +supplied by content and media bindings. Equal-size decision regions prevent +object scale from implying value. Each option names: -### 7.14 Settings: `SET-001..010` +- the next decision it changes; +- current eligible target or party interaction; +- conflict or opportunity cost; +- claim destination; and +- skip outcome when legal. -- A quiet unframed settings workspace replaces the world while retaining the - top-left back path and current category rail. -- Left category rail is 240 px at reference; right content begins with current - effect and interactive preview. -- Binary preferences use switches/checkboxes, finite option sets use segmented - controls or menus, volume uses sliders with numbers, remapping uses dedicated - input rows. -- Reset and delete are isolated at the bottom of Data and Reset; never next to a - routine toggle. +Claim animation begins only after receipt. The final state is a persistent +named ownership change, not particles alone. -## 8. Motion Language +### 8.14 Recovery Choice -Motion communicates work, pressure, and committed state. It does not make the -interface hover continuously. +Recovery options are unframed paths leaving the causal result: reconfigure, +replace, restore, or end the run only when supplied by `BIND:RECOVERY_OPTIONS`. +Each shows full cost, retained state, recruits affected, and next destination. +Unavailable paths remain inspectable with reason. -| Event | Anticipation | Impact | Recovery / final | Reduced motion | -|---|---:|---:|---:|---| -| Select | 40 ms edge tension | 90 ms lift/outline | stable raised state | instant outline and marker | -| Equip | 80 ms item draw | 140 ms layer seat + exact delta | 180 ms settle | crossfade final layer, delta remains | -| Route commit | 120 ms cord tension | node seal closes | camera travels 300-500 ms | instant selected route with direction arrow | -| Telegraph | actor windup authored per skill | lane projection locks | countdown remains linear | final poses + stepped countdown | -| Directive | mechanism arm 80-160 ms | event insertion and actor response | return to battle within 300 ms | event line and final pose only | -| Damage | readable anticipation from skill | 40-90 ms hit response and value | 120-240 ms recovery | no shake/hit-stop; contour/value change | -| Reward | object enters from encounter source | Cache clasp responds | item rests visibly in satchel | direct placement + receipt stamp | -| Restoration | service attempts once | route pulse reaches destination | persistent working loop begins | before/after dissolve and stable active pose | +### 8.15 Empty, Error, Notice, And Receipt -Continuous ambient animation is limited to the focal service, weather, and up -to three background workers/processes. Low-power mode samples them at reduced -frequency or replaces them with authored final poses. UI layout dimensions -never animate. +| Component | Required content | Forbidden behavior | +|---|---|---| +| Empty state | what is empty, why, legal next action | decorative illustration with no action | +| Loading state | named operation, blocked scope, progress when known | generic spinner over active controls | +| Inline error | plain cause, retained state, retry/alternate | raw internal exception or vanished content | +| Binding error | binding name in diagnostics, player-facing affected feature, safe exit | invented zero/default value | +| Notice | one changed fact and optional Inspect | stacking duplicate transient messages | +| Receipt | stable operation, committed result, timestamp/order, duplicate behavior | success feedback before authority confirms | +| Confirmation | target, before, after, cost, risk, undo policy | vague `Are you sure?` alone | -## 9. VFX Language +Notices reserve layout space or overlay noncritical world space. They never +cover the primary action, Back, playback tools, target projection, or focus. -- Aether routes: double-line cyan energy with visible direction nodes, never fog. -- Repair: gold seam closes from source to destination and leaves a material - change behind. -- Ally action: clean jade or profession-color arc tied to weapon/device motion. -- Enemy danger: coral forecast geometry appears before impact; impact may use - black ink fragments but cannot hide targets. -- Guard/Ward: Guard uses angular enamel plates; Ward uses circular glass rings. -- Break: stability contour fractures into four readable segments and exposes a - white center; reduced flashes uses no luminance spike. -- Hush: action glyph loses its secondary stroke; it is not merely desaturated. -- Strain: one to three tied violet repair knots on the character pennant. -- Anchored/Drift: ground pin versus directional cloth ribbon, both shape-coded. -- Reward/commit: physical item/value path reaches Cache, inventory, or service; - particles alone never imply ownership. +## 9. Canonical Layout Families -At reference size, concurrent transient VFX may cover no more than 18% of the -battlefield and may not overlap Directive controls or the next-event strip. +### 9.1 Title And Run Screens: `SYS-003..007` -## 10. Localization And Accessibility Behavior +- Full-bleed working guild threshold; the product name occupies no more than + one fifth of frame height. +- Continue and verified run summary sit together at lower-left on clear ground. +- Run ledger uses one unframed vertical list and one details rail. +- Accessibility, Settings, and run selection are compact tools, always visible. +- Save recovery uses an aligned lineage comparison, not competing alert cards. -- English and Simplified Chinese use the same component hierarchy, not separate - compressed layouts. -- Chapter titles may use an authored display treatment; all mechanics and - controls remain engine text. -- A telegraph, status, lane, rarity, and target relation use shape/pattern/text - in addition to color. -- Captions identify speaker/event direction through name and directional icon. -- All draggable operations have tap-select/tap-destination equivalents. -- Controller focus has a double white/ink contour and never uses hover alone. -- Important battle events remain accessible in a pauseable linear log. -- Reduced motion removes camera travel, parallax rotation, shake, and continuous - UI motion while retaining event timing and final state. -- Reduced flashes caps luminance change, removes full-screen white, halves - particles, and keeps forecast geometry. -- Master mute changes no gameplay; captions and visual telegraphs remain. -- At 130%, secondary details move into a drawer rather than shrinking type, - buttons, actors, or essential state. +### 9.2 Guild Desk And Forecast: `HUB-001/002` -## 11. Design Tokens And Implementation Handoff +- Current pressure is represented in the world and repeated in concise text. +- Shop, Roster, Equipment, Party Line, and Risk are stable edge destinations. +- The prepared party occupies a shallow muster strip that reflects current + profession, condition, equipment, and order. +- Latest result change uses one attached receipt strip and disappears only after + inspection, not on a timer. -The prototype and eventual engine theme must expose tokens rather than inline -screen styling: +### 9.3 Shop And Recruit: `SHP-001..003` + +- Left/main: scrollable offer rows on a physical requisition surface. +- Right/context: selected offer at planning scale with tradeoff, fit, and cost. +- Filters are icon+text tools; option sets use menus, not clouds of rounded text. +- Refresh is visually secondary and always displays sourced consequence. +- Recruit and Buy actions appear only inside their review state. + +### 9.4 Roster And Recruit Detail: `REC-001..003` + +- Roster uses a muster wall or line of markers plus one selected planning figure. +- Filters prioritize deployed state, profession, trait, readiness, and condition. +- Detail organizes Identity, Mechanics, Equipment, Position, and History as tabs + or a compact category rail; no biography-first hero page. +- Dismissal is isolated below routine preparation actions and opens a full + transaction review. + +### 9.5 Equipment: `EQP-001/002` + +- Selected recruit remains visible; eligible inventory forms one scroll track. +- Current and candidate objects align around the recruit, not inside nested + panels. +- Behavior delta is the first comparison read; eligibility and conflicts are + adjacent to Apply. +- At 130% on phone, item list and comparison become two explicit views with a + persistent selected-item summary. +- `ART-001` uses a separate full-width shared-rule ledger; it never reuses the + per-recruit equipment silhouette or Apply flow. + +### 9.6 Party Line And Readiness: `PTY-001/002` + +- The ordered cord spans the main surface with clear First and Last endpoints. +- Available recruits use a lower muster strip; selected recruit expands in the + context rail without changing marker positions. +- Relation connectors use distinct patterns and remain under a text summary. +- Readiness replaces editing with a frozen party snapshot and grouped warnings. +- Save Order is the only primary action; undo/reset are icon tools. + +### 9.7 Risk Board: `RSK-001/002` + +- Choices occupy distinct parts of a region scene and align to one comparison + band below. +- The band compares known threat, uncertainty, cost, reward class, recovery + exposure, and coverage in that order. +- Commitment slides from the selected option and keeps party snapshot visible. + +### 9.8 Battle: `BAT-001..006` + +- Actors and event projections dominate the scene; UI follows edges. +- Objective and next urgent event sit top-left; pause/speed/inspect sit top-right. +- Actor markers attach to subjects and collapse when not urgent. +- Inspect uses the context rail or a full-screen linear surface at 130%/phone. +- Retreat exists only inside Pause and uses a separated destructive review. +- Resume Review is static: verified timestamp, speed, pending event, and Resume. + +### 9.9 Result And Recovery: `OUT-001..005` + +- Causal timeline owns the center; outcome and unresolved transaction remain in + a compact top strip. +- Affected recruits remain visible beside the event that changed them. +- Death review isolates one loss at a time with a persistent multi-loss index. +- Reward objects or rules use equal decision regions under the diagnosis. +- Recovery paths are distinct exits with complete transactions, not three + decorative cards. + +### 9.10 Progression, Records, And Postgame: `PRO-001..PST-003` + +- Progression emphasizes the decision each unlock opens and its prerequisite, + not a giant ornamental branching illustration. +- Records use one category rail, one entry list, and one large detail subject. +- Unknown content differentiates not encountered, partially known, and + deliberately undisclosed. +- Postgame setup keeps active modifiers, eligibility, slot, and ordinary New Run + access visible before commitment. + +### 9.11 Settings: `SET-001..009` + +- Settings is a quiet unframed workspace with category navigation and a live + preview where useful. +- Binary values use switches or checkboxes; small mutually exclusive sets use a + segmented control; larger option sets use menus; numbers use sliders with + displayed values; remapping uses dedicated input rows. +- Reset and deletion sit at the bottom of their own category, separated from + routine controls. +- Caller and Back destination remain visible: Title, Guild, or paused Battle. + +## 10. Interaction And Focus + +### 10.1 Focus Order + +Focus begins at screen heading, then the current state summary, primary content, +context rail, primary action, and secondary tools. The primary action is not +automatically focused after a destructive warning. Modal focus begins on +Cancel. Focus never follows moving actors or animation. + +Controller focus uses a `3 px` white outer and `2 px` ink inner contour plus a +small cobalt corner mark. Touch selection uses the same contour and a selected +label. Pointer hover may preview focus but cannot reveal unique content. + +### 10.2 Ordering And Selection + +- Selection and commitment are separate states. +- All drag operations have tap-select/tap-destination and controller paths. +- Reorder controls preserve stable IDs and announce old/new positions. +- Lists retain focus through sort/filter when the stable ID remains visible; + otherwise focus moves to Clear Filters or the first result with an + announcement. +- Double tap/press is not required for any essential action. + +### 10.3 Feedback And Haptics + +Visual feedback always carries meaning without audio or vibration. Haptics, when +available and enabled, distinguish focus movement, legal selection, confirmed +receipt, and blocked action. They never announce battle information that lacks +a visual and text equivalent. + +## 11. Motion, Effects, And Low Power + +Motion communicates source, direction, urgency, commitment, and final state. +Layout dimensions do not animate. + +| Event | Normal | Reduced motion | Reduced flashes | Low power | +|---|---|---|---|---| +| Select | `90 ms` edge lift and contour | instant contour and marker | unchanged geometry, no luminance spike | final selected state only | +| Recruit/equip receipt | source travels to roster/wearer, then stamped receipt | direct crossfade to final state plus receipt | no bright burst | final state and receipt only | +| Reorder | marker follows cord, relation connectors redraw | immediate position swap with numbered before/after | no flash | immediate final order | +| Risk commit | selected path tightens and scene advances | final selected route plus direction arrow | solid edge instead of pulse | static committed state | +| Event warning | authored anticipation and target projection | stepped poses and persistent geometry | capped luminance; no full-screen white | essential source/target frames only | +| Impact | short response and exact value/status change | no shake or hit pause | contour/value change; reduced particles | final actor state and event row | +| Death | readable exit followed by stable loss marker | direct final pose/marker | no fade-to-white | final pose/marker | +| Reward | ownership path then receipt | direct placement and receipt | no sparkle burst | receipt plus final placement | + +Reduced motion removes camera travel, parallax, continuous UI motion, and +nonessential ambient loops. Reduced flashes removes full-screen flashes, +alternating high-contrast frames, and rapid particle bursts. Low power lowers +ambient update frequency, effect density, and nonessential layer animation; it +does not change event order, timing rules, target clarity, decisions, or +receipts. + +Only one nonessential ambient focal process and two background loops run on a +short phone. They freeze under overlays and never resemble event warnings. + +## 12. Audio-Independent And Visual Accessibility + +- Master mute changes no mechanic, event order, target visibility, transaction, + or available decision. +- Captions name event, source, direction, and outcome using + `BIND:AUDIO_EVENT_CATALOG`; environmental captions remain visually quieter + than dangerous battle events. +- Output loss raises one nonblocking notice and keeps captions plus event + geometry active. +- Mono compatibility is verified by ensuring no necessary cue depends on stereo + position alone. +- Color-independent patterns distinguish safe, harmful, uncertain, selected, + disabled, and complete. +- High contrast simplifies region textures behind labels and actors without + replacing region identity. +- Screen-reader order follows the focus order. Party positions are announced as + `position [index], [name], [profession], [condition]`; battle events announce + source, action, target, outcome, and time/order. +- A pauseable full-screen event log provides all urgent automatic battle + information in chronological text. +- Controls retain at least `48x48` targets at every scale and do not overlap + device insets, captions, notices, or each other. + +## 13. State Grammar + +Every reusable actionable component implements these semantics consistently: + +| State | Visual/text contract | Input result | +|---|---|---| +| Available | full subject, action verb, sourced cost/effect | opens inspect/review or commits only where explicitly allowed | +| Focused | double contour, corner marker, complete accessible name | first activation selects or invokes the stated tool | +| Selected | raised edge/check, selected label, stable dimensions | enables review; activation alone does not spend | +| Pending | operation name and progress, unchanged geometry | duplicate input ignored; Cancel only if source allows | +| Active | active label and persistent state marker | inspectable; does not restart | +| Unaffordable | current and required values plus shortfall | inspectable; commit disabled | +| Incompatible | conflicting stable subject/rule and correction path | inspectable; commit disabled | +| Locked | named prerequisite and where to meet it | opens requirement when legal | +| Temporarily unavailable | reason and restoring event | inspectable; no success feedback | +| Complete | named result and receipt mark | opens result; cannot claim again | +| Recoverable error | plain cause, retained state, Retry/Alternate | retries with operation identity | +| Blocking error | affected binding/integrity boundary and safe exit | cannot continue dependent workflow | + +State words in localized copy must remain semantically distinct. Disabled +opacity alone is insufficient, and disabled text still meets contrast targets. + +## 14. Design Tokens And Handoff ```text space: 4, 8, 12, 16, 24, 32, 48, 64 radius: 0, 4, 8 control_min: 48 +touch_primary_min: 56 stroke: 1, 2, 3 -safe_small: 56x40 +safe_phone: 56x40 + device insets +safe_tablet: 64 + device insets safe_reference: 96 -panel_max: 720 -drawer_width: 420 / 560 -motion_fast: 90ms +context_rail: 360, 420, 520 +motion_select: 90ms motion_commit: 180ms -motion_reward: 480ms +motion_receipt: 360ms focus_outer: 3px white focus_inner: 2px ink +text_scale: 100%, 115%, 130% ``` -Stable component IDs, icon IDs, material sprites, localized strings, animation -events, and semantic colors must be declared in data. A screen may choose a -chapter material variant but cannot redefine state meaning or interaction. +The later prototype and runtime theme must declare stable component IDs, screen +IDs, localized strings, semantic tokens, focus order, icon IDs, operation IDs, +and binding references in structured data. Screen-specific styling may select a +region material but may not redefine state, color semantics, transaction rules, +focus, or accessibility behavior. -## 12. Presentation Acceptance Checklist +Every gallery frame must record: -- [ ] The title, Guild, route, battle, failure, reward, and restoration read as - a working magical repair expedition without explanatory title copy. -- [ ] World/actor art occupies the primary surface; UI is docked and not a card - wall. -- [ ] Battle priority is telegraph, threatened ally, then Directive. -- [ ] Every control shows state, cost/condition, and consequence. -- [ ] All canonical layouts remain functional at 1280x720, 1920x1080, - 2560x1440, English, zh_CN, and 130%. -- [ ] Touch, mouse/keyboard, and controller share the same verbs and no drag is - required. -- [ ] Reduced motion/flashes, mute, high contrast, and low power preserve - decisions and final state. -- [ ] Chapter palettes and compositions remain distinct without changing - semantic UI color. -- [ ] Generated or drawn art is not called final before source, processing, - integration, runtime, agent, human, and device states are recorded. +- screen ID and state; +- viewport and safe-area fixture; +- language and text scale; +- input mode and focus target; +- motion, flash, audio, contrast, and power settings; +- resolved and intentionally unresolved bindings; and +- source revision plus whether the frame is static or interactive. -The next presentation authority must enumerate the exact art, animation, VFX, -music, ambience, and SFX required to realize this system. +## 15. Presentation Acceptance Checklist + +- [ ] The actual shop, recruit, equipment, artifact, party, risk, battle, result, death, + reward, recovery, progression, Settings, and postgame decisions dominate + their pages. +- [ ] Generated recruits remain replaceable run participants and still read as + distinct mechanical identities at roster, planning, and battle scales. +- [ ] The ordered party is immediately readable from First to Last on landscape + phone and tablet without moving controls or shrinking labels below tokens. +- [ ] Automatic battle prioritizes urgent cause, affected actors, objective, + playback state, and inspect; no control implies insertion of an attack or + skill into the timeline. +- [ ] Result names the earliest meaningful divergence before totals or rewards. +- [ ] Every action exposes state, target, cost, consequence, reversibility, + pending state, receipt, and safe return where applicable. +- [ ] Every screen remains functional at required phone/tablet fixtures, + English, Simplified Chinese, and 130% text/UI scale. +- [ ] Touch, controller, and keyboard/mouse support the same complete verbs; no + essential action depends on drag, hover, double tap, or pointer precision. +- [ ] Reduced motion, reduced flashes, mute/captions, high contrast, screen + reader order, and low power preserve decisions and causal information. +- [ ] Cards remain limited to repeated items and reviews; world/actors are the + primary surface and components do not nest decorative containers. +- [ ] Gameplay values and media identities remain sourced bindings until their + owning authorities integrate them. +- [ ] No design fixture is described as implementation, final media, device, + comprehension, fun, packaging, store, or release acceptance.