UX Spec: Inventory — Bag & Shared Storage

Status: Reviewed — APPROVED (/ux-review re-pass 2026-08-31: 0 blocking, 4 advisory — applied) · v0.3
Author: Jeroen + ux-designer
Last Updated: 2026-08-31
Journey Phase(s): unknown — no player journey map yet (see Open Questions)
Template: UX Spec
Variants: Bag (opened with Inventory anywhere) · Bag + Storage (opened with Interact at a storage chest)
Requirements input: inventory quick-spec Rules 1–7 + Tuning Knobs; harvesting UI Requirements (full-bag cue, no-op cue family OQ6); crafting Rule 12 / AC-13 / AC-33 (equip swap-in-place, maker's mark in tooltip + rack, aggregation ban); base-building Rule 12 (storage instantiated per chest); art bible §7.1–7.5; ui-hud quick-spec Rule 4 (Inventory row) + queue item ①
Patterns used: #3 Panel/Modal · #4 Focus & Nav · #5 Tooltip/Inspect · #6 Reason String · #7 Honest No-Op Cue · #12 Maker's-Mark Inspect · #13 Storage Who-Took-What · #17 Carry Meter · #19 Feedback Split · #21 Stack Grid (new — defined here)

Purpose & Player Need

The bag is where the loop's tension becomes a decision. Every harvest swing, every demolish refund, every craft lands here, and the tide makes the bag's fill level the one question that matters on a docked land: bank or push? The player arrives at this screen wanting to see what I'm carrying and decide what to do with it — check the fill, equip the thing Mara just made, empty the haul into the chest so the next trip starts clean. If this screen is slow, fiddly, or lies about what's in the chest, the co-op loop breaks in the most annoying way possible: two friends hauling the same timber, or a full bag discovered by a failed swing instead of a glance. The quick-spec names this the "chronically underestimated" risk; the ui-hud queue puts it first, before the first friend playtest.

What it is not: a management game. No weight, no sorting, no filtering, no favourites, no "made by" grouping (aggregation ban). Ten slots, two equipment slots, one chest at a time.

Player Context on Arrival

• First encounter: minutes into the first session, after the first harvest swing lands a stack in the bag and the carry meter ticks — curiosity, "what did I get?"
• Typical encounters: (a) mid-trip on a docked land, glancing at the bag to judge remaining room — calm-to-time-pressured, the violet is rising; (b) at home at a chest, dumping a haul — relieved, sorting out what to keep; (c) at home after a craft, equipping new gear — pleased, wants the swap to be instant.
• Voluntary: always. Nothing sends the player here; the bag-full no-op nudges via the HUD carry meter (#17), never by opening the panel.
• Emotional assumption: the design assumes the player may be under tide pressure in variant Bag (open/close must cost nothing) and relaxed in variant Bag + Storage (home is hostile-free at MVP, BB Interactions).

Navigation Position

This screen lives at: Gameplay → Bag (top-level, always reachable while alive) and Gameplay → Chest → Bag + Storage (context-dependent: within interaction range of a storage structure at home). Never reached from pause or the main menu; no inventory tab in Settings. Only one panel is open at a time (pattern #3): opening the bag while another panel is open replaces it via the panel stack.

Entry & Exit Points

No exit is one-way; no exit changes persistent state by itself (state changes are per-transfer host commits that already resolved).

Layout Specification

Information Hierarchy

• The bag grid — what I'm carrying, at a glance (the reason the panel exists)
• Equipment slots — weapon + armor, visually distinct from bag slots (not bag space — quick-spec Rule 4)
• Chest grid (Bag + Storage variant) — host-confirmed contents + the who-took-what feed (#13)
• Capacity read — n/N slots (mirrors the HUD carry meter #17)
• Discovered, not shown: per-item detail — maker's mark, wear, count vs maxStack (tooltip #5/#12)
• Contextual only: reason strings on a blocked action (#6)

Deliberately absent: sort buttons, filters, search, weight, categories, favourites, any per-crafter view — the ban list (quick-spec Rule 3/Pillar 4; aggregation ban).

Layout Zones

Arrangement: fixed-bag (ruled 2026-08-30) — the bag never moves; spatial memory holds across variants.

• Z1 — Bag panel (both variants; anchored right-of-centre, identical position always): bag grid 5×2 (bagSlots 10), equipment strip below it (Weapon · Armor — heavier outline, visually offset from the grid), capacity read n/N in the panel footer. Width ≈ 380 px @1080p/100 % scale.
• Z2 — Chest panel (Bag + Storage only; slides in left of Z1, 24 px gutter): chest grid 8×5 (storageSlots 40), header "Chest" (no chest naming at MVP), who-took-what tags (#13) inline on the affected stack. Width ≈ 560 px.
• Z3 — Tooltip layer (#5): anchored to the focused/hovered stack, above both panels.
• Z4 — Reason-string slot (#6): one line in the footer of whichever panel refused the action.
• Background: gameplay stays visible and live around the panels (the world never pauses); the closed-list HUD (party HP, Downed indicator, tide glint, carry meter) is never occluded (#3 layering rule).

All px values at 100 % UI scale; multiply with the accessibility scale option (pattern-library scale convention).

Component Inventory

New pattern flagged: #21 Stack Grid — interaction rules defined here, to be lifted into interaction-patterns.md after this spec is approved (its reserved number).

ASCII Wireframe

Bag + Storage variant (Bag variant = Z1 alone, same position):

 gameplay visible & live ······································ HUD stays visible
┌─ Chest ────────────────────────────────┐  ┌─ Bag ──────────────────┐
│ ┌────┬────┬────┬────┬────┬────┬────┬────┐ │  │ ┌────┬────┬────┬────┬────┐ │
│ │timb│timb│fibr│    │sinw│    │    │    │ │  │ │timb│fibr│fibr│ ⚔︎* │    │ │
│ │ 20 │ 12 │ 20 │    │  4 │    │    │    │ │  │ │  7 │ 20 │  3 │    │    │ │
│ ├────┼────┼────┼────┼────┼────┼────┼────┤ │  │ ├────┼────┼────┼────┼────┤ │
│ │ −12 · Alex        (2 s tag, #13)     │ │  │ │    │    │    │    │    │ │
│ ├────┼────┼────┼────┼────┼────┼────┼────┤ │  │ └────┴────┴────┴────┴────┘ │
│ │ …4 more rows (row 2 shown above;     │ │  │  ⚔ Weapon   🛡 Armor        │
│ │  8×5 = 40 slots total)               │ │  │  ┌──────┐  ┌──────┐        │
│ └────┴────┴────┴────┴────┴────┴────┴────┘ │  │  │ axe  │  │cloth │        │
│                                        │  │  └──────┘  └──────┘        │
│                                        │  │              Bag  7/10     │
└────────────────────────────────────────┘  └────────────────────────────┘
   [reason-string line appears under the refusing panel]        * = the ONE focused element
   focused slot: 3 px outline + inset tick (─▸); tooltip anchors to it

Z1 is pixel-identical between variants; Z2 slides in/out left of it. Focus starts on the bag's first occupied slot.

States & Variants

Interaction Map

Mapping for KB/M (primary) and gamepad (partial, twin-stick) per technical-preferences; UI capture semantics per ADR-0007 §3. One verb per container, context-labelled (provisional, playtest item): Submit on a bag stack = equip (gear) when no chest is open, deposit when one is; Submit on a chest stack = withdraw; the footer hint names the active verb for the focused cell. Escape hatch stated: to equip while banking, step out of chest range (Degrade) — no second verb exists at MVP (OQ 2).

Focus adjacency (complete — every edge defined; no wrap anywhere):

Numbered order (the QA traversal sequence, not the entry point): Bag variant — bag 1…10 row-major, then Weapon (11), Armor (12). Bag + Storage — chest 1…40 row-major, then bag 1…10, then Weapon, Armor (matches #13). First focus is always the bag: first occupied bag slot (slot 1 if empty). Empty cells are focusable. Exactly one element is focused at all times.

Gutter asymmetry — intentional (ruled 2026-08-31): the bag has 2 rows, the chest 5, so crossing clamps: chest rows 3–5 → bag row 2, and Left from bag row 2 returns to chest row 2, not the row departed; Weapon.Left → chest row 5, whose Right lands on bag row 2. Nothing is trapped; it may read as odd in play — OQ 8 (a sticky last-chest-row is the fallback).

No drag, no split, no multi-select, no modifier-click at MVP (ruled 2026-08-30 — one press = one whole stack = one host transaction, transferBatchWindow 0). Focus starts on the bag's first occupied slot (slot 1 if empty).

Stack Grid (#21) rules distilled for the pattern library: fungible slots (a stack fills the first free slot) except the AC-33 swap, which reuses the vacated slot; the adjacency table above with no wrap; Submit = the container's single verb; icon + count (count hidden at 1); tagged stacks (gear) never merge; empty slot = outlined cell; no drag/split at MVP; input on a stack with a pending host verdict is ignored.

Events Fired

No analytics events exist in this project (no telemetry at MVP).

Transitions & Animations

• Enter: instant (≤ 1 frame, #3) — the world keeps moving behind it. Exit: 100–150 ms ease-out fade; input released on the close edge.
• Z2 slide (chest open / degrade): 120 ms ease-out horizontal; reduced-motion: appears / disappears in place.
• Stack move: no travel animation — the stack leaves one grid and appears in the other on confirm (a travel tween would imply a world event that isn't); the bag flash (#17) marks arrival.
• Equip swap: instant icon exchange + one 150 ms outline brighten on both slots; reduced-motion: no brighten.
• Who-took-what tag: per #13 (2 s, fade over the last 200 ms; reduced-motion: static 2 s).
• Nothing here gates input (art bible §7.5). Motion-sickness risk: none (no parallax, no scaling).

Data Requirements

Architectural flag: the UI owns nothing. Every write is an ICommand on the host channel (ADR-0002) or an owner-rail equip; "CARRY predicted, STORAGE confirmed, withdraws not predicted" is the split ADR-0010 must implement.

Accessibility

Tier: Standard (design/accessibility-requirements.md).

• Keyboard-only path: Tab opens; arrows traverse bag grid → equipment strip → (chest grid when open) in the declared order; Enter acts; Esc / Tab closes. Every element reachable without a mouse.
• Gamepad order: the numbered order + adjacency table in the Interaction Map (no wrap; no focus trap — every edge defined); first focus = first occupied bag slot. Visible focus = 3 px outline + inset tick (#4). Gamepad disconnect: focus stays, glyphs switch.
• Contrast (per element): counts / header / footer text #E8E6DE on slate #3A3D42 ≥ 4.5:1; cell outlines ink on slate ≥ 3:1 (non-text); focus outline slate-light on slate ≥ 3:1 plus the weight/tick channel — all verified before theme lock.
• Text: counts Medium 16–18 px; tooltip Small 13–14 px floor; contrast ≥ 4.5:1 on slate (verified before theme lock). All values scale with the 100 / 125 / 150 % option.
• Colour-independent: empty vs occupied = outline + icon; gear vs material = shape (tier hardening) + tooltip; fresh vs worn = shape accent (frayed edge), never hue; who-took-what = text + sign; refused = text.
• Reduced motion: slide → in place; brighten / flash off; tags static.
• No hover-only: tooltips also on focus-dwell; the footer verb hint is text.
• Screen reader: out of scope (documented limitation).
• Motor: one press per action; no holds, no drag, no timing windows.

Localization Considerations

Any element marked HIGH must survive 40 % text expansion without wrapping to a second line, except where a line cap is stated instead. Layout at 150 % UI scale: (380 + 24 + 560) × 1.5 = 1446 px ≤ 1920 — fits 1080p (AC 11).

Acceptance Criteria

• [ ] Inventory press opens the bag panel within 1 frame (≤ 16.7 ms) with the world still moving behind it; a second press closes it.
• [ ] With ten distinct stacks the bag grid shows exactly 10 occupied cells and 10/10; with none, 10 outlined empty cells and 0/10; no placeholder text.
• [ ] At a chest, Interact opens Bag + Storage with the bag panel in the same screen position as the Bag variant (pixel-identical Z1).
• [ ] Clicking / Submit on a bag material stack with a chest open moves the whole stack to the chest; the bag cell empties immediately and the chest cell appears when the host confirms.
• [ ] Clicking a chest stack when the bag is full moves nothing and shows "bag is full" under the bag panel; no dialog, no error sound.
• [ ] With a full bag, focusing an equipment slot shows no verb hint and "bag is full — deposit something first"; Submit does nothing; after depositing one stack the unequip verb returns.
• [ ] A second Submit on a chest stack before its withdraw confirms sends no second transfer (host log shows one InventoryTransfer).
• [ ] Gamepad: from the Armor slot, Up reaches bag row 2 col 5, Left reaches Weapon; from Weapon with a chest open, Left reaches chest col 8 row 5 — no focus position is a dead end.
• [ ] Two clients click the same last chest stack: exactly one bag gains it; on the other client the chest cell disappears and shows a "− N · [name]" tag for 2 s; the loser's bag never showed the item.
• [ ] Submit on a gear stack with no chest open equips it instantly and the previously equipped item lands in the exact slot vacated (crafting AC-33); bag count unchanged.
• [ ] Walking out of chest range slides the chest panel out and leaves the bag panel open in place.
• [ ] Gamepad-only: every slot, both equipment slots, and close are reachable via UI.Navigate / UI.Submit / UI.Cancel with a visible 3 px focus outline; no action requires a pointer.
• [ ] Tooltip on any gear item shows crafter name, "forged N tides ago", and tier; no grid offers any sort, filter, or "made by" control (reflection + manual check).
• [ ] At 150 % UI scale on 1080p no text clips and both panels fit without overlap.

Open Questions

• Player journey map not yet created (.claude/docs/templates/player-journey.md) — this spec assumed arrival contexts (a)–(c); validate at the playtest.
• Context-labelled Submit (equip when no chest / deposit when a chest is open) — playtest: does anyone deposit gear they meant to equip? Fallback: RightClick / a second gamepad verb for equip.
• Stack splitting — none at MVP; a Tier 1 question once more materials and recipes make partial withdraws useful.
• ~~Unequip destination~~ Ruled 2026-08-31: swap → exact vacated slot (AC-33); empty-handed unequip → first free slot; with a full bag the unequip verb is not offered (no refusal). Watch at the playtest whether "deposit something first" reads clearly.
• Chest naming / multiple chests — header is "Chest" at MVP; a name field would be text entry, and no input field exists anywhere (pattern-library note).
• Who-took-what name truncation at 16 chars — check against the friends' actual display names.
• ~~Downed read-only~~ Ruled 2026-08-31: dropped — Downed is an ordinary bag (quick-spec Rule 8; ADR-0015 suppresses only Strike/Dash/Demolish). If a designer ever wants Downed to gate inventory verbs, that is a combat-GDD rule via /quick-design, not a UI decision.
• Gutter-crossing asymmetry (chest rows 3–5 ↔ bag row 2; Weapon ↔ chest row 5) — intentional clamp; if the playtest reads it as a bug, add a sticky "last chest row" so the return edge restores it.