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

name	classification	success_metric	skip	status	created	merged	depends_on	umbrella
liquid-glass-layout-shell	feature	`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.		merged	2026-06-03	2026-06-03	liquid-glass-design-tokens liquid-glass-modal-and-surface-primitive	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):

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.