DOMAIN:FRONTEND

OWNER: floris (Team Alpha), floor (Team Beta)
HOTFIX: tobias (Team Zulu)
UPDATED: 2026-03-24
SCOPE: all client projects, all teams

---

PURPOSE

THIS_PAGE: domain overview, ownership map, cross-references for frontend development
STACK: Next.js (App Router), React 19+, Tailwind CSS v4, shadcn/ui, Radix UI, TypeScript strict mode
TESTING: Vitest (unit/component), Playwright (E2E), axe-core (accessibility)
DESIGN_SYSTEM: shadcn/ui + Radix UI primitives, customized per client via CSS variables

---

OWNERSHIP

Area	Primary	Secondary	Notes
Frontend architecture	floris	floor	Team leads decide patterns for their team
Component library	alexander	floris, floor	Design system shared across teams
Frontend hotfix	tobias	—	Production incidents, Team Zulu
TDD / test specs	antje	—	Writes test specs before implementation
Code quality	koen	—	Linting, formatting, code review gates
E2E testing	marije, judith	—	Playwright test suites
Accessibility audit	julian	floris, floor	Julian owns domain, frontend implements
Performance audit	nessa	—	Core Web Vitals, Lighthouse CI

---

STACK_DECISIONS

WHY_NEXTJS: App Router is the production standard for React. Server Components reduce client JS. Built-in image/font optimization. Vercel deployment optional but supported.
WHY_REACT_19: Server Components stable. useActionState/useOptimistic reduce boilerplate. React Compiler eliminates manual memoization. Concurrent features for streaming.
WHY_TAILWIND_V4: CSS-first config eliminates tailwind.config.js. 5x faster builds. CSS variables as design tokens. Container queries in core. OKLCH color space.
WHY_SHADCN: Components copied into project (no dependency lock-in). Built on Radix (accessibility). Tailwind-styled. Full customization. data-slot attributes for styling.
WHY_TYPESCRIPT_STRICT: catches null/undefined bugs at compile time. Enables safe refactoring. Required for all client projects.
WHY_VITEST: fast, ESM-native, compatible with React Testing Library. Replaces Jest.
WHY_PLAYWRIGHT: cross-browser E2E. Built-in axe-core integration. Visual regression. Network mocking.

---

PROJECT_STRUCTURE

STANDARD_LAYOUT:

app/
  (auth)/           # Route group: login, register, forgot-password
  (dashboard)/      # Route group: authenticated pages
    layout.tsx       # Shared dashboard layout (server component)
    page.tsx         # Dashboard home
    settings/
      page.tsx
  api/               # Route handlers (webhooks, external APIs)
  layout.tsx         # Root layout (server component)
  loading.tsx        # Root loading state
  error.tsx          # Root error boundary
  not-found.tsx      # 404 page
components/
  ui/                # shadcn/ui components (generated, customized)
  forms/             # Form-specific components
  layouts/           # Layout components (sidebar, header, footer)
  [feature]/         # Feature-specific components
lib/
  actions/           # Server actions
  hooks/             # Custom React hooks (client-only)
  utils/             # Shared utilities (cn(), formatters, validators)
  api/               # API client functions
  schemas/           # Zod validation schemas
  types/             # TypeScript type definitions
public/              # Static assets
styles/
  globals.css        # Tailwind imports, CSS variables, theme

RULES:
- EVERY component file uses .tsx extension
- EVERY utility file uses .ts extension
- NO barrel files (index.ts re-exports) — import directly from source
- NO default exports except for page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx
- Server components are the DEFAULT — only add "use client" when needed
- Colocate tests next to source: Component.tsx + Component.test.tsx

---

CROSS_REFERENCES

NEXTJS_DEEP_DIVE: domains/frontend/nextjs-app-router.md
REACT_PATTERNS: domains/frontend/react-patterns.md
TAILWIND_SHADCN: domains/frontend/tailwind-shadcn.md
SSR_HYDRATION: domains/frontend/ssr-hydration.md
STATE_MANAGEMENT: domains/frontend/state-management.md
PERFORMANCE: domains/frontend/performance.md
ACCESSIBILITY: domains/frontend/accessibility.md
THOUGHT_LEADERS: domains/frontend/thought-leaders.md
PITFALLS: domains/frontend/pitfalls.md

SECURITY: domains/security/index.md (OWASP, CSP, XSS prevention)
PRIVACY: domains/privacy/index.md (GDPR, cookies, consent management)
ACCESSIBILITY_DOMAIN: domains/accessibility/index.md (EN 301 549, EAA compliance)
PERFORMANCE_DOMAIN: domains/performance/index.md (SLO definition, regression detection)

---

QUALITY_GATES

BEFORE_PR:
- [ ] TypeScript strict mode passes (tsc --noEmit)
- [ ] Vitest passes (vitest run)
- [ ] ESLint passes (eslint .)
- [ ] No "use client" on components that do not need interactivity
- [ ] No barrel file imports
- [ ] Accessibility: axe-core reports zero violations
- [ ] Performance: no new bundle size regression (check with next build output)
- [ ] All images use next/image
- [ ] All fonts use next/font

BEFORE_DEPLOY:
- [ ] Lighthouse CI score meets page-type budget (see performance.md)
- [ ] E2E tests pass in Playwright (Chromium + Firefox + WebKit)
- [ ] No hydration warnings in production build
- [ ] Error boundaries wrap all async data fetching
- [ ] Loading states defined for all route segments with data fetching

---

AGENT_GUIDANCE

IF task = "build new page" THEN:
1. read nextjs-app-router.md (routing, data fetching, caching)
2. read react-patterns.md (component patterns, Server Components first)
3. read tailwind-shadcn.md (styling, component selection)
4. read state-management.md (where to put state)
5. read accessibility.md (semantic HTML, ARIA, keyboard)

IF task = "fix bug" THEN:
1. read pitfalls.md (common mistakes, hydration issues)
2. read ssr-hydration.md (if hydration error)
3. read performance.md (if performance regression)

IF task = "performance optimization" THEN:
1. read performance.md (Core Web Vitals, budgets, tools)
2. read ssr-hydration.md (streaming, selective hydration)
3. read nextjs-app-router.md (caching layers)

IF task = "accessibility audit" THEN:
1. read accessibility.md (WCAG criteria, testing, ARIA patterns)
2. read domains/accessibility/index.md (compliance requirements)

IF task = "new component" THEN:
1. read tailwind-shadcn.md (check if shadcn/ui has it)
2. read react-patterns.md (compound components, composition)
3. read accessibility.md (keyboard, screen reader, focus management)

---

CONTRIBUTING

ON_NEW_KNOWLEDGE:
1. read existing domain page
2. add in appropriate section using agentic format (CHECK/IF/THEN/TOOL/etc.)
3. tag with date and source
4. IF pitfall THEN add to pitfalls.md
5. update agent LEARNINGS.md