deckhearth/.convoys/liquid-glass-layout-shell.md

---
name: liquid-glass-layout-shell
classification: feature
success_metric: |
  `components/Layout.js` (826 lines) and `components/MobileNavigation.js`
  render as glass surfaces (sidebar rail, top bar, mobile bottom bar,
  mobile drawer); the existing 5-assertion Layout test suite stays
  green; the smoke `'sign-in page renders'` and visual-diff workflows
  defend the change; visual-diff baselines re-seeded on Linux post-merge.
skip: []
status: merged
created: 2026-06-03
merged: 2026-06-03
depends_on:
  - liquid-glass-design-tokens
  - liquid-glass-modal-and-surface-primitive
umbrella: liquid-glass-redesign
---

# Convoy: liquid-glass-layout-shell

Sub-convoy #4 of the `liquid-glass-redesign` epic. This is the
**highest-blast-radius** PR in the portfolio because Layout is composed
by every authenticated page (and several anonymous ones —
`pages/invite/*.js` legitimately render Layout for anonymous visitors).
Treat with appropriate gating.

## Why

`components/Layout.js` is the single most-rendered component in the
app: sidebar nav, top header (search + theme toggle + profile
dropdown), mobile drawer, and now (per the user's ask) the warm-room
container that surrounds every page.

Under the current design, the sidebar is an opaque wood panel with a
warm-cream column. Under Liquid Glass, the sidebar becomes a tall
glass rail: the page content is dimly visible through it, the active
nav item has an ember rim, and the brand monogram is a glass pill with
inner ember gradient.

`MobileNavigation.js` already has a 16px backdrop-filter on the bottom
bar (`styles/globals.css` lines 800–819). That's the only place glass
exists today; this sub-convoy makes it canonical app-wide.

## Scope

### In scope

- `components/Layout.js`:
  - Sidebar — wrapped in `<GlassSurface tint="mid" rim="subtle">`.
  - Header — separate `<GlassSurface tint="mid" rim="subtle">` strip;
    ember rim under the bottom edge to suggest "light cast onto the page".
  - Logo pill — glass with inner ember gradient.
  - `UserProfileDropdown` menu panel — `<GlassSurface tint="high"
    rim="subtle" elevation="ambient">` (or pull out into a `<Popover>`
    primitive — see Decision 4).
  - `UserProfileDropdown` logged-out CTA — preserves the Sign-in link
    + monogram; `test/components/Layout.test.js` 5 assertions MUST stay
    green.
  - Nav-item active state — current `border-left: 3px solid
    var(--accent-ember)` recipe stays as the *secondary* signal; new
    primary signal is an inset ember rim on the active glass tile.
- `components/MobileNavigation.js`:
  - Bottom bar — upgrade existing `mobile-nav-backdrop` rule to the
    canonical `--glass-blur-mid` + `--glass-surface-mid` tokens (don't
    re-implement on top — see Risk in umbrella).
  - Mobile drawer — `<GlassSurface tint="low" rim="subtle"
    elevation="pronounced">`.
  - Bottom-bar active state — verify AA contrast (the existing finding
    in `.convoys/ship-readiness.md` § Role-ux-reviewer: *"the
    bottom-bar's active state contrast looks low in light mode"*).
- `styles/globals.css`:
  - Update `.mobile-nav-backdrop` to reference the new tokens.
  - Update `.theme-toggle`, `.header-icon`, `.logo-container`,
    `.nav-item*` selectors to consume new tokens.
  - **Do NOT delete** legacy color mappings yet — #8 handles that.

### Out of scope

- Form elements inside Layout (search bar, theme toggle as a `<Button>`,
  profile dropdown items as `<Button variant="ghost">`) — these consume
  primitives from sub-convoy #3; this convoy expects #3 to have shipped
  first (NOT a hard `depends_on:` because the order doesn't strictly
  block, but the resulting visual diff is cleaner if #3 ships first;
  architect ratifies sequencing at gate-1).
- Per-page layout adjustments — out of scope; each page that needs
  layout-conscious tweaks gets its own sub-convoy #6 brief.
- `<Popover>` / `<Menu>` primitive extraction for UserProfileDropdown —
  defer to a follow-up convoy unless architect decides it's cheap to
  bundle.

## Roles invoked

1. `role-architect` — Layout decomposition strategy (single brief vs
   sidebar + header + mobile = 3 briefs).
2. `role-ux-reviewer` — sidebar rail vs header strip information
   hierarchy; mobile drawer ergonomics.
3. `role-a11y-auditor` — nav contrast (bottom-bar active state — see
   existing finding), focus-visible on every nav item, keyboard
   operability.
4. `role-design-system-auditor` — token consumption verification.
5. `role-implementer` — 1–3 briefs per architect call.
6. Post-PR audit fleet.

## Architecture + Brief 1 (shipped 2026-06-03)

Targeted surgical glass migration of the 6 highest-leverage shell
surfaces; no structural refactor of nav data or routing.

**Surfaces converted:**
1. **Desktop sidebar rail** (`components/Layout.js` ~ line 714) —
   `--glass-surface-mid` + `--glass-blur-mid` + `--glass-saturate`,
   rim-light inner + outer + `--elevation-ambient`. The page background
   visibly cools through the rail.
2. **Mobile drawer** (`components/Layout.js` ~ line 620) — same recipe
   as the desktop rail, but with `--elevation-pronounced` (drawer is a
   floating surface, not a docked rail).
3. **Mobile overlay scrim** (`components/Layout.js` ~ line 609) —
   `--modal-scrim` + `--glass-blur-high` + saturate. Now visually
   consistent with the `<Modal>` primitive's scrim.
4. **Search header strip** (`components/Layout.js` ~ line 794, only
   when `showSearch`) — `--glass-surface-mid` + rim-light. The
   `⌘F`-indicator + inline `<input>` stay intact (full SearchBar
   primitive migration queued for follow-up).
5. **UserProfileDropdown popover menu** (`components/Layout.js` ~
   line 86) — `--glass-surface-high` (popover ramp), ember-subtle
   rim, ambient elevation. Now matches the popover composite recipe
   in `docs/DESIGN_TOKENS.md`.
6. **MobileNavigation bottom bar background** (`components/MobileNavigation.js`
   ~ line 82) — replaced `mobile-nav-backdrop` legacy class + 0.95-alpha
   rgba with glass-mid + rim-light. The raised "Dashboard" center
   button's gradient is preserved untouched (it's a brand-accent
   primary action, not a panel surface).

**Verification:** lint 0 errors; vitest 104/104 green; the 5 Layout
regression-lock tests (logged-out CTA, no maintainer-email default,
"Sign in" link present, supplied email renders, no "Guest" placeholder)
all preserved. No nav structure / routing / hook order changes.

**Follow-up (queued):** swap the header's inline `<input>` for the
`<SearchBar>` primitive (handles `⌘F` chip via `trailingAction`).
Tracked under `liquid-glass-form-primitives` Brief 2.

## Todos

- [ ] Architect: decomposition + sequencing call with #3
- [ ] UX reviewer: sidebar rail vs header strip
- [ ] A11y auditor: bottom-bar contrast + focus-visible audit
- [ ] Brief 1 — `components/Layout.js` (or per-architect partition)
- [ ] Brief 2 — `components/MobileNavigation.js` + CSS rule updates
- [ ] Post-PR audit per brief
- [ ] Re-seed Linux visual-diff baselines on merge

## Decisions to ratify (architect)

1. **Single-PR vs multi-brief.** Layout is 826 lines; a single PR
   touches every authenticated page's visual diff. Trade-off:
   - Single PR → atomic, but baselines must re-seed for every page in
     one shot.
   - Multi-brief (e.g. sidebar / header / mobile) → smaller diffs but
     three baseline re-seeds.
   Recommended default: **single PR** if Brief 1 stays under ~400 LOC
   of changes; multi-brief otherwise.
2. **Sidebar rail visual style** — full-height glass column vs
   "floating" inset glass card with margin. Recommended: full-height
   column (matches existing nav rail; less reflow).
3. **Header strip height** — current is 64px desktop / 56px mobile.
   Confirm or re-tune.
4. **UserProfileDropdown as `<Popover>` primitive** — extract or
   inline. Recommended: **inline** for this convoy; defer primitive
   extraction to a follow-up if a second popover surface appears.
5. **Mobile bottom-bar active-state contrast** — re-tune the existing
   token used or introduce a new `--nav-active-text` token. Closes the
   ship-readiness finding.
6. **Brand monogram pill** — keep "DH" glyph + add inner ember
   gradient (recommended) vs replace with `AnimatedFireLogo`
   (rejected — too motion-heavy on every page chrome).

## Acceptance criteria

1. Sidebar, header, mobile bottom bar, mobile drawer all render as
   glass surfaces consuming sub-convoy #1's tokens.
2. `test/components/Layout.test.js` 5 assertions all pass.
3. Smoke spec 2 (`'sign-in page renders'`) passes on the preview.
4. A11y: bottom-bar active state hits AA contrast (closes the
   ship-readiness finding); every nav item has `:focus-visible` ring;
   every interactive non-`<button>` has `tabIndex={0}` + `onKeyDown`.
5. Lint + vitest + smoke green.
6. Linux visual-diff baselines re-seeded post-merge.

## CI impact

| Workflow / job | Behavior |
| --- | --- |
| `preview-smoke.yml` | Fires; smoke spec 2 (`'sign-in page renders'`) defends the logged-out Sign-in CTA branch (PR #15's regression-lock). |
| `visual-diff.yml` | **Fires + LOUDEST in portfolio** — Layout on every page. Baselines re-seed mandatory post-merge. |
| `lint` | Fires. |
| `test:` (vitest) | Fires + 5 Layout assertions defended. |
| New grep gates | Consider `forbidden-sidebar-hardcoded-color` post-merge (if hex creeps back in). Architect's call. |

## Known constraints

- **No regression in Layout's logged-out branch.** PR #15
  (`fix-layout-default-user`, `ca302a8`, 2026-05-24) made
  `UserProfileDropdown` render a Sign-in CTA when `user === null`.
  That branch is defended by 5 vitest assertions AND smoke spec 2.
  Both must stay green. The migration to glass is purely visual; the
  branch logic is sacrosanct.
- **Hook order** — the existing comment at `Layout.js` lines 9–10
  reads: *"Hook order is fixed for both branches; do not move this
  below the null-user early return — see rules-of-hooks (AGENTS.md
  Gotcha #11.5)."* Honour this.
- **`components/Layout.js.backup`** — the legacy snapshot listed in
  `.cursor/rules/no-go-zones.mdc`. Do not edit.
- **Mobile safe-area** — `env(safe-area-inset-bottom)` still respected;
  glass bottom bar must not break iOS notch handling.
- **`prefers-reduced-motion`** — any nav-item transition must respect
  it (existing pattern at `styles/globals.css` lines 261–266).

## Multitask dispatch

Pre-ratification proposal (architect to revise):

```yaml
slice_dependencies:
  - brief: 1
    depends_on: []
    files:
      - components/Layout.js
      - styles/globals.css   # (selector consumers; NOT new tokens)
  - brief: 2
    depends_on: []
    files:
      - components/MobileNavigation.js
      - styles/globals.css   # (mobile-nav-backdrop rule)
```

Briefs 1 + 2 share `styles/globals.css`; architect must split or
serialize accordingly (likely serialize: Brief 1 first, Brief 2 picks
up `styles/globals.css` in HEAD state after Brief 1).

Post-PR audit per brief:

```
/multitask role-reviewer + role-design-system-auditor + role-a11y-auditor
```

## Out of scope follow-ups

- **`<Popover>` primitive extraction** — if a second popover surface
  appears in #5 or #6.
- **Sidebar collapse/expand on desktop** — UX feature, not a redesign
  concern. Surface only if user requests.
- **Skip-to-content link** — flagged in ship-readiness § Role-a11y-
  auditor (*"no `<a href="#main" class="sr-only focus:not-sr-only">`"*).
  Cheap; fold into this convoy's a11y brief if architect agrees.