Imported from findmydoc-platform/website (src/app/(frontend)/AGENTS.md). Install upstream with npx skills add findmydoc-platform/website --skill (frontend). Copyright stays with the author.

Frontend App Routes (Next.js + UI)

Priorities

• P0: Correct architecture boundaries and accessibility.
• P1: Reliable, testable UI behavior.
• P2: Visual consistency and maintainable styling.

Architecture Defaults

• Next.js App Router + RSC by default.
• Use 'use client' only at interaction leaves.

Critical Rules

• Keep reusable atoms and molecules presentation-only.
• Do not place business logic or data fetching inside reusable UI components.
• Favor parent-controlled inputs (value/onValueChange, checked/onCheckedChange).
• Keep molecules router-agnostic; pass navigation callbacks as props.

Boundary Reminder

• UI components stay Payload-free.
• Follow src/AGENTS.md for canonical Payload and application API ownership, normalized props, and callback ports.

Storybook Expectations

• Keep stories isolated and deterministic.
• Use docs/frontend/mobile-ai-playbook.md when defining mobile states, viewport expectations, and responsive QA notes for route-level UI work.
• For route-level mobile work, verify the composed route directly; use Playwright or equivalent route-level runtime evidence for runtime-sensitive risks such as sticky overlap, drawers, sheets, filters, forms, or scroll containment, and use screenshots or route-level stories only as supporting evidence or for static layout checks.

Styling Protocol

• Tailwind CSS v4 + shadcn atoms (src/components/atoms).
• Keep component variants in code (CVA), not semantic global CSS classes.
• Avoid inline styles unless no other option exists.
• Use design tokens and utility composition before arbitrary values.
• Public route canvas, shared chrome, and structural page bands must use the site surface tokens (site-canvas, site-chrome, site-section, site-divider); reserve raw bg-white, bg-muted/*, and local divider colors for cards, panels, media overlays, or intentionally contrasting content sections.

Heading Rule

• Use the Heading atom for headings.
• Do not introduce raw h1-h6 in feature UI code.

Data and Validation

• Business validation belongs in Payload hooks/access logic.
• Public UI forms must suppress browser validation bubbles with the shared PublicFormValidation + FieldError pattern. Keep native control constraints in place, but expose failures inline with data-invalid, aria-invalid, and aria-describedby.
• Prefer server-side data fetching in App Router unless client reactivity is required.
• For every new or materially changed public page, route, or server-data loader, record one cache-impact decision in the plan or PR notes. Static pages need no catalog entry; public cached output must use the existing policy and planner boundary.
• Keep draft, preview, private, cookie-bound, auth-bound, and request-bound reads live. Do not add direct revalidation, Cache Components primitives, or new cache semantics without an ADR decision.
• For local verification of authenticated admin-facing routes under src/app/(frontend)/admin/**, prefer the shared Playwright session output/playwright/sessions/admin.local.json instead of redoing login in each browser run.
• If local verification of public frontend routes is blocked by Temporary Landing Mode, disable the PostHog temporary-landing-mode flag for the local host before accepting proxy-level 404 responses as route evidence. Mention the flag state in the QA note.
• For route-level mobile work, apply the canonical mobile matrix from docs/frontend/mobile-ai-playbook.md; include the additional 1280px check only when the playbook marks it as required.
• Review sticky headers, drawers, accordions, carousels, filter bars, and modal heights for touch reachability and scroll containment on small screens.
• When the route uses sticky CTAs, sticky bars, fixed navigation, drawers, sheets, dialogs, or full-height panels, apply the playbook short-height checks and name the reduced-height states you verified.
• When reporting route-level mobile verification, name the exact interaction cycles checked per viewport, for example open/use/scroll/close for mobile nav or drawers, apply/clear filters, or invalid-submit/error/fix/submit for forms.
• When shared mobile UI such as header, navigation, or sticky bars spans multiple route types, sample at least two representative routes or content densities.
• When route layout depends on real content shape, also verify at least one worst-case content state with long labels, dense CMS content, or empty/loading/error states.
• For image-heavy routes, verify composed-route image sizing and sizes assumptions at mobile widths instead of relying only on component-level checks.

Animation Stack

• Default animation tooling: GSAP + ScrollTrigger.
• Sticky layout uses native CSS (position: sticky) with top offset.
• Avoid scroll-jacking libraries.