# Phase 19 — Plain Background: UI/UX specification

> **Status:** UI/UX direction revised per user feedback from the user-approved PNG mockups. The current-color chip is the sole entry to the custom picker; there is no separate **More colors** button. The default color is approved as warm off-white `#F5EFE0`; the color swatches and sample views must show a flat fill.
>
> **Design references:** [Phase 19 Plain Background brief](../plans/phase_19_plain_background.md), [approved PNG mockups](../plans/assets/phase_19_plain_background/), [Phase 19 Scenery UI/UX specification](phase_19_scenery_backgrounds_ui_ux.md), and [Child-Facing Dialog Design Principles](dialog_design_principles.md).

## Child promise

A child can start with an empty stage filled by one color, choose another color in EDIT, and return to that color after trying a Sky. The color fills the whole camera view. It does not create a selectable object or change the colors and behavior of placed pieces.

## File → New

- Keep the existing unsaved-work Save/Discard/Cancel gate. Do not replace the current scene until a starter card is chosen.
- Use the existing themed `AssetSelector` shell and `AssetCard` presentation with a fixed **Choose a starter scene** heading, a scrollable responsive card body, and a reachable visible **Close** action. The card order and tab order are **Plain Background**, **Open Sky**, **Town Street**, **Living Room**.
- At desktop widths, show an equal-sized 2 × 2 card grid. At narrow widths, wrap to one column and scroll the body while keeping the title and Close action available. Preserve the popup's screen anchor when its layout changes.
- Make this chooser materially larger than the current roughly 660 × 560 logical-pixel asset selector: target about 1160 logical pixels wide on a roomy desktop, with a natural height that shows both card rows and the Close action. Cap both dimensions to the usable viewport with safe margins; a short display scrolls the card body while the title and Close stay reachable. At the preferred width, each card's preview should be about 500 pixels wide and at least 240 pixels tall, occupying roughly two-thirds of the card height. Scale the preview with its card instead of leaving a small fixed thumbnail inside a large tile. The [larger starter chooser mockup](../plans/assets/phase_19_plain_background/05_large_starter_chooser.png) shows the intended balance; its pixel dimensions are illustrative, not a fixed window size.
- Plain Background's thumbnail is a uniform opaque `#F5EFE0` fill with no horizon, gradient, Sky motif, checkerboard, or object. Its copy is: **“An empty stage with one color. Choose a new color whenever you like.”** Starting it creates a new unsaved scene with no Ground or placed objects and no additional setup step.
- Open Sky previews the existing neutral gradient, sun, and clouds. Its copy is: **“An empty stage with a soft sky. Sun and clouds, ready for your story.”** This is the existing empty neutral-Sky starter under a clearer name.
- Town Street and Living Room retain their authored compositions and existing descriptions.
- Activating a card by pointer, touch, Enter, or Space opens that starter. Close or Escape leaves the current scene intact.

## Fresh Sandbox startup

- When the Sandbox Stage launches as the active scene without a requested scene, show **Choose a starter scene** once for that Stage session. This gives children the same clear starting point as File → New.
- If an autosave is available, resolve its recovery prompt first. Restoring it opens the recovered scene without the starter chooser; discarding it opens the chooser afterward.
- A command-line scene load or load error does not open the starter chooser. The chooser must not cover recovery or another modal dialog.
- Close or Escape leaves the empty EDIT Stage available. Do not automatically reopen the chooser during that session; File → New remains available when the child wants another starter.

## EDIT → Scenery → Backgrounds

- Extend the current `AssetSelector` Backgrounds tab with a **Plain Background** card alongside **Clear Day**, **Cloudy Day**, **Sunset**, and **Starry Night**. Keep **Wall panel** and **Background ground** visually separated under a **More backgrounds** row.
- Show the heading **Choose the scene background** above the five scene-wide choices. The Plain Background card preview uses the remembered plain color even while a Sky is active.
- Mark the active choice with the existing cyan selected fill/border and a stable **Current background** badge. Keep the keyboard focus outline visually distinct from selection. Do not identify the current choice by color alone.
- Sky cards retain their immediate selection behavior and leave the chooser open. Activating Plain Background immediately restores/applies its remembered color and opens the Plain Background color choices. Back or Close from those choices keeps Plain Background active.
- Neither a Sky nor Plain Background is Stage-selectable or included in Pieces here. Switching background never starts placement or changes the current cursor mode.

