settled-reach/docs/sprints/sprint-12/visual.md

Sprint 12: Build — Visual Tasks

Goal: Lay the production-layer foundations — simulation tier system, sound event pipeline, visual grammar, and knowledge boundary enforcement — and complete all v0.1 copy authoring so content packs, opening hooks, and world-building docs are done.

Branch: visual Agents: Araminta (art direction)

Carry-over from Sprint 11

None. Sprint 11 was 7/7 done.

New Tickets

#	Title	Blocked by
#303	v0.1 Visual Grammar Document	—
#252	Placeholder art specification	—
#311	Spatial layout: Logistics Hub (The Terminal)	#303
#312	Spatial layout: Bar (The Last Shift)	#303
#313	Spatial layout: Smuggling spaces and transition corridors	#303

Use db/connectors/ticket show <id> for full details.

Key Decisions

• decisions/perception.md — D-043 (art direction — "functional warmth"), D-044 (visual hierarchy: entity > object > structure), D-045 (environmental neutrality — strict zero shift), D-046 (lighting — three-reference model), D-047 (two-tier animation system), D-048 (neural insert overlay visual design), D-049 (z-level rendering stack — 8 layers)
• decisions/scope.md — D-036 (Sova Transit District as v0.1 setting)
• decisions/architecture.md — D-066 (dual-scale grid: 0.5m simulation, 1m visual)
• decisions/content.md — D-052 (character favorite colors — object-layer identification)

Notes

#303 — v0.1 Visual Grammar Document

• This is the sprint's single highest-leverage deliverable. It directly unblocks 11 downstream tickets: #304, #311, #312, #313, #314, #315, #316, #317, #318, #333, #334.
• One document, approximately 4–6 pages. Contents:
  1. Color palette — three zone palettes (logistics hub: cool industrial, bar: warm amber, corridors: neutral) with explicit hex values. Cross-reference D-043 "functional warmth" and D-045 environmental neutrality (environment NEVER shifts to signal danger/safety — only entities carry emotional color).
  2. Entity sizing and proportions — NPC rectangle dimensions at 1m visual grid. Player indicator. Static object sizing.
  3. Entity color system — relationship states (D-033, D-052): unknown=teal #4a9ebb, known/friendly=green #6bc9a6, person-of-interest=amber #e8c547, hostile=red #d45d5d, static objects=grey #8899aa. This IS #304 content — write it as a section of #303, then close #304 as covered.
  4. Z-level layer assignments — per D-049: 8 layers from floor (0) to UI overlay (7). Which layer gets tiles, NPCs, player, fog, UI elements.
  5. Typography baseline — font (Michroma, introduced Sprint 10), sizes, weights for dialogue, monologue, environmental text, HUD.
  6. Animation tier baseline — per D-047: Tier 1 (8-frame idle/walk loop for Active NPCs) vs Tier 2 (static sprite for Background NPCs).
  7. Neural insert overlay — per D-048: the insert HUD aesthetic. Smuggler vs detective visual variants.
• Deliver as docs/design/visual-grammar-v01.md (or equivalent path in the visual branch).
• Write this first. Everything else in this sprint is blocked on it.

#252 — Placeholder art specification

• Define: tile size in pixels (at 1m visual grid per D-066), NPC sprite dimensions, animation frame count requirements, color palette constraints, file format.
• This is a short spec document (1–2 pages). Unblocks #133 (placeholder art pipeline implementation).
• Can be written in parallel with #303 — it feeds from the same decisions (D-043, D-044, D-066) but doesn't need #303 to be complete first.

#311 — Spatial layout: Logistics Hub (The Terminal)

• Tile-level floor plan for the logistics hub. Blocked by #303 (need the visual grammar before doing tile-level design).
• Contents: scanner bays, main corridor (chokepoint — key player observation position), manifest processing area, break room, supervisor office (window overlooking floor), restricted storage entrance.
• Include sightline analysis: which positions have LOS to which areas. This feeds #190 (Mellanie's workplace content pack) and is critical for investigation design.
• D-066 dual-scale grid: draw at 1m visual grid, note that simulation runs at 0.5m internally.
• Deliver as a diagram or annotated tilemap sketch in docs/design/ with accompanying notes.

#312 — Spatial layout: Bar (The Last Shift)

• Converted maintenance staging area. Irregular layout is intentional — organic feel per D-043 "functional warmth."
• Key elements: long bar counter (high visibility from most positions), corner booth (key observation position — can see both entrance and bar), bathroom corridor (secondary exit, NPC private conversations), back room (staff only).
• Same sightline analysis as #311. Feeds #191 (bar content pack).

#313 — Spatial layout: Smuggling spaces and transition corridors

• The smuggling ring does NOT have a separate building. Operations run through:
  1. Restricted storage within the logistics hub
  2. Maintenance corridors (off main paths)
  3. Dead-drop locations (3 specific spots)
  4. Transition corridors between hub and bar district (~40m)
• Mark the corridors with expected NPC traffic density (sparse/moderate/busy affects how conspicuous player movement is).
• Feeds #192 (smuggling ring content pack).

Cross-team note: #311, #312, #313 are blockers for copy team's content packs (#190, #191, #192). Deliver these as early as possible after #303 is done. If full tile maps can't be finalized before content packs start, provide wireframe versions so Mellanie can proceed with draft content.

Dependency Chain

#303 (visual grammar) → #311, #312, #313 (spatial layouts)
#252 (placeholder spec) — parallel, standalone
#311 → unblocks copy #190
#312 → unblocks copy #191
#313 → unblocks copy #192

PR Workflow

When ready to submit, create a PR with tea CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(visual): Sprint 12 — visual grammar, placeholder spec, spatial layouts" --description "body" --base main --head visual