Skeleton for now — filled in as UI gets built.


Route groups — (marketing), (auth), (app)

Added 2026-07-27, restructuring what had been every page flattened directly under src/app/. A folder wrapped in parentheses — (marketing)/, (app)/ — is a Next.js route group: it organizes files and can carry its own layout.tsx, but the parentheses themselves never appear in the URL. src/app/(app)/dashboard/page.tsx still serves /dashboard, not /(app)/dashboard. This is purely an organizational tool — its whole purpose is letting different sections of one app have entirely different shells (navbar, sidebar, or none at all) without those sections needing different URLs to get there.

Three groups now:

  • (marketing)/ — the public landing page (/), its own minimal navbar (logo + Login/Sign up).
  • (auth)/ — login/signup, deliberately has no layout.tsx of its own, so it renders directly under the root layout with no extra chrome around the forms.
  • (app)/ — everything behind login (dashboard, settings, hall of shame, onboarding), one shared layout.tsx with the real navbar + sidebar.

The (app) layout itself branches on whether the user has a circle yet — someone mid-onboarding gets a minimal header (logo + log out), not the full sidebar with links to a dashboard/settings/hall-of-shame that wouldn’t make sense without a circle. That branch lives in the layout, not in each page, so every page under (app)/ automatically gets the right chrome for whichever state the user’s actually in.

A min-h-screen gotcha this surfaced: pages that used to be the entire screen (src/app/page.tsx, when it had no wrapping layout) had min-h-screen on their own root <div>. Once a page starts rendering inside a shared layout that already establishes the full-screen flex container, an inner min-h-screen double-stacks — the page tries to be at least a full screen tall inside something that’s already a full screen tall. Fixed by switching those inner divs to flex-1 (fill whatever space the parent layout already gives them) instead. Worth checking any time a page moves from being layout-less to living inside a new shared layout.

A repeat of the Base UI asChild gotcha, this time on Button: wanted a <Button> that renders as a next/link <Link> (so it’s a real link, not a button with an onClick). Radix’s answer would be <Button asChild><Link href="...">text</Link></Button> — but per src/components/ui/button.tsx, this project’s Button is built on Base UI, which doesn’t have asChild at all. The fix is the same render prop pattern already seen on Dialog/Select: <Button render={<Link href="/login" />}>Log in</Button> — the element to render as goes in render, the button’s own content stays as children.

Refined 2026-07-27: the marketing page itself doesn’t redirect a logged-in visitor away — only /login//signup do. First pass had proxy.ts bounce anyone authenticated straight to /dashboard from any public route, including /. Product call: a logged-in user should still be able to see the landing page (share it, revisit it, whatever) — it’s the login/signup forms specifically that don’t make sense to show someone already signed in. So (marketing)/layout.tsx and (marketing)/page.tsx are both Server Components that check supabase.auth.getClaims() themselves and swap their own CTA (Login/Sign up → Dashboard) rather than the page redirecting away entirely. Two different jobs even though both check “is this user authenticated”: proxy.ts decides whether a route is reachable at all; a page/layout checking auth itself decides what that same route shows once you’re already allowed to see it.

shadcn/ui — how it’s actually installed (not a normal npm dependency)

npx shadcn@latest init then npx shadcn@latest add <component> doesn’t add a runtime package to node_modules the way npm install some-ui-lib would. Instead it generates the component’s actual source code directly into your repo — that’s why you now have real, editable files at src/components/ui/button.tsx, card.tsx, tabs.tsx, etc.

Why this matters: you own and can freely edit these files (change a class, tweak a variant) without fighting an external library’s API — there’s no “eject” step because you never left. The trade-off is you also own keeping them updated; there’s no npm update pulling in shadcn’s fixes automatically. components.json (also generated) records your style/alias choices so future add commands generate files consistent with what’s already there.

We ran init -d (defaults) then pulled in the components the PRD wireframe actually needs: card, tabs (the MY TASKS / AUDIT THE GEES tab bar), progress (completion bars), badge (status pills), dialog (task creation modal), input, label, avatar, textarea, separator, plus select and checkbox (added later, for the task-creation form).

shadcn’s underlying primitive changed: Base UI, not Radix

