aetherbound-guild/docs/presentation/UI_AND_VISUAL_SYSTEM.md

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.

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:

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.