stickman/plans/PHASE_7_UI_POLISH.md

High-Level Architectural Plan: Graphical UI & Palette Polish Phase

Objective

To overhaul the SandboxStage user interface into a polished, kid-friendly graphical experience, while establishing a flexible, schema-driven theme system that seamlessly supports present UI elements and future feature additions (such as dynamic speech bubble styling, sound customization, and extended rule editors).

---

1. Centralized Theme & Resource Infrastructure

1.1 JSON Theme Schema Expansion (sandbox_theme.json)

• Unified Theme Specification: Expand the sandbox_theme.json contract to serve as the single source of truth for typography, spatial grids, mode accent colors, and component-specific visual presets.

• Subsystem Category Blocks: Structure the schema into modular sub-dictionaries (e.g., fonts, mode_colors, grid, popups, speech_bubbles).

• Graceful Fallback Pipeline:

1. Specific component override value.

2. Subsystem block default (e.g., speech_bubbles.style_defaults).

3. Global theme default (fonts.ui_font).

4. System fallback (ThemeDB.fallback_font).

• Resource Preloading & Validation: Ensure the theme loader validates paths, gracefully handles missing assets with non-blocking warnings, and caches loaded Font and StyleBox objects.

---

2. Graphical Stage Chrome & Mode Navigation

2.1 Mode Switcher & Viewport Frame

• 3-Segment Graphical Switcher: Replace standard text toggles with a stylized 3-segment mode control ([✏️ Edit | 🎬 Direct | ▶️ Play]).

• Viewport Frame Accent: Render a screen-constant border frame (_mode_frame) around the viewport that dynamically tints according to the active mode accent color.

• Mode Badge Pill: Maintain a rounded, high-contrast status badge in the viewport corner displaying the active state with mode-specific icons and accent backgrounds.

2.2 Status Bar & Dynamic Cursor System

• Status & Coordinate Bar: Polish the bottom bar for scannability, hosting contextual operational hints and live spatial coordinates.

• Contextual Cursors & Floating Tooltips:

• Swap between arrow/crosshair, placement cursors, and custom action reticles depending on mode and pending operations.

• Attach floating, high-contrast tooltip pills offset from the cursor during target selection workflows (e.g., direct mode commands or trigger mapping).

---

3. Icon-Based Palette & Thumbnail Engine

3.1 Draggable / Clickable Card Palette

• Visual Asset Cards: Transition spawner controls from text buttons to visual card tiles displaying item icons, labels, and category badges.

• Placement Integration: Support both click-to-select active placement and direct drag-and-drop actions onto the stage.

3.2 Modal Asset Selector & Thumbnail Pipeline

• Asset Selector Modal: Refine the modal popup and its dimming background backdrop for browsing extended stickmen and prop libraries.

• Asynchronous Thumbnail Cache:

• Streamline off-screen thumbnail generation for custom props and stickmen.

• Cache generated preview textures to prevent UI stuttering during library scans.

---

4. Visual Overlay & Placement Feedback Engine

4.1 Terrain Drag-Painting & Ghosting Feedback

• Block-Unit Stride Alignment: Align placement ghosts and Bresenham line painting to the active terrain template's AABB extent.

• 3-State Ghost Tinting:

• Green: Valid, empty space ready for placement.

• Faint / Neutral: Same-type block (skipped to avoid double-stamping).

• Red: Conflicting entity or invalid geometry.

4.2 Guidance & Target Trajectories

• Axis-Aligned Guides: Render high-contrast dashed lines along cardinal axes during Shift-locked terrain drags.

• Rubber-Band Trajectories: Draw contextual connection lines and target reticles from character origins to mouse targets during Direct mode actions.

---

5. Reusable Control Widgets & Forward-Compatible Systems

5.1 Standardized Kid-Friendly UI Components

Develop a suite of reusable, theme-aware control widgets that can be embedded across dialogs, action popups, and future parameter editors:

• Color Swatch Selector: Clickable circle palettes populated from theme swatch arrays or editor history.

• Preset Size Toggles: Segmented buttons for coarse adjustments (e.g., Small, Medium, HUGE) mapping to backend integer/scale metrics.

• Preset Style / Font Pickers: Visual icon or text buttons allowing selection between preset fonts (e.g., Standard, Comic, Pixel, Scary).

• Emoji Quick Grid: A dedicated grid widget for inserting expressive graphics directly into text fields.

5.2 Context Menus & Action Popups

• Uniform Popup Styling: Apply standardized theme rules, font sizes, and emoji scaling across action context menus, trigger submenus, and dialogs.

• Clean Action Dialogs: Align text input (Speak), duration (Wait), and rename popups with dark-mode sandbox styling.

5.3 Extension Blueprint: Speech Bubble Customization System

Architect the theme and component pipeline so that future speech bubble upgrades plug directly into the visual foundation without refactoring:

• Data Contract: Ensure the speak action payload accepts visual parameters (font_preset, size_preset, color, bubble_style) alongside text.

• Style Engine Integration: Speech bubble nodes consume geometry styles (Standard, Yell, Thought, Whisper) and theme font presets directly from sandbox_theme.json.

• UI Reusability: The standard Color Swatch, Size Toggle, Font Picker, and Emoji Grid widgets drop directly into the Direct mode Speak parameter dialog.

---

Recommended Execution Sequence

1. Phase 1: Theme Engine & Core Schema: Extend sandbox_theme.json schema, build centralized theme loading/fallback pipeline, and integrate theme application hooks across stage UI.

2. Phase 2: Chrome & Mode Navigation Polish: Implement the 3-segment mode control, viewport frame accents, status badges, and cursor/tooltip overlay controllers.

3. Phase 3: Reusable UI Component Library: Build the Color Swatch, Size Toggle, Font Picker, and Emoji Grid widgets.

4. Phase 4: Graphical Palette & Modal Overhaul: Implement icon-based asset cards, refine the AssetSelector modal, and optimize asynchronous thumbnail caching.

5. Phase 5: Context Menus & Overlay Polish: Update action popups with uniform theme sizing and polish drag-painting ghost/guide overlays.