settled-reach/docs/design/text-display-hierarchy.md

Text Display Hierarchy — Visual Specification

Version: v0.1 (Sprint 14) Author: Araminta (Visual Designer) Date: 2026-02-20 Ticket: #316 Status: Active — extends monologue display spec (#315); constrains client #122 implementation Foundation: Visual Grammar v0.1 (§5), Monologue Display Spec (#315)

---

1. Overview — Four Content Pipelines

The game has four distinct text channels, each with different visual identity, screen position, z-layer, and content source. They must be immediately distinguishable from each other at a glance — not through decoration but through consistent placement, size, and color rules.

Pipeline	Source	Screen position	Z-layer	Content register
Dialogue	NPC speech + player response options	Bottom of screen	7	External — what is said aloud
Internal monologue	Player character's inner voice	Lower-left, above dialogue	7	Internal — what the character thinks
Observation / overheard	Perceived NPC speech, passive panel	Bottom of screen, passive mode	7	Filtered external — what the player overhears
Environmental text	Signage, terminals, news tickers	World layer, in-scene	2–4	Diegetic — part of the physical world

The dialogue and observation pipelines share the same screen container (bottom panel) but in different modes. Internal monologue occupies the lower-left quadrant. Environmental text lives in the world, not in any HUD layer.

---

2. Pipeline 1 — Dialogue

2.1 Layout

Per D-061 and D-076:

Property	Value	Notes
Screen position	Bottom center	Centered horizontally, anchored to bottom edge
Max height	20% of screen height	216px at 1080p
Max width	640px	Per D-076. Grid-aligned (20 × 32px tile). Centered.
Layout direction	NPC speech on top, response options below	Left-aligned within the box
Max visible response options	3	Locked options invisible — D-062
Portraits	None	NPC is on screen. Portrait is redundant.

2.2 Typography

Element	Size	Hex	Opacity	Weight
NPC speech	16px Michroma	#e8eaf0	100%	Regular 400
NPC speaker name	14px Michroma	D-033 color of NPC	90%	Regular 400
Player response option	14px Michroma	#c0c8d8	90%	Regular 400
Confrontation option	15px Michroma, italic	#e0e8f0	100%	Regular 400

Speaker name treatment: The NPC's name renders in their current D-033 relationship color — teal, green, amber, or red. This is the one place where the D-033 color system bleeds into the text layer and it is intentional: the player sees "Kael" in green and "Sera" in amber and reads that immediately.

Confrontation options are italicized and 1px larger than standard response options. They express the character's internal voice speaking aloud — they should feel heavier than regular dialogue choices. No bold. Italic alone signals the weight.

2.3 Box Framing

The dialogue box has minimal framing — not a heavy panel, not floating text:

• Thin 1px border at #333340 (standard outline color) at 60% opacity
• Background: #0e1218 at 75% opacity (matches Terminal zone ambient, cool neutral dark)
• No rounded corners — geometric, insert-styled
• Box is full max-width (640px) even when content is shorter — consistent spatial expectation

2.4 Passive Mode (Overheard Conversation — D-078)

When the player is overhearing an NPC-to-NPC conversation, the same box renders in passive mode:

• No response options rendered
• Header row: [NPC_A] → [NPC_B] in their respective D-033 colors, at 13px, 70% opacity
• Overheard speech line at 16px, but at 70% opacity (vs 100% for direct dialogue)
• 1px border at #333340 at 40% opacity (dimmed vs interactive 60%) — visual signal that this is passive
• Occluded words rendered as ... in #555566 (fog blob grey) — the player sees the gap

Walking out of earshot dismisses the panel naturally (no close button, same as direct dialogue).

2.5 Walk-Away Fade

When the player walks away (WASD during dialogue), the dialogue box fades over 300ms (D-064). No close button. No "dismiss" verb. Walking away is the action.

---

3. Pipeline 2 — Internal Monologue

