Fix app shell layout with stable top bar and dynamic nav offset.

Unified chrome keeps the home logo top-left, measures bottom nav height
for scroll clearance, and adds responsive content widths for mobile/desktop.

app/globals.css

@@ -4,6 +4,8 @@
 
 @layer base {
   :root {
+    --app-topbar-height: 3.5rem;
+    --app-nav-offset: var(--bottom-nav-height);
     --bottom-nav-height: 6rem;
     --background: 252 38% 10%;
     --foreground: 52 100% 88%;
@@ -168,7 +170,11 @@
 
 @layer utilities {
   .pb-nav {
-    padding-bottom: var(--bottom-nav-height);
+    padding-bottom: var(--app-nav-offset);
+  }
+
+  .pt-topbar {
+    padding-top: calc(var(--app-topbar-height) + env(safe-area-inset-top, 0px));
   }
 
   .image-pixelated {

components/avatar/avatar-customize-layout.tsx

@@ -1,4 +1,5 @@
 import { AppPageHeader } from "@/components/layout/app-page-header";
+import { AppTopBar } from "@/components/layout/app-top-bar";
 
 type AvatarCustomizeLayoutProps = {
   eyebrow?: string;
@@ -14,14 +15,17 @@ export function AvatarCustomizeLayout({
   children,
 }: AvatarCustomizeLayoutProps) {
   return (
-    <div className="relative bg-background bg-[radial-gradient(circle_at_20%_0%,hsl(var(--primary)/0.12)_0%,transparent_45%),radial-gradient(circle_at_80%_100%,hsl(var(--secondary)/0.1)_0%,transparent_40%)]">
-      <AppPageHeader
-        eyebrow={eyebrow}
-        title={title}
-        description={description}
-      />
+    <div className="relative min-h-dvh bg-background bg-[radial-gradient(circle_at_20%_0%,hsl(var(--primary)/0.12)_0%,transparent_45%),radial-gradient(circle_at_80%_100%,hsl(var(--secondary)/0.1)_0%,transparent_40%)] pt-topbar">
+      <AppTopBar />
 
-      <main className="mx-auto max-w-6xl px-5 py-6">{children}</main>
+      <main className="mx-auto max-w-lg px-4 py-6 md:max-w-3xl md:px-5 lg:max-w-6xl">
+        <AppPageHeader
+          eyebrow={eyebrow}
+          title={title}
+          description={description}
+        />
+        {children}
+      </main>
     </div>
   );
 }

components/layout/app-nav.tsx

@@ -2,6 +2,7 @@
 
 import Link from "next/link";
 import { usePathname } from "next/navigation";
+import { forwardRef } from "react";
 import {
   Home,
   ListPlus,
@@ -36,7 +37,10 @@ type AppNavProps = {
   items?: readonly NavItem[];
 };
 
-export function AppNav({ items = appNavItems }: AppNavProps) {
+export const AppNav = forwardRef<HTMLElement, AppNavProps>(function AppNav(
+  { items = appNavItems },
+  ref,
+) {
   const pathname = usePathname();
   const columnCount = Math.min(
     items.length,
@@ -45,8 +49,8 @@ export function AppNav({ items = appNavItems }: AppNavProps) {
 
   return (
     <nav
+      ref={ref}
       className="bottom-nav fixed inset-x-0 bottom-0 z-50 border-t-2 border-border bg-background/95 shadow-[0_-4px_0_0_hsl(280_45%_28%/0.35)] backdrop-blur supports-[backdrop-filter]:bg-background/90"
-      style={{ height: "var(--bottom-nav-height)" }}
     >
       <div
         aria-hidden
@@ -54,7 +58,7 @@ export function AppNav({ items = appNavItems }: AppNavProps) {
       />
       <div
         className={cn(
-          "mx-auto grid h-full max-w-6xl gap-1 px-2 pb-[max(0.5rem,env(safe-area-inset-bottom))] pt-2",
+          "mx-auto grid max-w-6xl gap-1 px-2 pb-[max(0.5rem,env(safe-area-inset-bottom))] pt-2",
           gridColsClass[columnCount],
         )}
       >
@@ -71,10 +75,10 @@ export function AppNav({ items = appNavItems }: AppNavProps) {
               aria-label={item.label}
               title={item.label}
               className={cn(
-                "bottom-nav-item flex flex-col items-center justify-center gap-1.5 border-2 px-1 py-2 text-[9px] leading-none transition-all duration-75",
+                "bottom-nav-item flex flex-col items-center justify-center gap-1.5 overflow-hidden border-2 px-1 py-2 text-[9px] leading-none transition-colors duration-75",
                 isActive
-                  ? "border-secondary bg-primary text-primary-foreground shadow-[var(--retro-shadow-sm)] -translate-y-0.5"
-                  : "border-transparent text-muted-foreground hover:border-border hover:bg-muted hover:text-foreground hover:-translate-y-0.5",
+                  ? "border-secondary bg-primary text-primary-foreground shadow-[var(--retro-shadow-sm)]"
+                  : "border-transparent text-muted-foreground hover:border-border hover:bg-muted hover:text-foreground",
               )}
             >
               <Icon
@@ -90,4 +94,4 @@ export function AppNav({ items = appNavItems }: AppNavProps) {
       </div>
     </nav>
   );
-}
+});

components/layout/app-page-header.tsx

@@ -1,42 +1,27 @@
-import { HomeLogoLink } from "@/components/layout/home-logo-link";
-import { cn } from "@/lib/utils";
-
 type AppPageHeaderProps = {
   title: string;
   description?: string;
   eyebrow?: string;
-  wide?: boolean;
 };
 
 export function AppPageHeader({
   title,
   description,
   eyebrow,
-  wide = false,
 }: AppPageHeaderProps) {
   return (
-    <header className="border-b-2 border-border bg-card/60 shadow-[var(--retro-shadow-sm)]">
-      <div
-        className={cn(
-          "mx-auto flex items-start justify-between gap-4 px-5 py-5",
-          wide ? "max-w-6xl" : "max-w-lg",
-        )}
-      >
-        <div className="min-w-0 flex-1">
-          {eyebrow ? (
-            <p className="mb-2 text-xs uppercase tracking-[0.2em] text-muted-foreground">
-              {eyebrow}
-            </p>
-          ) : null}
-          <h1 className="text-sm">{title}</h1>
-          {description ? (
-            <p className="mt-2 text-xs leading-relaxed text-muted-foreground">
-              {description}
-            </p>
-          ) : null}
-        </div>
-        <HomeLogoLink className="mt-0.5" />
-      </div>
+    <header className="mb-6 border-b-2 border-border bg-card/60 px-1 pb-5 shadow-[var(--retro-shadow-sm)]">
+      {eyebrow ? (
+        <p className="mb-2 text-xs uppercase tracking-[0.2em] text-muted-foreground">
+          {eyebrow}
+        </p>
+      ) : null}
+      <h1 className="text-sm">{title}</h1>
+      {description ? (
+        <p className="mt-2 text-xs leading-relaxed text-muted-foreground">
+          {description}
+        </p>
+      ) : null}
     </header>
   );
 }

components/layout/app-shell.tsx

@@ -1,4 +1,5 @@
 import { AppPageHeader } from "@/components/layout/app-page-header";
+import { AppTopBar } from "@/components/layout/app-top-bar";
 import { cn } from "@/lib/utils";
 
 type AppShellProps = {
@@ -8,6 +9,11 @@ type AppShellProps = {
   wide?: boolean;
 };
 
+const contentWidthClass = {
+  default: "max-w-lg md:max-w-2xl lg:max-w-4xl",
+  wide: "max-w-lg md:max-w-3xl lg:max-w-6xl",
+} as const;
+
 export function AppShell({
   children,
   title,
@@ -15,16 +21,17 @@ export function AppShell({
   wide = false,
 }: AppShellProps) {
   return (
-    <div className="relative bg-background bg-[radial-gradient(circle_at_20%_0%,hsl(var(--primary)/0.12)_0%,transparent_45%),radial-gradient(circle_at_80%_100%,hsl(var(--secondary)/0.1)_0%,transparent_40%)]">
-      {title ? (
-        <AppPageHeader title={title} description={description} wide={wide} />
-      ) : null}
+    <div className="relative min-h-dvh bg-background bg-[radial-gradient(circle_at_20%_0%,hsl(var(--primary)/0.12)_0%,transparent_45%),radial-gradient(circle_at_80%_100%,hsl(var(--secondary)/0.1)_0%,transparent_40%)] pt-topbar">
+      <AppTopBar />
       <main
         className={cn(
-          "mx-auto px-5 py-6",
-          wide ? "max-w-6xl" : "max-w-lg",
+          "mx-auto px-4 py-6 md:px-5",
+          wide ? contentWidthClass.wide : contentWidthClass.default,
         )}
       >
+        {title ? (
+          <AppPageHeader title={title} description={description} />
+        ) : null}
         {children}
       </main>
     </div>

components/layout/app-top-bar.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+
+import { HomeLogoLink } from "@/components/layout/home-logo-link";
+import { routes } from "@/lib/routes";
+import { cn } from "@/lib/utils";
+
+type AppTopBarProps = {
+  className?: string;
+};
+
+export function AppTopBar({ className }: AppTopBarProps) {
+  const pathname = usePathname();
+  const isHome = pathname === routes.avatar;
+
+  return (
+    <header
+      className={cn(
+        "app-top-bar fixed inset-x-0 top-0 z-40 border-b-2 border-border bg-background/95 shadow-[var(--retro-shadow-sm)] backdrop-blur supports-[backdrop-filter]:bg-background/90",
+        className,
+      )}
+      style={{
+        height: "var(--app-topbar-height)",
+        paddingTop: "env(safe-area-inset-top, 0px)",
+      }}
+    >
+      <div className="mx-auto flex h-full max-w-6xl items-center px-4">
+        <HomeLogoLink
+          className="mt-0"
+          aria-current={isHome ? "page" : undefined}
+        />
+      </div>
+    </header>
+  );
+}

components/layout/global-bottom-nav.tsx

@@ -3,10 +3,20 @@
 import { useEffect, useState } from "react";
 
 import { AppNav } from "@/components/layout/app-nav";
+import {
+  NavOffsetProvider,
+  useNavOffsetRef,
+} from "@/components/layout/nav-offset-provider";
 import { HABIT_PET_DATA_UPDATED_EVENT } from "@/lib/app-events";
 import { getOnboardingStatusClient } from "@/lib/onboarding-status";
 import { createClient } from "@/lib/supabase/client";
 
+function MeasuredAppNav() {
+  const navRef = useNavOffsetRef();
+
+  return <AppNav ref={navRef} />;
+}
+
 export function GlobalBottomNav() {
   const [showNav, setShowNav] = useState(false);
 
@@ -43,9 +53,9 @@ export function GlobalBottomNav() {
     };
   }, []);
 
-  if (!showNav) {
-    return null;
-  }
-
-  return <AppNav />;
+  return (
+    <NavOffsetProvider enabled={showNav}>
+      {showNav ? <MeasuredAppNav /> : null}
+    </NavOffsetProvider>
+  );
 }

components/layout/home-logo-link.tsx

@@ -5,13 +5,18 @@ import { cn } from "@/lib/utils";
 
 type HomeLogoLinkProps = {
   className?: string;
+  "aria-current"?: "page" | undefined;
 };
 
-export function HomeLogoLink({ className }: HomeLogoLinkProps) {
+export function HomeLogoLink({
+  className,
+  "aria-current": ariaCurrent,
+}: HomeLogoLinkProps) {
   return (
     <Link
       href={routes.avatar}
       aria-label="Go to home"
+      aria-current={ariaCurrent}
       className={cn(
         "group flex shrink-0 items-center justify-center border-2 border-border bg-card/80 p-2 shadow-[var(--retro-shadow-sm)] transition-transform hover:-translate-y-0.5 hover:border-primary/60",
         className,

components/layout/nav-offset-provider.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  type ReactNode,
+  type Ref,
+} from "react";
+
+type NavOffsetContextValue = {
+  setNavElement: (element: HTMLElement | null) => void;
+};
+
+const NavOffsetContext = createContext<NavOffsetContextValue | null>(null);
+
+export function useNavOffsetRef<T extends HTMLElement>() {
+  const context = useContext(NavOffsetContext);
+
+  if (!context) {
+    throw new Error("useNavOffsetRef must be used within NavOffsetProvider.");
+  }
+
+  const setNavElement = context.setNavElement;
+
+  return useCallback(
+    (node: T | null) => {
+      setNavElement(node);
+    },
+    [setNavElement],
+  ) as Ref<T>;
+}
+
+type NavOffsetProviderProps = {
+  children: ReactNode;
+  enabled?: boolean;
+};
+
+export function NavOffsetProvider({
+  children,
+  enabled = true,
+}: NavOffsetProviderProps) {
+  const navElementRef = useRef<HTMLElement | null>(null);
+  const observerRef = useRef<ResizeObserver | null>(null);
+
+  const syncOffset = useCallback(() => {
+    const root = document.documentElement;
+
+    if (!enabled || !navElementRef.current) {
+      root.style.setProperty("--app-nav-offset", "0px");
+      return;
+    }
+
+    root.style.setProperty(
+      "--app-nav-offset",
+      `${navElementRef.current.offsetHeight}px`,
+    );
+  }, [enabled]);
+
+  const setNavElement = useCallback(
+    (element: HTMLElement | null) => {
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+
+      navElementRef.current = element;
+
+      if (!element || !enabled) {
+        syncOffset();
+        return;
+      }
+
+      const observer = new ResizeObserver(() => {
+        syncOffset();
+      });
+
+      observer.observe(element);
+      observerRef.current = observer;
+      syncOffset();
+    },
+    [enabled, syncOffset],
+  );
+
+  useEffect(() => {
+    syncOffset();
+    window.addEventListener("resize", syncOffset);
+
+    return () => {
+      window.removeEventListener("resize", syncOffset);
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+      }
+      document.documentElement.style.setProperty("--app-nav-offset", "0px");
+    };
+  }, [syncOffset]);
+
+  useEffect(() => {
+    if (!enabled) {
+      setNavElement(null);
+    }
+  }, [enabled, setNavElement]);
+
+  return (
+    <NavOffsetContext.Provider value={{ setNavElement }}>
+      {children}
+    </NavOffsetContext.Provider>
+  );
+}

components/reminders/in-app-reminder-banner.tsx

@@ -36,7 +36,7 @@ export function InAppReminderBanner() {
       role="status"
       aria-live="polite"
       className="fixed inset-x-0 z-[60] px-4 pb-[env(safe-area-inset-bottom,0px)]"
-      style={{ bottom: "calc(var(--bottom-nav-height) + 0.5rem)" }}
+      style={{ bottom: "calc(var(--app-nav-offset, var(--bottom-nav-height)) + 0.5rem)" }}
     >
       <div className="mx-auto flex max-w-lg items-start gap-3 rounded-xl border border-primary/30 bg-card p-4 shadow-lg">
         <div className="rounded-full bg-primary/10 p-2">

components/shop/shop-content.tsx

@@ -202,7 +202,7 @@ export function ShopContent() {
   const roomItems = items.filter((item) => item.type === "room");
 
   const itemGridClassName =
-    "grid grid-cols-1 gap-3 sm:grid-cols-2 xl:grid-cols-3";
+    "grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3";
 
   return (
     <>

components/ui/toast-provider.tsx

@@ -45,8 +45,8 @@ export function ToastProvider({ children }: { children: ReactNode }) {
       {children}
       <div
         aria-live="polite"
-        className="pointer-events-none fixed right-4 z-50 flex w-[min(100vw-2rem,20rem)] flex-col gap-2"
-        style={{ bottom: "calc(var(--bottom-nav-height) + 0.75rem)" }}
+        className="pointer-events-none fixed right-4 z-[60] flex w-[min(100vw-2rem,20rem)] flex-col gap-2"
+        style={{ bottom: "calc(var(--app-nav-offset, var(--bottom-nav-height)) + 0.75rem)" }}
       >
         {messages.map((message) => (
           <div

docs/superpowers/specs/2026-05-24-app-shell-layout-design.md

@@ -0,0 +1,65 @@
+# App Shell & Responsive Layout Design
+
+**Date:** 2026-05-24  
+**Status:** Approved for implementation  
+**Approach:** Unified app chrome + dynamic nav inset (Approach 2)  
+**Desktop nav:** Option A — bottom bar on all screen sizes
+
+## Problem
+
+1. Page content and overlays appear under the fixed bottom nav because clearance uses a static `--bottom-nav-height: 6rem` that does not match the real rendered nav height (safe-area insets, label toggling, active-state transforms).
+2. The home logo in `AppPageHeader` sits top-right and shifts vertically/horizontally as page titles vary in length.
+3. Layout is mobile-first only; desktop gets narrow centered columns with no breakpoint strategy.
+
+## Solution
+
+### App chrome structure
+
+- **AppTopBar:** Fixed top bar with `HomeLogoLink` always top-left; consistent height via `--app-topbar-height`.
+- **AppPageHeader:** Content-only title/description block inside main — no logo.
+- **NavOffsetProvider:** `ResizeObserver` on bottom nav sets `--app-nav-offset` on `document.documentElement`.
+- **Overlays:** Toasts and reminder banner use `bottom: calc(var(--app-nav-offset) + offset)`.
+
+### Responsive (Option A)
+
+| Breakpoint | Content width |
+|------------|---------------|
+| default | `max-w-lg` |
+| `md` | `max-w-2xl` |
+| `lg` (standard pages) | `max-w-4xl` |
+| `lg` (wide: shop, customize) | `max-w-6xl` |
+
+Bottom nav remains on all sizes, centered in `max-w-6xl`.
+
+### CSS variables
+
+- `--app-topbar-height: 3.5rem` — fixed top chrome height
+- `--app-nav-offset: 0px` — set dynamically by NavOffsetProvider; fallback 6rem in CSS
+- `--bottom-nav-height` — retained as fallback default for `--app-nav-offset`
+
+### Files
+
+- `components/layout/app-top-bar.tsx` (new)
+- `components/layout/nav-offset-provider.tsx` (new)
+- `components/layout/app-page-header.tsx` — remove logo
+- `components/layout/app-shell.tsx` — top bar + responsive widths
+- `components/layout/app-nav.tsx` — forwardRef for measurement; contain active transform
+- `components/layout/global-bottom-nav.tsx` — wrap with NavOffsetProvider
+- `components/avatar/avatar-customize-layout.tsx` — same shell pattern
+- `app/(app)/layout.tsx` — dynamic padding classes
+- `app/globals.css` — CSS vars and utility classes
+- `components/ui/toast-provider.tsx` — use `--app-nav-offset`
+- `components/reminders/in-app-reminder-banner.tsx` — use `--app-nav-offset`
+
+### Edge cases
+
+- Nav hidden (logged out / onboarding): `--app-nav-offset` reset to `0px`.
+- Safe-area: measured `offsetHeight` includes safe-area padding automatically.
+- Home page `/avatar`: logo visible; optional `aria-current="page"` when active.
+
+### Testing
+
+- Scroll to bottom on Shop, Habits, Profile — content fully visible above nav.
+- Trigger toast + reminder — no overlap with nav.
+- Logo position stable across Avatar, Shop, Habits, Customize.
+- Viewports: 375px, 768px, 1280px.