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

docs: repair onboarding presentation flow

Browse Source
This commit is contained in:
wushenghua
2026-08-11 10:04:22 +08:00
parent c0666cba07
commit 14ea46ecdb
2 changed files with 229 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/presentation/UI_AND_VISUAL_SYSTEM.md
+143 -32
View File
@@ -39,12 +39,13 @@ lead who must remain in the party.
| Moment | First read | Second read | Third read | Desired feeling |
|---|---|---|---|---|
| Title | active guild threshold and distant unstable route | current safe run state | Continue and accessibility access | invited, not advertised to |
| New run setup | four equally weighted provisional Recruit offers | selected `0/2..2/2` and comparison | Review Company then Create Run | consequential choice without a recommended build |
| 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 |
| Final-survivor dismissal | disabled Dismiss and `One member must remain` | separate run-abandonment action | retained Recruit and zero-delta result | protected consequence without a dead end |
| 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 |
| Party line | protected rear-left through numbered positions to exposed front-right | 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 |
@@ -141,6 +142,7 @@ readable silhouette.
| Decision surface | Primary | Secondary | Deferred to inspect |
|---|---|---|---|
| Guild desk | upcoming pressure, latest change, preparation readiness | sourced resources and open decisions | complete run history |
| New run setup | four stable provisional identities, Profession job, Trait benefit/cost, selected count | rolled distribution, default loadout, Contract/difficulty | unrelated catalog and future progression |
| 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 |
| Dismissal/abandonment | eligibility and affected scope | returned equipment, rebate or run-close consequence | unrelated Recruit history |
@@ -295,7 +297,69 @@ 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.
### 8.4 Recruit Identity
The first-Market variant marks at least two sourced base-Profession Recruit
offers as affordable without marking either `recommended`. A persistent opening
status reads owned Company separately from Line capacity and updates only from
authoritative hire receipts: `Company 2 | Line capacity 4`, `Company 3 | Line
capacity 4`, then `Company 4 | Line capacity 4`. Each hire keeps its own review,
cost, receipt, and focus return; no combined `Hire two` action exists.
### 8.4 Provisional Recruit Selector
`SYS-005` uses a dedicated provisional variant, not the Shop offer row. It
renders exactly four stable positions from `BIND:PROVISIONAL_RECRUIT_OFFERS` and
never shows price, refresh, lock, rarity promotion, or purchase language.
Each overview marker has stable dimensions and contains:
- generated name and stable offer ID;
- Recruit figure/portrait at the common marker scale;
- base Profession icon, localized job sentence, and target/reach read;
- Trait seal with one benefit and one cost;
- one decision-relevant rolled distribution read;
- `No Coin cost`;
- a Select checkbox with a checkmark that does not imply Party-line order; and
- a separate Inspect icon with accessible label.
Touch activation on Select toggles Company selection; tapping the marker only
focuses it and opens no destructive state. Controller focus enters offers in
stable source order; Select toggles the focused offer, while Inspect opens and
closes its full details without changing selection. Compare is a separate
command: it pins offer `A`, then offer `B`, and opens an aligned Profession,
Trait, attribute, and default-loadout comparison. The A/B pair may use any two
offer IDs and never changes the two Company checkboxes.
The selected-count component has fixed dimensions and explicit states:
| State | Label and control state | Result |
|---|---|---|
| none | `Choose two - 0/2`; Review Company disabled | Inspect, Compare, Back, and first selection remain legal |
| one | `Choose one more - 1/2`; one stable ID checked | selecting a second enables review |
| two | `Company selected - 2/2`; both stable IDs checked; Review Company enabled | either selection may be cleared or replaced before review |
| third attempt | `Two already selected`; current two remain unchanged | focus moves to the selected-count explanation; no automatic eviction |
| invalid source | expected four/received count or affected stable ID; all Select controls disabled | Retry Same Set or Return to Run Ledger |
| loading | four fixed skeleton positions, named operation, no identity or selection | resolved stable ID stays in its original position |
Review replaces details without discarding the four-offer strip. The selected
two occupy the main Company comparison; the two unchosen stable IDs remain in a
quiet `Not retained` summary. `Revise Recruits` returns to the same four
positions, selected IDs, A/B comparison, and focus. Create Run is the only
primary action and enters a fixed-size pending state, so a spinner or long
localized status cannot shift Revise, Cancel, or offer markers.
On a short landscape phone, the four markers form a fixed `2 x 2` layout; the
selected marker's details replace the context rail. On tablet/reference they
form one four-marker row above one comparison region. At 130%, generated names
may wrap to two lines and the Profession/Trait text moves to Inspect, but all
four identities, checked state, `0/2..2/2`, Select, Inspect, Compare, Back, and
Review Company remain visible. English (`en`) and Simplified Chinese (`zh_CN`)
share offer order and control geometry.
No offer starts selected, pulses as preferred, receives a larger portrait,
sorts by a hidden score, or gains a tutorial arrow. Teaching may highlight the
Select and Inspect controls as a group, never one Recruit.
### 8.5 Recruit Identity
The component has four canonical scales supplied by
`BIND:ART_RECRUIT_PRESENTATION`:
@@ -312,7 +376,7 @@ 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.
### 8.5 Equipment Row And Comparison
### 8.6 Equipment Row And Comparison
An item row shows object, name, equipment position from `BIND:EQUIPMENT_RULES`,
current wearer, one behavior sentence, eligibility, and relevant sourced delta.
@@ -323,7 +387,7 @@ 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.
### 8.6 Dismissal And Run Abandonment
### 8.7 Dismissal And Run Abandonment
Dismiss is a destructive text-and-icon action below routine Recruit actions.
Its state comes from `BIND:DISMISSAL_ELIGIBILITY`, which uses the total live
@@ -360,18 +424,20 @@ separate abandonment action occupy three stable rows. They do not overlap the
Recruit name, Back, or safe-area inset. The Simplified Chinese (`zh_CN`) fixture
may wrap each label to two lines without merging the two actions.
### 8.7 Party-Line Editor
### 8.8 Party-Line Editor
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.
One horizontal cord runs from `Protected rear` at left to `Exposed front` at
right. The rightmost occupied marker is authoritative position `0`; larger
position numbers extend leftward toward the rear. Every prepared Recruit
occupies a stable numbered marker joined to that cord. The component renders
the count from `BIND:PARTY_CAPACITY`; it never labels capacity as owned Company.
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.
positions with sticky Rear/Front indicators, position `0` pinned at the right
edge indicator, and a full miniature order strip.
Selecting a recruit then a destination previews only sourced changes:
@@ -385,7 +451,13 @@ 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.
### 8.8 Active Artifact Ledger
Protection connectors point from the protected Recruit toward contributing
actors ahead of it on the right. Front and rear use icon, localized text, edge
shape, and position number; color or reading direction alone is insufficient.
English, Simplified Chinese, touch, controller, and screen-reader fixtures keep
the same spatial orientation rather than mirroring the line by locale or input.
### 8.9 Active Artifact Ledger
Artifacts are presented as run-wide rule modifiers, never as equipment attached
to a recruit. Each ledger row shows sourced emblem, name, changed rule,
@@ -394,7 +466,7 @@ 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.
### 8.9 Risk Choice
### 8.10 Risk Choice
Risk options are aligned by known pressure, uncertainty, entry cost, reward
class, recovery exposure, and current coverage. Options use different threat
@@ -404,13 +476,13 @@ 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.
### 8.10 Battle Actor And Event Projection
### 8.11 Battle Actor And Event Projection
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.
The battlefield owns at least `68%` of usable area. Player actors stage from
protected rear at left to exposed position `0` front at right and face the
enemy across the central action gap. Enemy staging faces toward that front.
Order remains legible through numbered ground marks and target/protection
connectors; the planning cord itself is not drawn as a large HUD over combat.
Actor-attached information is limited to:
@@ -424,7 +496,7 @@ compact and are available through Inspect. Event projections originate at the
acting subject, name affected targets, include time/order, and keep actors
visible.
### 8.11 Playback And Inspect Tools
### 8.12 Playback And Inspect Tools
Pause, play, speed, and inspect use symbol-first controls with tooltips and
accessible labels. Speed is a segmented symbol control populated by
@@ -442,7 +514,7 @@ Inspect freezes or preserves playback according to sourced rules and opens:
On short phones or at 130%, this becomes a full-screen linear view. Closing it
restores the exact prior playback state.
### 8.12 Causal Timeline
### 8.13 Causal Timeline
Result uses a two-track timeline: expected responsibilities from the accepted
party snapshot above, actual events below. The first meaningful divergence has
@@ -453,7 +525,7 @@ 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.
### 8.13 Death And Party Gap
### 8.14 Death And Party Gap
Loss presentation is quiet and explicit. The affected recruit remains visible
at a respectful readable scale with generated name, stable ID, profession,
@@ -464,7 +536,7 @@ 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.
### 8.14 Reward Choice
### 8.15 Reward Choice
Rewards appear as actual object, profession, recruit, or rule presentations
supplied by content and media bindings. Equal-size decision regions prevent
@@ -479,14 +551,14 @@ object scale from implying value. Each option names:
Claim animation begins only after receipt. The final state is a persistent
named ownership change, not particles alone.
### 8.15 Recovery Choice
### 8.16 Recovery Choice
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.
### 8.16 Empty, Error, Notice, And Receipt
### 8.17 Empty, Error, Notice, And Receipt
| Component | Required content | Forbidden behavior |
|---|---|---|
@@ -511,6 +583,13 @@ cover the primary action, Back, playback tools, target projection, or focus.
- 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.
- `SYS-005` begins with Contract/difficulty review, then gives the main surface
to four equally weighted provisional Recruit markers and a stable `0/2..2/2`
selection status. Inspect/Compare uses the context region; Review Company is
the only primary action after `2/2`.
- The creation review keeps the four-offer strip, expands the selected two,
labels the unchosen two `Not retained`, and separates `Revise Recruits` from
Create Run. Pending/error states cannot rearrange or replace offer IDs.
### 9.2 Guild Desk And Forecast: `HUB-001/002`
@@ -518,6 +597,9 @@ cover the primary action, Back, playback tools, target projection, or focus.
- 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.
- The first-Market variant keeps Company count and Line capacity separate and
exposes two individual affordable-hire reviews; no visual treatment chooses
either base-Profession offer for the player.
- Latest result change uses one attached receipt strip and disappears only after
inspection, not on a timer.
@@ -555,10 +637,13 @@ cover the primary action, Back, playback tools, target projection, or focus.
### 9.6 Party Line And Readiness: `PTY-001/002`
- The ordered cord spans the main surface with clear First and Last endpoints.
- The ordered cord spans the main surface from protected Rear at left to
exposed Front at right. Position `0` is the rightmost front; larger position
numbers extend left toward the rear.
- 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.
- Protection/target/reach connectors use distinct patterns, name their numbered
endpoints, 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.
@@ -572,7 +657,9 @@ cover the primary action, Back, playback tools, target projection, or focus.
### 9.8 Battle: `BAT-001..006`
- Actors and event projections dominate the scene; UI follows edges.
- Player actors stage rear-left to front-right, with position `0` and the enemy-
facing action gap at the right; actors and event projections dominate the
scene while 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.
@@ -625,6 +712,13 @@ 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.
In `SYS-005`, focus enters Contract/difficulty, then the four offers in stable
source order, selected count, Compare, Review Company, and Back. Inspect returns
to the invoking offer; comparison returns to its last pinned offer; Revise
returns to the first selected offer still present. Offer focus order never
changes because of selection, generated-name length, loading completion, or a
tutorial highlight.
A policy-disabled destructive control remains focusable so its reason is
readable. It is skipped only after the same reason has been announced by an
adjacent required notice. Focus order never treats the separate abandonment
@@ -635,8 +729,11 @@ the separate abandonment action on the player's next navigation input.
### 10.2 Ordering And Selection
- Selection and commitment are separate states.
- Provisional Company checkboxes, A/B comparison pins, and Create Run are three
separate state machines; changing one never silently changes another.
- All drag operations have tap-select/tap-destination and controller paths.
- Reorder controls preserve stable IDs and announce old/new positions.
- Reorder controls preserve stable IDs and announce old/new numbered positions,
front/rear meaning, and movement left/rear or right/front.
- 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.
@@ -691,8 +788,13 @@ short phone. They freeze under overlays and never resemble event warnings.
- 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.
`position [index], [front/rear meaning], [name], [profession], [condition]`;
position `0` is announced as exposed front/right and larger positions as
progressively rear/left. Battle events announce source, action, target,
outcome, and time/order.
- `SYS-005` announces `four offers`, the current checked count, each offer's
stable position and checked state, Profession job, Trait benefit/cost,
no-Coin cost, Compare A/B state, and whether Review Company is available.
- 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
@@ -768,13 +870,22 @@ Every gallery frame must record:
their pages.
- [ ] Generated recruits remain replaceable run participants and still read as
distinct mechanical identities at roster, planning, and battle scales.
- [ ] `SYS-005` visibly holds four unique stable provisional offers, separate
Inspect/Compare/Select controls, exactly-two gating, review/revision,
no-Coin and unchosen-not-retained consequences, complete invalid/loading/
error/interruption states, and no tutorial-selected build.
- [ ] The `0:00-3:00` path commits one choose-two run creation and then two
separate affordable first-Market hires, ending at Company/Line capacity
labels `Company 4 | Line capacity 4` without combining purchases or
preselecting an offer.
- [ ] At one total live Recruit across deployed and reserve, Dismiss is visible
and disabled with `One member must remain`; explicit abandonment is a
separate run-level action and review.
- [ ] A stale final-survivor dismissal confirmation closes with no Recruit or
equipment mutation, no rebate, a readable reason, and deterministic focus.
- [ ] The ordered party is immediately readable from First to Last on landscape
phone and tablet without moving controls or shrinking labels below tokens.
- [ ] The ordered party is immediately readable from protected rear at left to
exposed position `0` front at right on landscape phone and tablet; larger
numbers extend left and protection contributors remain explicit.
- [ ] Automatic battle prioritizes urgent cause, affected actors, objective,
playback state, and inspect; no control implies insertion of an attack or
skill into the timeline.