stickman/docs/guides/editor_visual_style_guide.md

# Editor Visual Style Guide

**Scope:** Establish a practical visual and interaction direction for the Prop Editor and Stickman Editor, using the Sandbox Stage UI as a product reference.
**Status:** Guidance for future editor design and implementation. It documents current patterns and gaps; it does not assert that the editors already share the Stage theme or components.

## 1. Product direction

Both editors should feel like approachable creative workspaces in the same Stickman Studio product:

- Keep the canvas or preview as the main work surface. Put tools and settings around it, not on top of the artwork unless a temporary task requires an overlay.
- Make the current task and mode easy to recognize. Use direct labels such as **Arrange**, **Reshape**, **Attach**, **Save**, and **Cancel**.
- Prefer visible feedback on the object over abstract state: selection outlines, vertex handles, previews, mode coloring, and status text.
- Preserve a stable layout while the child works. Opening an inspector section, showing help, or changing a mode should not make the active control jump away from the pointer.
- Make recovery and destructive actions predictable. Show what is about to happen and keep a visible way to cancel.
- Share a visual language, not necessarily identical panel layouts. A vector canvas, a modal dialog, an in-stage inspector card, and a stickman-part panel have different jobs.

The Sandbox Stage establishes a useful baseline for hierarchy, contrast, child-facing language, control states, safe viewport behavior, and theme tokens. Its in-stage inspector and capture bar are Stage patterns; they should be adapted only when an editor workflow has the same interaction needs.

## 2. Current implementation map

| Surface | Current implementation | Reuse implication |
| --- | --- | --- |
| Sandbox Stage | SandboxTheme loads validated tokens from [sandbox_theme.json](../../sandbox_theme.json). Stage inspector controls live under [scripts/shared/stage_ui](../../scripts/shared/stage_ui/). | Use as the product reference for semantic colors, readable type, focus, action roles, and reusable theme access. |
| Stage inspector | The approved [Stage panel UI system](../specs/stage_panel_ui_system.md) targets in-stage selected-object cards. | Do not insert StageInspectorPanel into editor inspectors by default. Borrow fitting rules and state behavior; use its components only if the layout and ownership match. |
| Stage dialogs | [StageDialogStyler](../../scripts/shared/stage_ui/stage_dialog_styler.gd) styles child-facing dialogs hosted by the Stage overlay. | Reuse its visual contract. Its overlay host and lifecycle are Stage-specific unless deliberately generalized. |
| Prop Editor | [PropTheme](../../scripts/editors/prop/prop_theme.gd) reads [prop_theme.json](../../prop_theme.json); the controller creates a local inspector Theme. The main scene uses split containers, a scrollable inspector, modes, and a nested Attach preview. | Keep values token-driven and scoped. Current Prop colors and target sizes differ from Stage tokens. |
| Stickman Editor | [stickman_editor.gd](../../scripts/editors/stickman/stickman_editor.gd) coordinates ten BodyPartPanels and the Whole Stickman preview. The scene currently uses fixed top-bar offsets and a three-column workspace. | The canvas/preview model is established, but it has no apparent SandboxTheme or PropTheme integration. Harmonization is future work. |
| Child-facing dialogs | [Dialog Design Principles](../specs/dialog_design_principles.md) documents the rounded, labeled-action pattern and stable resizing behavior. | Apply these rules to editor dialogs, adapting ownership and host behavior to each editor. |

The Prop Editor user guide at [prop_editor_user_guide.md](prop_editor_user_guide.md) describes its current controls and layout. Use it to avoid documenting proposed changes as existing behavior.

## 3. Shared visual system

### 3.1 Semantic color roles

Use color to reinforce meaning consistently. Keep labels, shapes, icons, or state text alongside color so meaning survives grayscale, low contrast, and color-vision differences.