## Plain Background color choices

- Reuse the bounded chooser shell, `StageSurfaceColorControls` and shared `ColorSwatchSelector` visual language; the full-stage preview and scene-specific copy are the only feature-specific presentation.
- Keep the **Choose background color** heading. Put **‹ Backgrounds** in the fixed footer, left of **Close**, instead of in the title row. Both are large, outlined secondary actions with 12–16 px separation; at narrow widths, stack them vertically as full-width targets. The scrollable body contains:
  1. Helper text: **“Tap a color to use it on the Stage.”**
  2. A large, flat, opaque preview of the confirmed color with no text over the color sample.
  3. The current color swatch and readable hex value.
  4. **Recently used** colors, using the shared recent color list (up to eight).
  5. **Colors** preset swatches.
- If recents are empty, show **“Colors you use will appear here.”** Opening Plain Background at the untouched default does not add that default to recents.
- Tapping a recent or preset swatch immediately confirms it. The full Stage, preview, current swatch, selected outline/check, dirty state, and recent ordering update together. Leaving and reopening the view preserves that confirmed choice.
- Give the selected swatch an outline/check that is distinct from keyboard focus. Make all swatches at least 44 × 44 logical pixels, including compact layouts; the current 42-pixel compact swatch default is too small here.
- The current-color chip is the sole entry point to the full custom picker. It is a focusable button with clear hover, pressed, and focus states and the tooltip **“Choose a custom color.”** Activating the chip opens the picker; there is no separate **More colors** button.
- Keep the Stage at full brightness while Plain Background color choices or its custom picker are open so live color changes can be judged accurately. Keep the modal input-blocking layer active but visually transparent; clicks outside the dialog must not reach the Stage. The dialog keeps its opaque shell, outline, and footer for modal clarity. Other chooser views retain the normal dim backdrop.

## Full custom picker

- Reuse/extend `StageSurfaceColorPickerView`, its native `ColorPicker`, large preview, theme, and compact-height behavior. Use a flat, opaque preview matching the Stage with no text overlay.
- Use the heading **Choose background color** and a simple **Preview** label above the large color sample. The tentative behavior is communicated by the Stage updating during picker movement and the visible **Use color** / **Back** actions; no explanatory preview message is needed.
- On open, snapshot the last confirmed plain color. Moving native color controls updates only the temporary Stage preview and large sample. It does not change history, scene dirty state, or serialized data.
- Use a fixed, visible footer with a dark secondary **Back** (or **Cancel**) button and a blue, bold, white **Use color** primary button, separated by 12–16 logical pixels. All actions remain at least 44 × 44 logical pixels.
- **Use color** confirms once, updates the remembered color and recent history once, marks the scene dirty once, and returns to the color choices.
- Back, Cancel, Escape, or closing the picker restores the confirmed snapshot and returns to color choices with Plain Background still active.
- Mode changes, scene replacement, or unexpected popup dismissal also clear a temporary preview and restore the confirmed color. A temporary color must never enter Save or autosave.

## Focus, layout, and theme

- Use `SandboxTheme` values from `popups.asset_selector`, `popups.dialog`, `stage_surface_colors`, `stage_panels.action`, and `mode_colors.edit`. Add a small Plain-preview token group only if the existing theme has no suitable values; avoid a parallel swatch or picker system.
- Keep cards, swatches, and actions at least 44 × 44 logical pixels. Preserve the existing dialog style: rounded surfaces, visible outlines, readable type, blue primary action, and labeled Close/Back/Use actions.
- Tab order: starter cards → Close; Scenery tabs → scene-background cards → surface cards → Close; color choices: Back → current-color chip → recent swatches → preset swatches → footer; custom picker → Back → Use color.
- Opening a subview moves focus to its heading or first useful action. Returning from the color choices restores focus to Plain Background; returning from the custom picker restores focus to the current-color chip.
- Keep the title and footer actions reachable while the body scrolls. Cap the popup to the safe viewport; do not force clipping or horizontal scrolling to retain compact horizontal swatch columns. Stack the Back/Close footer actions and current/recent/preset sections at narrow widths. Preserve the popup anchor when switching gallery, color, and custom-picker views.
- Pointer, touch, and keyboard users get the same selected, hover, focus, and confirmation feedback. Clicking outside must not silently confirm a tentative custom color.

