Blacksite/docs/adr/0049-penpot-led-editor-visual-system.md

# ADR 0049: Penpot-Led Editor Visual System

## Status

Accepted

## Context

Blacksite's editor controls evolved inside individual panels. Even after the material data and
Inspector composition became shared, local egui styling still produced inconsistent spacing,
typography, interaction states, and narrow-panel behavior. The Penpot **Inspector Material Slot**
provides an authored reference for the visual language rather than another implementation-specific
mock-up.

## Decision

The Penpot **Inspector Material Slot** is the source of truth for geometry, type roles, control
heights, radii, spacing, property-column geometry, and interaction states. Color is semantic rather
than panel-owned: Penpot's Assets / Colors library and `editor::ui::theme::EditorVisualPalette`
name the same roles, with Blacksite's existing palette as the default. A later Editor Settings slice
may select or override that palette without changing widgets or material behavior. At the 620 px
reference width, implementations match the documented geometry. Below that width, controls deliberately
reflow instead of shrinking, clipping, scrolling horizontally, or hiding required state.

Fixed Penpot sections use deterministic geometry models rather than nested egui flow layouts.
Surface, parameter rows, texture fields, UV groups, and Advanced each receive an owning rectangle;
every child rectangle is derived from it and clipped to it. The 569 px and 369 px section widths
encode the exported wide and compact references. A bounded transient mode below 372 px keeps all
rectangles finite, stacks the row, and collapses low-frequency texture actions into overflow while
the Inspector restores its 420 px minimum.

The reusable implementation lives under `editor::ui::design_system`. It consumes the editor-owned
semantic palette and owns spacing tokens, Source Sans Pro Regular/Bold typography roles, section chrome, property grids,
asset and texture fields, segmented controls, switches, status presentation, and the Blacksite
color picker. Domain widgets consume these primitives instead of copying raw colors or absolute
Penpot coordinates.

Material authoring is the first migrated domain. One action-returning `MaterialsSection` is used by
primitive, static-mesh, and skinned-mesh inspectors. It owns an ordered list of collapsible
`MaterialSlotPanel` models, and every returned action carries its stable slot ID. The widgets do not
query or mutate arbitrary world state.
Supported material behavior only is shown. Asset identity, health, inheritance, dirty state, and
read-only state share one geometry, while stable IDs and fingerprints remain in secondary
diagnostics.

The final Penpot component supersedes the earlier v2.2/v2.3 geometry. A 32 px **Materials** heading
precedes repeated slots. Expanded slot headers are 82 px with a 64 px preview; collapsed headers
are 52 px with a 32 px preview. A cyan disclosure spine and **PARAMETERS** ownership label inset the
Surface, Inputs, UV, and Advanced body. The asset identity block owns the single Shader selector. Penpot's former duplicate Surface
"Shading Model" selector was removed from the component and every state reference in handoff
v2.3.1. Surface contains blend mode, Separate/ORM selection, and Double Sided. UV
precedes Advanced with
an explicit 8 px section gap. Advanced render controls
that do not yet have renderer contracts are shown only as a clearly disabled preview: they emit no
actions and create no authored or runtime state.

The Material slot header is one assignment interaction, not an identity block beside a second drop
box. Its whole 596 x 82 px wide reference area accepts valid Material/Instance drops. Preview and
identity clicks plus the first-class Browse action open the compact current/recent Penpot menu;
Shader, Locate, Clear,
and overflow actions are isolated and cannot accidentally open it. The picker returns a stable
asset reference to the owning Inspector instead of mutating scene or world state.

The custom 420 x 350 color popup is a fixed modal centered over its owning Inspector clip, with an
Inspector-local dim layer rather than application- or viewport-relative placement. Its header,
mode tabs, wheel and values regions, RGBA byte fields, HSV degree/percentage fields, HEX copy,
checkerboard alpha control, recents, and footer use the exported Penpot coordinates. The exported
eyedropper lane remains a tooltip-labelled disabled preview until screen sampling has an owned
runtime contract. Apply keeps the in-memory dirty value and closes; Cancel, Escape, Close, or
outside dismissal restores the exact pre-open value. Neither path saves source or schedules derived
processing.

Standard Lit declares seven independently stored inputs but six primary presentation rows.
`emissive_intensity` is a schema companion of `emissive_color`; the Emissive popup previews and
restores both values as one interaction without merging their authored/runtime identities. Custom
shader binding counts likewise count primary rows while rendering companions through their owner.

Bounded scalar material inputs use the exported visible-child geometry rather than the narrower
transparent Penpot parent frame. At the 620 px reference that is a 138.8 px group composed from a
6 px leading inset, 93.8 px track, 6 px gap, and 33 x 22 numeric field. At 420 px the track expands
to 160.3 px while the number remains fixed. Expanding the 178 px Advanced preview requests a bounded
Inspector scroll reveal so its note and lower boundary are visible. The same no-implicit-persistence
rule applies to sliders, texture assignments, and shader controls.

