Filetree Example

Complete file-by-file breakdown of the Cloud Architect Profile Form. Every file needed for a working multi-step form inside Next.js App Router with React 19 server actions, BDD-aligned validation, upload protection, pending UX, and Playwright-ready test hooks.

The Filetree

cloud-architect-profile/
├── features/                              ← BDD Spec
│   ├── profile-form/
│   │   ├── 01-purpose.feature
│   │   ├── 02-field-types.feature
│   │   ├── 03-multi-step.feature
│   │   ├── 04-validation.feature
│   │   ├── 05-submission.feature
│   │   ├── 06-ui-ux.feature
│   │   ├── 07-accessibility.feature
│   │   ├── 08-file-uploads.feature
│   │   ├── 09-type-safety.feature
│   │   └── 10-tech-stack.feature
│   └── step-definitions/
│       ├── form-steps.ts
│       └── upload-steps.ts
├── lib/
│   ├── schemas/
│   │   └── architect-profile.ts           ← Validation Rules (shared zod)
│   └── actions/
│       └── create-profile.ts              ← Submission Logic (server action)
├── stores/
│   └── profile-form-store.ts              ← Step Logic (zustand)
├── components/
│   └── profile-form/
│       ├── profile-form-provider.tsx       ← Form UI (react-hook-form root)
│       ├── profile-form-wizard.tsx         ← Stepper Control (step router)
│       ├── step-indicator.tsx              ← Stepper Control (progress bar)
│       ├── step-navigation.tsx             ← Stepper Control (Back/Next)
│       ├── step-announcer.tsx              ← Accessibility (screen reader)
│       ├── auto-focus-step.tsx             ← Accessibility (focus management)
│       ├── accessible-field.tsx            ← Form UI (reusable field)
│       ├── personal-info-step.tsx          ← Form UI (step 1)
│       ├── experience-step.tsx             ← Form UI (step 2)
│       ├── job-history-step.tsx            ← Form UI (step 3, dynamic fields)
│       ├── skills-step.tsx                 ← Form UI (step 4)
│       ├── uploads-step.tsx                ← File Upload (step 5 layout)
│       ├── file-upload.tsx                 ← File Upload (drag/drop/preview)
│       └── submit-step.tsx                 ← Submission Logic (review + useActionState)
├── app/
│   └── profile/
│       └── create/
│           └── page.tsx                   ← Page entry point
└── e2e/
    └── profile-form.spec.ts               ← Playwright E2E tests

Where Each Responsibility Lives

File-by-File Code

1. BDD Spec -- features/profile-form/04-validation.feature

The Gherkin files are the source of truth. Every validation rule, UI behavior, and error message originates here. Developers implement code to satisfy these scenarios.

# features/profile-form/04-validation.feature
Feature: Profile Form Validation
 
  Background:
    Given the architect is logged in
    And they navigate to "/profile/create"
 
  Scenario: Required fields show errors when empty
    Given the architect is on step 1 "Personal Info"
    And they have not filled in any fields
    When they click "Next"
    Then they should see 

Key code points:

• Background runs before every scenario — sets up a logged-in user on the create page
• Each Scenario maps to exactly one test case — the title describes the expected behavior
• Given / When / Then steps read like plain English so non-developers can review acceptance criteria
• Error message strings (e.g., "Full name is required") must match the zod schema messages exactly
• The .refine() scenario (end date after start date) shows cross-field validation in Gherkin form
• File upload scenarios test both size limits and MIME type rejection as separate cases

2. Validation Rules -- lib/schemas/architect-profile.ts

The single source of truth for all validation. Every zod error message matches a Gherkin Then they should see "..." exactly. Imported by the client (zodResolver) and the server action (safeParse).

// lib/schemas/architect-profile.ts
import { z } from "zod";
 
// ── Shared constants ───────────────────────────────────
const ACCEPTED_IMAGE_TYPES = ["image/jpeg", "image/png", "image/webp"];
const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
const MAX_DIAGRAM_COUNT

Key code points:

• imageFileSchema is a reusable zod refinement — validates both size (5MB) and MIME type, shared by all upload fields
• Each step has its own exported schema (personalInfoSchema, experienceSchema, etc.) so trigger() can validate one step at a time
• .refine() on jobEntrySchema handles cross-field validation (end date > start date) with a custom path targeting the specific field
• .or(z.literal("")) on linkedinUrl allows the field to be left empty while still validating format when filled
• STEP_SCHEMAS maps step numbers to their schema — used by StepNavigation to validate only the current step's fields
• architectProfileSchema merges all step schemas into one — used by zodResolver (client) and safeParse (server) for full-form validation
• z.infer<typeof ...> generates TypeScript types from each schema — single source of truth for both validation and types