| Role | Sandbox Stage reference | Editor guidance |
| --- | --- | --- |
| Main background | global.bg_color #171B24F2 | Use a dark neutral around the work area; avoid competing with authored art. |
| Raised surface | global.surface_color #252B38FA | Use for toolbars, inspector shells, and cards. Distinguish adjacent surfaces by value, border, or spacing. |
| Primary text | global.text_color #F5F7FA | Use for titles, control names, and important values. |
| Secondary text | global.muted_text_color #AAB2C0 | Use for helper text and secondary status; keep readable at the chosen size. |
| EDIT accent | mode_colors.edit #22C6FF | Suitable for active edit mode, selection accents, and editor guidance. It is not the current PropTheme accent. |
| DIRECT accent | mode_colors.direct #FFB300 | Reserved for the Stage's directing mode. Do not use as a generic warning color in editors. |
| PLAY accent | mode_colors.play #33DD77 | Reserved for Stage playback state. |
| Primary action | Stage dialog/action blue #087DBA | Use for the single most important forward action in a dialog. |
| Destructive action | Stage danger #E66B75 with dark red surfaces | Use only for destructive actions; pair with explicit wording and a cancel path. |
| Focus | Stage dialog focus #8BD9FF | Give keyboard focus an outline that remains visible over selected, hovered, and dark states. |
| Canvas grid | Stage tokens vary with canvas treatment; Prop canvas currently uses #FFFFFF26. | Keep grid lines subtle. The work, selection, and handles must dominate the grid. |

These values are current Stage reference values, not a mandate to paste literal hex values into editor controls. Resolve colors through validated theme accessors. If an editor needs a warmer or quieter local accent, define a semantic editor token and document its mapping to Stage meaning.

### 3.2 Current token differences to resolve during harmonization

The current palettes are related but not at parity:

- PropTheme uses ui.colors.accent **#4FA3FF**, while SandboxTheme EDIT uses **#22C6FF**.
- PropTheme defaults its button and row minimum heights to **36 px** and its mode button minimum height to **56 px**. Stage action targets are **48 px**, and child-facing UI guidance calls for at least **44 × 44 logical pixels**.
- PropTheme's canvas is #1F1F1F; its inspector token is #262C39. The Stage uses #171B24F2 / #252B38FA for global background and surface.
- The older Stickman Editor has no apparent editor theme integration. Its scene uses 32 px menu/top bars, a 28 px status bar, 4 px preview corners, and a 14 px preview title; body-part headings are around 13–14 px. It defines preview surface and borders directly in the scene.

Treat these as migration work, not evidence that the editors already match the Stage. Before implementation, decide whether to harmonize the accent, minimum targets, border/focus states, and surface roles. Preserve canvas contrast where it serves drawing readability.

### 3.3 Type, spacing, and shape

Use these Stage examples as starting points, then tune them for the denser editor workspace:

- Stage inspector hierarchy: title **24 px**, section **20 px**, body **20 px**, helper **16 px**.
- Stage inspector shell: **12 px** padding, **8 px** header gap, **12 px** section gap, **10 px** corner radius.
- Stage choice row: **56 px** minimum height; Stage toggle row: **64 px** minimum, increasing when helper text is visible.
- Large child-facing dialogs: title about **28–30 px**, body about **20 px**, button about **20 px**, **2 px** borders, **12–18 px** corner radii, and generous footer spacing.
- Stage generally uses dark surfaces with a restrained border. The dialog guide's stronger borders and rounder controls are for modal emphasis, not a requirement to put every editor widget inside a thick outline.

For compact inspectors, shorten the hierarchy only after checking it at the intended window size. Prefer a clear label and value over shrinking type until it becomes difficult to read. Use container spacing and alignment rather than per-control position nudges.

### 3.4 State styling contract

Every interactive control should have distinct, inspectable states:

| State | Expected feedback |
| --- | --- |
| Neutral | Stable surface and legible label; no implied selection. |
| Hover | Small surface or border change. Must not resemble selected or focused. |
| Selected / active | Persistent fill, border, pressed state, or explicit status. Keep the label unchanged when possible. |
| Keyboard focus | High-contrast focus ring or border that is visible even over selected fill. |
| Disabled | Control cannot activate, remains readable, and explains why when the reason is not obvious. |
| Dragging / live preview | Immediate object feedback; indicate the active handle or preview and make cancellation discoverable. |
| Error / invalid | Explain the problem near the affected task and offer a concrete next step. Do not rely on red alone. |
| Saved / dirty | Show a concise, persistent status such as **Saved** / **Unsaved changes** where it helps prevent lost work. |

For drawing handles, keep a contrasting backing/halo where the canvas can contain arbitrary colors. The Prop canvas's two-tone selection halo and the Stage gizmo backing are useful precedents. Selection should be readable at all zoom levels; keep handle sizes in screen space when scaling the canvas.

