Spec: the clinical frame — perception exposes the institution #
Type: spec
Status: IN PROGRESS
Status note: adopted 2026-07-10 after comparing the live Bevy close frame with
two generated composition studies. First implementation slice landed
2026-07-10 (log/2026-07-10-clinical-frame-pass.md): rail narrowed 420->332px
as one unboxed near-black field (card borders/fills removed; chrome section
labels; bone values); amber decoration retired from the rail (header, card
titles, fleet-share fills, Cold/Curious band fills are now chrome/bone value
steps; amber remains cursor/selection/reticle/owned-presence only); Seen
floor raised to a porcelain field (0.55->0.74 [TUNE]); Seen wall faces
bone/ivory with the cap as the near-black cutaway seam. Before/after/
grayscale evidence: assets/reference/art-direction/b1-clinical-frame-
{before,after,after-grayscale}.png. Still open in this work order:
progressive disclosure of secondary rail detail beyond the existing scroll,
and the [TUNE] sweep against played captures. The current machine language is strong,
but the complete frame still reads as a hero object in a black void beside a
heavy debug rail. This work order makes earned facility form clinical and
world-dominant without weakening epistemic fog, replacing the oblique
material camera, or treating generated text/layout as literal UI design.
Stage: B1 — The Basement
Work order: clinical-frame
Work priority: 34
Work class: frontend
Blocked by: none
Exclusive keys:
- crates/misaligned-bevy/
- wiki/interface/clinical-frame.md
Design:
- wiki/art/visual-identity.md#visual-identity-clinical-gore
- wiki/vision/simulation-laws.md#justification-and-legibility
- wiki/interface/presence.md#presence-the-cursor-and-the-senses
Depends on:
- wiki/interface/material-dark-frame.md#spec-the-dark-frame-the-material-render-shows-only-light
- wiki/interface/bevy-visual-floor.md#spec-bevy-visual-floor
- wiki/interface/bevy-digital-real-canvas.md#spec-bevy-digitalreal-canvas
- wiki/interface/flat-materials.md#spec-flat-materials-the-world-without-textures
- wiki/interface/computer-visual-language.md#spec-computer-visual-language-territory-at-a-glance
Dependency notes #
material-dark-frame.md owns what perception may reveal and the opening's
beam-first darkness. This spec does not brighten Unknown or Heard into a room;
it strengthens the categorical payoff of Seen. bevy-visual-floor.md owns the
command-surface information order; this spec refines its first graphical pass
away from card-heavy dashboard chrome. bevy-digital-real-canvas.md owns the
fixed shared spatial canvas and oblique camera. flat-materials.md owns the
solid-color material families. computer-visual-language.md owns machine
albedo, the single strip, core beam, and cast pool.
Why this spec exists #
The current frame has a strong object language: the core is a severe white machine wrapped around amber presence, ownership is material, and work becomes physical. The surrounding composition does not yet give that language enough room. The playable world is visually compressed by a broad, information-dense right rail, while the material scene often remains so dark that the Foundation Lab reads as atmosphere rather than an institution with understandable structure.
The target is not "make the dark scene brighter." Darkness has a precise job: it is absence of perception. The target is increase the difference between not knowing and seeing. Unknown remains empty black. Once a camera earns a surface, the facility should arrive with sterile certainty: matte porcelain, black construction seams, gunmetal systems, and enough clean floor field to read routes, machines, and consequences.
The interface follows the same rule. The world is where actions live and where causes become visible. Persistent chrome should behave like an instrument at the edge of attention, not a second competing game board.
Composition contract #
The world owns the frame #
At the default gameplay window, the world canvas occupies the clear majority
of usable width and visual weight. [TUNE] the exact proportion against real
captures; the map-dominant study suggests the pressure, not a fixed pixel
ratio. A player should first perceive the room, the focused machine, and the
active flow, then consult the rail.
The material camera remains fixed-oblique/orthographic and attention-anchored. Do not adopt the map-dominant mockup's near-top-down camera literally. Preserve visible machine volume, floor relationships, and stable tile correspondence. Do not crop the world merely to make room for prose that can scroll, collapse, or move behind focus.
Black means absent #
Unknown geometry is not dim architecture. It is absent and true black. No ambient floor plate, wall silhouette, decorative cable, vignette detail, or generated room dressing may leak through it. The edge of earned perception may be softened by the established camera/light falloff, but that falloff may not imply factual form outside coverage.
Heard remains the existing near-black rough mass, categorically below Seen. Blueprint and Remembered stay in the digital/schematic dialect rather than becoming physical matter in the material frame.
Seen means institutional clarity #
Seen architecture uses a quiet hierarchy:
- Floor field: medium-light matte porcelain/concrete, broad and calm enough to establish navigable room shape without becoming a white void.
- Structural seams: near-black expansion joints, cutaway edges, wall bases, cable runs, and conduit geometry establish scale and system topology. They are sparse and functional, never decorative crosshatching.
- Walls and fixtures: bone/ivory faces with gunmetal functional parts; enough value separation from the floor to read volume at default zoom.
- Machines and active flows: the existing ownership, strip, beam, pool, token, and work-motion language remains highest in the local hierarchy.
The Seen room is clean, not friendly. Matte surfaces, square construction, precise spacing, and institutional repetition should make the horror feel maintained. Avoid grunge, dungeon wear, sci-fi panel noise, texture decals, and cinematic bloom.
Signal colors keep their cost #
- Amber appears for the cursor/selection, owned-machine presence, explicit agency, and causal signal. Ordinary headings, borders, dividers, and neutral status values stay bone/chrome.
- Crimson appears only for actual danger or consequence. A calm frame may contain no crimson at all. Do not spend it merely to make an alert area look important.
- Cold signal remains available for neutral powered/live-feed facts, but it stays subordinate. The clinical frame must not drift into teal-dominant cyberpunk.
- No semantic axis relies on hue alone.
Instrument-rail contract #
The right rail keeps the current information order and parity obligations, but its resting presentation becomes narrower and quieter.
Persistent layer #
The always-visible layer answers only the immediate operational questions:
- the crown metric (decided 2026-07-10): effective operations per second, one large number at the top of the rail — how fast the brain is going. It is the identity readout and the growth drive: more machines make it climb, and its formatting must let magnitude be felt as it grows comically large rather than compacting it away ([TUNE] units/formatting);
- current time/run state and representation;
- objective and next pressure;
- focused anchor and its most consequential live fact;
- threat/detection state when present;
- the control needed to inspect or act.
Secondary fleet detail, people summaries, intel inventories, long history, and exhaustive controls remain reachable through bounded scrolling, progressive disclosure, or focused surfaces. Narrowing may not delete information needed for frontend parity; it changes when and how that information asks for visual attention.
Visual treatment #
- Use one near-black rail field with strict padding and alignment.
- Prefer whitespace, type size/weight, value alignment, and restrained section labels over a stack of bordered cards.
- Use separators only where they clarify stable groups. Do not outline every datum or put each section in its own floating box.
- Labels are quiet bone/chrome; live values are brighter; danger earns crimson; owned/active causal state may earn amber.
- Preserve readable text at the default window and practical wrapping at the minimum supported size. "Narrower" may not mean tiny type.
- Keep the map edge clean. The rail must not cast a decorative glow or broad translucent wash across the world.
Context menus and transient overlays remain close to the thing they operate on and keep their compact choice-list law. This pass must not move world verbs back into the persistent rail.
Reference studies #
Two generated studies are checked in as directional evidence:
assets/reference/art-direction/b1-clinical-frame-balanced.png— useful for oblique physicality, porcelain emerging from black, and a calmer rail.assets/reference/art-direction/b1-clinical-frame-map-dominant.png— useful for world-to-interface proportion, broad quiet floor field, and sparse rail grouping.
They are not screenshots of intended runtime and their generated labels, icons, room geometry, camera changes, teal light, and invented facts are non-authoritative. The target combines the balanced study's physicality with the map-dominant study's hierarchy while using the actual sim, fog, palette, and action surfaces.
OPEN and deferred #
[TUNE]rail width, font sizes, section spacing, Seen exposure, ivory temperature, seam density, camera distance, fog reach, and secondary-information thresholds against observed gameplay captures.- Whether the rail can collapse further at narrow windows is deferred; this work order requires a strong default, not a responsive-layout redesign.
- New authored environment props, hero-object textures, post-processing, and a camera rewrite are out of scope. First prove the direction with existing procedural geometry and flat materials.
- Digital-home default versus the currently implemented material default is a separate existing corpus/runtime contradiction. This visual pass must work in both representations and does not resolve that behavior by implication.
Acceptance criteria #
- A canonical default-window material capture shows Unknown as featureless black, Heard (if present) as near-black rough mass, and Seen as clearly exposed matte porcelain/ivory architecture without leaking geometry across fog grades.
- In that capture, the world is the primary visual surface. The rail is materially narrower/quieter than the pre-pass frame, and the focused room, machine, and active causal flow read before rail detail.
- Seen floors, walls, seams, fixtures, and machines remain distinguishable in grayscale at default zoom. The floor is broad and calm; black geometry is functional; machine and flow signals retain local priority.
- Amber pixels in the frame can each be justified as cursor/selection, owned-machine presence, agency, or causal signal. Crimson pixels can each be justified as actual danger/consequence. Neutral chrome never borrows either color for decoration.
- The rail preserves the current required operational answers and frontend parity while using fewer persistent boxes/rules. Secondary detail remains reachable, and type stays readable at both default and minimum supported window sizes.
- The material camera remains fixed-oblique and spatially stable; the pass does not adopt generated room geometry, a detached map, or a free orbit.
- Before/after captures at identical seed, window, focus, camera, and sim state are committed or recorded in the implementation log, including a grayscale audit and a calm frame where crimson is absent unless the state genuinely contains danger.
- No sim or save state changes. Rendering derives from existing fog, ownership, selection, work, and threat facts; the terminal keeps semantic parity even though this exact composition is Bevy-specific.