--- name: parked-diegetic-audit description: "⭐ THE CLARITY VETO — the owner's standing ruling that function legibility outranks flavor in every name and label. Plus the durable design lens and the never-trade-usability-for-immersion guardrail. The original parked audit brief is retired." metadata: node_type: memory type: project originSessionId: 0b7c5f41-bb34-4ab4-93be-fdb363f5eb40 --- *Correction 2026-07-20: the verbatim parked audit brief that made up most of this file has been retired — it described the stack, cited a rules file that no longer exists, and restated gate/cache/test mechanics that live in `CLAUDE.md` + `rules/` and would only drift here. **The CLARITY VETO below is CURRENT and is the reason this file exists.** It is preserved verbatim.* --- # ⭐⭐ OWNER RULING — CLARITY BEATS FLAVOR **Owner, 2026-07-11, reacting to a queued "diegetic renames" item (he sent a screenshot):** > *"do not rename inventory to manifest. things should be in theme but not confusing."* **THE RULE:** a diegetic rename is only allowed when the in-world word is **immediately understandable** to the user. If the themed term makes the user stop and think *"wait, what is this screen?"*, it is a **REGRESSION** and must not ship — no matter how good the fiction is. **Function legibility outranks flavor, always.** - ❌ **DO NOT rename INVENTORY → MANIFEST.** Explicitly vetoed by the owner. (Note: the OPERATIONS panel already carries a "CARGO MANIFEST" board title as *decoration* — that is fine as a board name. What is banned is retiring the plain word "inventory" as the concept's name.) - ❌ The blanket "rename every feature into house language" sweep is **NOT approved as a blanket sweep.** It is a per-term judgment call, each measured against: *would a user who has never read the lore instantly know what this is?* - ✅ Themed naming is still WANTED where it's obvious and adds charm — the boot sequence, status words, hardware/board names, error framing, the machine's own voice. - ✅ When a diegetic term is used for a *panel/board title*, keeping the literal word visible nearby (a sub-label, an aria-label, or the searchable sub-label pattern the Module Bay already uses) is the sanctioned way to have both. This generalizes the Module Bay guardrail — *real control labels ride along as searchable sub-labels so the new fiction never obscures what a control actually does* — to **ALL** naming. **Any house standard must carry the clarity veto as a top-line constraint: any proposed term that reduces comprehension is rejected on sight.** Related: [[parked-nv-overhaul-design-audit]] (the owner's other intentional-design vetoes), [[design-overhaul-direction]], [[fo3-pipboy-program]]. --- ## THE DESIGN LENS (durable evaluation standard, if a diegetic pass is ever run again) Derive the house standard **from what's already in the codebase**, never impose an outside one: find the strongest existing in-world surfaces (the boot text, the best-written copy, the established palette, the terminology already in use) and distill them into a one-screen HOUSE STANDARD — canonical voice/register, palette and type rules, and the locked terminology table. Audit everything else against *that*, not a generic Fallout vibe. **Where the codebase contradicts itself, the strongest/most-used form wins and becomes canon.** Every surface is judged on whether it reads as native RobCo hardware: - **Diegetic-first** — framed as operating real terminal hardware; no app vocabulary surfaces to the user. Not "dark mode" → **phosphor colour**. Not a spinner → **DECRYPTING…**. Copy speaks in the cheerful-dystopian institutional register. - **Retrofuturist hardware logic** — a CRT/vacuum-tube machine: monospace, ASCII/box-drawing, phosphor glow, beeps and hums, keyboard-driven, no modern GUI chrome. Ask of any surface: *would this machine present it this way?* - **Native vocabulary** — the fiction's own words, used consistently. - **The audit move:** for each existing surface ask *"does this read as native hardware — and if not, what's the honest in-world version?"* Dimensions worth walking: voice and copy · terminology and naming drift · visual language and chrome · interaction feedback · system states (empty/loading/error/offline/success, each framed in-world) · shell and boot · **auth as diegesis** (usually the worst offender — you cannot reskin a third-party popup, but you can frame the *approach* around it; frame around the flow, never change the flow) · out-of-frame surfaces (manifest name/description, page title, splash, icon, install prompt, notification and share copy — seen constantly, forgotten easily) · microcopy in flows · internal consistency against the house standard. ## ⚠ GUARDRAIL — NEVER TRADE REAL USABILITY FOR IMMERSION Diegetic copy is **visible copy only**. This work must never regress accessibility: - **ARIA labels and alt text stay literal and clear** for screen readers, even where visible text is stylized. - **Flicker, scanlines and type-out animation must honour reduced-motion preferences.** - **The phosphor palette must still pass contrast requirements** — glow never beats legibility. - **Keyboard navigation and focus order must survive** any chrome restyle. **Any finding whose "fix" would break one of these is logged as a tension, not applied.** Severity triage put anything that harms accessibility straight into SKIP, with the reason recorded. ## FILE-NAME OVERHAUL — the constraint that makes it spec-first Owner folded a repo file/asset **naming** overhaul into this same "native language" work — but it is constrained, hence *"where possible"*: script load order, import paths, service-worker precache paths, cache-name references, and test assertions all break if a file is renamed without updating every reference. **So filename renames are SPEC-FIRST and done as coordinated units — rename + update all references + cache bump + test updates in ONE commit.** The clarity veto applies here too: a cleverer filename that makes the file harder to find is a regression. ## PLAN-ONLY DISCIPLINE The owner's standing override for this kind of pass: **produce the triaged report, the house standard, and the specs — implement nothing, not even the safe fixes.** Every fix waits for an explicit go. When unsure, ship the report and a spec, not the change.