# Phase 2.1: App Shell, Navigation & Search Foundation - 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-05-08
**Phase:** 02.1-app-shell-navigation-search-foundation
**Areas discussed:** Tab bar shape & chrome placement, Search affordance behavior, Empty state design language, Theme tokens + Liquid fallback

---

## Tab bar shape & chrome placement

### Q1 — Adopt the mockup's floating pill dock for the tab bar?

| Option | Description | Selected |
|--------|-------------|----------|
| Floating pill dock (Recommended) | Centered, bottom-anchored Liquid-glass capsule. Active wider with icon+label, inactive icon-only circles. | ✓ (with modification) |
| Static bottom tab bar (full-width) | Edge-to-edge fixed-width tabs. | |
| Platform-adaptive | iOS pill, Android Material 3 NavigationBar. | |

**User's choice:** Floating pill dock — but with labels on inactive tabs too (not just active). When search opens, the dock collapses to a single button showing only the active tab's icon (no label, slightly reduced height).
**Notes:** User explicitly preferred a single visual language across platforms and wanted all tabs to remain readable; differentiation is by width/emphasis, not by hiding labels.

### Q2 — Tab order and default landing tab?

| Option | Description | Selected |
|--------|-------------|----------|
| Mockup order: Planer / Przepisy / Spiżarnia / Zakupy (Recommended) | Lands on Planer (hero feature). | ✓ |
| REQ order: Przepisy / Planer / Spiżarnia / Zakupy | Follows UI-03 listing literally. | |
| Last-used tab persisted | Remember across launches. | |

**User's choice:** Mockup order; lands on Planer.
**Notes:** Aligns with the "my week is planned" core value.

### Q3 — Top app bar in v1?

| Option | Description | Selected |
|--------|-------------|----------|
| No top bar — bottom chrome only (Recommended) | Mirror mockup; one chrome surface. | ✓ |
| Minimal top bar with title | Plain text title per tab. | |
| Top bar with title + profile/settings icon | Adds global affordance. | |

**User's choice:** No top bar.
**Notes:** Simpler chrome story; profile/settings will find its slot when Phase 3 lands.

### Q4 — Mockup's collapsible-dock behavior in this phase?

| Option | Description | Selected |
|--------|-------------|----------|
| Defer collapse-to-toggle (Recommended) | Static pill; revisit in Phase 10. | |
| Implement collapse-to-toggle now | Match mockup fully. | ✓ (scoped to search-open) |
| You decide | Claude's discretion. | |

**User's choice:** Implement the collapse, but only as the transition that happens when search opens (not the per-tab/scroll-state collapse). Inspired by Apple apps where bottom chrome morphs as search context activates.
**Notes:** Per-tab/scroll collapse is deferred to Phase 10; only search-open collapse is in scope here.

---

## Search affordance behavior

### Q1 — Where does the search button live?

| Option | Description | Selected |
|--------|-------------|----------|
| Per-tab on Przepisy + Spiżarnia (Recommended) | Floating circular button next to dock; only on tabs with searchable content. | ✓ |
| Global on every tab | Always present; ambiguous on Planer/Zakupy. | |
| Per-tab on all four tabs | Tab-scoped behavior including tabs with no v1 search. | |

**User's choice:** Per-tab on Przepisy + Spiżarnia only.
**Notes:** Matches mockup; avoids designing search states for tabs with no v1 content.

### Q2 — Search surface behavior before real data exists (this phase)?

| Option | Description | Selected |
|--------|-------------|----------|
| Functional input + empty-state placeholder body (Recommended) | Open/close + query, body shows "Brak danych do przeszukania". | |
| Functional input + dimmed/disabled visual | Greyed body. | |
| Just open/close + query echo | No body content rendered. | ✓ |

**User's choice:** Open/close + query echo only.
**Notes:** Lightest scaffolding; Phase 5 will wire result rendering. UI-10 is satisfied by demonstrating the affordance is functional, not by faking content.

### Q3 — Search query state — what persists?

| Option | Description | Selected |
|--------|-------------|----------|
| Cleared on close (Recommended) | iOS-typical behavior. | ✓ |
| Persists per-tab within session | Foreground only. | |
| Persists per-tab across launches | Saved via multiplatform-settings. | |

**User's choice:** Cleared on close.
**Notes:** Simplest mental model; aligns with iOS conventions.

### Q4 — Search input — inline pill or full-screen sheet?

| Option | Description | Selected |
|--------|-------------|----------|
| Inline bottom pill, dock collapses next to it (Recommended) | Mockup behavior. | ✓ |
| Full-screen modal sheet | iOS Settings/Mail style. | |
| Inline with results overlay | Pill + translucent overlay. | |

**User's choice:** Inline bottom pill.
**Notes:** Coordinated with the dock-collapse transition (Tab Q4).

---

## Empty state design language

### Q1 — Empty state visual treatment?

