ryan/stickman
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a9c0886348a89cf86a36f2bf170f91b8e25f4c22
stickman/docs/guides/editor_visual_style_guide.md
T

46 KiB
Raw Blame History

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 current and future editor UI. Prop and Stickman share EditorVisualTheme for editor chrome and selected reusable controls; Stage-only layouts and components remain Stage-specific unless explicitly generalized.

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. Stage inspector controls live under 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 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 action plans Phase 20b defines the DIRECT Step Stack, action markers, target capture, and action picker. Use these as Stage-specific references. Reuse their general feedback principles in editor workflows only when the interaction fits.
Stage object names and overlap chooser Phase 20a defines the name-and-Rename inspector header and the anchored Objects here chooser. Reuse the rename interaction for other renameable objects; reuse the chooser shell and state tokens for similar non-modal object pickers. Follow the click-versus-drag and transform-handle priority in §4.6. Keep object-specific naming rules with the owning feature.
Stage and editor dialogs StageDialogStyler draws the shared confirmation card over the active scene while retaining native dialog signals. The style reads popups.confirmation from SandboxTheme. Use this shared card for Prop and Stickman confirmation, recovery, and short action dialogs. Native file picker content remains native.
Shared editor chrome EditorVisualTheme loads validated tokens from editor_visual_theme.json and builds each editor's local control Theme. EditorSelectionDropdown and EditorContextMenu supply shared selection and canvas-menu styling. Use shared semantic tokens and controls for matching editor workflows. Keep editor-specific document behavior in its owner.
Prop Editor PropTheme reads prop_theme.json for material, geometry, and canvas defaults; editor chrome comes from EditorVisualTheme. The main scene uses split containers, a scrollable inspector, modes, and a nested Attach preview. Keep Prop artwork/material values and canvas contrast in PropTheme; use shared editor tokens for chrome, inspector states, and selection dropdown styling.
Stickman Editor stickman_editor.gd uses EditorVisualTheme for chrome and coordinates ten BodyPartPanels in a two-column Overview beside the Whole Stickman preview, plus a Focus view for one large panel. Overview columns and panels expand to the workspace size, retaining a 230 × 160 px minimum and scrolling when space is short. Keep the splitter draggable, preserve panel state, and show the part title inside its panel in both views.
Child-facing dialogs Dialog Design Principles 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 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 Shared editor accent for active modes, selection accents, and editor guidance through EditorVisualTheme.
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 Shared chrome and intentional editor differences

Both standalone editors now use EditorVisualTheme for shared chrome roles, sizing, and local control Themes. Keep these domain-specific values in their existing owner:

  • PropTheme retains material tints, primitive defaults, outline widths, and the Prop canvas surface/grid. Keep its neutral charcoal canvas distinct from the blue-tinted editor panels. Stickman canvas grid and selection colors remain in EditorVisualTheme.stickman_canvas tokens.
  • EditorVisualTheme owns common editor surfaces, text, EDIT accent, focus, action roles, menu sizes, and minimum targets. SandboxTheme continues to own Stage-specific panels and dialog tokens.

Preserve these boundaries when extending the UI: share semantic chrome roles where workflows match, and keep canvas, material, and runtime-domain colors local to their owner.

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.
  • For short numeric settings such as a wait duration, keep the value directly editable, show its unit, and offer a large touch-size stepper. Optional quick picks should update the same value. Keep typed input, stepping, quick picks, and bounds synchronized; choose an increment that suits the setting.
  • 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. 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. Separate sections with rounded cards, readable headings, colorful section icons, and concise helper copy; keep related values grouped in compact tiles. Reuse Stage's hierarchy and state clarity, but 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. 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.
  • Anchored object chooser: use the non-modal chooser pattern in section 4.6 for resolving overlapping canvas targets. Keep it visually distinct from a centered dialog and from a persistent inspector.
  • 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.

Both standalone editors build their chrome Theme from EditorVisualTheme; Prop also uses PropTheme for prop-specific art and material defaults. Stage remains the reference for fitting, dialog hierarchy, and child-facing language, but its in-stage inspector layout is not a default editor-inspector component.

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.
  • Stickman Overview uses two equal, flexible columns of five body-part drawing panels beside the Whole Stickman preview. Let both columns fill the Overview pane and share extra width; let the five rows share extra height while preserving a 230 × 160 px minimum panel size. Scroll the Overview when the viewport is shorter than its minimum content size.
  • Keep the Overview/preview splitter draggable. On narrow windows, use the existing Focus view to give one body-part panel the available space; keep Whole Stickman access available through its dedicated control. Switching views must preserve each panel instance, authored geometry, selection, and view transform. In Focus, use the title inside the active panel as the only canvas heading; do not repeat it above the panel.
  • Validate the layout at wide and narrow windows, with raised fonts and resized panels, before claiming responsive behavior.

4.4 Shared confirmation dialog style