Per the full specification in Monologue Display Spec (#315). This section summarizes the key positioning rules for hierarchy legibility.

3.1 Position Summary

Property	Value
Horizontal anchor	Left edge + 5% screen width margin
Vertical anchor	25% from screen bottom (above dialogue box + 5% gap)
Max text width	50% screen width (960px at 1920px)
Z-layer	7
Font	13px Michroma
Stack direction	Bottom-up (newest line at bottom)
Max visible lines	3

3.2 Relationship to Dialogue Box

Monologue floats above the dialogue box, always. When dialogue is inactive, monologue remains anchored at 25% from bottom — it does not slide down into the vacated space. Consistent lower-left positioning trains the player to read the lower-left as inner thought.

3.3 Character Colors

Character	Standard	Urgent
Detective	#d0d4e0 at 85%	#e0e8f8 at 100%
Smuggler	#d8d0c4 at 85%	#f0e4d4 at 100%

Full fade/timing specification is in the Monologue Display Spec. These values are restated here for hierarchy reference only.

---

4. Pipeline 3 — Observation / Overheard

The observation pipeline has two sub-modes:

Overheard NPC-to-NPC conversation: Rendered in the passive dialogue panel (see §2.4). Same screen container, different visual mode (dimmed border, no response options, header speaker attribution, stochastic word-drop via ...).

Non-conversation observation text: When the player perceives something worth narrating — an NPC's behavior, environmental detail, non-verbal event — this routes through the internal monologue system via the observe_npc, observe_anomaly, or witness_interaction triggers. These render as standard monologue lines (§3) per the Monologue Display Spec. They are NOT a separate visual element.

Design note: Observation and monologue share the same rendering pipeline because from the character's POV, observation IS internal monologue. The character notices something → the character thinks about it → the same text appears in the same position. The authoring side distinguishes them via trigger type; the rendering side does not.

---

5. Pipeline 4 — Environmental Text

Environmental text is part of the world layer, not the HUD. It renders as if physically present in the scene — on surfaces, above terminals, in scrolling tickers.

5.1 Z-Layer Assignment

Sub-type	Z-layer	Notes
Floor signage (painted markings)	0–1	On the floor, walked over
Wall signage	2 (with furniture/objects)	On object layer, y-sorted
Terminal ambient display	4 (overhead layer)	Above entities. Semi-transparent.
News ticker	4 (overhead layer)	Same as terminal ambient

Environmental text is in the world, not in the HUD layers (6–7). It must not occlude entities: anything on z-layer 4 renders at semi-transparent (~70% opacity per the overhead occlusion rule, D-049 §4.4). If an entity passes behind a sign, the sign's opacity means the entity remains partially visible.

5.2 Typography

All environmental text uses Michroma — no exceptions. The fiction is that all text is mediated through the character's neural insert perception layer. Even handwritten signs are rendered in Michroma at appropriate size/opacity.

Sub-type	Size	Hex	Opacity	Notes
Zone signage (short)	11px	#8899aa	70%	1–3 words, spatial label
Terminal ambient ID	11px	#8899aa	60%	Equipment identifier, visible at range
Terminal active (readable)	13px	#a8b8c8	85%	When player is adjacent and interacts
News ticker	10px	#8899aa	55%	Scrolling. Ambient, not blocking.
Informal signage	11px	#9aa890	65%	Slightly warmer/greener hue for social zones

The environmental text color range (#8899aa to #9aa890) sits clearly below entity saturation — muted blue-greys and grey-greens. They are legible without competing with entities.

5.3 Two-State Terminals

Terminals have two visual states:

Ambient state (player at range):

• Terminal displays an ambient identifier — short text, equipment type or designation
• 11px Michroma at #8899aa, 60% opacity
• Rendered on z-layer 4 (overhead) above the terminal sprite
• Visible from up to ~4 visual tiles (sufficient to plan approach)

Active state (player adjacent, Observe/Interact verb triggered):

• Full terminal text readable
• 13px Michroma at #a8b8c8, 85% opacity
• Displayed in a small floating text block anchored above the terminal sprite
• Max width: 200px. Text wraps. Capped at ~12 lines of content.
• Same z-layer 4, but increased opacity signals active state
• Dismissed when player moves away (same as dialogue walk-away — no close button)

5.4 Bilingual Treatment (D-036)

The Krenn System has two linguistic registers:

Concordat Standard — the colonial lingua franca. Neutral, bureaucratic, formal. Written in normal Michroma weight.

Krenn vernacular — the local dialect. Compact, consonant-heavy, social. Rendered in the same Michroma but at slightly lower opacity (60% vs 70%) and, when design calls for it, in the informal signage color (#9aa890 greener hue). This subtle warmth distinguishes the local voice from the colonial layer.

Context	Language	Color	Opacity
Formal facility signage	Concordat Standard	#8899aa	70%
Equipment identifiers	Concordat Standard	#8899aa	60%
Social zone informal signs	Krenn vernacular	#9aa890	65%
Bar menu, worker notices	Krenn vernacular	#9aa890	65%
Mixed audience (official but social)	Concordat Standard primary, Krenn secondary at 50% opacity	Both	Stacked, smaller
News ticker	Concordat Standard	#8899aa	55%

Where both languages appear together: Formal signage targeting mixed audiences renders the primary language at standard opacity, with a smaller Krenn vernacular translation at 50% opacity below it. The two-layer approach communicates the bilingual reality of the district without requiring two UI elements — it is one sign with two registers.

5.5 News Tickers

News tickers are ambient environmental text elements attached to specific terminal or screen fixtures in the scene. They are not HUD overlays.

Property	Value
Position	Anchored above the emitting fixture sprite
Z-layer	4
Width	Width of the fixture sprite (typically 64–128px)
Font size	10px Michroma
Color	#8899aa at 55% opacity
Scroll behavior	Right-to-left. Speed: ~30px/second. Loops.
Pause on player proximity	When player within 2 visual tiles, scroll pauses.
Language	Concordat Standard

News tickers are ambient information — not intended to be read at a glance. The player has to choose to stand near one to catch the scrolling text. This is intentional: news is environmental texture, not tutorial.

---

6. Hierarchy Clarity Rules

These are the rules that keep the four pipelines visually distinct without active management:

1. Position is identity. Lower-left = inner thought. Bottom center = speech (active or overheard). In-world = physical reality. Players learn this in 5–10 minutes and stop reading position consciously.

2. Opacity descends from HUD to world. HUD text (monologue, dialogue): 85–100%. Environmental text: 55–85%. The world is legible but subordinate to what the character is actively processing.

3. Size descends from speech to environment. Dialogue speech: 16px. Monologue: 13px. Environmental text: 10–13px. The most important active channel is always the largest.

4. Color temperature signals register. Cool grey-blue (#c0c8d8 and variants) = system/HUD/player-facing. Warm cream variants = character voice (smuggler). Muted blue-grey (#8899aa) = world/environment.

5. D-033 colors in text only for speaker names. NPC name in dialogue rendered in their relationship color. No other text element uses D-033 colors — those are reserved for entity sprites.

---

Appendix A — Decision Cross-References

Decision	Relevance
D-016	Internal monologue as core perception system. Source for monologue pipeline.
D-036	Sova Transit District + Krenn vernacular. Bilingual treatment basis (§5.4).
D-049	Z-level rendering stack. Z-layer assignments for all four pipelines.
D-061	Dialogue box layout. Source for §2.
D-062	Invisible locked dialogue — no locked options visible.
D-064	Walk-away — 300ms dialogue fade, WASD dismissal.
D-076	Dialogue max-width = 640px.
D-078	Overheard NPC conversation — passive dialogue panel with occlusion filter.

Appendix B — Quick Reference for Stig

Pipeline	Position	Z-layer	Font size	Primary hex
Dialogue — NPC	Bottom center, 640px wide	7	16px	#e8eaf0
Dialogue — player response	Bottom center, below NPC	7	14px	#c0c8d8
Dialogue — passive header	Bottom center, header row	7	13px	D-033 colors
Monologue — standard	Lower-left, 25% from bottom	7	13px	Per character
Environmental — signage	World / object layer	2–4	11px	#8899aa
Environmental — terminal active	World / overhead layer	4	13px	#a8b8c8
Environmental — news ticker	World / overhead layer	4	10px	#8899aa