Blacksite/docs/editor/visual-language.md

Editor Visual Language

Blacksite's editor UI is a dense production tool. Its visual system prioritizes scan speed, stable controls, viewport legibility, and unambiguous editing state over decorative surfaces.

Palette Roles

• Near-black neutral surfaces separate canvas, panels, controls, and elevated popovers without a light-gray cast or single-hue tint.
• Amber is the Blacksite action accent: active tools, the primary selection, warnings, and rendering paths that need attention.
• Cyan identifies secondary selections, links, and neutral viewport information.
• Red, green, and blue are reserved for the X, Y, and Z axes across transform gizmos, the world grid, and the viewport orientation widget.
• Green and red communicate success/running and error/blocked states. They are not decorative.

Editor Chrome

• A compact Blacksite mark and amber signal line identify the tool without turning the workspace into a branded landing surface; squared controls and tight radii reinforce the industrial tone.
• Menus, the grouped creation/file toolbar, centered transport controls, dock tabs, and the status strip keep stable dimensions so mode changes do not shift the workspace.
• Controls use familiar symbols with hover labels. Persistent text is reserved for state, values, selection identity, and task-specific feedback.
• Dock tabs use an amber active edge, while splitters and panel borders stay neutral until hovered or dragged.
• Popovers and viewport chips share one elevated surface, border, corner radius, and shadow.

Viewport Language

• The top-left toolbar groups transform, coordinate space, shading, grid/snap, visualizer, focus, and display controls.
• The top-right selection chip identifies the active object, selection count, and overlapping-pick position. It moves below the toolbar when the viewport is narrow.
• The bottom-right orientation widget and combined shading/render-path chip provide camera and render context without covering scene content.
• Dragging an asset over the viewport produces an amber placement boundary and compact placement card, pointer reticle, and corner brackets before the drop is committed.
• Grid lines use minor/major weights. The world X and Z axes retain their gizmo colors.

Selection And Gizmos

• The first selected object is primary: amber x-ray rim and corner brackets, hierarchy edge, and selection HUD identity.
• Additional selected objects are secondary: cyan rim, brackets, and hierarchy edge.
• All unlocked authored objects in a multi-selection receive grouped transform-gizmo targets; a single interaction is captured as one undoable group transform.
• Transform gizmos use restrained X/Y/Z colors, an amber interaction highlight, larger stable screen size, and translation snapping synchronized with the viewport snap toggle and increment.
• Brush vertex, edge, and face modes reuse the same palette and enlarge active element handles. Face mode outlines the selected face instead of showing only a center point.

Drag And Drop

• Drag previews follow the pointer and name both the payload and pending action; they never rely on cursor shape alone.
• Hierarchy rows expose their full remaining width as attach targets. Amber means attach, cyan means root/reorder, and red means the requested hierarchy would be invalid.
• Reparenting preserves world placement, keeps selected subtrees intact, expands the new parent, and records parent, sibling order, and local transform in one undoable command.
• Manual hierarchy sort exposes between-row insertion targets; semantic Name and Type sorts expose parenting without pretending a manual reorder will remain visible.

Visualizers

• Visualizers preserve semantic category colors while selected objects receive stronger emphasis.
• Camera visualizers include near and far frustum planes plus a forward vector.
• Spot lights show inner and outer cones; point lights, directional lights, colliders, spawns, gameplay markers, volumes, prefab/model anchors, and runtime helpers remain independently toggleable.
• Editor-only visualizers and selection helpers never enter saved scene data.

Maintenance Rules

• Add shared colors and surface frames in ui/theme.rs; do not introduce local panel palettes unless the color has domain meaning.
• Keep selection semantics consistent across the viewport, hierarchy, inspector, and status bar.
• New viewport overlays must adapt before they overlap existing controls at narrow widths.
• Visual polish must preserve picking, undo/redo, clean game view, and scene serialization behavior.