## 4. Layout and reuse rules

### 4.1 Use the right pattern for the job

- **In-stage selected-object inspector:** follow StageInspectorPanel, choice groups, and toggle rows in the [Stage UI spec](../specs/stage_panel_ui_system.md). Its title/Close header, fixed header with scrolling body, and safe-rect fitting are specific to a floating selection card.
- **Editor inspector:** favor a persistent column beside the canvas, with labeled groups and vertical scrolling. The Prop Editor already uses a split container and scrollable inspector. Reuse spacing, hierarchy, colors, and control states; do not force the floating Stage card structure into this column.
- **Temporary targeting step:** the Stage capture bar is for a short-lived click-on-stage task. An editor can borrow the prompt-plus-visible-Cancel contract when it has a similar temporary canvas capture step, but should not copy the bar just because it is visible in Stage.
- **Modal dialog:** follow [Dialog Design Principles](../specs/dialog_design_principles.md). Keep a labeled **Cancel**, **Done**, or **Back** action; use one visually clear primary action; preserve the clicked control's anchor when content grows; cap height and scroll content on short viewports.
- **Canvas tools:** keep mode and document controls outside the draw area where possible. Put contextual handles and temporary prompts near the object only if they do not obscure the task.

### 4.2 Reuse through tokens and small components

1. Put repeated colors, font sizes, minimum sizes, spacing, radii, border widths, and state colors in a validated theme source.
2. Use typed accessors with sensible fallbacks. Avoid repeating raw values across script-built controls and .tscn files.
3. Apply per-control StyleBox overrides. Do not mutate a cached/shared Theme to style one editor or one accent variant.
4. Extract a reusable control only after the behavior or presentation appears in at least two appropriate contexts. Keep domain rules and document mutations in the editor controller.
5. Prefer native Button, ButtonGroup, CheckBox, OptionButton, and LineEdit semantics. Custom-drawn controls should separate visual drawing from input and expose a clear typed API.
6. Keep canvas-specific rendering tokens separate from chrome tokens. Grid, artwork, shape fill, selection halo, vertex handles, and preview ghosts have different contrast jobs.
7. Do not serialize UI state unless it is part of the authored document. Tool preference, document content, preview-only state, and persistence should be deliberately separated.

The current code already demonstrates local theme ownership in Prop Editor (_ui_theme) and Stage token validation/cache behavior in SandboxTheme. This guide recommends extending those strengths; it does not claim the editor themes are currently unified.

### 4.3 Responsive workspace behavior

- Preserve canvas priority. When space is constrained, inspector content scrolls before drawing tools or essential canvas controls are clipped.
- Keep splitters draggable and give both sides a useful minimum. Prop Editor has the outer canvas/inspector split and an Attach preview split; these are good workspace patterns to retain.
- Use container-driven rows (FlowContainer, HBoxContainer, VBoxContainer) instead of fixed offsets for control groups that can wrap or grow with theme fonts.
- Keep top actions and mode controls reachable at smaller window sizes. Wrap or stack controls only when necessary, and preserve their order and mode meaning.
- Keep toolbars, status bars, and dialogs inside safe margins. A dynamic dialog should grow from a stable anchor and scroll rather than jump or recenter after each choice.
- For Stickman Editor, the current scene uses fixed top bar offsets and a three-column layout. A responsive pass should specifically validate narrower windows, custom fonts, longer translations, and panel resizing before claiming parity with Prop Editor's split workspace.

## 5. Editor flows and state maps

The following maps describe the current interaction architecture at a level useful for future visual work. They are not proposed additions to file formats.

### 5.1 Prop Editor flow

Current primary flow, based on [prop_editor.gd](../../scripts/editors/prop/prop_editor.gd) and [prop_canvas.gd](../../scripts/editors/prop/prop_canvas.gd):

~~~mermaid
flowchart TD
    Open[Open Prop Editor] --> Recovery{Recover autosave?}
    Recovery -->|Restore| Dirty[Restore document as dirty]
    Recovery -->|Discard / none| New[New or loaded document]
    Dirty --> Arrange[Arrange shapes]
    New --> Arrange
    Arrange --> Reshape[Reshape vertices]
    Arrange --> Attach[Attach anchors and preview]
    Reshape --> Arrange
    Attach --> Arrange
    Attach --> Reshape
    Arrange --> Save[Save / Save As]
    Reshape --> Save
    Attach --> Save
    Save --> Clean[Saved status; autosave cleared]
    Arrange --> Exit{New / close with changes?}
    Reshape --> Exit
    Attach --> Exit
    Exit -->|Save| Save
    Exit -->|Discard| Close[Close or start new]
    Exit -->|Cancel| CurrentMode[Return to current mode]
