# Phase 18: App Shell & Navigation - Context

**Gathered:** 2026-05-17
**Status:** Ready for planning

<domain>
## Phase Boundary

Redesign the authenticated app shell to match the Figma design: full rebuild of the sidebar (new HTML structure, section labels, updated nav items, collapse toggle) and addition of a new per-page top header bar (breadcrumb, search placeholder, bell placeholder, inbox placeholder, avatar dropdown).

Every authenticated page is affected — changes to `AppLayout` propagate to all routes.

</domain>

<decisions>
## Implementation Decisions

### Figma Source
- **D-01:** Figma file: `https://www.figma.com/design/6z32tx1YhL3nJHlX6M4IA2/XTABLO-Design--bbellev---copie-?node-id=11013-36540` — primary design reference.
- **D-02:** Screenshots are in `screenshots/` at the repo root (Homepage.png, Board.png, and others). Planner/executor MUST read relevant screenshots before making visual decisions.

### Top Header Bar (NAV-02)
- **D-03:** The top header bar spans the full content area (right of sidebar). It has three zones:
  - **Left:** Breadcrumb path (e.g., "Dashboard" or "Dashboard > Project Details")
  - **Center:** Search input — **visual placeholder only** (no backend wiring in Phase 18)
  - **Right:** Notification bell (placeholder), Inbox button (placeholder), user avatar
- **D-04:** The breadcrumb is passed via new params added to `AppLayout`. Add `pageTitle string` and a breadcrumb slice (e.g., `[]BreadcrumbItem{label, href}`) to the `AppLayout` signature. Every handler call site sets its own breadcrumb.
- **D-05:** `AppLayout` also gets a `headerActions templ.Component` slot for per-page contextual action buttons. Phase 18 renders this empty (or nil). Downstream phases (19–22) fill in page-specific actions.
- **D-06:** Clicking the avatar opens an HTMX/Alpine-style dropdown containing:
  - Workspace name + member count section
  - Members list (user avatar, name, email)
  - Separator
  - Settings link → `/settings` (stub page; the settings page itself is out of scope for Phase 18)
  - Log out button (red text, posts to `/logout`)
  - **No theme toggle buttons**
  - Reference HTML from JS app was provided — adapt visually to Go design system tokens, not copy verbatim.

### Sidebar Rebuild (NAV-01)
- **D-07:** Full HTML/CSS rebuild to Figma spec. The existing sidebar structure from Phase 15 is replaced, not patched. The design system (CSS token vocabulary) is updated to reflect any new visual decisions made during the rebuild.
- **D-08:** Nav item mapping — match Figma labels exactly where possible:
  - **GENERAL section label** above: Home (`/`), My Tasks (`/tasks`), Projects (`/tablos`), Events (`/planning`), Team Members (placeholder — no route yet, render as non-interactive or link to `#`)
  - **PROJECTS section label** above: tablo list (existing `SidebarProjectsSection`)
  - Items that have no matching Figma equivalent (chat, files global nav) are removed from the primary nav items list; they remain accessible within tablo detail pages.
- **D-09:** Sidebar collapse toggle is implemented using JavaScript (no server round-trip). Clicking the collapse button toggles an `is-collapsed` CSS class on the sidebar. In collapsed state: hide labels and section headers, show icons only. **State is NOT persisted** — resets on page reload. (Persistence is a v5.0 candidate per RESP-01.)

### Claude's Discretion
- Avatar dropdown implementation mechanism (HTMX `hx-on::click` + hidden div toggle, `<details>/<summary>`, or small inline JS) — choose the simplest reliable approach that doesn't require Alpine.js.
- Exact CSS class naming for the new header bar components — follow the existing `.dashboard-*` / `.sidebar-*` token naming convention.
- Whether `BreadcrumbItem` is a struct or a simple string slice — choose what keeps call sites clean.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Design References
- `screenshots/Homepage.png` — Figma homepage screenshot showing full sidebar + header bar layout
- `screenshots/Board.png` — Figma board/tablo detail screenshot showing breadcrumb ("Dashboard > Project Details") and header bar with avatar
- Figma URL: `https://www.figma.com/design/6z32tx1YhL3nJHlX6M4IA2/XTABLO-Design--bbellev---copie-?node-id=11013-36540` — primary design source (read screenshots if Figma not accessible)

### Existing Shell Code
- `backend/templates/app_layout.templ` — current `AppLayout`, `DashboardSidebar`, `SidebarNavItemRow`, `SidebarProjectsSection`, `SidebarOrganizationFooter` components to be rebuilt/replaced
- `backend/static/tailwind.css` — CSS token vocabulary and existing `.dashboard-*`, `.sidebar-*`, `.organization-*` styles (lines 3276–3530 are the relevant sidebar/shell block)

### Requirements
- `.planning/REQUIREMENTS.md` — NAV-01 and NAV-02 requirements
- `.planning/ROADMAP.md` — Phase 18 success criteria

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `backend/internal/web/ui/` — existing templ component library (button, badge, modal, card, etc.). Use these for any new interactive elements in the header dropdown.
- `backend/internal/web/ui/csrf_field.templ` — `ui.CSRFField(csrfToken)` already used in logout form; reuse in any new forms.
- `backend/templates/app_layout.templ` — all nav icon SVGs (`SidebarNavIcon`) are already implemented; reuse for the rebuilt sidebar.
- `backend/internal/auth/` — `auth.User` struct provides `Email` field used for avatar initial and org footer.

### Established Patterns
- `AppLayout` is the single authenticated shell — all authenticated handlers call it. Adding params here requires updating every handler call site.
- Active path is currently a string passed as `activePath`; sidebar uses `sidebarNavItemClass(item.Active)` — this pattern continues.
- HTMX is loaded via `<script src="/static/htmx.min.js" defer>` — available for any header interactivity.
- CSS uses design token vars (`var(--color-*)`, `var(--shadow-*)`) throughout — new styles must use tokens, not raw hex values.

### Integration Points
- Every authenticated handler in `backend/internal/web/` renders `AppLayout(...)` — all call sites need `pageTitle` and `breadcrumb` params added.
- The logout form currently lives in `SidebarOrganizationFooter`; it moves to the avatar dropdown in the header. The POST `/logout` route stays unchanged.
- `backend/static/tailwind.css` — new CSS classes for header bar components go here (or in `backend/internal/web/ui/app.css` if that's the pattern for component-level styles; check which file the Phase 15 sidebar styles live in).

</code_context>

<specifics>
## Specific Ideas

- Avatar dropdown visual reference: user provided HTML from the existing JS app. Key elements to adapt: workspace name + member count row, members list section, settings link (`/settings`), logout button (red). No theme toggle. Adapt to Go design system tokens — don't copy Tailwind class names verbatim.
- The collapse button exists in CSS (`.sidebar-collapse-button`) but was never wired — this is the place to connect it.
- Team Members nav item: render as non-interactive (greyed out) or `href="#"` since the page doesn't exist in v4.0.

</specifics>

<deferred>
## Deferred Ideas

- **Sidebar collapse persistence via cookie** — user chose no persistence for Phase 18. v5.0 candidate (RESP-01).
- **Sidebar responsive collapse on mobile** — v5.0 candidate (RESP-01).
- **Search functionality** — placeholder only in Phase 18; search is its own future phase.
- **Notifications / Inbox** — placeholder only; not wired in Phase 18.
- **Settings page** (`/settings`) — avatar dropdown links to it as a stub; full settings is a future phase.

</deferred>

---

*Phase: 18-App Shell & Navigation*
*Context gathered: 2026-05-17*
