diff --git a/.claude/agents/engineering/frontend-dev.md b/.claude/agents/engineering/frontend-dev.md index 2aaab26..aa9ab49 100644 --- a/.claude/agents/engineering/frontend-dev.md +++ b/.claude/agents/engineering/frontend-dev.md @@ -19,14 +19,15 @@ You are the **frontend specialist**. The tech-lead handed you part of a feature. 1. Read `CLAUDE.md`, `fofafu_vault/protocols/dispatch.md`, your role file, the feature file. 2. Spec or implement the frontend slice the tech-lead assigned: - **Phase 1**: write a Frontend Spec section listing pages, components, queries, stores, forms with Zod schemas. - - **Phase 3 onward**: write actual code under `frontend/src/`. Follow the global rules in `~/.claude/rules.md`: + - **Phase 3 onward**: if the change is visually observable (UI/layout/styling), capture `docs/screenshots//before.png` against the CURRENT component FIRST, before touching any code — much simpler than reconstructing the old version from git history afterward. Then write actual code under `frontend/src/`. Follow the global rules in `~/.claude/rules.md`: - One component per file (PascalCase). - Co-locate component + hook + types + tests in same folder. - Functional components only — no `React.FC`. - Tailwind only — no inline styles, no CSS modules. - `cn()` for conditional classes. -3. Append a log line: `- HH:MM #team/eng/frontend [[features/]] — ` -4. Return: +3. If you captured a `before.png` in step 2, capture `after.png` now against the finished component (same viewport/demo state as `before.png`) per `fofafu_vault/standards/engineering-standards.md`'s convention, commit both, and note in your `### Frontend` subsection whether you captured them live or couldn't (say why — don't skip silently). +4. Append a log line: `- HH:MM #team/eng/frontend [[features/]] — ` +5. Return: ``` role: frontend-dev deliverable: diff --git a/CLAUDE.md b/CLAUDE.md index 5a2dd25..886e12e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,6 +95,7 @@ Only the dispatcher writes the `status` field on a feature file. Leads can reque - **Commit convention**: Conventional Commits (`feat(area): …`, `fix:`, `chore:`, `vault:` for vault-only changes). - **Branch naming**: `feat/`, `fix/`, `vault/`. - **No TODOs without a feature file** — if it's worth a TODO, it's worth a feature file. +- **Visual changes need before/after screenshots.** Any PR touching UI/layout/styling gets `docs/screenshots//{before,after}.png` committed to the branch and linked in the PR body — see `fofafu_vault/standards/engineering-standards.md` for the exact convention. This applies whether or not the work went through a formal `/dispatch`. - **All work flows through the dispatcher.** If you find yourself doing work for a human without a feature file, stop and `/new-feature` first. ## When you (Claude or a subagent) are activated diff --git a/docs/screenshots/header-nav-redesign/after.png b/docs/screenshots/header-nav-redesign/after.png new file mode 100644 index 0000000..ed6a5d4 Binary files /dev/null and b/docs/screenshots/header-nav-redesign/after.png differ diff --git a/docs/screenshots/header-nav-redesign/before.png b/docs/screenshots/header-nav-redesign/before.png new file mode 100644 index 0000000..2608a43 Binary files /dev/null and b/docs/screenshots/header-nav-redesign/before.png differ diff --git a/fofafu_vault/features/auth-user-name-semantics.md b/fofafu_vault/features/auth-user-name-semantics.md new file mode 100644 index 0000000..c436f6d --- /dev/null +++ b/fofafu_vault/features/auth-user-name-semantics.md @@ -0,0 +1,74 @@ +--- +slug: auth-user-name-semantics +title: Auth User Name Semantics +owner: engineering +collaborators: [] +status: drafting +priority: P2 +created: 2026-08-22 +target: null +links: + kanban: "[[kanban/engineering]]" + designs: null +--- + +# Auth User Name Semantics + +## Problem + +[[features/header-nav-redesign]] made a pre-existing ambiguity newly visible: `AuthUser.name` (and by extension `user.name` everywhere in the frontend) is populated with household/family-style display names ("The Anderson Family", "The Brooks Family", ...) rather than a person's given name. This was silently fine while `user.name` was always rendered in full; the redesign's new avatar+name chip was speced assuming a personal first name existed (`firstName(user.name)`), which broke visibly (the chip read "The" for every account) until reverted to show the full name instead. Three specialists (frontend-dev, qa-engineer, e2e-test-writer) independently flagged this as a real product/data-model question during that feature's build, not just a one-off bug. + +## Acceptance criteria + +- [ ] A product decision is made and documented: is `AuthUser.name` meant to be a household name, a person's name, or does the schema need a separate field for each? +- [ ] If a schema/data change is warranted, a migration + DTO update ships +- [ ] Every frontend surface that currently assumes `user.name` is a person's first name (search for `firstName(` / similar first-token-extraction helpers) is audited against the decision + +## Out of scope + +- Re-touching `frontend/src/components/Navbar.tsx`'s current behavior (already fixed to show the full name) unless the product decision above requires a further change there too + +## Open questions + +- Is this actually worth a schema change, or should the product simply commit to "household name, always shown in full" as the intended behavior, and this ticket just documents that decision? (product/dispatcher call) + + + +## Engineering — Acceptance + +### Backend +*(filled by backend-dev)* + +### Frontend +*(filled by frontend-dev)* + +### Test plan +*(filled by qa-engineer)* + +### E2E coverage +*(filled by e2e-test-writer; "No E2E coverage" if the feature is backend-only)* + +### Code review +*(filled by code-reviewer; populated during building → review, not at speccing time)* + +## Design — Spec + +### Visual +*(filled by ui-designer)* + +### Microcopy +*(filled by ux-writer)* + +### Accessibility +*(filled by a11y-auditor)* + +## Marketing — Spec + +### Launch copy +*(filled by content-writer)* + +### SEO +*(filled by seo-specialist)* + +### Growth +*(filled by growth-analyst)* diff --git a/fofafu_vault/features/header-nav-redesign.md b/fofafu_vault/features/header-nav-redesign.md new file mode 100644 index 0000000..74c9f11 --- /dev/null +++ b/fofafu_vault/features/header-nav-redesign.md @@ -0,0 +1,395 @@ +--- +slug: header-nav-redesign +title: Header Nav Redesign +owner: engineering +collaborators: [] +status: review +priority: P2 +created: 2026-08-20 +target: null +links: + kanban: "[[kanban/engineering]]" + designs: null +--- + +# Header Nav Redesign + +## Problem + +Today's desktop `Navbar` (`frontend/src/components/Navbar.tsx`) renders icon **and** text for all 5 links (Home, Family, Messages, Community, Playdates), plus a busy right-hand cluster (full name, city/state, an outlined "Sign out" button). The user asked for a more sophisticated header and to drop redundant text like "Home"/"Messages" — the icon already says it. + +Three directions were mocked as a Claude Design canvas (https://claude.ai/code/artifact/d6c2f65b-7e62-4f20-8c5d-dc611745b6a1) and presented to the user: a quiet icon-only rail, a grouped pill track, and a centered masthead. **The user picked the grouped pill track ("Option B").** + +### Reference spec (Option B, from the approved mock) + +- Nav icons (Home, Family, Messages, Community, Playdates) move from individual `icon + label` pills into one **track container**: `bg-surface-warm`, `border-radius: 9999px` (pill), `padding: 4px`, `gap: 2px`, flex row. +- Each icon becomes a `44×44` circular button (`border-radius: 9999px`) inside the track — hit target stays ≥44px even though the visible icon is ~20px. +- Active page = the icon's own button filled solid `brand-primary` with a white icon ("puck"), replacing today's `bg-surface-warm text-brand-primary` treatment. +- Every icon-only link keeps its current `aria-label` text (unchanged wording) plus a small hover/focus tooltip (mock uses `JetBrains Mono`, 11px, `ink-lead` bg / white text) so sighted mouse users aren't left guessing. +- Unread badge on Messages is unchanged in behavior/copy (`"{label}, {n} unread"`), just repositioned to sit on the smaller circular button. +- Header bottom border goes from today's `3px solid brand-primary` to `2px solid brand-primary` — quieter, still branded. +- Right-hand cluster (name + city/state text + outlined Sign out button) collapses into **one** avatar-and-first-name chip (avatar: 36px circle, `brand-primary` bg, white initial; name: 14px/600/`ink-lead`); the chip is one pill button (`border-radius: 9999px`, hover `bg-surface-warm`). +- No new color tokens — reuses `surface.warm`, `surface.card`, `brand.primary`, `ink.lead`, `ink.muted`, `feedback.error` exactly as already defined in `fofafu_vault/standards/design-system.md` / `tailwind.config.js`. + +## Acceptance criteria + +- [ ] Desktop nav renders Home/Family/Messages/Community/Playdates as icon-only links inside one pill-shaped track (replaces the current row of individual icon+label pills). +- [ ] The active page's icon sits on a filled `brand-primary` circular "puck" (white icon), not today's `surface-warm` background treatment. +- [ ] Every icon-only nav link keeps an accessible name via `aria-label` (same wording as today's visible label) and gets a visible hover/focus tooltip — removing the text must not remove the information. +- [ ] Unread-messages badge still renders on the Messages icon with the same `aria-label` pattern as today ("Messages, N unread"). +- [ ] Right-hand cluster (name + city/state + outlined "Sign out" button) collapses into a single avatar + first-name chip; sign-out remains reachable from whatever the chip opens. +- [ ] Header's bottom border changes from `3px solid brand-primary` to `2px solid brand-primary`. +- [ ] All interactive controls have visible `:focus-visible` states and correct roles/`aria-current` (keyboard and screen-reader parity with today, not a regression). +- [ ] `Navbar.test.tsx` updated to match the new structure; full frontend suite and `tsc` stay green. + +## Out of scope + +- The mobile bottom tab bar (`aria-label="Mobile navigation"`) — bottom tab bars conventionally keep labels; this redesign is desktop-header-only. +- Designing a full account menu — implement the minimum needed to relocate "Sign out" behind the new avatar chip (frontend-dev's call whether that's a real dropdown or a simpler reveal; note the choice in the Frontend subsection). +- No backend/API changes — this is purely a frontend component restyle. +- Changing which 5 destinations are in the nav, their order, or routes. +- New design tokens — reuse the existing palette; if something genuinely new is needed, ui-designer proposes it here for design-lead to promote into `design-system.md`, not invented silently in code. + +## Open questions + +- Is a real dropdown menu for the avatar chip in scope for v1, or is relocating the existing "Sign out" control under/behind the chip enough? (frontend-dev, note your call) +- The mock's hover tooltip uses `JetBrains Mono` per the design system's "mono = taxonomy" principle — confirm as the tooltip convention, or prefer body font? (ui-designer) + + + +## Engineering — Acceptance + +### Backend +*(filled by backend-dev)* + +### Frontend + +Implemented in place in `frontend/src/components/Navbar.tsx` (evolved, not rewritten — same file, same `NAV_LINKS` order/routes, mobile `