~~~

Presentation rules for this flow:

- Arrange, Reshape, and Attach are persistent tool modes. Keep the active mode visually selected and keep mode labels stable.
- Mode changes may change available controls and inspector sections. Explain missing controls through a short label or helper only when the reason is not obvious from the mode.
- Shape/anchor edits change the document and should visibly change dirty status. Preview motion, visibility toggles, and other session-only controls should not imply the document was edited.
- Saving should confirm completion in the status area or title state. Errors should identify the failed file action and retain the child's work.
- New and close with unsaved changes offer explicit **Save**, **Discard**, and **Cancel** outcomes. For actions that could replace work, name the consequence in the prompt.
- In Attach mode, show the selected anchor and its editable handles clearly on the canvas, and keep the private stickman/prop preview visually separate from the authoring surface.

### 5.2 Stickman Editor flow

Current primary flow, based on [stickman_editor.gd](../../scripts/editors/stickman/stickman_editor.gd), [body_part_panel.gd](../../scripts/editors/stickman/body_part_panel.gd), and [whole_stickman_preview.gd](../../scripts/editors/stickman/whole_stickman_preview.gd):

~~~mermaid
flowchart LR
    LoadOrStart[Load or start stickman] --> Parts[Choose a body-part drawing panel]
    Parts --> Draw[Draw and color one or more shapes]
    Draw --> Select[Select shape or vertex]
    Select --> Preview[Inspect whole-stickman assembly]
    Preview --> Guide[Toggle pose guide / reset views]
    Guide --> Parts
    Parts --> Save[Save stickman]
    Save --> Continue[Continue editing]
    LoadOrStart --> Clear[Clear with confirmation]
    Clear --> Parts
~~~

Presentation rules for this flow:

- Make the active body-part panel and active shape unambiguous. Selecting a shape in one panel clears selection in the others.
- Keep local drawing context and the assembled Whole Stickman preview distinct but visually related. A change in one body part should have a prompt, visible effect in the assembly preview.
- Use the pose guide as quiet construction help beneath selection gizmos. Guide colors distinguish left/right limbs; the guide must not capture pointer input or obscure active edits.
- Keep color editing and recent colors close to the relevant part, and confirm a color only through the explicit dialog action.
- Keep grid/snap and guide visibility available as tool preferences, visually separated from authored shape color and geometry.

### 5.3 Reusable dialog transaction

For either editor, the expected child-facing sequence is:

1. State the action in the title and one short sentence.
2. Show the effect or consequence when it may be surprising.
3. Present one primary action, any needed destructive action, and a visible **Cancel**.
4. Keep focus in the dialog, preserve the current anchor during resize, and return focus to the invoking control after close where practical.
5. On success, close the dialog and update the affected editor state once. On cancel, leave the document unchanged.

This is a target interaction contract for editor dialogs. Existing controls should be checked individually before being treated as compliant.

## 6. Interaction, feedback, and child-facing language

### 6.1 Input and feedback

- Support mouse and touch-size targets; target at least **44 × 44 logical pixels** for child-facing actions. Prefer Stage's **48 px** action target where the layout allows.
- Keep keyboard navigation visible and complete: Tab reaches meaningful controls, Enter/Space activates them, Escape cancels temporary tasks, and focus does not disappear behind a selected style.
- Keep right-click and keyboard shortcuts as optional accelerators. A visible menu item or button should remain available for important operations.
- For dragging, preview changes continuously, show which handle is active, commit on release, and provide a clear cancel path when the operation is consequential or multi-step.
- Avoid hit-test surprises: decorative labels/icons ignore mouse input; a large row toggle has one activation target; a canvas guide is visual only.
- Preserve the world point under the cursor during zoom. Keep selected gizmos and handles visible above artwork and grid.
- Use both visual and textual feedback for snap, mode, selected state, disabled reason, save state, and errors.