## Canvas contrast and feedback

- Review white, black, and saturated Plain Background colors. On light fills such as `#F5EFE0`, the current white EDIT grid and white selection outlines have about 1.15:1 contrast and nearly disappear. Provide a theme-backed contrasting grid treatment for light and dark fills, keeping minor lines subdued and major lines legible.
- Give Stage selection, hover, and gizmo outlines a dark backing plus bright core on Plain Backgrounds of any brightness, following the existing two-tone selection-halo practice. Do not recolor authored artwork.
- Keep EDIT chrome and mode pill dark-backed with cyan accents, DIRECT framing amber, and PLAY free of edit-only grid and gizmos. Preserve speech styles and their authored colors. Check cursor pills and placement ghosts at light, dark, and saturated backgrounds.
- A Plain Background color is a scene-wide visual setting only: it never intercepts Stage selection or changes object ordering, placement, action behavior, or camera movement.

## Acceptance scenarios

1. Open Sandbox Stage without a scene and verify the starter chooser appears. Close it and verify the empty EDIT Stage remains available without another automatic prompt in that session. Open a scene through the CLI and verify the chooser does not appear.
2. If an autosave is available at startup, restore it and verify the chooser stays closed; discard it and verify the chooser appears afterward without overlapping the recovery prompt.
3. In a dirty scene, use File → New and verify the existing unsaved gate appears first. Cancel the starter chooser and confirm the previous scene remains. Choose Plain Background and verify the new unsaved Stage is a single flat `#F5EFE0` with no Sky, Ground, or placed objects. Verify Open Sky reproduces the existing neutral Sky appearance.
4. In EDIT, open Scenery → Backgrounds. Verify all five scene-wide choices are visible, the current choice is identified with text and a border, and Wall panel/Background ground remain separate. Choose Plain Background and verify it opens with the remembered color.
5. Tap one preset and one recent swatch. For each, verify the Stage and preview update immediately, the color becomes selected, and recent ordering updates. Close and reopen the choices and verify the confirmed value remains.
6. Activate the current-color chip to open the custom picker. Move a color control, then choose Back. Verify the Stage and preview return to the last confirmed color and the scene/recent history remain unchanged. Repeat and choose Use color; verify the choice and history update once and remain after Save/reopen.
7. Repeat custom-picker cancellation through Escape, visible Cancel/Back, close, mode change, and scene replacement. No temporary preview may leak into the next Stage or saved scene.
8. With each of Sky and Plain active, pan, zoom, resize the viewport, enter/stop PLAY, and reopen a saved scene. Verify the solid fill covers the camera view with no edge and that the remembered plain color returns after switching back from Sky.
9. On light, dark, and saturated fills, inspect grid, selection, hover, gizmos, cursor pills, placement ghosts, speech, and mode chrome. Confirm the Stage remains readable and placed artwork colors remain unchanged.
10. At narrow viewport sizes, navigate each card, swatch, and action by pointer, touch, and keyboard. Verify the content scrolls without clipping; focus and selection remain distinct; Back/Use/Close remain visible; returning from subviews restores the opener focus and popup anchor.

## Reuse boundary

| Surface | Reuse direction |
| --- | --- |
| Starter and Scenery cards | Extend `AssetSelector` and `AssetCard`; use `StageBackgroundCardPreview` for a real solid-color thumbnail and add the Plain-specific label/selection state. Do not create another card gallery. |
| Color choices and recents | Reuse `StageSurfaceColorControls` and `ColorSwatchSelector`/shared history. Extend layout for 44-pixel minimum targets and narrow layouts instead of introducing a parallel swatch system. |
| Custom picker | Reuse `StageSurfaceColorPickerView` and the native `ColorPicker`; give the scene-wide background its own flat preview and explicit temporary/confirm/cancel lifecycle. |
| Stage contrast | Use `SandboxTheme` tokens and the existing two-tone selection halo pattern; do not mutate user-authored object colors or make a second editor theme. |