ADR-0012: One UI kit, plain words and pro-tool habits for the Studio

• Status: Accepted
• Date: 2026-10-05

Context

By step 4 of M11 the Studio worked: it opened, checked, played and talked to the Director. It was not yet a product. Its theme was 78 lines with ten colors and one font size; documents showed as raw JSON; ids and temp paths were on screen; panels could not be folded, resized or remembered; there were no shortcuts and no Studio unit tests.

Reelwright Studio, the owner's other Godot studio, solved the same problems in the same week (research/reelwright-studio.md). For it the owner set a bar: standard pro-tool affordances without being asked, checked against VS Code, Figma and DaVinci, and called the missing ones "standard ui/ux best practices which you obviously should have implemented". The bar holds here.

Decision

• One kit. Every Studio control is styled by one Theme (GwStudioTheme): palette tokens, a type scale, a spacing scale, radii and named type variations. Gamewright's own look, the night coast of gamewright.diy: a deep blue-green ramp, sand text, tide teal as the accent and focus, lamp amber for the brand and Play. Inter for text, Space Grotesk for display, both bundled (OFL). Icons are SVG source rasterized at the display's scale (GwStudioIcons). Components build their trees with the kit's factories (GwStudioUi) and never hard-code a color or size. Ported from Reelwright's ui/theme/ and ui/widgets/ with Rw* renamed GwStudio* (the games' own UI kit already owns GwUi*: GwUiTheme is a game's theme); each file's first line names its source and commit.
• Plain words. People see names, never ids, pointers or temp paths: a kind reads as what it is, a pointer as the label the core gives it ("Max health", "Speed (m/s)"), a path from home (~/Games/tideline), a proposal as what it changes. Ids go in tooltips. One formatter (GwStudioWords) does this for the whole Studio.
• Pro-tool habits. Side panels fold and unfold (a header button, a strip to bring them back, a shortcut), have a draggable width, and are remembered. Every action with a key is in one shortcut registry, shown by Ctrl+/ and F1, and reachable by Ctrl+K. Every icon button has a tooltip that is also its accessible name. One-line labels end in an ellipsis. A rebuild gives keyboard focus back to where it was. Every empty view says what to do and offers the action.
• Proved by tests and pictures. UI invariants are gdUnit tests: text contrast at least 4.5:1 on every surface, control edges 3:1, a 2 px focus ring on each focusable type, every icon draws, every tooltip can show, nothing pushed off a 1280×720 window. Each surface has a sized tour (--size WxH) whose frames are Read before a change is done.
• Same on the web. When the web edition comes, it is this UI, exported.

Consequences

• The Studio's existing panels are rebuilt on the kit; ad-hoc styling goes.
• New Studio work starts from the kit and the formatter. A screen without a sized tour is not done.
• The kit lives in engine/studio/ui/, outside the player's export presets: games never carry it.