Almost every shadcn tutorial/blog post assumes the components are built on Radix UI — that’s been true historically and is still what most training data and search results describe. But npx shadcn init on this project generated components built on @base-ui/react instead (visible right in the generated files: src/components/ui/dialog.tsx imports { Dialog as DialogPrimitive } from "@base-ui/react/dialog"). Same underlying idea (unstyled, accessible primitives you compose), different library, different prop API in a couple of real ways that broke on first use here:

  • No asChild prop. Radix’s pattern for “render this trigger as a different element” (e.g. a <DialogTrigger> that should actually render as your <Button>, not wrap it) is <DialogTrigger asChild><Button>...</Button></DialogTrigger>. Base UI doesn’t have asChild — the equivalent is a render prop: <DialogTrigger render={<Button variant="outline" />}>+ Add New Task</DialogTrigger>. The trigger’s own text/children go as the component’s children; the element to render as goes in render.
  • onValueChange can receive null. Radix’s Select onValueChange is typed (value: string) => void. Base UI’s is (value: string | null, eventDetails) => void — passing a plain useState setter directly (onValueChange={setType}) fails to typecheck, because setType doesn’t accept null. Fix: wrap it — onValueChange={(value) => setType(value ?? "fallback")}.
  • Button’s render prop needs nativeButton={false} too, or it warns at runtime. Button render={<Link href="/dashboard" />}>Dashboard</Button> (the exact pattern from the bullet above) typechecks fine and looks like it works — but Base UI’s Button defaults an internal nativeButton prop to true, meaning it expects to actually render a <button> underneath for proper form/accessibility semantics. Swap in a Link (which renders an <a>) without also telling it nativeButton={false}, and it throws a runtime warning in dev: “A component that acts as a button expected a native <button>… Use a real <button> in the render prop, or set nativeButton to false.” This one didn’t show up until the marketing pages actually got used with a real Button-as-Link, since it’s a runtime check, not a type error — tsc and eslint both pass clean regardless. Fixed centrally in src/components/ui/button.tsx rather than patching every call site: nativeButton={nativeButton ?? render === undefined} — defaults to false automatically whenever render is passed (which in this app is always a Link, never an actual button), while leaving Base UI’s own true default intact for every plain <Button> that doesn’t use render at all. Worth remembering: Base UI’s own docs actually recommend not using Button for links at all — styling the <a> directly with the button’s CSS classes instead — but the nativeButton={false} override is the documented escape hatch when you want to keep using the shared Button wrapper anyway.

