# Phase 17: UI Optimization & Polish - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-06-17
**Phase:** 17-ui-optimization-polish
**Areas discussed:** Scope breadth, Fix technique, Regression guard, Phase shape, Branding asset ownership, Dark-mode depth, Styling-refresh boundary, Logo/brand direction

---

## Phase shape / sequencing

Initial framing was a CSS-only layout-polish phase. Mid-discussion the user expanded scope to also include branding/logo assets (started but unfinished, incl. favicon), groundwork for themes (dark mode), and a modern styling refresh. This pushed past the ROADMAP's original "CSS/layout only, not a redesign" boundary, so scope was re-negotiated.

| Option | Description | Selected |
|--------|-------------|----------|
| One phase, four workstreams (A layout + B branding + C dark mode + D styling) | Keep everything in Phase 17 | |
| Split — keep layout + branding + token groundwork; defer dark theme & styling | Bound the phase, route the rest to backlog | ✓ |
| One phase but styling "light" | A+B+C full, D incidental only | |

**User's choice:** "spin dark mode and styling into /gsd-capture --backlog. We do the rest in the phase." → Phase 17 = layout polish + branding + theme-token groundwork. Shipped dark theme → backlog 999.20; styling refresh → backlog 999.21 (future milestone).
**Notes:** ROADMAP Phase 17 goal/scope updated to match; two backlog items created and committed (916fb34).

## A — Scope breadth (layout)

| Option | Description | Selected |
|--------|-------------|----------|
| Seed defect + targeted sweep | Fix overlap, then run Phase 7 layout.spec checklist across phone routes | ✓ (implied by keeping the layout workstream) |
| Seed defect only | Fix just the bottom-bar overlap | |
| Broad small-viewport audit | Free-form audit of every phone screen | |

**User's choice:** Layout workstream retained as the bounded, checklist-driven sweep (D-01).
**Notes:** Phase 7 `layout.spec.ts` assertions are the checklist.

## A — Fix technique & regression guard

| Option | Description | Selected |
|--------|-------------|----------|
| Shared bar-height token + padding / inline calc / shrink column | CSS technique for the overlap | (researcher decides) |
| Add overlap assertions to layout.spec / manual playwright-cli / both | Regression guard | (researcher decides) |

**User's choice:** "5 - have the researcher decide."
**Notes:** Delegated to research/planning (D-02). Default lean noted: shared `--bottom-chrome-h` token + CI assertion, but researcher decides on the merits.

## B — Branding asset ownership

| Option | Description | Selected |
|--------|-------------|----------|
| AI-generate in-phase | Claude generates logo + full icon set, wires in, user approves | ✓ |
| User supplies final art | User provides logo, Claude derives icon set | |
| Generate placeholders now, real art later | Stopgap improved mark via the seam | |

**User's choice:** "2a" — AI-generate in-phase.
**Notes:** No existing logo draft found beyond the "FS" placeholder + stub icons. Full icon set incl. proper maskable + favicon.ico/svg (D-03/D-04/D-05).

## C — Dark-mode depth

| Option | Description | Selected |
|--------|-------------|----------|
| Groundwork only | Themeable token restructure, light stays default; dark flippable later | ✓ |
| Ship working dark mode | Finished dark theme via prefers-color-scheme | |
| Ship dark mode + in-app toggle | Plus persisted light/dark/system toggle | |

**User's choice:** "3a" — groundwork only. Combined with "spin dark mode into backlog," the *token restructure* stays in-phase; the *shipped dark theme + toggle* go to backlog 999.20 (D-06).
**Notes:** Light remains the sole shipped theme this phase.

## D — Styling-refresh boundary

| Option | Description | Selected |
|--------|-------------|----------|
| In-system polish | Modernize within existing design system | |
| Component-level refresh | Rework high-visibility surfaces | |
| Broader visual overhaul | Open-ended modern restyle | (deferred) |

**User's choice:** "Dont do 4 - that goes into future milestone." → routed entirely to backlog 999.21.
**Notes:** Redesign risk; own track in a future milestone.

## Logo / brand direction

**User's choice (free-text):** "FamilySync is the brand — family orientated. I like caricature family kind of vibes, warm tones, rounded corner sort of thing. Something that makes you feel comfortable and at home."
**Notes:** Captured verbatim into CONTEXT Specific Ideas as the acceptance lens for generated logo/icon options. Current theme-color `#4A90D9` (cool blue) may be revisited toward warm tones within light-theme scope.

---

## Claude's Discretion

- Fix technique + regression-guard mechanism for the layout overlap (delegated to researcher — D-02).
- Specific small-viewport issues surfaced by the `layout.spec` sweep (fix as found, no behaviour change).
- Logo visual execution within the brand brief, subject to user approval at a checkpoint.

## Deferred Ideas

- Shipped dark theme + light/dark/system toggle → backlog **999.20**.
- Modern visual styling refresh → backlog **999.21** (future milestone).
- (Reviewed, not folded) `2026-06-10-gitea-ci-regression-and-docker-publish.md` — weak keyword match, already-shipped CI work, unrelated to this UI phase.

---

## Process note — interactive question tool blocked

The `AskUserQuestion` tool returned "Permission denied by hook" during this discussion. Investigation: no configured PreToolUse hook or permission rule matches `AskUserQuestion` (user-settings matchers are only `Write|Edit`/`Bash`/`MultiEdit`; `defaultMode: bypassPermissions`; no managed settings). The block correlates with an active background subagent (the Phase 19 `--fix --auto` fixer) running concurrently — interactive questions are suppressed while a background agent is live. Discussion proceeded via the plain-text numbered-list fallback.