Use the Sandbox Stage confirmation card for child-facing confirmation, recovery, and short action dialogs in both standalone editors. The shared implementation is StageDialogStyler, with color, sizing, and spacing values from SandboxTheme.popups.confirmation.

  • Draw a dim backdrop and a centered, rounded dark card. Use the themed card width (560 px target), 22 px inset, 18 px corners, and 2 px border; fit the card inside the safe viewport.
  • Put a contextual icon badge and a left-aligned 28 px title in the header. Put the message in a left-aligned 20 px body. Wrap longer copy and scroll the body if the viewport is short.
  • Order actions as primary, destructive, then Cancel. Use Stage blue for Save, Restore, and other forward actions; use the danger treatment for Discard, Start Over, and other destructive choices; use the neutral surface for Cancel. Make action labels at least 52 px high and 112 px wide, with 12 px gaps.
  • Keep the visible Cancel action even when Escape is supported. Do not show a native title-bar ×. Focus the primary action when present; for a destructive-only prompt, focus Cancel.
  • Keep the native AcceptDialog or ConfirmationDialog as the signal source and open its shared overlay through StageDialogStyler. This keeps confirmation, custom-action, cancellation, keyboard, and safe-viewport behavior consistent.
  • Apply this pattern to Prop recovery, unsaved changes before New/Close/Stage return, off-origin save choices, anchor rename, and error acknowledgement; apply it to Stickman Start Over, unsaved changes, grid setup, and error acknowledgement. File pickers keep their native file-selection interface.

Treat the card as one shared product pattern. Do not create editor-local confirmation palettes or button-role variants.

4.5 Renameable object inspector header

When a selected object has a user-editable name, show that name once in the inspector header beside the object's type icon. Put a clearly labeled Rename button beside it; the title itself should not be an undisclosed rename hotspot. Truncate a long title with an ellipsis and expose the full value as a tooltip. Keep the header and Rename action visible when the inspector body is collapsed.

Activating Rename reveals a prefilled, single-line field anchored directly below the header. Provide a prominent Done action and a neutral Cancel action, both with child-sized targets. Enter commits and Escape cancels. Keep validation beside the field, explain the problem in plain language, and offer a concrete suggestion when possible. A failed rename keeps the draft visible. Cancel restores the inspector's previous expanded or collapsed state; a successful rename updates the header and any visible object labels.

Use this interaction for other renameable objects when their inspector can support the same compact header and inline edit. Keep validation, uniqueness, and persistence rules in the owning feature; this visual pattern does not prescribe domain rules. Store shared header, edit, button, focus, and spacing values in the owning UI theme rather than inventing local styling for each object type.

4.6 Anchored object chooser

Use an anchored chooser when a click lands on multiple real canvas targets and the child must choose which one to act on. The Stage's Objects here popup is the implementation reference. It is a temporary, non-modal popup near the click, not an inspector or a centered confirmation dialog.

  • Resolve selection clicks and movement gestures together. When the already-selected object is one of the overlapping targets, check its rotate and resize handles first on pointer press; a handle gesture starts that transform immediately. A press on the selected object's visible body becomes a drag after movement exceeds the screen-space threshold (8 logical pixels in Stage). If released before the threshold, open the chooser and preserve the prior selection. Measure movement in screen space so zoom does not change the gesture; other canvas workflows can tune the threshold while keeping this ordering.

  • Give the popup a dark raised shell with a clear 2 px border, a 12–16 px corner radius, a restrained local shadow, and 12–16 px of inner space. Keep the stage visible; do not dim the canvas behind this short selection task.

  • Use full-width rows at least 44 px high, preferably around 56 px, with about 8 px between them. Keep the candidate's icon and name together. The selected candidate keeps a teal fill, cyan outline, and a visible Selected label; hover and keyboard focus each remain easy to distinguish from selection.

  • Keep a rounded, neutral Cancel button in a separate footer, at least 48 px high. Escape may also cancel. An outside click closes the chooser and is consumed so it cannot select the stage underneath.

  • Keep the clicked art visible where possible, fit the popup to safe viewport margins, and cap the list height so longer candidate lists scroll. Keep pointer hover and keyboard focus behavior equivalent when they preview a candidate.

  • Define shell, row, selected, hover, focus, badge, spacing, and Cancel values as theme tokens. The Stage implementation uses SandboxTheme.popups.anchored_chooser; other workflows should reuse the visual contract through their own appropriate theme owner.

4.7 Stage action planning and target capture

These are Stage-specific references, not a new inspector layout for the standalone editors. The Phase 20b spec owns the exact action behavior and component placement.

Temporary target capture: Keep one short, action-specific prompt and a visible Cancel together in a stable capture bar. Dim and block the underlying inspector while the stage is waiting for a target. Escape and right-click may act as shortcuts, but the visible Cancel remains available. Cancel discards the draft, restores the prior selection and focus, and leaves the plan and dirty state unchanged. Show a cursor marker and action-specific feedback: highlight only valid Set Down surfaces, keep Move feedback grounded at the actor's walking level, and preserve Throw's ballistic preview. Do not show a movement-looking trajectory while choosing a Pick Up prop.

