41 lines
4.7 KiB
Markdown
41 lines
4.7 KiB
Markdown
# 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](stage_panel_ui_system.md).
|
||
|
||
## 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.
|
||
- Use `StageDialogStyler` in `scripts/shared/stage_ui/stage_dialog_styler.gd` for Sandbox Stage and standalone Prop/Stickman confirmation, recovery, and short action dialogs. It owns the shared shell, typography, and primary, secondary, or destructive button roles through `SandboxTheme.popups.confirmation`. Custom Control-based dialogs can reuse its `panel_style()` and `style_button()` helpers.
|
||
- Render the shared modal surface as a Control in the active scene's UI CanvasLayer. Keep the native `AcceptDialog` or `ConfirmationDialog` hidden as the signal source; a full-screen native Window can replace the active scene with a blank surface on some render paths. Native `FileDialog` contents remain native.
|
||
- 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.
|
||
|
||
## Anchored object chooser
|
||
|
||
An anchored chooser resolves a temporary canvas choice, such as picking between objects under one click. It is non-modal and remains visually attached to the stage context; it does not use the dim backdrop or centered card used by a confirmation dialog. Follow the rounded shell, row states, selected badge, footer Cancel, safe-viewport fit, and outside-click behavior in [Editor Visual Style Guide, section 4.6](../guides/editor_visual_style_guide.md#46-anchored-object-chooser). The current Stage implementation is **Objects here** and its tokens live in `SandboxTheme.popups.anchored_chooser`.
|
||
|
||
Keep **Cancel** visible even when Escape is supported. Outside dismissal consumes that click so the stage beneath the popup does not receive it. Keep previews transient until the child activates a candidate.
|
||
|
||
## 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.
|