stickman/docs/specs/dialog_design_principles.md

Child-Facing Dialog Design Principles

Use this guide when creating or revising child-facing dialogs, popups, and short setup flows. It captures the shared visual language established in the Choose Scenery dialog. In-stage selected-object inspectors continue to follow the Stage panel UI system.

Visual style

• Use rounded dialog shells, buttons, choice tiles, and preview containers. A corner radius around 16–22 logical pixels is a useful starting point for large controls; use smaller radii for compact swatches.
• Give controls a clear outline. Use about a 2 px border at rest and 3 px for selected, hovered, or focused states. Keep focus visually distinct from selection.
• Style the main action with a saturated blue fill, bold white text, and a visible border. Use the theme’s action color or edit-mode blue token rather than adding a one-off color.
• Use dark neutral fills and light text for secondary actions. Leave about 12–16 logical pixels between separate footer buttons so they read as individual choices.
• Use large, readable type: roughly 30 px for a dialog title, 22–26 px for section headings, and 20–22 px for main control labels and body copy. Helper text can be smaller when it remains easy to read.
• Keep pointer targets at least 44 × 44 logical pixels. Provide generous padding around labels and icons.

Dismissal and action labels

• Give the child a visible, labeled action that describes what happens, such as Cancel, Done, Back, or Close.
• Avoid making a small corner × the default or only way to dismiss a dialog. Use it only when it adds a useful secondary shortcut; the labeled action remains available.
• Make the primary action’s wording describe the result, such as Draw wall panel or Use color. Keep Cancel separate from the primary action and visually secondary.
• Escape can remain a keyboard shortcut, but it does not replace a visible action.

Theme and implementation

• Put reusable colors, sizes, spacing, radii, and border widths in SandboxTheme or PropTheme tokens. Apply local stylebox overrides instead of mutating a shared theme resource.
• For Sandbox Stage modal windows, use StageDialogStyler in scripts/shared/stage_ui/stage_dialog_styler.gd for the shared shell, typography, and primary, secondary, or destructive button roles. Custom Control-based dialogs can reuse its panel_style() and style_button() helpers.
• Render the shared modal surface as a Control in the stage UI CanvasLayer. Keep the native AcceptDialog or ConfirmationDialog hidden as the signal source; a full-screen native Window can replace the stage with a blank surface on some render paths.
• Keep larger text from clipping: use containers that can expand or wrap, and size the dialog after its visible content has been laid out.
• Preserve clear hover, pressed, selected, focused, and disabled states. Do not use color as the only indication of a state.
• Adapt the arrangement to each workflow while keeping this shared visual language. The Choose Scenery dialog in scripts/shared/ui/asset_selector.gd and its popups.asset_selector theme tokens are the current implementation reference.

Stable position during dynamic resizing

• When a dialog changes size after a tab, filter, or other in-place choice, preserve its current anchor so the clicked control stays under the pointer.
• Let the dialog grow from its stable edge while there is room. Before expanding, account for the usable viewport; if the full content will not fit, cap the dialog and let its content area scroll.
• Move the dialog only as much as needed to keep essential controls visible. Avoid recentering after every content change, which makes controls jump away from the pointer.