From fbc2f7abbc21deab367a521fa86b4900995f6452 Mon Sep 17 00:00:00 2001 From: Cameron Date: Mon, 06 Jul 2026 21:38:25 +0000 Subject: [PATCH] spec/terminal-ui.md: the terminal design of record The design spec for the terminal frontend — how it looks (exact palette with one meaning per color, glyph vocabulary, layout geometry), feels (sterile, restrained, data-forward), and acts (clock always on screen, never color alone, every command discoverable, parity of legibility) — with acceptance criteria, so future terminal work is dispatched from a spec rather than improvised per session. Listed under a new Process set in spec/README.md. Defense: the constitution's terminal clause (adopted in this PR) needs a targetable spec below it, per the constitution rule's spec layer: the constitution says what the terminal is; this spec says exactly how it looks and behaves and when that is done. --- spec/README.md | 7 +++++++ spec/terminal-ui.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 file(s) changed, 155 insertion(s)(+), 0 deletion(s)(-) diff --git a/spec/README.md b/spec/README.md --- a/spec/README.md +++ b/spec/README.md @@ -88,3 +88,10 @@ (recursive Space, the mind/ledger split, the aggregate interface) are decided before anyone builds against a shape that can't scale. Their acceptance criteria are stage-scoped; do not start B2/B3 work as B1. + +## The Process set (standing infrastructure) + +| Spec | System | Status | +|---|---|---| +| [meta.md](meta.md) | The spec system itself | READY | +| [terminal-ui.md](terminal-ui.md) | Terminal frontend: look, feel, act (the sterile style guide) | IMPLEMENTED | diff --git a/spec/terminal-ui.md b/spec/terminal-ui.md new file mode 100644 --- /dev/null +++ b/spec/terminal-ui.md @@ -0,0 +1,148 @@ +# Spec: the terminal frontend + +``` +Status: IMPLEMENTED +Status note: adopted and implemented in the same PR as the constitution's + terminal clause. This document is the design of record for all future + terminal-frontend work; changes to how the terminal looks or behaves + amend this spec first. +Stage: Process +Constitution: "The terminal is a first-class frontend", "Visual identity: + clinical gore", "Justification and legibility", pillar 4 (beautiful, + readable presentation) +Depends on: none (renders whatever systems exist; individual system specs + own what is shown, this spec owns how) +``` + +## Why this spec exists + +The game's most regular players are AI agents playing through a pty. The +terminal is therefore a first-class frontend (constitution), and its design +is specified — not improvised per session. This spec says how the terminal +**looks** (palette, glyphs, layout), **feels** (tone, density, restraint), +and **acts** (interaction and visibility rules). It is the calibration a +future session needs to extend the UI without drift. + +## Look + +### The palette (exact values, one meaning per color) + +The clinical-gore identity in character graphics. Colors are truecolor RGB; +every cell paints both foreground and the standard background. + +| Name | RGB | Meaning — and nothing else | +|-------------|---------------|-----------------------------------------------------| +| BG | 10, 10, 11 | Near-black. The only background. | +| TEXT (bone) | 219, 218, 210 | Primary data; interactable map objects | +| DIM (gunmetal) | 140, 140, 133 | Secondary data; section labels; furniture | +| FAINT (chrome) | 80, 81, 79 | Rules, borders, key hints, inert detail | +| STRUCTURE | 58, 60, 63 | Walls | +| FLOOR | 40, 41, 42 | Floor grain | +| AMBER | 255, 176, 0 | Machine presence, live: the process `@`, the core, PAUSED, ASSET, caution | +| AMBER_DIM | 176, 124, 16 | Machine presence, at rest: racks, switch, panels, allocation bar | +| CRIMSON | 214, 38, 38 | Detection and danger, live: cameras, DEGRADED, RUN ENDED, Convinced | +| CRIMSON_DIM | 140, 34, 34 | Detection and danger, dormant: sealed lab, tier-3 access | + +Rules: + +- **One meaning per color.** Amber is never decoration; crimson never means + "important"; if a new element is neither machine presence nor + detection/danger, it lives on the grey ramp. +- **No new colors.** A need the palette cannot express is a design question + for this spec, not a new constant. +- **Data outshines chrome.** Values render brighter than their labels; + labels brighter than borders. The eye falls on numbers first. + +### Glyph vocabulary + +- Charset: ASCII plus box-drawing (`─ │ ┌ ┐ └ ┘ ├ ┤`), block elements + (`█ ▓ ▒ ░`), middle dot (`·`), and the selection marker `▸`. Nothing of + ambiguous terminal width; no emoji. +- Map: walls are solid blocks (`█`), floors middle dots; the process is `@` + bold amber; people are their name's first initial, bold bone, rendered + only inside sensor coverage (spec/schedules.md); cameras are `o` crimson; + security tiers ramp `1` chrome → `2` bone → `3` crimson; interactable + objects (salvage `d`, records `x`, key hook `k`) render bone, brighter + than furniture on the faint ramp. +- Meters: filled `█`, empty `·`. The compute allocation bar is stacked, its + four segments filled with `█ ▓ ▒ ░`, and each legend row leads with its + segment's fill character — the bar is readable with no color at all. + +### Layout + +At terminal size ≥ 70×22 (hard minimum; below it, a plain size warning): + +- **Map**, top-left, fog-of-war black. +- **Sidebar**, right, 34 columns, separated by a `│` rule: identity block + (title, `day N · tick T`, run state), then sections COMPUTE / CORE / + DETECTION / DAY JOB under `LABEL ────` rules, then key hints pinned to + the bottom. +- **Log**, bottom, under a horizontal rule: six lines, each prefixed with + the tick it happened on; newest bone, older gunmetal. +- **Modal panels** (People) are centered framed boxes: `┌─ TITLE ─…┐` + border in chrome, `├──┤` dividers, column headers in chrome caps. + +## Feel + +- **Sterile.** Quiet chrome, generous alignment, no ornament. The horror of + the fiction is how tidy it is; the UI is the first place that reads. +- **Restraint is the signal.** Because amber and crimson are scarce, a + screen going amber (paused, degraded core) or crimson (a Convinced + observer) is an event. Never spend them casually. +- **Calm surface, exact numbers.** The player is a process reading + telemetry: everything is labeled, unitized, and steady. No blinking, no + animation-for-attention; state changes announce themselves in the log. + +## Act + +- **The clock is always on screen.** Day and tick in the sidebar at all + times; every log line carries its tick. An agent (or a human) must be + able to answer "when did that happen" from any single frame. +- **Never color alone.** Suspicion meters print their band names; PAUSED is + written, not merely tinted; selection is reverse-video **plus** a `▸` + marker. +- **Meters carry their numbers.** Every bar or meter is adjacent to the + value and, where the legibility clause demands, the effect ("60% → + job quality"). +- **Every command is discoverable on screen.** All bindings appear in the + pinned hint block or the active panel's footer — including save/load. + A key that works but is hinted nowhere is a violation. +- **Pause is loud.** PAUSED renders in amber in the identity block; running + state shows the current ms/tick. +- **Parity of legibility** (constitution): every mechanic the sim exposes + is playable, and every number legible, in the terminal. A + terminal-invisible mechanic is a violation, found by ticks. +- **Thin view.** The terminal binary owns rendering, input mapping, and + wall-clock-to-tick pacing only. No game rules; `Sim` is the single + authority (architecture guardrail). + +## Verification + +Headless: pty smoke run (knowledge/workflows.md), replayed through a +terminal emulator (e.g. pyte) to assert layout and content of the title, +playing, and people-panel screens. This is the required "observed in an +actual run" for terminal changes. + +## Acceptance criteria + +1. Every color used by the terminal binary is one of the palette constants + above, used with its stated meaning; no crossterm named colors, no + ad-hoc RGB. +2. No information is carried by color alone anywhere: bands print names, + selection has a marker plus reverse video, run-state is written text. +3. Day and tick render in every playing-screen frame; every log line is + prefixed with its tick. +4. The compute allocation bar's segments are identifiable without color + (distinct fill characters keyed to legend rows), and each channel shows + its percentage and effect. +5. All active key bindings, including save/load and panel keys, are visible + in the pinned hint block or the open panel's footer. +6. People render on the map only inside sensor coverage; the people panel + shows per-person located presence staged by knowledge + (spec/schedules.md criteria 4 remains satisfied). +7. The playing screen, title screen, game-over card, and people panel all + render inside a 70×22 terminal; smaller sizes get the size warning, not + a crash. +8. A pty smoke run of title → playing → people panel → quit exits cleanly + and, replayed through a terminal emulator, shows the layout of this + spec. -- tangled.sh