# Workshop UI rework Design specification, updated 2026-11-01. Implementation status is listed below. Physical parts, typed signals and ECU requirements are defined in the [machine systems roadmap](MECHANICAL_BUILDER_PLAN.md). ## Implementation status The first UI pass implements the dark theme, shared adaptive panel geometry, resizing/collapse with saved preferences, library search/categories and previews, an Objects list, a measured inspector with stacked property fields, fitted control labels and hover disclosure, direct click/drag connections, persistent Run/Pause/ Step controls, navigable checks, and a separate resizable oscilloscope dock. Existing ECU assignment ports use input rings and filled output circles; gas ports retain their physical semantics. The Sense inspector now adds physical sensor taps, unresolved binding repair and per-sample live outputs, using green Number and red Boolean output dots. Sensor attachments remain locked during Test. The builder and desktop UI regressions pass. Rendered review covers empty, ECU, Checks, Meters, running/paused and collapsed layouts at 1920x1080 and 1280x720. Logic/split views now share the running machine, with a searchable node library, typed click/drag wiring, reference selection, live values/controls, parameter inspectors and compact number trends. Input rings/output circles and red Boolean/ green Number colors are checked in rendered output. Thirteen focused suites pass; graph and split layouts are reviewed at 1920x1080 and 1280x720. Grouped ECU connectors follow their runtime systems. Automatic DPI/UI scale overrides, an object hierarchy with visibility groups, richer property grouping/help and pinned operator controls remain follow-up UI work. Their design below remains the intended direction. ## Confirmed direction - Dark engineering editor with compact toolbars, clear panels and restrained colors. Reserve strong colors for signal types, selection and relevant state. - Separate **3D** and **Logic** tabs, with an optional split view. Selection and running simulation are shared across views; camera and canvas navigation state remain independent. Switching views does not restart Test. - Connect by dragging between ports or clicking a port then its target. A dedicated Connect mode is not required. Escape cancels a pending connection. - Signal inputs are hollow rings; outputs are filled circles. Boolean is red, Number green. Bidirectional physical ports use neutral domain symbols. - Panels remain in predictable positions, resize and collapse, and remember their widths. Provide a reset-layout action and constrain restored sizes to the current window so the central workspace stays usable. - The library uses compact rows with small previews, categories and search. Selecting an item shows a larger preview with its purpose and essential ports. - Starting Test preserves the current workspace, selection and navigation state. Lock structural edits while allowing safe live tuning and logic inspection. - Test starts running. Pause and Step remain visible; Step is enabled when paused, with a tooltip explaining that state when disabled. - Primary design target is a 1920x1080 desktop window. The first priority is consistent appearance and layout, especially preventing text/control overlap. - Remaining routine design decisions are made autonomously, per user direction. ## Layout and visual baseline Use a shared layout/component layer rather than individually positioned controls. Rendering and hit testing consume the same computed rectangles. Define shared theme values for spacing, typography, surfaces, borders and interaction states. Initial dimensions below are logical pixels at 100% UI scale, and may be tuned through visual review while preserving the agreed structure. | Element | Default | | --- | --- | | Spacing | 4 px base unit; 8 px control gaps; 12 px panel padding; 16 px section gaps | | Typography | 14 px body/fields, 12 px secondary labels, 16 px section titles; measured line height | | Controls | 30 px minimum row height, increased when text or UI scale requires it | | Top command bar | 44 px, with less-used file actions in a menu | | Workspace toolbar | 36 px; 3D/Logic tabs and split toggle stay discoverable | | Left panel | 260 px default; resizable between 220 and 420 px | | Inspector | 340 px default; resizable between 280 and 520 px | | Bottom area | Collapsed initially; 240 px default when opened, vertically resizable | | Status bar | 24 px minimum; longer messages go to Checks or a tooltip | | UI scale | Auto from display scaling, plus 100%, 125%, 150% and 200% overrides | Use a neutral charcoal palette with clear panel boundaries and one restrained selection accent. Reuse the same fields, buttons, tabs, badges and menus across all views. Strong red/green remains reserved for the agreed signal types; add icons/text to distinguish faults and success from those types. Support a 1280x720 window at 100% scale through a compact layout. As available logical space shrinks, move secondary toolbar actions into an overflow menu, collapse the library/object panel, and offer the inspector as a temporary panel. Preserve access to required actions and readable text instead of shrinking fonts. If split view cannot fit two usable canvases, use a single tab and explain why split is unavailable. Large UI scaling follows the same compact behavior. Choose a vertical split by default: 3D left, Logic right, with a draggable divider and a swap action. Remember divider position, panel widths/collapse states and active view in user preferences; clamp them on restore. Store machine-specific camera/canvas layout separately from physical geometry and signal values. ### Text and overlap rules - Measure text before layout. Use content-sized rows and explicit minimum sizes; never assume every property label fits a fixed width. - Inspector rows place label, value, unit and optional action in separate layout cells. Narrow inspectors stack labels above fields; units never cover digits. - Wrap help and diagnostic text and grow the row. Ellipsize long names only in compact lists/tabs, with the complete name available on hover and in selection. - Clip rendering and pointer handling to the same panel scroll region. Fixed headers and footers reserve their own space so scrolling content cannot cover buttons, tabs or trace controls. - Tooltips and menus reposition within the window and respect their anchor. Keep the focused text field visible when scrolling or opening a panel. - Lay out ECU ports from descriptor rows with adequate label/value space; nodes grow vertically as ports expand. Wires route away from pin labels before bends. - World labels use screen-space placement with collision suppression; prioritize selected/hovered labels and expose the rest on demand. Hidden labels must not hide the underlying port's tooltip or named connection-list access. ## Workspace structure Proposed layout: a slim document/command bar, workspace tabs, a left library/object panel, central workspace, right inspector, and optional bottom diagnostics/traces. Use resize handles and collapse controls within this predictable layout. - Top bar: machine name, unsaved status, file actions, undo/redo and simulation controls. Show current run state unambiguously even in Logic view. - 3D toolbar: Select, Move, Rotate, Route, snapping and fit/focus. Connection gestures work directly on visible ports and do not start a transform drag. - Logic toolbar: node search/add, frame selection/all, connection filters and live-value visibility. Node creation targets the canvas under the pointer. - Library: parts, sensors, logic nodes and saved assemblies with search and categories, displayed as compact rows with small previews. Show a larger selected-item preview and compatibility when adding from a signal port. - Objects: named parts, sensors, shafts, ECUs and assemblies. Search, select, focus, rename and hide without removing simulation membership. - Inspector: selection identity, grouped properties, connections and contextual help. Show units next to editable values and explain locked Build properties. - Bottom area: navigable checks, traces and event history. Selecting an issue locates the relevant part, port or connection in the appropriate view. - Status bar: current gesture, keyboard hints and short feedback. Important failures remain in Checks rather than disappearing with a transient message. ## Core workflows ### Place and configure Search for a part, select it, preview placement, then click to place. Shift repeats placement. Escape cancels. Placed parts immediately expose a name and the small set of essential properties; advanced groups expand on demand. Preserve current copy/paste, assembly and undo workflows as the UI changes. For multiple selections show selection count, pivot and mixed values. Edits apply only to compatible properties; do not display one arbitrary part's value as a shared value. Selection/focus is synchronized with the object tree and Logic view. ### Connect Hover highlights a port with name, domain, direction, units and connection state. Dragging from it or clicking it begins a preview. Compatible targets stand out; incompatible targets explain the reason. A separate checkmark/cross communicates validity without overwriting the red/green signal colors. Keep ring centers easy to pick and port target size readable at any zoom. For overlapping ports provide a named candidate chooser. Clicking a part body selects it; hovering a hidden port must not silently steal a move gesture. Signal connections do not move physical parts. Gas connections keep their current geometry/snapping rules and show the proposed pipe path before commit. Physical port alignment errors are visible. Disconnect/reconnect commands are available from ports and the inspector; all connection edits are undoable. ### Add sensors and configure ECUs Use Add sensor on a selected part or a specific pipe location. Offer supported sensor types, show the tap/pickup marker, and create a matching Logic reference. Selecting either representation reveals its host and measurement location. ECU inspector groups Required, Connected and Optional inputs by function. Keep connected ports visible and let optional groups expand. A guided checklist helps choose a strategy, attach required sensors and assign actuator targets. Every measurement displays units, source, validity and fallback state. ### Inspect and test Simulation controls are independent of 3D/Logic tab selection. Distinguish Run, Pause, Step and Stop/return-to-edit. Show simulation speed and time. Structural properties explain why editing is locked during Test; safe live tuning shows its applied value without resetting the machine. Entering Test does not switch to a different workspace or change selection. Keep the current 3D camera, Logic canvas and split-view arrangement. Stopping returns to editing in that same context; live tuning retains existing persistence and undo behavior. Start running immediately, with Pause and Step available in the persistent simulation controls. Hovering a signal reveals its current value; the inspector can pin it to a trace or control panel. Physical measurements can also be added from the selected part. Readouts identify the shaft, sensor or port they measure. Missing and invalid signals never display as an ordinary zero or false state. ## Readability and interaction requirements - Text and controls respond to window size and UI scaling. Scroll panels rather than drawing controls outside their bounds; avoid the current fixed-coordinate overlap risk as parts and properties grow. - Focused numeric fields accept keyboard edits, units are visible, and invalid input remains editable with a local explanation. Escape cancels the edit; shortcuts do not trigger transforms while typing in a field. - Preserve useful shortcuts, add visible tooltips, and keep camera gestures separate from node-canvas gestures. Document both in a compact help overlay. - Selection, warning and disabled states remain legible in the dark theme. Signal meaning is also conveyed through labels and direction shapes. - Keep the viewport stable when changing selection. Fit/focus is explicit. Unrelated panel refreshes must not jump scroll position or steal text focus. - Keep raw rendering and UI state ownership explicit so panel rendering remains reliable after 3D drawing. Rendering optimization must preserve hit testing. ## Delivery slices 1. Appearance and layout foundation: shared controls/theme, responsive panels, typography, text measurement, clipping and consistent input handling. Rework the existing workshop first so today's parts already have a coherent UI. 2. Descriptor-driven inspector, connection gestures, named ports and filters. 3. Searchable library/object tree, then Logic tab and optional split view with shared selection, stable node layout and live values. 4. Sensor placement and grouped ECU connector workflow. 5. Integrated test controls, traces, checks and pinned operator controls. Coordinate these slices with the systems roadmap: UI can display a type only after document/runtime descriptors define it. Validate layouts at the agreed minimum window size and scaling, connection picking in dense assemblies, keyboard focus, save/restore behavior and the same workflows across 3D, Logic and split view. ## Navigation decisions Keep the existing familiar 3D controls: Alt+left drag or right drag on empty space orbits, middle drag pans, wheel zooms, F focuses selection and Home fits all. An actual drag orbits; right click without dragging opens the context menu. UI interaction consumes input before viewport handling, and text editing captures its shortcuts. Escape cancels the active gesture before clearing selection. Logic uses wheel zoom about the pointer and middle drag to pan. Plain left click selects, Shift modifies selection, and dragging empty canvas makes a selection rectangle. Drag nodes by their header, ports by their connector and panel sizes by their divider; the pointer/hover state identifies the pending action. ## First milestone acceptance Review the existing single-cylinder, flat-six and V8 imports with long names, multi-selection, pipe route editing, ECU properties, Checks and instruments. Exercise empty, selected, hovered, disabled, focused, invalid and running states. At 1920x1080 and 1280x720 at 100% scale, and at representative larger display scales, verify that text never overlaps unrelated controls, field units remain readable, panels scroll within bounds and essential commands stay reachable. Resize while editing, reopen saved panel layouts, expand long property groups and open menus near window edges. Appearance/layout review is required before adding the new systems' more complex panels. Later slices repeat this review for the dense ECU connector view, Logic and split view as they become available. No further preference decisions are blocking this plan. Implementation will use these defaults and adjust details through focused visual and interaction review.