From 0548792b3fda1e4bd08f62f8621bb73bab5da6f1 Mon Sep 17 00:00:00 2001 From: wusumac <736139669@qq.com> Date: Mon, 10 Aug 2026 20:05:42 +0800 Subject: [PATCH] docs: define landscape game UI and visual system --- docs/presentation/UI_AND_VISUAL_SYSTEM.md | 519 ++++++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 docs/presentation/UI_AND_VISUAL_SYSTEM.md diff --git a/docs/presentation/UI_AND_VISUAL_SYSTEM.md b/docs/presentation/UI_AND_VISUAL_SYSTEM.md new file mode 100644 index 00000000..069e21fe --- /dev/null +++ b/docs/presentation/UI_AND_VISUAL_SYSTEM.md @@ -0,0 +1,519 @@ +# Aetherbound Guild: UI And Visual System + +> Authority: landscape composition, visual identity, semantic color, type, +> component behavior, motion, and canonical layout families. +> +> 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. + +## 1. Visual Thesis + +**A working magical expedition journal laid over a living hand-painted 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 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. + +### 1.1 Experience Reads + +| State | First read | Second read | Third read | Intended 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 | + +### 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. + +## 2. Canvas, Camera, And Safe Areas + +The design canvas is `1920x1080`, rendered responsively at a fixed landscape +aspect policy. + +| Target | Logical viewport | Safe area | 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 | + +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. + +On-screen subjects have protected composition zones: + +- 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. + +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. Semantic Palette + +The palette combines daylight pigments and dark ink structure. No single hue +family owns more than half of a normal scene. + +| Token | Color | Role | Non-color backup | +|---|---|---|---| +| `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 | + +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. + +### 3.1 Chapter Palette Shifts + +| Chapter | Dominant environment pigments | Aether interruption | Avoid | +|---|---|---|---| +| 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 | + +## 4. Typography And Numeric Display + +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. + +Reference sizes at `1920x1080` and 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 | + +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. + +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. + +## 5. Shape, Material, And Icon Grammar + +### 5.1 Structural Shapes + +| Meaning | Shape language | +|---|---| +| 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 | + +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. + +### 5.2 Icons + +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: + +- silhouette icon; +- short localized name; +- one-line mechanical effect; +- source and remaining duration/stack when applicable; +- event-log form. + +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. + +## 6. Core Components + +### 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 | +|---|---|---| +| 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 | + +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. + +### 6.2 Resource 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. + +### 6.3 Adventurer Representation + +Each adventurer appears at three canonical scales: + +- `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. + +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. + +### 6.4 Item Row + +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. + +### 6.5 Telegraph + +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. + +### 6.6 Route Node + +Node art shows the actual place type and its pressure. The marker contains: + +- place silhouette; +- encounter type shape; +- forecast confidence; +- reward family; +- supply/cache consequence when known; +- objective/recruit/mastery marker if authored. + +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. + +### 6.7 Modal And Review + +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. + +## 7. Canonical Layout Families + +### 7.1 Title: `SYS-004` + +- 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. + +### 7.2 Guild Yard: `GLD-001` + +- 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. + +### 7.3 Roster And Adventurer: `GLD-003/004` + +- 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. + +### 7.4 Formation Workshop: `GLD-005` + +- 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. + +### 7.5 Profession, Skill, And Equipment: `GLD-007..009` + +- 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. + +### 7.6 World And Chapter: `WLD-001..003` + +- 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. + +### 7.7 Expedition Route: `EXP-002/003` + +- 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. + +### 7.8 Encounter Preview: `EXP-004` + +- 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. + +### 7.9 Live Battle: `BAT-002` + +- 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. + +### 7.10 Directive Flow: `BAT-005..007` + +- 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. + +### 7.11 Diagnosis And Recovery: `RES-002..004` + +- 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. + +### 7.12 Reward And Cache: `EXP-008/009` + +- 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. + +### 7.13 Records: `REC-001..009` + +- 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. + +### 7.14 Settings: `SET-001..010` + +- 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. + +## 8. Motion Language + +Motion communicates work, pressure, and committed state. It does not make the +interface hover continuously. + +| 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 | + +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. + +## 9. VFX Language + +- 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. + +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. + +## 10. Localization And Accessibility Behavior + +- 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. + +## 11. Design Tokens And Implementation Handoff + +The prototype and eventual engine theme must expose tokens rather than inline +screen styling: + +```text +space: 4, 8, 12, 16, 24, 32, 48, 64 +radius: 0, 4, 8 +control_min: 48 +stroke: 1, 2, 3 +safe_small: 56x40 +safe_reference: 96 +panel_max: 720 +drawer_width: 420 / 560 +motion_fast: 90ms +motion_commit: 180ms +motion_reward: 480ms +focus_outer: 3px white +focus_inner: 2px ink +``` + +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. + +## 12. Presentation Acceptance Checklist + +- [ ] 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. + +The next presentation authority must enumerate the exact art, animation, VFX, +music, ambience, and SFX required to realize this system.