Focused visual iteration uses a standalone `ui_gallery` binary that links the same `editor_ui` and
`material_schema` production crates as the editor. It owns no project, scene, renderer, or gameplay
runtime. Exact reference presets, direct Penpot PNG comparison, runtime fixture/theme reload, and a
managed last-good rebuild/restart loop shorten the edit cycle without creating a second widget
implementation. Gallery evidence is diagnostic until the same component passes a named full-editor
interaction scenario.

Renderer comparison uses the same rule. The renderer array, renderer identity, property heading,
indexed material heading, and material slots are production `editor_ui` components. A material
slot's asset header and parameter disclosure are related but distinct presentation state: renderer
arrays may keep the complete asset/action header visible while the expensive parameter body is
collapsed. Empty assignments use a first-class empty presentation instead of reusing pending or
failed thumbnail state.

Inspector overflow is part of the shared visual contract. A floating scrollbar keeps component
width stable as content crosses the vertical overflow threshold, and every nested component clip is
an intersection with the owning Inspector body. Ready texture fields use the typed thumbnail as
their sole leading identity; generic image glyphs are reserved for empty states.

Standard Lit exposes one shared UV Offset/Tiling transform through the same schema-driven input
document. The renderer maps it to Bevy StandardMaterial UV transforms and to every Surface ABI
texture lane. Material Instances may override it sparsely; resetting an instance restores its base.

Penpot's `CODEGEN MAP` and handoff annotations are design documentation. Runtime egui layout remains
responsive and semantic; generated SVG or code is not copied into production. Reviewed numeric
geometry is represented by small testable layout models instead of ad hoc child flow or generated
widget trees.
The same release slice applies the active Inspector Header, Array Header, renderer-panel, asset
field, vector, selection, and overlay components across the Inspector. Built-in component cards
dispatch through the registry and share one clipped actor-body scroll owner; domain behavior stays
outside the visual primitives.

The Content Browser is the next migrated workspace. Its Penpot reference deliberately includes a
36 px standalone title row, but the production dock tab already owns that identity; docked content
therefore renders the remaining 55 px single-row toolbar at wide widths rather than duplicating
chrome. Compact composition uses the exported 88 px two-row toolbar, starts with the content grid,
and exposes mutually exclusive Sources and Details drawers from explicit actions. Wide composition
uses fixed 216 px Sources and a 290 px default resizable Details pane around a flexible content
lane. The 56 px content heading precedes one continuous row-major card stream in which folders and
assets share the same bounded card footprint. Toolbar, breadcrumb, content header, cards, Details
identity, and the catalog/processing/selection footer consume the same semantic tokens and return
actions to the owning editor module. Long identity and dependency paths use the exported bounded
two-line Details geometry rather than unbounded egui wrapping or a single unreadable clipped line.
Those presentation functions live together in
`editor_ui::content_browser` and are invoked by both the production panel and the UI Gallery;
`editor::ui::asset_browser` remains the sole owner of project queries, selection, transactions,
thumbnail scheduling, and action resolution. A fixture-only Gallery body is not valid evidence for
production conformance.

The 1240 px toolbar remains the standard-wide reference. A separate 1600 px expanded reference
exposes sort and thumbnail scale in the toolbar at the 1400 px production breakpoint; standard and
compact layouts retain those controls in overflow. Card scaling preserves a fixed 40 px identity
footer and changes only the preview footprint, with square cached artifacts aspect-fitted rather
than stretched. Sorting and scaling are presentation operations and never mutate authored content.

## Consequences

- New editor UI has one reviewed visual vocabulary rather than panel-local approximations.
- Standalone design/gallery boards and docked production panels share one component without
  duplicating dock-owned title chrome.
- Theme colors have one runtime owner and one design-side asset vocabulary; the material panel does
  not carry a private blue/teal palette.
- The 620 px and 420 px geometries are deterministic and unit-testable. The Inspector has a 420 px
  floor and one actor-body scroll region; material slots never introduce nested scrolling.
- Unsupported prototype controls are omitted until their runtime contracts exist.
- The explicitly approved Advanced preview is the sole exception: it is disabled, muted, and
  labelled as planned work rather than functioning authoring state.
- Native acceptance compares rendered geometry, typography, states, and interaction behavior with
  the Penpot reference; compile-only evidence is insufficient.
- Source Sans Pro and its SIL Open Font License are bundled with the editor.
- ADR 0048 continues to own composition and module-size policy. This ADR owns visual tokens,
  responsive component geometry, and interaction presentation.

Related decisions: [ADR 0035](0035-shared-material-assets-and-renderer-slots.md),
[ADR 0047](0047-editor-authored-asset-documents.md), and
[ADR 0048](0048-modular-editor-composition-and-debt-ratchet.md).