The Stage panel's full-row toggle and stable help layout are useful behaviors when a row switch is appropriate. In an editor inspector, apply the same principles without copying the Stage card's floating shell.

### 6.2 Copy and labels

Prefer concise, concrete verbs and familiar terms:

| Prefer | Avoid |
| --- | --- |
| **Arrange**, **Reshape**, **Attach** | Technical labels such as “Transform mode” or “Edit points mode” as the main child-facing label |
| **Add Shape**, **Erase Shape**, **Create Point**, **Remove Point** | Ambiguous labels such as “Apply” when the result can be named |
| **Save**, **Save As…**, **Load**, **Cancel** | Icon-only actions with no tooltip or accessible label |
| “This shape was reshaped.” | A disabled Radius field with no explanation |
| “Choose where this prop attaches.” | Internal terms such as “anchor payload” |
| “Unsaved changes. Save before starting a new prop?” | Generic “Are you sure?” without naming the consequence |

Emoji can help distinguish common actions, as used by Prop Editor menus, but should be an optional cue rather than the only meaning. Keep the text label understandable if an emoji font is unavailable. Use the same wording for the same action in menu, dialog, toolbar, tooltip, and user guide.

### 6.3 Icons and emoji

- Use one icon or emoji to help scan a familiar action; do not put emoji on every label by default.
- Keep the text label as the source of meaning. Provide a tooltip or accessible name for icon-only canvas tools.
- Use icons consistently for the same action across menus, toolbars, empty states, and dialogs. Avoid changing icon meaning between editors.
- Avoid using an emoji's color as the only state cue; fonts and platforms may render it differently.
- The Prop Editor already uses emoji in File and mode labels. The Stickman Editor currently uses plain menu labels. Treat a visual icon pass as a recommendation that should be applied consistently, not as a current shared convention.

### 6.4 Empty, loading, and error states

The current editors have different levels of state guidance. The following table separates known behavior from recommended presentation:

| State | Current reference | Recommended presentation |
| --- | --- | --- |
| New/empty Prop canvas | Arrange has an add-shape context menu and an Arrange-only empty-canvas hint; Reshape does not offer adding a shape. | Keep the canvas mostly clear. Show a short Arrange hint only when it helps discover the next action; hide it as soon as artwork exists. Do not show a dead-end hint in Reshape or Attach. |
| Empty Prop inspector selection | Inspector sections depend on mode and selected shape/anchor. | State what to select or create when the empty inspector would otherwise look broken. Keep the message short and do not add a second competing empty-canvas prompt. |
| Prop load/recovery | Load failures use an error dialog; autosave recovery offers Restore or Discard. | Name the file/action in the message, preserve the current artwork on failure, and keep Restore/Discard outcomes distinct. Loading feedback should not imply that the document is already saved. |
| Stickman panel before drawing | The ten body-part panels are the main workspace; the panel script owns drawing and selection behavior. | Give each blank panel a concise, low-contrast drawing cue if discovery testing shows it is needed. Remove it on first shape so it does not compete with artwork. |
| Stickman load/clear | Load and save use file dialogs; Clear has a confirmation dialog; error dialogs report failures. | Keep the current document intact on a failed load. State the consequence in Clear confirmation and offer a visible cancel path. |
| Save / dirty state | Prop Editor has status/title and autosave behavior; Stickman Editor status bar reports cursor coordinates and snap state. | Make save status easy to find in both editors. Do not treat autosave as a user-visible successful save unless the file was actually saved to the chosen destination. |

Do not add spinners or blocking overlays for synchronous work without evidence that the operation takes long enough to need them. If an operation becomes asynchronous, keep progress near the task and preserve access to cancellation where safe.

### 6.5 Motion and reduced motion

- Use motion to show cause and effect: a brief selection flash, a panel entering, or a successful action cue. Keep it short and do not delay the next input.
- Do not animate every hover or value change. Motion should help the child understand an edit, not decorate idle controls.
- Keep persistent mode and selection state visible after any transition ends.
- Respect a reduced-motion preference for nonessential transitions and flashes. Provide an equally clear static state.
- The current code has short visual effects such as the Prop canvas's new-point flash and Stage completion effects. A unified reduced-motion preference is not established by the referenced theme/specs; treat it as a future product-level decision.

## 7. Theme and implementation checklist

Before adding or revising an editor control:

### Design

