UX Spec: Settings — Controls, Display, Audio, Accessibility

Status: Reviewed — APPROVED (/ux-review pass 3 2026-08-31: 0 blocking, 4 advisory — applied; pass 1 3 B / 8 A and pass 2 2 B / 4 A applied the same day) · v0.4
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: reached from the title screen and from pause (same screen, same state; the in-game variant returns to pause)
Requirements input: design/accessibility-requirements.md — the ten committed controls (UI scale, reduced-motion, flash-reduction, HUD opacity, mono, Music / SFX / UI volume, gamma + calibration image, toggle-hold revive) + full rebinding; ADR-0007 §4 (rebind flow, swap-on-confirm, protected actions, reset floor, bindings.json); pattern #20 Rebind Row; ui-hud quick-spec Rule 4 (Movement / Camera row) + queue item ⑤; art bible §7; Tier 1 stubs reserved: Help panel, deadzone / aim-sensitivity sliders
Patterns used: #1 Button · #3 Panel/Modal · #4 Focus & Nav · #6 Reason String · #20 Rebind Row · #25 Slider, #26 Toggle, #27 Option Cycler (new — defined by this spec; the pattern-library gap that blocks the accessibility commitments)
Related specs: design/ux/hud.md (opacity scope; UI-scale mechanics OQ 1), design/ux/build-mode.md (#31 single-press alternative), design/ux/inventory.md (panel conventions); title-screen and pause specs do not exist yet — named as dependencies in Navigation

Purpose & Player Need

Settings is where a friend makes the game fit their hands, eyes, ears and screen — and then never thinks about it again. The player arrives wanting to rebind a key, fix the volume balance, or turn on the option that lets them play at all (reduced motion, flash reduction, toggle-hold revive, UI scale). It must be reachable from anywhere (title and pause), operable entirely on either scheme, honest about conflicts (swap-on-confirm, never silent), impossible to lock yourself out of (protected Menu, the reset floor), and free of ceremony: every change applies the moment it is made and persists without an Apply button. It is the only screen in the game with sliders and toggles, so it also defines those controls for the project (patterns #25–27).

Player Context on Arrival

• First encounter: the title screen, first launch — usually a friend checking volume or whether the game "has controller support". Calm, exploratory.
• Typical: (a) title screen before joining — rebinding to taste, setting scale for a TV; (b) pause mid-session — a quick volume tweak, or turning on reduced motion after a friend says the flyouts bother them; the world keeps running (host-and-play never pauses the tide), so the in-game variant must be quick to enter and leave; (c) an accessibility need discovered mid-play (flash sensitivity) — must be fixable now, hence live-apply.
• Emotional assumption: calm at the title; slightly time-aware in pause (the tide is moving); never pressured by the screen itself.
• Voluntary: always.

Navigation Position

Title → Settings; Gameplay → Menu (Esc / Start) → Pause → Settings. One screen, one state, two return targets. A captured panel (#3; UI map live) with a tab bar — the project's only tabbed screen. Title-screen and pause specs do not exist yet; this spec fixes only that both offer a "Settings" entry and that Back returns to whichever opened it. Sub-flows: Rebind (inline listening state on a row, #20); the title-screen reset floor (hold the default Menu control 3 s — lives on the title screen, ADR-0007 §4) is mirrored by this screen's Reset button.

Entry & Exit Points

No one-way exits. The only persistent effects are per-change writes to settings.json (new — this spec; persistentDataPath/Driftlands/settings/) and bindings.json (ADR-0007 §4) — both per machine via ADR-0004's atomic replace (temp + File.Replace) without the save's rolling .1/.2/.3 backups or F_FULLFSYNC — the same trim ADR-0007 §4 applies to bindings.json: a lost settings write is not data loss, and a corrupt file recovers through the settings.bad.json path (States), not a backup — never in the world save (ADR-0007 §4; ADR-0004's save defines no settings table).

Layout Specification

Information Hierarchy

• Which tab am I on — the tab bar (Controls · Display · Audio · Accessibility).
• What is each thing set to — row label + current value, readable without touching anything (numeric readouts on sliders, the word on toggles, the value on cyclers, the binding glyph on rebind rows).
• The control itself — the means to change it, right-aligned in one column so the eye scans down.
• Consequence text where it matters — a Small line under the row: rebind conflict prompt, the brightness calibration strip, the HUD-opacity scope note, the flash cap, the toggle-hold instruction.
• Footer — Back; Reset to defaults on the Controls tab only.

Absent by design: an Apply / Save button (live-apply, ruled), profiles, per-player settings (settings are per machine), search, a "restore previous" undo (every change is one step to reverse by hand).

Layout Zones

Arrangement: one centred captured panel (#3), 720 × 520 px @100 % scale (1080 × 780 at 150 % — fits 1080p with margins; ruled 2026-08-31). Height = 48 header + 40 tabs + 360 rows + 56 footer + 16 vertical padding (8 top, 8 bottom). Settings is the project's only centred panel: it is reached from the title or from pause, never from a world verb, so the bag's right-of-centre anchor (which keeps the player's own character visible) buys nothing here and 720 px at that anchor would clip at 150 % on 1080p. Width = 16 pad + 400 px label column + 24 gutter + 260 px control column + 20 pad.

• Z1 — Header (48 px): "Settings", Large 24 px, left-aligned. No close glyph (Back lives in the footer; UI.Cancel / Menu always work).
• Z2 — Tab bar (40 px, full-bleed — ignores the panel's side padding, so four cells of 180 px span the 720 px width): Controls · Display · Audio · Accessibility. The active cell is filled and underlined (weight + fill, never colour alone). The bar is one focus stop: ←/→ on it switches tabs immediately (commit on focus — the #2 default). No shoulder-button tab switching exists: the UI map is Unity's reference set and carries no such action (ADR-0007 §1).
• Z3 — Row list (360 px): rows of 44 px (label Medium 16–18 px left; control right-aligned in the 260 px column); a row with a consequence line is 64 px (Small 13–14 px line beneath, spanning both columns). ≈ 8 plain rows visible. Scrolls only when the tab needs it (Controls); scrolling follows focus so the focused row is always fully visible; a thin, non-focusable slate scroll indicator on the right edge (mouse-draggable, ignored by gamepad).
• Z4 — Footer (56 px): Back (Secondary #1) left · reason-string slot (#6) centre · Reset to defaults (Secondary #1 — ruled 2026-08-31: the screen has no Primary, because its default action is leaving, and the one bulk-discard must not carry the heaviest weight) right — Controls tab only; the other tabs show an empty right slot (no per-tab reset at MVP).
• Background: the title art (title variant) or the live world with the closed-list HUD (pause variant) — the HUD is never occluded by this panel (#3 layering). The world keeps running; nothing on this screen says otherwise.

All px at 100 % UI scale (pattern-library scale convention); the panel, its columns and its rows scale together.

Component Inventory

Every row is label · control · optional consequence line. Three control patterns are new — defined by this spec (#25 Slider, #26 Toggle, #27 Option Cycler); #20 Rebind Row and #1 Button already exist.

Control anatomy (new patterns — lifted to interaction-patterns.md as #25–27 when this spec is drafted; ruled 2026-08-31):

• #25 Slider — track + knob + numeric readout always shown (the number is the non-visual channel; never a bare track). Keyboard / gamepad: ←/→ moves one step (key-repeat per #4: 300 ms then 100 ms); mouse: drag the knob or click the track. Live-apply on every step. Ends: the knob stops; the readout states the bound.
• #26 Toggle — a two-cell switch [ OFF | ON ]; the active cell is filled and carries the word (state by word + fill, never colour or position alone). UI.Submit / click / ←/→ flips it. Live-apply.
• #27 Option Cycler — ◂ value ▸; ←/→ steps through a fixed ordered list, no wrap: the arrow at an end turns dashed (the disabled grammar, #1 / #8); UI.Submit steps forward when possible, otherwise no-op (the dashed arrow already says why — no cue). Mouse: click either arrow; clicking the value does nothing. Live-apply.

Rulings folded into the table (2026-08-31): Interact and Revive are one row — they share E / West by design (ADR-0007 §1) and rebinding the row applies one override to both actions; §4's same-map conflict rule must exempt this pair (Open Questions → ADR-0007 / ADR-0014). Shared controls survive rebinding by control identity (ruled 2026-08-31, ADR-0007 §3 amendment): Strike / Place share LMB and Demolish / Cancel share RMB by design; if a rebind moves one half away, build mode's shared-control routing follows whatever Player action now holds the control a Build action shares — nothing on this screen pairs those rows. Fixed secondary bindings (ruled 2026-08-31, ADR-0007 §4 amendment): ADR-0007 §1's rule (b) is a minimum, and two KB/M actions ship with a second binding — Build.Cancel RMB / Esc and PickPrev / PickNext Q · R / scroll (§1's single pair row named only "Q / scroll" and left PickNext without a key; split 2026-08-31 into Q = Previous, R = Next, scroll as the pair's secondary). Those secondaries (Esc, scroll) are fixed: never displayed, never rebindable, never overridden — Esc because it is Menu's protected control (so Cancel can never leave Esc and build mode's "Esc exits then opens pause" in build-mode.md always holds), scroll because it is a pointer affordance like AimPointer. Every rebind row therefore edits exactly one binding — the scheme's primary — and "one rebindable binding per action per scheme" is true of the default set. Window mode / Resolution / VSync are provisional: no GDD or ADR commits them; a PC build cannot ship without them; ADR-0014 owns confirming or removing them. AimPointer (mouse position) is not rebindable — there is nothing to rebind a pointer to; AimStick is (left-handed stick swap).

ASCII Wireframe

Controls tab (Keyboard / Mouse scheme, mid-rebind) and Display tab. * = the one focused element (3 px outline + inset tick ─▸); ▒ = scroll indicator.

┌─ Settings ───────────────────────────────────────────────────────────┐
│ ▌Controls▐   Display     Audio     Accessibility                     │
├──────────────────────────────────────────────────────────────────────┤
│ Scheme                                   ◂  Keyboard / Mouse  ▸      │
│ Move · up                                  [ W ]        Rebind       │
│ Move · down                                [ S ]        Rebind       │
│ Strike                                     [ LMB ]      Rebind       │
│ Dash  ─▸*                                  [ press a key… 5 ]        │ ← listening
│ Interact / Revive (hold)                   [ E ]        Rebind       │
│ Demolish                                   [ RMB ]      Rebind       │
│ Menu                                       [ Esc ]      🔒           │▒
├──────────────────────────────────────────────────────────────────────┤
│ [ Back ]                                        [ Reset to defaults ]│
└──────────────────────────────────────────────────────────────────────┘

┌─ Settings ───────────────────────────────────────────────────────────┐
│  Controls   ▌Display▐    Audio     Accessibility                     │
├──────────────────────────────────────────────────────────────────────┤
│ Window mode                              ◂    Borderless    ▸        │
│ Resolution                               ◂   1920 × 1080    ▸        │
│ VSync                                        [ OFF |▐ON▌ ]           │
│ Brightness  ─▸*                          ──────●──────   +10 %       │
│   ▓▓▓ ▒▒▒ ░░░ ♟   set until the left figure is just visible          │
│ HUD opacity                              ────────●────    80 %       │
│   never dims your own health or a downed friend                      │
├──────────────────────────────────────────────────────────────────────┤
│ [ Back ]                                                             │
└──────────────────────────────────────────────────────────────────────┘

The Controls list continues below the fold (Inventory, Build mode, then the Build-map divider with Place / Cancel / Previous structure / Next structure); the Gamepad scheme replaces the four Move part rows with one stick row and adds Aim stick. Checked at 150 %: 1080 × 780 on 1080p leaves 420 px of margin on each side and 150 px above and below; the row count per screen is unchanged because rows scale with the panel.

States & Variants

No tutorial, locked, premium or platform-variant states exist (PC only; nothing on this screen is progression-gated).

Interaction Map

Input scope (technical-preferences): Keyboard / Mouse primary, Gamepad partial — every action below is reachable on both. The panel captures the UI map (ADR-0007 §3); Menu and Inventory are the only Player edges that survive capture, and Inventory does nothing here (it only closes the bag it opened, #3).

Nothing is pointer-only: every control has a Navigate / Submit route, and Rebind is the row's own Submit (unlike crafting's pointer-only Craft button, which mirrors a focused row). No hold exists on this screen.

Focus adjacency — first focus = the first row of the remembered tab (default Controls → Scheme):

No traps: every element reaches the tab bar in ≤ (rows + 1) presses of ↑ and Back in ≤ (rows + 1) presses of ↓; Esc / East closes from anywhere except two row-local states: mid-listen (the first press cancels the listen, the second closes) and a conflict prompt (Esc / East is the prompt's Cancel; the prompt is dismissed only by Confirm or Cancel, so a stray Esc never closes the panel over an undecided swap). The calibration strip is non-focusable (no controls; it shows and hides with the Brightness row's focus).

Events Fired

No analytics system exists in the project; every event here is local, and nothing crosses the wire (settings are per machine; ADR-0007: input never leaves the machine).

Flagged for architecture: both persistent files live in persistentDataPath/Driftlands/settings/, per machine, written by ADR-0004's atomic replace without its rolling backups or F_FULLFSYNC (deliberate — see Entry & Exit), outside the world save (asserted by ADR-0007 §4; ADR-0004's save schema defines no settings table — the enforcing Schema_* test is ADR-0014's, OQ 4). settings.json is a new file: ADR-0014 owns its schema and the write path; whether it appears in ADR-0006's data manifest at all (it is runtime-written like bindings.json, not shipped data) is an Open Question. The UI owns none of this state — it reads the applied values and asks the owning systems to change them.

Transitions & Animations

Art bible §7.5 binds: 100–150 ms ease-out only; nothing animates that gates an input.

No screen shake, no bounce, no open delay, no confirm-hold. The only timed element on the screen is the 5 s listen timeout, and it is a safety cancel (#20), not an input window — the a11y doc's "no timed input that cannot be extended or toggled" clause is untouched.

Data Requirements

Nothing updates per frame. The UI owns no game state: it displays applied values and asks the owning system (settings service, rebind service, mixer, HUD presenter, PanelSettings, combat's local revive handling) to change them.

Accessibility

Tier: Standard (design/accessibility-requirements.md). This screen delivers ten of that document's commitments; the document stays the source of truth for each one's scope.

• Keyboard-only and gamepad-only paths: complete via the adjacency table (Interaction Map); nothing pointer-only; no hold; Esc / East closes from any non-listening state.
• Focus: 3 px outline + inset tick (#4); exactly one focused element at all times; first focus named (first row of the remembered tab).
• Text: labels Medium 16–18 px; consequence lines, reason strings and notices Small 13–14 px (the floor); header Large 24 px; slate #3A3D42 / text #E8E6DE ≥ 4.5:1 — verified at theme lock (AC-17).
• Colour never alone: toggle = word + fill; cycler end = dashed arrow; conflict = outline weight; slider = numeric readout; focus = weight + tick; active tab = fill + underline; disabled Rebind = dashed + reason on focus.
• Hit targets: rows 44 px tall; footer buttons ≥ 44 × 160 px; tab cells ≥ 40 × 120 px.
• Lockout-proof: Menu / UI.Cancel protected (lock glyph, no button); refuse-unbind; Reset to defaults on this screen and the title-screen reset floor (hold the default Esc / Start 3 s — ADR-0007 §4). The floor works with no usable Player bindings at all; the on-screen button is always reachable because the UI map is not rebindable.
• Commitment map: UI scale · reduced motion · flash reduction · HUD opacity (element-scoped, hud.md) · mono · Music / SFX / UI · brightness + calibration strip · toggle-hold revive · full remapping — each is a row in the Component Inventory.
• Reduced motion: the Transitions table; the toggle takes effect on this very screen the frame it flips.
• Timed element: the 5 s listen timeout is a safety cancel (#20), restartable without limit — a player with slow reach may still find 5 s short → Open Question 8 (raise to 10 s).
• Cognitive: one column, one control per row, plain-verb labels ("Place", not "Confirm"); consequence lines state what changes in the world, never a system term; at most one prompt on screen at a time; no confirmation dialogs.
• Screen reader: out of scope (a11y doc, Known Intentional Limitations). 150 %: 1080 × 780 verified in Layout; row count per screen unchanged.

Localization Considerations

Every layout-critical string above is flagged for 40 % expansion; the two-line allowances are the accommodation. No RTL commitment exists at MVP (no RTL language is planned for a friend-group release).

Acceptance Criteria

• [PLAYMODE] Opens within 1 frame of the entry press from the title and from pause; the focus tick is on the first row of the remembered tab (Controls → Scheme on first open).
• [MANUAL] Every non-provisional row exists with the stated range, step and default (Component Inventory); each change applies within 1 frame (audio the same frame; HUD opacity and UI scale the next frame).
• [PLAYMODE] Change any value, quit without pressing Back, relaunch → the value is restored; exactly one settings.json write per committed change.
• [PLAYMODE] Rebind Dash on both schemes, restart → restored (ADR-0007's own criterion); rebind the Interact / Revive row to F → bindings.json carries the override on both action ids.
• [PLAYMODE] Rebind Dash to E → the prompt names "Interact / Revive" with focus on Confirm; Confirm → Dash = E and Interact / Revive = Space (exchange); no action is left unbound; Cancel changes nothing.

5b. [PLAYMODE] On the Keyboard / Mouse scheme, rebind Strike to Esc → no prompt appears; footer reads "Menu always stays on Esc"; Strike stays LMB; Esc still opens pause from gameplay and still exits build mode. 5c. [PLAYMODE] Rebind Inventory to LMB, Confirm → Strike = Tab and Inventory = LMB; enter build mode, press LMB → a structure is placed and build mode stays active; the Cancel row shows RMB only and rebinding it never affects Esc.

• [UNIT / MANUAL] The Menu row shows a lock and no Rebind; no row exists for Navigate, Submit, Cancel, Point, Click, RightClick, MiddleClick, ScrollWheel, TrackedDevicePosition or TrackedDeviceOrientation.
• [MANUAL] Gamepad-only: full traversal per the adjacency table; ↓ from any element reaches Back; East closes from any non-listening state; mid-listen East cancels the listen only.
• [MANUAL] Listening: 5 s without input restores the glyph; a click on another tab cancels the listen and switches tabs; on the Gamepad scheme, Esc cancels the listen without being captured as a binding.
• [MANUAL] Unplug the gamepad on the Gamepad tab → Rebind rows dashed with "no gamepad connected" on focus; plug it back in → re-enabled without reopening.
• [PLAYMODE] Corrupt settings.json → defaults, settings.bad.json beside it, one footer notice on the first open, none on the second.
• [MANUAL] Read-only settings folder → the change applies for the session; the footer says so; no crash, no retry storm (one retry per subsequent change).
• [MANUAL] 1080p and 1440p at 100 / 125 / 150 %: panel 720 × 520 → 1080 × 780; no clipping, no overlap, focus order unchanged; EN consequence lines on one line.
• [MANUAL] Reduced motion ON: tab swap and close are cuts; the slider knob snaps (frame capture shows no intermediate position).
• [MANUAL] Toggle-hold ON: one press starts the revive channel, a second press cancels it; taking damage, dashing, and walking out of reach of the downed friend each still cancel the revive, exactly as with the hold.
• [MANUAL] The mouse wheel over a focused slider scrolls the list and leaves the value unchanged.
• [MANUAL] Open pause-settings while Downed → every control operable (no invented gate).
• [AUTOMATED] All text on the screen ≥ 4.5:1 against its background, measured on the locked theme.
• [MANUAL] While a conflict prompt is showing, ↑ / ↓ do nothing, Esc / East dismisses the prompt without closing the panel, and both rows keep their old bindings.

Open Questions

• Player journey map not yet created. Template available at .claude/docs/templates/player-journey.md. Run /ux-design Phase 2b or create it manually to establish player context for this screen.
• ADR-0007 §4 swap semantics — ruled 2026-08-31: exchange. "Confirm clears the other binding, subject to the empty-binding refusal" was dead on the default set (one binding per action per scheme → every conflict refused). Amendment: Confirm exchanges — the colliding action receives the control the rebound action vacated. ADR-0007 §4 + pattern #20 amended in this change; IRebindService.RebindAsync must return the exchange as one atomic result. Two edge rulings added after /ux-review (2026-08-31): a collision with protected Menu is refused before any prompt; a shared LMB / RMB control follows control identity in build-mode routing after a rebind (ADR-0007 §3 amendment). Second re-review (same day): the "one binding per scheme" premise was false for Build.Cancel (RMB / Esc) and PickPrev / PickNext (Q / scroll) — ruled fixed secondaries (hidden, unrebindable; rows edit the primary only), which also settles Esc's sharing with Menu. Pass 3: PickNext had no named KB/M primary → ADR-0007 §1 row split, Q = Previous, R = Next (R was unbound on both KB/M maps).
• Interact / Revive pair — one row, one override applied to both action ids; ADR-0007 §4's same-map conflict rule must exempt the pair (they share E / West by design, §1). ADR-0007 amendment (with 2); ADR-0014 implements.
• ~~settings.json schema and write path~~ — CLOSED 2026-09-01 by ADR-0014 §2: 14-key schema at persistentDataPath/Driftlands/settings/settings.json, written with ADR-0004's atomic writer (no backups, no F_FULLFSYNC), per-change commit debounced 250 ms, flushed on close and quit; malformed → defaults + loud log + settings.bad.json. Confirmed out of ADR-0006's shipped-data manifest. Original note: → ADR-0014. It is runtime-written like bindings.json, so it does not belong in ADR-0006's shipped-data manifest — confirm when ADR-0014 is written. ADR-0014 also owns the Schema_* test that keeps settings out of the world save (ADR-0007 §4 asserts it; ADR-0004 does not test it).
• ~~Window mode / Resolution / VSync provisional~~ — CLOSED 2026-09-01 by ADR-0014 §2 (user ruling): KEPT, with the proposed defaults Borderless / native / ON. Note Application.targetFrameRate = 60 is pinned regardless of the vsync setting (ADR-0014 §9), so vsync selects tearing behaviour only and never changes the 16.6 ms budget.
• ~~UI-scale mechanism (a11y OQ 1)~~ — CLOSED 2026-09-01 by ADR-0014 §3: the knob is PanelSettings.scale (uniform), separate from scaleMode/referenceResolution which stay Scale with Screen Size @ 1920×1080. World-space text does NOT scale — recorded as a Known Intentional Limitation in the a11y doc. Original note: UI Toolkit PanelSettings scale mode + reference resolution, and whether world-space text (flyouts, tags, ring prompt) scales with it.
• Title-screen and pause specs do not exist — both must offer a "Settings" entry, Back must return to the opener, and the reset floor lives on the title screen (/ux-design title-screen, /ux-design pause).
• Listen timeout 5 → 10 s for slower motor response (#20 amendment) — ask the friend group (a11y OQ 3).
• Binding display names: InputControl.displayName is layout-aware, InputControlPath.ToHumanReadableString is not — pick one at the first settings story and verify on an AZERTY layout.
• ~~AimStick rebindable / AimPointer not~~ — CONFIRMED 2026-09-01 by ADR-0014 §7: AimStick is rebindable (left-handed stick swap), AimPointer is not.
• Ultrawide / letterbox policy (ui-hud Rule 4) — camera quick-spec owns it; no control on this screen at MVP.
• Tier 1 reserved rows: Help panel; deadzone / aim-sensitivity sliders (bottom of the Controls tab, below the Build divider).
• "caps hit flashes at 3 per second" assumes the per-screen cap (a11y OQ 5) — retext if combat rules per-enemy.