hope-voice-api/.artifacts/20260831-105824-plan-code-ui-audit/ui-research-implementation.md

# UI Research Implementation Report

- Task: 20260831-105824-plan-code-ui-audit
- Agent: coder (UI/UX research pass)
- Model: litellm-lan/qwen3.8-27b (the fixed model this agent runs on; note the user asked for a "cheap local qwen3.8-27b" — this is exactly that model, routed via LiteLLM LAN)
- Date: 2026-08-31
- Status: complete

## Summary

Research-only pass: located and analyzed the square Hope visual element in the reference
projects, audited every SwiftUI source file in `voice-ios`, extracted the web design-token
system, and produced a full redesign specification. **No product code was modified** —
the only files written are this report and `ui-ux-spec.md`.

### The square Hope element (resolved)

The square Hope element is the **LED-wall avatar** in the web UI: a 320×320 px square
(`border-radius: 26px`) containing a 21×21 dot matrix that blooms with audio.

Evidence:
- `hope-voice-api/web/style.css` L331–346 — `.led-wall { width: 320px; height: 320px;
  display: grid; grid-template-columns: repeat(21, 1fr); border-radius: 26px }`
- `hope-voice-api/web/style.css` L349–359 — glass panel backing (radial iris gradient + border)
- `hope-voice-api/web/style.css` L361–372 — `.led-dot` (base 5 px, 90 ms linear transitions)
- `hope-voice-api/web/style.css` L376–392 — state palette: idle `#56739E`, connecting/thinking
  `#D99A6C`, listening `#6F8FF7`, speaking `#9DC2FF` + drop-shadow
- `hope-voice-api/web/app.js` L265–341 — build (21×21, per-dot radial + phase) and per-frame
  render (gaussian falloff, ripple, audio-reactive sizing, listening dimmed to 0.55×)
- `hope-voice-api/web/index.html` L61–62 — wall is `aria-hidden`, separate `aria-live="polite"` label

Two related marks documented for the redesign:
- **Favicon glyph** (`hope-voice-api/web/favicon.svg`): 64×64 rounded square, plate `#08111F`,
  iris circle + tilted orbit ellipse + warm dot — compact identity mark.
- **Companion icon** (`hope_companion/resources/icon.png`, generated by
  `scripts/gen-icons.mjs`): 1024² rounded square (r≈22.3%), indigo→violet diagonal gradient,
  white two-node + arc + ring mark. Verified 1024×1024 RGBA via `sips`.

The current iOS app uses **none** of these: `OrbView.swift` L45–47 is a plain 120 pt system-color
`Circle()`, and `Resources/Assets.xcassets/AppIcon.appiconset/Contents.json` has no images.

## Files Changed

Product code: **none** (research-only mandate).

Artifacts written:
- `.artifacts/20260831-105824-plan-code-ui-audit/ui-ux-spec.md` — full audit + redesign spec
  (asset provenance, current-state findings N1–N3/C1–C11, navigation hierarchy, color/shape/
  motion tokens with exact values, per-component specs incl. LED-wall formulas, accessibility,
  app-icon plan, 4-phase rollout, acceptance criteria, risks)
- `.artifacts/20260831-105824-plan-code-ui-audit/ui-research-implementation.md` — this report

## Paths Inspected

### voice-ios (all SwiftUI sources read in full)
- `Sources/App/VoiceApp.swift`, `Voices.swift`, `SettingsStore.swift`
- `Sources/Features/Conversation/ConversationView.swift`, `OrbView.swift` (incl. TranscriptListView)
- `Sources/Features/Settings/SettingsView.swift`, `ConnectionTestView.swift`
- `Sources/Features/Tasks/TaskPanelView.swift`
- `Sources/Features/Media/MediaPanelView.swift`
- `Sources/LiveKit/VoiceSession.swift`, `ConversationState.swift`, `TranscriptHandler.swift`,
  `TranscriptHistory.swift`, `ControlChannel.swift`, `TaskStore.swift`, `AgentMonitor.swift`
- `Sources/Media/MediaPlayerController.swift`, `PinnedMediaResourceLoader.swift`, `MediaAPI.swift`
- `Sources/Networking/TokenClient.swift`, `ServerConfig.swift`, `TLSPinning.swift`
- `project.yml`, `Resources/Info.plist`, `Resources/Assets.xcassets/AppIcon.appiconset/Contents.json`
- `PLAN.md`, `UPDATE_PATH.md`, `AGENTS.md`

### hope-voice-api (reference)
- `web/style.css` — token block L1–26, brand glyph L125–166, LED wall L316–429, buttons L431+,
  message bubbles L702–764, task dots L1120–1150, keyframes L427/L709/L1133
- `web/app.js` — LED wall build/render L265–341, mic level smoothing L343–354, state setter L389
- `web/index.html` — ARIA structure (L18–107)
- `web/favicon.svg` — full file (square Hope glyph)

### hope_companion (reference)
- `scripts/gen-icons.mjs` — full SDF icon generator (plate, gradient, mark geometry)
- `resources/icon.png` — metadata via `sips` (1024×1024 RGBA)
- `package.json`, `electron-builder.yml` — icon usage

## Verification

Commands run (research-only; no build performed since no code changed):
- `sips -g all hope_companion/resources/icon.png` → 1024×1024, RGBA, hasAlpha: yes ✓
- `rg "led-wall|led-dot|orb" hope-voice-api/web/style.css` → located all LED-wall rules (L317–1563) ✓
- `rg "square" voice-ios/` → no hits; confirmed the term maps to the LED-wall container, not a literal "square" identifier ✓
- Read-based verification of every cited line range above.

No build/test commands were run because the brief restricts this pass to research and
specification; the spec's Phase A–D implementation will carry its own verification per
`ui-ux-spec.md` §11 (XcodeBuildMCP simulator build + the PLAN.md Phase 8 reconnect matrix).

## Design Decisions (recorded for the implementer)

1. LED wall is procedural (Canvas + TimelineView ≤30 fps), not a raster asset — matches web
   implementation and keeps the asset catalog clean.
2. Exact port of app.js formulas (falloff/ripple/sizing) rather than an approximation — the
   spec includes the verbatim math so behavior matches the reference pixel-for-pixel in intent.
3. System colors fully replaced by a `HopeColor` token enum derived from web `:root`;
   semantic mapping (mint=success, danger=error, warm=thinking) documented in spec §5.1.
4. Accessibility mirrors web ARIA: wall hidden from VO, separate live status element,
   announcements throttled to meaningful transitions only.
5. Four-phase rollout (tokens/assets → LED wall → transcript/composer → polish) so each
   phase is independently reviewable and revertible.

## Risks And Limitations

- Simulator mic is dead (-4010, PLAN.md Phase 2): listening-side wall reactivity is
  device-only; speaking-side verifiable in sim via agent TTS. Recorded as R1 in the spec.
- No automated tests exist in the repo (also noted in manifest Open Risks); verification
  for the implementation phases will be simulator-based + Instruments profiling for the wall.
- `Color(hex:)` helper does not exist yet — required prerequisite for Phase A (spec R3).

## Follow-up For Reviewer

1. Confirm the "square Hope element" identification (LED wall) matches the user's intent;
   if they meant the favicon glyph or companion icon instead, spec §9 already covers both as
   secondary assets and only §6.1/§10-B would need re-scoping.
2. Review spec §5.1 token table for any brand values that should differ from web (e.g., if a
   lighter iOS-native surface treatment is preferred over the dark canvas).
3. Approve Phase A–D sequencing before coder implementation begins; each phase has exit
   criteria in §10 and global acceptance criteria in §11.