- [ ] Is the control's job clear and is it in the correct workspace area?
- [ ] Does it follow the correct pattern: persistent inspector, modal dialog, canvas tool, or temporary capture?
- [ ] Are neutral, hover, selected, focused, disabled, dragging, and error states defined?
- [ ] Does selected state remain distinct from hover and focus?
- [ ] Are colors backed by labels, icons, position, or shape cues where appropriate?
- [ ] Are labels child-readable and consistent with the existing action vocabulary?
- [ ] Can the layout handle smaller windows, longer names, and larger font presets?

### Theme

- [ ] Are colors, type sizes, spacing, radii, borders, and target sizes tokens rather than repeated literals?
- [ ] Does the token use a semantic name rather than a control-specific unexplained hex?
- [ ] Does it have a validated accessor, fallback, and range clamp where applicable?
- [ ] Are per-control style changes local and isolated from a shared cached Theme?
- [ ] Is the difference from Stage tokens intentional and documented?

### Interaction

- [ ] Can pointer, touch, and keyboard users reach and activate the control?
- [ ] Does a disabled control explain why, if not self-evident?
- [ ] Does temporary work have an obvious Cancel/undo path?
- [ ] Does a control's position remain stable while help, validation, or mode content changes?
- [ ] Does changing a tool preference avoid marking the document dirty unless that is intentional?
- [ ] Does success/failure produce visible feedback without hiding the canvas or losing authored work?

### Architecture

- [ ] Does the editor controller own document mutation, persistence, and dirty state?
- [ ] Does a reusable control emit a typed intent and display a supplied value?
- [ ] Is new reuse actually shared by more than one appropriate UI context?
- [ ] Are UI preferences, preview-only state, and document data kept separate?
- [ ] Are new theme values represented in both default config and committed JSON?
- [ ] Are existing user guides/specs updated only after the behavior is verified?

### Implementation recipe

For a new editor UI element, use this sequence:

1. Name its job and state owner. Decide whether the editor controller, canvas, or reusable view owns the value and mutation.
2. Identify the closest reference pattern: Stage inspector, Stage dialog, Prop Editor mode control, Prop canvas selection, or Stickman body-part panel. Record what should carry over and what should not.
3. Define the semantic tokens and states before styling. Reuse existing token names where their meaning matches; add new names to the theme defaults and JSON with validation/fallback behavior.
4. Build with Godot containers and native controls first. Add a custom control only when it provides repeated behavior or custom canvas drawing.
5. Wire typed intent signals to the owning controller. Refresh controls from document state without emitting a second mutation.
6. Check the smallest supported window, larger type, long labels, all modes, selected/disabled/focused states, and save/error/cancel paths.
7. Capture before/after screenshots or a short manual checklist. Update the user guide after the behavior is accepted.

This is recommended implementation order, not a claim that every current editor control follows it.

### Recommended harmonization order

1. **Agree on token ownership and names.** Define shared semantic roles for background, surface, text, muted text, EDIT accent, focus, primary/destructive action, spacing, radii, borders, and minimum targets. Keep canvas-specific colors separate.
2. **Resolve token drift.** Decide whether Prop's #4FA3FF accent and 36 px button/row minima should move toward the Stage reference, or remain intentional editor overrides. Record the choice and add an accessibility rationale for target sizes.
3. **Bring Stickman chrome into token ownership.** Move its scene-level colors, font sizes, spacing, and bar sizing into a validated theme source while preserving the panel/preview composition that supports drawing.
4. **Improve responsive layout.** Replace brittle fixed offsets where font or window growth can clip controls; establish minimum column widths and wrapping behavior for both editors.
5. **Unify states and dialogs.** Verify focus, disabled reasons, save/error status, destructive confirmation, and cancel behavior. Reuse dialog styling only after its host/lifecycle works in the editor.
6. **Validate visually at agreed sizes.** Compare the editor screenshots with the Stage reference and adjust intentional differences explicitly.

This order is a recommendation. It does not select a new shared-theme class or authorize a source migration; choose the theme architecture when implementation scope is defined.

### Visual QA checklist

