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

---
title: "Text Display Hierarchy"
description: "Visual specification for four text pipelines: dialogue, monologue, observation, and environmental text"
type: design
status: active
ticket: "#316"
decision_refs: [D-016, D-036, D-049, D-061, D-062, D-064, D-076, D-078]
author: "Araminta"
created: 2026-02-20
updated: 2026-02-20
---

# 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](visual-grammar-v01.md) (§5), [Monologue Display Spec](monologue-display-spec.md) (#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](monologue-display-spec.md) (#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)

Van Maanen's Star has two linguistic registers:

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

**Van Maanen's Star 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 | Van Maanen's Star vernacular | `#9aa890` | 65% |
| Bar menu, worker notices | Van Maanen's Star vernacular | `#9aa890` | 65% |
| Mixed audience (official but social) | Concordat Standard primary, Van Maanen's Star 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 Van Maanen's Star 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 + Van Maanen's Star 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` |