Lesson: when a generated/scaffolded file’s behavior doesn’t match what a tutorial says, read the actual generated source first (src/components/ui/*.tsx here) rather than assuming the tutorial is right and your code is wrong — the import line at the top (@base-ui/react/... vs @radix-ui/react-...) tells you immediately which primitive library you’re actually on, before you waste time debugging against the wrong docs.

Next.js 16 specifics (this project uses 16.2.12, not 14)

create-next-app@latest installed Next 16, which is newer than the PRD’s original “14+” and has real breaking changes vs. most tutorials/AI training data, which mostly assume 14/15:

  • middleware.ts → proxy.ts. The file that runs before every request was renamed (exported function proxy now, not middleware) specifically to stop confusion with Express-style middleware — it was never a chain of handlers, just one function acting like a network proxy in front of the app. See learning/supabase.md §1 for why we need this file at all. The old name still works but is deprecated (Next ships a codemod to auto-rename: npx @next/codemod@canary middleware-to-proxy .).
  • Every “request-time” API is now fully async — no synchronous fallback. cookies(), headers(), params, searchParams all return Promises that must be awaited. Next 15 allowed the old synchronous style as a deprecated compatibility path; Next 16 removed it entirely, so old code/tutorials using cookies().get(...) without await will throw, not just warn.
  • Turbopack is the default bundler for both next dev and next build now (previously needed an explicit --turbopack flag). Only relevant if you had a custom Webpack config — we don’t yet.
  • Every export from a "use server" file must itself be an async function. src/app/tasks/actions.ts had a plain sync helper (parseDaysOfWeek(formData), no await anywhere in it) exported alongside the real Server Actions in the same file, so a new file (circle-goals/actions.ts) could reuse it instead of duplicating the parsing logic. Broke the production build: Error: Server Actions must be async functions — from Turbopack, not tsc. npx tsc --noEmit passes clean on this — it’s a Next.js compiler-level rule about what a "use server" module is allowed to export (every export becomes a callable Server Action reference sent to the client), not a TypeScript type error, so typecheck alone won’t catch it; only an actual next build (or touching that route in next dev) does. General rule: a "use server" file is for Server Actions only — any plain helper a Server Action needs (parsing, formatting, validation) belongs in its own ordinary module and gets imported into the actions file, never exported from it. Fixed by moving parseDaysOfWeek into a new plain file, day-of-week.ts, imported by both tasks/actions.ts and circle-goals/actions.ts.

To cover as we build

  • Next.js App Router basics: file-based routing, server vs. client components
  • Tailwind CSS utility-first styling
  • Optimistic UI updates (marking a task done instantly, before the server confirms)
  • Mobile-first responsive layout (max-w-md centered pattern from the PRD wireframe)

Design/UX pass (2026-07-27) — why the whole app was gray, and the fixes

Every color was set to zero chroma — that’s why it looked “dry”

shadcn’s default theme in globals.css defines colors as oklch(L C H) triples — lightness, chroma (how saturated/colorful), hue (which color, on a wheel). Every single variable (--primary, --ring, --accent, --sidebar-primary, etc.) had chroma set to literally 0 — meaning pure gray at every lightness, no hue at all. Buttons, badges, the progress bar, focus rings — all of them reference these same handful of variables, so they were never going to look colorful no matter how the components themselves were built. The fix wasn’t touching any component — it was giving --primary (and the handful of variables tied to it: --ring, --accent, --sidebar-primary, --chart-1) real chroma and a hue (picked emerald green — ties into the existing 🔥 streak, and reads naturally as “good standing” for the VERIFIED badge, staying visually distinct from the red already used for destructive/rejected). One CSS file change recolored the entire app — button, progress bar, badges, focus rings, sidebar accents — because they’d all been built correctly to reference the shared variables rather than hardcoding gray; the theme was the only thing actually gray.

Also added a warning badge variant (amber, plain Tailwind amber-500/amber-700 utility classes rather than a new CSS variable — a fine, common mix for a one-off semantic color that doesn’t need theming infrastructure) so the “Auditing” status reads as its own color instead of the same flat gray as everything else.

Dark/light mode via next-themes

next-themes handles a real problem plain useState can’t: on first load, before React hydrates, something has to decide whether to apply .dark to <html> — and if that decision happens only after JS runs, there’s a visible flash of the wrong theme. next-themes solves it with a tiny inline script injected before hydration that reads the stored preference (or system preference) and sets the class immediately.

Setup: wrap the app in <ThemeProvider attribute="class" defaultTheme="system" enableSystem> (root layout.tsx) — attribute="class" specifically means “toggle by adding/removing the dark class on <html>,” which is exactly what globals.css’s .dark { ... } block is already waiting for (no change needed there — the dark-mode variables already existed, just nothing was ever switching to them). Then anywhere in a Client Component, useTheme() gives { theme, setTheme } — the profile dropdown’s Light/Dark/System submenu just calls setTheme("light" | "dark" | "system").

The navbar search filters through the URL, not local state

The search input lives in the navbar (app-shell.tsx), but the actual filtering happens in the Dashboard Server Component. The link between them is the URL’s ?q= query param, not shared React state: the input debounces and calls router.replace(pathname + "?q=" + value), and the Dashboard page reads it back via its searchParams prop (async in Next 16 — const { q } = await searchParams) and filters the task list server-side before rendering.

Why not just local useState in a shared parent: the input lives in a layout-level component (app-shell.tsx), the data being filtered lives in a page component two levels down (dashboard/page.tsx) — a Server Component, which can’t hold useState at all. Routing the connection through the URL sidesteps needing to lift state across a Server/Client boundary that doesn’t actually support it, and comes with real side benefits for free: the filtered view is now bookmarkable and shareable (/dashboard?q=read), and back/forward navigation works correctly.

Why the search only renders on /dashboard at all: app-shell.tsx checks usePathname() === "/dashboard" before rendering <TaskSearch />. The navbar is shared across every (app) page, but there’s only something real to filter on the dashboard — showing the input everywhere else would be exactly the “control that looks interactive but does nothing” trap already named in learning/sys-design.md §8 (the Vouch button).

Retractable sidebar — a plain width transition, no extra library

app-shell.tsx holds one useState(false) for collapsed, and the sidebar’s own class list switches between md:w-56 and md:w-0 with transition-[width] duration-200 plus overflow-hidden on the container — collapsing is just animating a CSS width to zero, not conditionally unmounting the sidebar or reaching for a dedicated sidebar library. Simple, but worth knowing the alternative (icon-only collapsed state, i.e. shrinking to just icons instead of to nothing) is a common richer version of the same idea — not built here, since nav items don’t have icons yet.

The pre-commit hook catching a real bug: setState inside useEffect

CopyInviteLink originally used useEffect(() => setOrigin(window.location.origin), []) to learn the site’s own URL after mount (needed since window doesn’t exist during server rendering). The Husky pre-commit hook’s eslint --fix refused the commit outright — react-hooks/set-state-in-effect flags exactly this pattern, because it causes an extra, avoidable render pass: mount → render once with the initial (empty) state → effect runs → setState → render again with the real value. Not broken, but doing strictly more work than necessary for something knowable before the component ever needed to guess.

The actual fix wasn’t taming the effect — it was not needing one. circle-settings/page.tsx is a Server Component; it already runs on the server, where request info (via headers() from next/headers, reading the host header) is available directly. So instead of shipping a bare invite code down to a Client Component and having it reconstruct the full URL client-side after mount, the Server Component now builds the finished absolute link itself and passes it straight down as a plain string prop — no useState, no useEffect, no extra render, no hydration-mismatch risk from the value changing after first paint.

General pattern worth keeping: before reaching for useEffect + useState to derive a value a Client Component needs, ask whether a Server Component further up the tree already has (or could easily get) that value directly — if so, pass it down as a prop instead of re-deriving it client-side after the fact. This is exactly the kind of thing a fast pre-commit check is for: catching a real, if minor, inefficiency before it ships, not after.

Same rule, a second real hit — and it turned out add-task-dialog.tsx had been carrying the identical issue the whole time. edit-task-dialog.tsx copied add-task-dialog.tsx’s established useActionState + useEffect(() => { if (state?.success) setOpen(false) }, [state]) pattern for “close the dialog once the server action succeeds” — and the hook flagged it immediately. Checking the original add-task-dialog.tsx for the same shape confirmed it had never actually been linted: it was written before Husky was set up, so tsc --noEmit (which was being run after every change) had nothing to say about it, since this is a lint rule, not a type error. The real fix, applied to both: drop useActionState entirely in favor of a plain async submit handler (the same shape submit-proof-dialog.tsx already used) — call the Server Action directly, await it, and close/reset synchronously right after, in the same function, instead of via a separate effect reacting to a state change. A useRef on the form (not e.currentTarget) does the post-await reset, because React nulls out a synthetic event’s currentTarget once the handler’s synchronous portion finishes — reading it after an await has already yielded control back to the event loop is unsafe, exactly the kind of thing that works in a quick manual test and then breaks under different timing.

Ran a full npx eslint . across the whole project afterward specifically to check for other components written before the hook existed — came back clean, but the fact it needed checking at all is the lesson: a pre-commit hook only protects code that gets committed after the hook exists. Anything already in the repo before that point needs an explicit one-time sweep, not just trust that “the hook would have caught it.”

A font that was never actually loading — a circular CSS variable from day one

Asked for “a better font” led to finding a real bug that had been there since the very first scaffold: globals.css’s @theme inline block had --font-sans: var(--font-sans) — a variable defined in terms of itself. layout.tsx was loading Geist Sans correctly, but under the CSS variable name --font-geist-sans (matching the variable: "--font-geist-sans" option passed to the Geist() font loader) — a name that --font-sans: var(--font-sans) never actually referenced. The circular reference resolves to nothing meaningful, so every font-sans utility class in the app (which is most of the text, via the base html { @apply font-sans; } rule) was silently falling back to the browser’s generic default sans-serif the whole time, not Geist at all.

Two separate things got fixed together: swapping Geist Sans/for a more distinct pairing (Inter for body, Space Grotesk for headings — different fonts for different jobs is why CardTitle/DialogTitle already had a separate font-heading utility class sitting unused), and actually wiring --font-sans/--font-heading to the real loaded variable names (--font-body/--font-heading-sans) instead of the old circular/half-connected mapping. Worth remembering: when a CSS custom property’s value references its own name, that’s not a shorthand — it’s almost certainly a copy-paste leftover from a template that was supposed to be filled in, and it’ll fail silently (fallback to inherited/default, no error) rather than loudly, which is exactly why it went unnoticed through several rounds of “fix the colors” work before someone thought to ask about the font specifically.

The “retractable sidebar” above was desktop-only — mobile had no drawer at all

The width-transition trick in the section above only ever ran md: and up. Below that breakpoint, app-shell.tsx didn’t retract the sidebar — it hid it outright (hidden md:flex on the <aside>) and rendered a second, entirely separate <NavLinks> as a horizontal scrolling strip under the header instead. That’s a legitimate mobile-nav pattern on its own, but it wasn’t what “collapsible sidebar” implied, and it had no open/close affordance at all on mobile — the desktop collapsed toggle button was itself hidden md:inline-flex.

Fix: added a proper Base UI Dialog-backed side panel (src/components/ui/sheet.tsx, sibling to the existing dialog.tsx) instead of trying to make the horizontal strip “feel like” a drawer. Positioning/animation for a side panel is different enough from a centered modal (fixed inset-y-0 left-0 ... data-open:translate-x-0 data-closed:-translate-x-full vs. the centered dialog’s translate-to-center-then-scale) that reusing DialogContent with an override would’ve fought its own default classes more than it saved. app-shell.tsx now has its own mobileNavOpen state (separate from desktop’s collapsed) and a hamburger button, md:hidden, that opens the same grouped vertical nav list desktop uses (<NavLinks grouped />) inside the Sheet, instead of a link-order-only horizontal strip. NavLinks gained an onNavigate?: () => void prop threaded onto each Link’s onClick, so clicking a link closes the drawer — Base UI’s Dialog doesn’t auto-close on an arbitrary click inside its content, only on backdrop/Escape/explicit Close, so this had to be wired by hand.

The circle switcher — a client dropdown that mutates server state, then refetches (2026-08-04)

The sidebar’s circle name became a CircleSwitcher (src/app/(app)/circle-switcher.tsx) once a user could be in several circles. It’s a small but complete example of the “client component triggers a server mutation, then the server-rendered tree updates” loop, so worth unpacking:

  • The dropdown itself reuses the same Base UI DropdownMenu primitive ProfileMenu uses (see the “Base UI, not Radix” section above). Two idioms carry over: DropdownMenuItem takes a render={<Link href=... />} prop to become a link (composition instead of wrapping), and plain items use onClick. The active circle gets a <Check> with opacity-100 vs opacity-0 — kept mounted either way so the row height/text doesn’t shift when the checkmark toggles.

  • Switching is a server action, not a client fetch. setActiveCircle lives in switch-circle-action.ts ("use server"), calls the set_active_circle RPC, and — crucially — ends with revalidatePath("/", "layout"). The "layout" scope matters: the active circle drives every page’s data and the sidebar chrome (which lives in (app)/layout.tsx), so revalidating just the page wouldn’t refresh the sidebar’s own idea of which circle is active.

  • Why router.refresh() and revalidatePath? revalidatePath invalidates the server’s cache, but the client is already showing a rendered tree. router.refresh() (from next/navigation) tells Next to refetch the current route’s server components and reconcile them into the existing client state without a full reload. The action revalidates; the refresh pulls the new render. One without the other leaves you either with stale UI or a heavier navigation.

  • useTransition for the pending state. startTransition(async () => { await setActiveCircle(id); router.refresh(); }) — wrapping the await in a transition gives an isPending flag to disable the trigger while the swap is in flight, and keeps the refresh from blocking input. This is the idiomatic pairing for “await a server action, then refresh” in an interactive control.

  • Small guard: handleSelect early-returns if you click the already-active circle — no point paying for an RPC + refresh to switch to where you already are.

The layout feeds it circles (id + name for everything you’re in, ordered oldest-first so the list is stable) and activeCircleId (resolved via the same getActiveCircleId the pages use, defaulting to the first circle if the stored pointer is stale). “Join or create a circle” sits permanently at the bottom of the menu as a Link to /onboarding, which is how you reach circle #2 now that onboarding no longer bounces existing members to the dashboard.

↑ Back to gees-arise — Learning Notes