Senior Nextjs

app/
  (marketing)/page.tsx          # grouped, no URL segment
  extract/page.tsx              # the demo UI
  extract/loading.tsx
  extract/error.tsx
  history/[id]/page.tsx
  api/                          # only for webhooks; prefer FastAPI for real API
  layout.tsx
  globals.css

Forms

• Server actions for mutations. useActionState for pending/error UI.
• React Hook Form + Zod resolver for complex validation.
• No uncontrolled forms with hand-rolled onChange.

Images / fonts / metadata

• next/image everywhere. Never <img>.
• next/font for self-hosted fonts. No CLS.
• Static metadata via export const metadata; dynamic via generateMetadata.

State

• URL is state. Use search params for filter/sort/page — they're shareable and survive refresh.
• nuqs or native useSearchParams + router.replace for URL-driven state.
• TanStack Query for server state on the client. Never fetch in useEffect.
• Zustand only for genuinely cross-cutting client state (theme, command palette).

Performance budget (enforced in CI via Lighthouse)

• LCP ≤ 2.0s on slow-4G simulated.
• CLS ≤ 0.05.
• TBT ≤ 200ms.
• Route JS bundle ≤ 150KB gzipped (excluding framework).
• next build fails if largePageDataBytes threshold exceeded.

UI states (never ship without all four)

1. Loading — skeleton with correct layout, not a spinner.
2. Empty — helpful CTA, not a blank box.
3. Error — specific message + recovery action, not "something went wrong."
4. Success — obvious, not silent.

Accessibility (see accessibility-a11y skill)

• Every interactive element keyboard-reachable.
• next-themes respects prefers-color-scheme.
• Animations respect prefers-reduced-motion.

What's banned

• getServerSideProps / getStaticProps (Pages Router — we use App Router only).
• Client-side fetches for data available on the server.
• useEffect for data fetching.
• any in component props.
• Inline styles except for dynamic CSS custom properties.