- [ ] Compare Prop and Stickman editor startup screens side by side with the Stage's dark surface and EDIT accent references.
- [ ] Check every mode with no selection, with a selected object, during drag, and after release/cancel.
- [ ] Check primary action, destructive action, disabled control, hover, keyboard focus, and persistent selected states.
- [ ] Check prop autosave recovery, load failure, unsaved New/Close, and successful save feedback.
- [ ] Check Stickman Clear confirmation, load failure, snap status, pose guide, and cross-panel selection.
- [ ] Resize to the smallest supported viewport and increase font size. Confirm canvas access, scroll access, and nonoverlapping controls.
- [ ] Verify visible keyboard order and Return/Space/Escape behavior; confirm focus returns to the invoking control where appropriate.
- [ ] Check grid, artwork, selection halo, vertex handles, pose guide, anchor markers, and preview ghosts against light and dark artwork.
- [ ] Check text contrast and state distinction with a contrast measurement and color-vision simulation; the current specs do not provide measured results.
- [ ] Repeat the checks with emoji rendering unavailable or replaced; action meaning must remain clear from text.

## 8. Recommended additional coverage

To make this guide a stronger long-term design reference, add these pieces as the editor UI evolves:

1. **Annotated screenshots at canonical window sizes.** Include each editor's initial screen, every mode, selection/reshape states, Attach preview, and one modal. Mark which visuals are current and which are target.
2. **A shared token inventory.** Decide semantic names and authoritative ownership for surfaces, accents, focus, destructive actions, canvas grid, selection halo, typography, spacing, and minimum target sizes. Reconcile SandboxTheme, PropTheme, and Stickman Editor scene-level values in a planned migration.
3. **Responsive breakpoints and minimum workspace sizes.** Record minimum usable canvas/inspector widths, when controls wrap, how the Attach preview stacks, and how Stickman Editor's three columns adapt.
4. **Accessibility and contrast acceptance checks.** Specify contrast targets, keyboard tab order, focus visibility, touch target checks, color-vision-safe cues, and high-font-size behavior. The current references provide useful states and target sizes but do not establish a measured accessibility audit.
5. **Motion and sound rules.** Define when transitions, selection flashes, save feedback, and error feedback animate or use sound; keep them brief, informative, and respectful of reduced-motion preferences.
6. **Content and localization rules.** Include label length budgets, wrapping/truncation behavior, tooltip standards, pluralization, and translation expansion checks.
7. **Editor-specific control patterns.** Document mode bars, drawing canvases, color pickers, anchor lists, selection gizmos, empty states, and destructive file flows as reusable examples with their owning state and signals.
8. **Verification matrix.** Link each visual contract to a scene/test/manual check so future changes can distinguish an implemented pattern from a recommendation.

## 9. Reference files

- [AGENTS.md](../../AGENTS.md) — repository layout, editor architecture, shared Stage UI, and child-facing dialog guardrails.
- [Stage panel UI system](../specs/stage_panel_ui_system.md) — Stage inspector card, transient capture bar, component contracts, fitting, and acceptance criteria.
- [Dialog Design Principles](../specs/dialog_design_principles.md) — child-facing modal shell, action hierarchy, and stable resize behavior.
- [SandboxTheme implementation](../../scripts/stage/sandbox_theme.gd) and [SandboxTheme config](../../sandbox_theme.json).
- [PropTheme implementation](../../scripts/editors/prop/prop_theme.gd) and [PropTheme config](../../prop_theme.json).
- [Prop Editor controller](../../scripts/editors/prop/prop_editor.gd), [Prop Editor scene](../../scenes/editors/prop/prop_editor.tscn), and [Prop Editor guide](prop_editor_user_guide.md).
- [Prop canvas](../../scripts/editors/prop/prop_canvas.gd) — mode behavior, canvas gestures, selection handles, and context menus.
- [Stickman Editor controller](../../scripts/editors/stickman/stickman_editor.gd), [Stickman Editor scene](../../scenes/editors/stickman/stickman_editor.tscn), [BodyPartPanel](../../scripts/editors/stickman/body_part_panel.gd), and [Whole Stickman preview](../../scripts/editors/stickman/whole_stickman_preview.gd).
- [Stage dialog style helper](../../scripts/shared/stage_ui/stage_dialog_styler.gd) and [Stage capture bar](../../scripts/editors/stage/stage_use_target_capture_bar.gd).
- [Prop Editor UX specification](../specs/phase_9c_prop_editor_ux.md) — current approved Prop Editor mode, Attach preview, marker, and layout behavior.