3. Step Logic -- stores/profile-form-store.ts

Zustand store owns the step state machine. Knows which step is active, which are completed, and whether navigation is allowed. Decoupled from form data (react-hook-form owns that).

// stores/profile-form-store.ts
import { create } from "zustand";
 
export type StepStatus = "upcoming" | "current" | "completed";
 
export const STEPS = [
  { id: 1, label: "Personal Info" },
  { id: 2, label: 

Key code points:

• create<ProfileFormState>() defines a typed zustand store — state + actions in one object
• completedSteps uses a Set<number> for O(1) lookup of whether a step is done
• goToNext() clones the Set before mutating (new Set(state.completedSteps)) — zustand requires immutable updates
• goToPrevious() does not mark the current step as completed — going back is non-destructive
• canNavigateTo() enforces linear wizard flow: you can revisit completed steps or advance one step ahead, but not skip
• getStepStatus() returns "current" | "completed" | "upcoming" — drives the visual state of StepIndicator
• reset() clears all progress — used after successful submission or when the user wants to start over
• The store is decoupled from form data — zustand owns navigation state, react-hook-form owns field values

4. Submission Logic -- lib/actions/create-profile.ts

Server action receives FormData, validates server-side with the same zod schema, validates uploaded files independently, persists data, and redirects. The two-argument signature (prevState, formData) is required by useActionState.

// lib/actions/create-profile.ts
"use server";
 
import { z } from "zod";
import { redirect } from "next/navigation";
import { architectProfileSchema } from "@/lib/schemas/architect-profile";
 
// Server-only file schema -- stricter, checks actual MIME
const serverFileSchema = z
  .instanceof(File)

Key code points:

• "use server" marks this as a server action — it runs on the server, never shipped to the client bundle
• serverFileSchema duplicates file validation server-side — never trust client-only checks (users can bypass the browser)
• (prevState, formData) two-argument signature is required by useActionState — prevState carries the previous return value
• ProfileActionState return type has fieldErrors: Record<string, string> — the submit step maps these back to react-hook-form and navigates to the correct step
• .omit({ profilePhoto: true, ... }) strips file fields from the text schema — files are validated separately since safeParse can't handle File objects from FormData the same way
• formData.getAll("certifications") retrieves multiple values for the same form field name — used for array fields (certifications, platforms, specialties)
• redirect() throws internally in Next.js — the catch block must re-throw NEXT_REDIRECT or the redirect silently fails
• Steps 1-6 are numbered comments — the action follows a strict pipeline: parse → validate text → validate files → check duplicates → upload → create record → redirect

5. Form UI Root -- components/profile-form/profile-form-provider.tsx

Creates the single useForm instance shared across all steps. The zodResolver connects zod validation to react-hook-form. mode: "onBlur" gives real-time feedback when the user tabs away from a field.

// components/profile-form/profile-form-provider.tsx
"use client";
 
import { useForm, FormProvider } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import {
  architectProfileSchema,
  type ArchitectProfile,
} from "@/lib/schemas/architect-profile";
 
const defaultValues: Partial

Key code points:

• useForm<ArchitectProfile>() creates a single form instance typed to the full schema — shared across all steps via context
• zodResolver(architectProfileSchema) connects zod validation to react-hook-form — validation errors auto-populate formState.errors
• mode: "onBlur" validates fields when the user tabs away — gives real-time feedback without interrupting typing
• FormProvider wraps all children — any nested component can call useFormContext() to access form state without prop drilling
• defaultValues seeds the form with empty/zero values — prevents uncontrolled-to-controlled input warnings

6. Stepper Control -- components/profile-form/profile-form-wizard.tsx

Routes to the correct step component based on zustand state. Wraps the active step in accessibility helpers (screen reader announcer and auto-focus).

// components/profile-form/profile-form-wizard.tsx
"use client";
 
import { useProfileFormStore } from "@/stores/profile-form-store";
import { StepIndicator } from "./step-indicator";
import { StepNavigation } from "./step-navigation";
import { StepAnnouncer } from "./step-announcer";
import { AutoFocusStep } from "./auto-focus-step"

Key code points:

• STEP_COMPONENTS is a Record<number, React.ComponentType> lookup — maps step number to the component to render
• useProfileFormStore() reads currentStep from zustand — the wizard re-renders when the step changes
• StepIndicator + StepAnnouncer + AutoFocusStep + StepNavigation wrap the active step — separation of concerns between progress UI, accessibility, and navigation
• data-testid="profile-form-wizard" provides a Playwright hook for the wizard container

7. Stepper Control -- components/profile-form/step-indicator.tsx

The progress bar. Shows checkmarks for completed steps, highlights the current step, and disables future steps. Each step button has ARIA labels for screen readers.

// components/profile-form/step-indicator.tsx
"use client";
 
import { cn } from "@/lib/utils";
import { Check } from "lucide-react";
import { STEPS, useProfileFormStore } from "@/stores/profile-form-store";
 
export function StepIndicator() {
  const { currentStep, getStepStatus

Key code points:

• <nav aria-label="Form progress"> makes the step bar a landmark for screen readers
• <p className="sr-only"> announces "Step X of Y" — visible only to assistive technology
• aria-current="step" on the active button tells screen readers which step the user is on
• aria-label on each button includes the step number, label, and completion status (e.g., "Step 1: Personal Info (completed)")
• data-status={status} attribute enables both Playwright assertions (toHaveAttribute) and CSS styling
• canNavigateTo(step.id) disables forward steps — prevents skipping ahead in the wizard
• Completed steps show a <Check> icon with aria-hidden="true" — decorative, the aria-label already conveys status
• Connector lines (h-px w-8) between steps change color based on completion — visual progress indicator

8. Stepper Control -- components/profile-form/step-navigation.tsx

Back/Next/Submit buttons. "Next" validates the current step's fields via trigger() before advancing. The step-to-field mapping ensures only the active step's fields are checked.

// components/profile-form/step-navigation.tsx
"use client";
 
import { useFormContext } from "react-hook-form";
import { Button } from "@/components/ui/button";
import { useProfileFormStore, TOTAL_STEPS } from "@/stores/profile-form-store";
import type { ArchitectProfile } from "@/lib/schemas/architect-profile";
 
const STEP_FIELDS

Key code points:

• STEP_FIELDS maps each step number to its field names — trigger(fields) validates only the current step, not the entire form
• handleNext is async because trigger() returns a Promise<boolean> — it runs zod validation on just the listed fields
• goToNext() only fires if validation passes — the form cannot advance with errors
• On the last step, the button changes from type="button" (Next) to type="submit" (Submit Profile) — triggers the server action
• <div /> placeholder when isFirstStep keeps the flex layout aligned — Back button space is preserved

9. Form UI -- components/profile-form/accessible-field.tsx

Reusable field wrapper that wires up aria-required, aria-invalid, aria-describedby, and role="alert" error messages. Used by every step component.

// components/profile-form/accessible-field.tsx
"use client";
 
import { useFormContext } from "react-hook-form";
import { Label } from "@/components/ui/label";
import { Input } from "@/components/ui/input";
import type { ArchitectProfile } from "@/lib/schemas/architect-profile";
import type { HTMLInputTypeAttribute } 

Key code points:

• useFormContext<ArchitectProfile>() accesses the shared form — no props needed, the provider handles it
• register(name) connects the input to react-hook-form — handles onChange, onBlur, ref, and value
• aria-required={required} tells screen readers the field is mandatory
• aria-invalid={!!error} flips to true when validation fails — screen readers announce "invalid entry"
• aria-describedby={error ? errorId : undefined} links the input to its error message — screen readers read the error when the field is focused
• role="alert" on the error <p> makes it a live region — screen readers announce the error immediately when it appears
• data-testid={field-$} provides consistent Playwright selectors across all fields

10. Form UI Step 1 -- components/profile-form/personal-info-step.tsx

Uses AccessibleField for each input. Matches the Gherkin: "step 1 should render with name, email, phone, LinkedIn fields."

// components/profile-form/personal-info-step.tsx
"use client";
 
import { AccessibleField } from "./accessible-field";
 
export function PersonalInfoStep() {
  return (
    <fieldset data-testid="step-personal-info">
      <legend className="text-lg font-semibold mb-4">Personal Information</legend

Key code points:

• <fieldset> with <legend> groups related fields semantically — screen readers announce "Personal Information" when entering the group
• AccessibleField handles all ARIA wiring — each step component stays simple and declarative
• data-testid="step-personal-info" enables Playwright to assert which step is visible
• The required prop on AccessibleField adds both aria-required and the visual asterisk (*)

11. Form UI Step 2 -- components/profile-form/experience-step.tsx

Number input for years, text input for role, checkbox group for certifications, and a textarea with character counter for bio.

// components/profile-form/experience-step.tsx
"use client";
 
import { useFormContext } from "react-hook-form";
import { AccessibleField } from "./accessible-field";
import { Label } from "@/components/ui/label";
import { Textarea } from "@/components/ui/textarea";
import { Checkbox } from "@/components/ui/checkbox"

Key code points:

• watch("certifications") subscribes to the array value — re-renders the component when certifications change
• setValue("certifications", updated, { shouldValidate: true }) writes the toggled array back and triggers validation
• CERTIFICATIONS is a const array — keeps options centralized, easy to add/remove
• Textarea with aria-describedby conditionally points to either bio-error or bio-counter — screen readers get the right context
• Character counter changes color to text-destructive when over 1000 — visual warning before validation fires
• {certifications.length} selected shows a count below checkboxes — quick feedback without requiring the user to count

12. Form UI Step 3 -- components/profile-form/job-history-step.tsx

Dynamic field array with useFieldArray. Matches Gherkin: "supports repeatable entries", "Add Another Position", and "Remove" behavior.

// components/profile-form/job-history-step.tsx
"use client";
 
import { useFormContext, useFieldArray } from "react-hook-form";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Button } from "@/components/ui/button";
import { Textarea } from "@/components/ui/textarea"

Key code points:

• useFieldArray({ control, name: "jobs" }) manages the dynamic array — provides fields, append, and remove
• field.id (not index) is used as the React key — stable across additions and removals, prevents input value ghosting
• MAX_JOBS = 10 caps the array — the "Add Another Position" button hides when the limit is reached
• fields.length > 1 guards the Remove button — you can't remove the last entry (schema requires at least one)
• watch(jobs.$.isCurrent) disables the end date field when "I currently work here" is checked
• errors.jobs?.[index]?.endDate uses optional chaining for nested field array errors — the error path includes the array index
• errors.jobs?.root displays the array-level error ("Add at least one position") — separate from per-entry errors
• append({...}) adds a new blank entry with all required fields initialized — prevents uncontrolled input warnings

13. Form UI Step 4 -- components/profile-form/skills-step.tsx

Cloud platform checkboxes, specialty multi-select, and radio buttons for proficiency per platform.

// components/profile-form/skills-step.tsx
"use client";
 
import { useFormContext } from "react-hook-form";
import { Label } from "@/components/ui/label";
import { Checkbox } from "@/components/ui/checkbox";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
import type { ArchitectProfile } from

Key code points:

• togglePlatform / toggleSpecialty manually manage array state via setValue with { shouldValidate: true } — checkboxes don't use register() because they map to arrays, not individual values
• watch("cloudPlatforms") dynamically renders proficiency radio groups — only shows AWS/Azure/GCP proficiency when the platform is selected
• `${platform}Proficiency` as keyof ArchitectProfile computes the field name dynamically — e.g., selecting "aws" renders the awsProficiency radio group
• RadioGroup with onValueChange syncs the selected level back to the form via setValue
• PLATFORMS uses as const — TypeScript narrows the value to the literal union "aws" | "azure" | "gcp" matching the zod enum

14. File Upload -- components/profile-form/file-upload.tsx

Drag-and-drop with preview thumbnails, client-side type/size validation, and a remove button per file. Uses useController to sync files into react-hook-form state.

// components/profile-form/file-upload.tsx
"use client";
 
import { useCallback, useState, useRef } from "react";
import { useFormContext, useController } from "react-hook-form";
import { Button } from "@/components/ui/button";
import { X, Upload } from "lucide-react";
import { cn } from "@/lib/utils"

Key code points:

• useController({ control, name }) syncs file state with react-hook-form — unlike register(), it works with non-native inputs (drag/drop zones)
• validateFile runs client-side checks (MIME type, size, max count) before adding files — fast feedback without a server round-trip
• URL.createObjectURL(file) creates preview thumbnails — each URL is tracked in previews state for cleanup
• URL.revokeObjectURL(p.url) in removeFile prevents memory leaks — every created URL must be revoked when no longer needed
• isDragging state toggles border/background styling on drag-over — visual cue that the drop zone is active
• isMaxReached disables the drop zone and file input — prevents exceeding the maxFiles limit
• role="button" + tabIndex={0} + onKeyDown makes the drop zone keyboard-accessible — Enter/Space triggers the file picker
• The hidden <input type="file"> with className="sr-only" is the actual file input — the visible drop zone delegates clicks to it via inputRef
• Single vs. multiple mode: field.onChange(validFiles[0]) replaces for single, [...files, ...validFiles] appends for multiple

15. File Upload Layout -- components/profile-form/uploads-step.tsx

Composes three FileUpload instances: single photo, multiple diagrams, multiple screenshots.

// components/profile-form/uploads-step.tsx
"use client";
 
import { FileUpload } from "./file-upload";
 
export function UploadsStep() {
  return (
    <fieldset data-testid="step-uploads">
      <legend className="text-lg font-semibold mb-4">Upload Files</legend

Key code points:

• Composes three FileUpload instances with different configs — single (profile photo) vs. multiple (diagrams, screenshots)
• maxFiles={10} matches the zod schema's MAX_DIAGRAM_COUNT — client and server limits stay in sync

16. Submission UX -- components/profile-form/submit-step.tsx

Bridges react-hook-form values to the server action via FormData. Uses useActionState for pending/error state. Maps server field errors back to the correct step.

// components/profile-form/submit-step.tsx
"use client";
 
import { useActionState, useEffect } from "react";
import { useFormContext } from "react-hook-form";
import { Button } from "@/components/ui/button";
import { Loader2 } from "lucide-react";
import {
  createProfile,
  type

Key code points:

• useActionState(createProfile, initialState) returns [state, formAction, isPending] — bridges the server action to React's pending UI
• FIELD_TO_STEP maps field names to step numbers — when the server returns a field error, the UI navigates the user back to the correct step
• The first useEffect iterates state.fieldErrors and calls setError() for each — maps server validation errors back into react-hook-form so they display inline
• goToStep(targetStep) auto-navigates to the step containing the first error — the user doesn't have to manually find which step failed
• handleSubmit manually builds FormData from getValues() — bridges react-hook-form's state to the server action's expected FormData input
• formData.append() (not set) is used for array fields — certifications, platforms, specialties, and multiple file uploads
• JSON.stringify(values.jobs) serializes the job array — complex nested objects can't be sent as individual FormData entries
• isPending disables the submit button and shows a Loader2 spinner — prevents double submission
• ReviewCard component renders a summary card per step with an "Edit" button — lets the user jump back to any step before submitting

17. Accessibility -- components/profile-form/step-announcer.tsx

Invisible live region that announces step changes to screen readers.

// components/profile-form/step-announcer.tsx
"use client";
 
import { useEffect, useRef } from "react";
import { STEPS, useProfileFormStore } from "@/stores/profile-form-store";
 
export function StepAnnouncer() {
  const { currentStep } = useProfileFormStore();
  const announcerRef =

Key code points:

• role="status" + aria-live="polite" creates a live region — screen readers announce content changes without interrupting the current reading
• aria-atomic="true" ensures the entire announcement is read, not just the changed text
• className="sr-only" hides the div visually — it exists only for assistive technology
• previousStep ref prevents re-announcing when the component re-renders without a step change
• announcerRef.current.textContent = ... updates the text imperatively — React state changes would cause unnecessary re-renders

18. Accessibility -- components/profile-form/auto-focus-step.tsx

Moves focus to the first input when the step changes. Ensures keyboard users land in the right place.

// components/profile-form/auto-focus-step.tsx
"use client";
 
import { useEffect, useRef } from "react";
import { useProfileFormStore } from "@/stores/profile-form-store";
 
export function AutoFocusStep({ children }: { children: React.ReactNode }) {
  const

Key code points:

• querySelector with a complex selector finds the first focusable, non-hidden, non-disabled input — works for text inputs, selects, and textareas
• useEffect depends on currentStep — fires every time the step changes, moving focus to the new step's first field
• containerRef wraps the step content — scopes the query to only the current step's DOM, not the entire page

19. Page Entry -- app/profile/create/page.tsx

Server Component page that wraps the client-side form in the provider. This is where App Router meets the form.

// app/profile/create/page.tsx
import { ProfileFormProvider } from "@/components/profile-form/profile-form-provider";
import { ProfileFormWizard } from "@/components/profile-form/profile-form-wizard";
 
export default function CreateProfilePage() {
  return (
    <main className="max-w-2xl mx-auto py-10 px-4">
      <h1 className

Key code points:

• This is a Server Component (no "use client") — it renders on the server and sends HTML to the client
• ProfileFormProvider wraps ProfileFormWizard — the provider creates the form context, the wizard consumes it
• The page is a thin shell — all logic lives in the components, the page just composes them
• The route /profile/create maps to app/profile/create/page.tsx — Next.js App Router file-based routing

20. Playwright E2E -- e2e/profile-form.spec.ts

End-to-end tests that map directly to Gherkin scenarios. Uses the data-testid attributes added to every component.

// e2e/profile-form.spec.ts
import { test, expect, type Page } from "@playwright/test";
import path from "node:path";
 
const BASE_URL = "http://localhost:3000/profile/create";
 
// ── Helpers ────────────────────────────────────────────
async function fillStep1(page: Page) {

Key code points:

• Helper functions (fillStep1, fillStep2, etc.) mirror the Gherkin Given steps — reusable setup for each test
• test.describe groups map to Gherkin Feature names — "Multi-Step Navigation", "Validation", "File Uploads", etc.
• test.beforeEach navigates to the page — matches the Gherkin Background block
• getByTestId() selectors target data-testid attributes — decoupled from CSS classes or text content
• toHaveAttribute("data-status", "completed") asserts step indicator state — tests the same attribute the CSS uses for styling
• toHaveValue("Jane Doe") after navigating back verifies data persistence — matches the Gherkin scenario "navigating back preserves data"
• setInputFiles() with a Buffer.alloc(6 * 1024 * 1024) creates a synthetic oversized file — no real file needed for the rejection test
• fillStep1 → clickNext → fillStep2 → clickNext → ... chains in the upload test navigate to step 5 — each step must pass validation before advancing
• toBeVisible() assertions on error messages match Gherkin Then they should see "..." — the test verifies the exact user-visible error string
• Accessibility tests verify aria-required, aria-invalid, and aria-current — ensures the ARIA contracts documented in the Gherkin spec are implemented

Responsibility Flow Diagram

Gherkin Feature Files
        │
        ▼
┌──────────────────────────────┐
│   lib/schemas/               │ ← Validation Rules
│   architect-profile.ts       │   (shared zod, one source of truth)
└──────────┬───────────────────┘
           │ imported by
     ┌─────┴─────┐
     ▼           ▼
┌──────────┐ ┌─────────────────────────┐
│ Client   │ │ Server                  │ ← Dual Validation
│ zodRes.  │ │ safeParse in action     │
└────┬─────┘ └────────┬────────────────┘
     │                │
     ▼                ▼
┌──────────────┐ ┌──────────────────────┐
│ react-hook-  │ │ lib/actions/         │ ← Submission Logic
│ form + UI    │ │ create-profile.ts    │
│ components   │ │ (FormData → DB)      │
└────┬─────────┘ └───────┬──────────────┘
     │                   │
     ▼                   │
┌──────────────┐         │
│ zustand      │ ◄───────┘ ← Step Logic + Error Routing
│ step store   │   (FIELD_TO_STEP navigates to error step)
└────┬─────────┘
     │
     ▼
┌──────────────┐
│ Playwright   │ ← E2E tests verify Gherkin scenarios
│ e2e/         │   via data-testid selectors
└──────────────┘

Recipe

Quick-reference: what goes where.

Gotchas

• Missing data-testid -- Playwright tests rely on data-testid attributes. Every interactive element needs one. Add them when you create a component, not later.

• Schema file importing server modules -- lib/schemas/architect-profile.ts is shared between client and server. It must not import anything from "use server" files, next/headers, or database clients.

• useFieldArray index drift -- when you remove a job entry, all subsequent indexes shift. Use field.id (from useFieldArray) as the React key, not the array index.

• File previews not cleaned up -- every URL.createObjectURL must have a revokeObjectURL when the file is removed. The FileUpload component handles this, but if you build custom upload UI, track your URLs.

• redirect() in server actions -- Next.js redirect() throws an internal error. Your try/catch in the server action must re-throw it, or the redirect silently fails.

• Playwright file upload -- use page.locator('input[type=file]').setInputFiles() with a real file path or a Buffer. The visual drop zone is not a real file input, so target the hidden <input> inside it.

Alternatives

Related

• Gherkin Form Decision Checklist -- the 10-question checklist that defines WHAT to build
• Gherkin to Code -- how each Gherkin scenario maps to code patterns
• Testing Forms -- unit testing forms with Testing Library
• Playwright Patterns -- Playwright best practices
• Forms & Validation -- react-hook-form and zod deep dives