| Option | Description | Selected |
|--------|-------------|----------|
| Icon + headline + subline (Recommended) | Tab-themed icon, calm color, no bespoke art. | ✓ |
| Custom illustrations per tab | Bespoke SVG/PNG per state. | |
| Text-only, no icon | Centered headline + subline only. | |

**User's choice:** Icon + headline + subline.
**Notes:** No illustration assets needed; cheap and on-brand.

### Q2 — Empty state tone?

| Option | Description | Selected |
|--------|-------------|----------|
| Anticipatory — "soon you'll see X" (Recommended) | Forward-looking Polish copy. | ✓ |
| Neutral / informational | "Brak danych" style. | |
| Welcoming with onboarding hint | Chatty onboarding copy. | |

**User's choice:** Anticipatory.
**Notes:** Honestly signals the feature is real but waiting.

### Q3 — CTA buttons in empty states this phase?

| Option | Description | Selected |
|--------|-------------|----------|
| No CTAs in this phase (Recommended) | Add as actions become real. | ✓ |
| Disabled-looking CTA placeholders | Greyed, inert. | |
| Cross-tab CTAs | "Browse recipes" → Przepisy (also empty). | |

**User's choice:** No CTAs.
**Notes:** Households (Phase 3) and catalog (Phase 5) don't exist yet; CTAs would no-op.

### Q4 — Empty state component architecture?

| Option | Description | Selected |
|--------|-------------|----------|
| Single reusable EmptyState composable (Recommended) | `EmptyState(icon, title, subtitle, action?)`. | ✓ |
| Per-screen bespoke composables | Each screen rolls its own. | |
| You decide | Claude's discretion. | |

**User's choice:** Single reusable EmptyState composable with optional action slot.
**Notes:** Action slot reserved unused this phase; feature phases populate it.

---

## Theme tokens + Liquid fallback

### Q1 — Theme token scaffolding scope for this phase?

| Option | Description | Selected |
|--------|-------------|----------|
| Full scaffold: colors + typography + spacing + glass-surface (Recommended) | Phase 5 inherits cleanly; Phase 10 tunes. | ✓ |
| Minimal: only what the shell uses | Defer typography/spacing to feature phases. | |
| Full scaffold + lift mockup CSS palette directly | Seed palette from `--*-rgb` vars. | |

**User's choice:** Full scaffold; mockup palette is reference, not directly ported.
**Notes:** The visual rebuild owns its own palette.

### Q2 — Light/dark scheme posture?

| Option | Description | Selected |
|--------|-------------|----------|
| Both schemes defined; system-following (Recommended) | UI-05 foundation here, full landing in Phase 5. | ✓ |
| Light-only this phase, dark in Phase 5 | Half-build now. | |
| Both, but app forces dark | Light tokens un-tested. | |

**User's choice:** Both, system-following.
**Notes:** Avoids retrofit cost in Phase 5.

### Q3 — Liquid fallback strategy?

| Option | Description | Selected |
|--------|-------------|----------|
| Liquid → Haze → flat fallback chain (Recommended) | Layered primitive, same token API. | ✓ |
| Liquid + flat fallback (skip Haze) | Two-tier, no middle quality. | |
| Liquid-only, no fallback | Cheapest now. | |

**User's choice:** Three-tier layered fallback.
**Notes:** `GlassSurface` primitive consumes the same token API across all three paths.

### Q4 — When does fallback engage?

| Option | Description | Selected |
|--------|-------------|----------|
| Compile-time per-target + runtime debug toggle (Recommended) | Build-time selection; debug-build comparison toggle. | ✓ |
| Always-best, no toggle | Silent platform selection. | |
| Runtime perf detection auto-downgrades | Real engineering investment. | |

**User's choice:** Compile-time + debug toggle.
**Notes:** No automatic perf detection in v1; Phase 10 may add it.

---

## Claude's Discretion

- Liquid library API specifics (radius, blur, refraction values) — researcher to surface
- Nav graph topology — default to nested NavHost per tab unless research blocks it
- Whether to migrate Phase 2 Material 3 auth screens now — default: leave as legacy
- Specific empty-state copy strings (subject to Phase 11 copy pass)
- Icon source — Material Icons Outlined unless research surfaces a better fit
- Animation curves and durations for the dock-collapse-on-search transition
- Accessibility specifics (Role.Tab semantics, focus order)
- Whether to expose the GlassSurface debug toggle in-app or as a build flag

## Deferred Ideas

- Per-tab/scroll-state dock collapse (mockup) — Phase 10
- Profile/settings entry point in chrome — Phase 3 onboards households first
- Cross-tab CTAs in empty states — feature phases as content lands
- Custom empty-state illustrations
- Material 3 migration of auth screens
- Runtime perf detection auto-downgrade for GlassSurface — Phase 10
- Persisting search query across sessions / tab-switches
- Real-device Liquid tuning — Phase 10