aetherbound-guild/docs/plans/M48_UI_LAYER_CLEANUP.md

M48 UI Layer Cleanup

Status

• Plan: M48_UI_LAYER_CLEANUP
• Status: COMPLETE
• Activated: 2026-09-06
• Baseline: 41f854e (M47_UNIFIED_UI_MVP closure)
• Owner request: rework the representative UI because controls read as text and stacked borders/rails obscure the authored scene.

Objective

Repair the presentation layer of Market, Readiness and Battle Result without changing gameplay, controller snapshots, routing, Save/Receipt behavior, localization semantics or static-master art.

Player-visible stopping point

• Every actionable control has a visible, pressable surface with clear normal, hover/pressed, selected and disabled states.
• Each page has one visually dominant next action and no duplicate shell/title treatment competing with the page's own focal heading.
• Decorative rails and borders no longer stack into dark bands or cover authored text, characters, scene lines or primary controls.
• Secondary information is readable but visually subordinate at 760x360, 844x390 and 1280x720 in zh_CN and en.

UI layer contract

• Compact pages use a rule-only shell; no opaque full-width panel is added over the static master.
• Full pages use at most one identity rail, one focal/context surface and one command rail. A control owns one border treatment, not nested frames.
• Shared tokens and ABGUIFactory remain the only source for command surfaces, typography, semantic colors and state styling in rewritten code.
• Internal hashes, IDs and debug/status diagnostics stay out of normal views.
• Preserve stable node names and intent wiring so existing route tests remain authoritative.

Ordered steps

M48-A — Audit and baseline (COMPLETE)

• Record the concrete overlap/affordance failures from current captures.
• Freeze the fixed viewports, locales and target-page scope.
• Add acceptance checks for compact-shell opacity, duplicate headings and real button affordance.

Closure: M48-A closes at source 4be06de. The fixed scope and concrete overlap/affordance failures are recorded; no runtime product code changed.

M48-B — Shared surface repair (COMPLETE)

• Make compact shell decoration transparent/rule-only.
• Clarify shared flat-command normal/hover/pressed/disabled states and spacing.
• Add a focused foundation regression for shell and command affordance.

Closure: M48-B closes at source 4782c13. Compact shell rails are now rule-only, secondary command surfaces have visible default fills with hairline borders, and the focused marker ABG_M48_UI_LAYER_CLEANUP_OK passes.

M48-C — Page composition cleanup (COMPLETE)

• Remove duplicate Result shell/title layers.
• Rebalance Market and Readiness command/context surfaces so controls do not read as floating text or collide with authored lines/backgrounds.
• Keep all behavior and content identities unchanged.

Closure: M48-C closes at source e920200. Market category controls no longer carry a nested plate, offer hit areas have a shared visible affordance, the Readiness summary/warning surfaces are lighter, and Result uses one page identity layer. Focused M47/M48 foundation checks remain green.

M48-D — Verification and owner handoff (COMPLETE)

• Run focused View tests and the full first-cycle audit through the owned test attempt runner with strict diagnostics and exact markers.
• Inspect normal captures in all required sizes/locales and record remaining non-blocking observations.
• Update the checkpoint, ledger and visual audit, then hand off the local run.

Closure: M48-D closes at source 0eec3ed. The focused marker and full first-cycle audit pass with strict diagnostics 0; visual evidence and the remaining non-blocking Market observation are recorded in docs/runtime/M48_UI_LAYER_CLEANUP_VISUAL_AUDIT.md.

Plan closure

M48_UI_LAYER_CLEANUP is complete at its written stopping point. The next page-wide style migration requires a new owner-approved plan.

Acceptance checks

• ABG_M48_UI_LAYER_CLEANUP_OK appears exactly once in focused verification.
• Existing first-cycle markers, Save/Receipt tests and touch/restart checks stay green with strict diagnostics 0.
• Target captures show no blocking overlap, no duplicate page identity and visible button surfaces at the reference viewport.
• No gameplay, economy, content, routing, Save, audio, packaging or release scope is opened.

Frozen scope

• No new content or art generation; no static-master repaint.
• No battle/domain/controller changes and no release/device work.
• Preserve untracked .uid, .import and prototype_incremental/ files.

Commit boundaries

• M48-A: plan/checkpoint/ledger activation only.
• M48-B: shared shell/factory repair and focused test.
• M48-C: three-page composition repair.
• M48-D: evidence, audit and handoff.

Final handoff

ABG M48 UI LAYER CLEANUP READY FOR OWNER TRYOUT