Action markers: Use one readable icon-and-verb pill for each action. When actions run together, keep their pills separate and stack them so each remains identifiable. Anchor Pick Up at its prop, Say and Wait by the actor, and Move at its destination. Let pill color reinforce the action type while the label remains the source of meaning. Do not repeat the step number in the pill when its route flag already carries that number.

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 and prop_canvas.gd:

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, body_part_panel.gd, and whole_stickman_preview.gd:

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. If the only forward-looking choice is destructive (such as Start Over), keep it in the danger role and focus Cancel initially.
  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.
  • Keep the top-level File/Edit/View menu titles plain and use familiar emoji beside readable action labels inside their dropdowns. Match the Sandbox Stage menu scale: 22 px menu-bar labels and 26 px popup labels. Group file actions as New/Open/Recent, then Save/Save As, with separators before a distinct Rename or Start Over action where present. Use the restrained charcoal popup surface for menu-bar dropdowns; reserve the raised Studio List surface for canvas right-click menus.
  • Style single-choice editor pickers as a dark field with the chosen label and chevron. Popup rows keep readable text and may include a meaningful domain icon, as in Prop material and shape choices; do not show radio/check glyphs or an empty indicator lane. The current choice gets a full teal surface and cyan outline. Keep hover and keyboard focus visible, and give the field and rows at least 44 logical pixels of height. Use the shared EditorSelectionDropdown control for Prop and Stickman editor pickers.
  • Standardize Prop and Stickman canvas context menus on the Studio List pattern: a compact vertical list on a raised editor surface, with a subtle border, rounded corners, readable 20 px labels, and 48 px rows. Resolve surface, border, text, hover, EDIT accent, focus, and destructive colors through EditorVisualTheme tokens rather than local color literals.
  • Group related actions with spacing and separators, and keep each menu's actions specific to the current mode and hit target. Hover uses a lighter surface with a slim EDIT-cyan cue; keyboard focus has a distinct, high-contrast focus outline. Open with no focused row so mouse users do not mistake an action for a selection; show the focus outline after Up/Down navigation, and clear it when the pointer takes over. Give destructive actions explicit labels, separate them from regular actions, and place them last when practical; do not use color as their only cue.
  • Keep labels as the source of meaning and use icons sparingly and consistently. Open the menu near the pointer, keep the clicked point or shape edge visible, and clamp the menu within the viewport.
  • 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 both 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.
  • Both editors use icons beside readable menu action labels, with separators between distinct groups. Keep top-level File/Edit/View titles plain; place icons on actions and use the same symbol for the same operation across editors.
  • In the Prop inspector, use colorful, flat icons for section headings, material choices, 2D shape choices, and artwork tags. Keep text labels authoritative. Show tag selection with the selected surface and border; do not add a separate check badge. Shape icons must depict planar 2D geometry.

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's status bar reports cursor coordinates, snap state, and save state. Keep 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.
  • For a secondary chooser that slides out beside an inspector, align the panel tops and briefly dim the parent to show that the chooser is temporary. Keep a visible Cancel; Escape and an outside click should reverse the same transition. On close, restore the parent and return focus to the control that opened the chooser.
  • For card reordering, keep bold up/down buttons stationary and animate the affected cards exchanging places after activation. Keep the selected card selected and visually in front, preserve scroll and focus, and ignore repeat input until the swap finishes.
  • Respect a reduced-motion preference for nonessential transitions and flashes. Provide an equally clear static state.
  • When reduced motion is requested, show the chooser or reordered cards directly in their final state without the transition.
  • 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. Maintain token ownership. EditorVisualTheme owns shared standalone-editor chrome; PropTheme owns prop-domain and canvas defaults; SandboxTheme owns Stage-specific UI. Document any intentional override at the token or component that owns it.
  2. Audit remaining overrides. Check for editor chrome values that still bypass EditorVisualTheme; preserve the Prop canvas surface/material palette and Stickman canvas drawing tokens where they serve artwork contrast.
  3. Document responsive limits. Record minimum usable widths, toolbar wrapping, how the two Stickman Overview columns share space beside the preview, and when Focus or scrolling takes over.
  4. Audit remaining state gaps. Verify focus, disabled reasons, save/error status, destructive confirmation, and cancel behavior. Both editors use the shared StageDialogStyler card for confirmation, recovery, and short action dialogs.
  5. Validate visually at agreed sizes. Compare the editor screenshots with the Stage reference and adjust intentional differences explicitly.

This order is a maintenance checklist for the current shared chrome and editor-specific drawing patterns; it does not propose replacing the established theme architecture.

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 theme ownership map. Document how SandboxTheme, EditorVisualTheme, and PropTheme divide Stage UI, shared editor chrome, and Prop domain/canvas values. Note intentional overrides and identify any remaining editor chrome that bypasses its shared token.
  3. Responsive breakpoints and minimum workspace sizes. Record minimum usable canvas/inspector widths, when controls wrap, how the Attach preview stacks, and how the two Stickman body-panel columns share space with the Whole Stickman preview.
  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

Reference in New Issue View Git Blame Copy Permalink