wushenghua/aetherbound-guild
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define landscape game UI and visual system

Browse Source
This commit is contained in:
wushenghua
2026-08-10 20:05:42 +08:00
parent a90f9737bb
commit 0548792b3f
1 changed files with 519 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/presentation/UI_AND_VISUAL_SYSTEM.md
+519
View File
@@ -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.