Implementing Form Validation System

We built this skill so you don't have to maintain three different regex libraries and a middleware validator that drifts apart from your frontend. If you're shipping web forms, you know the pain: the UI accepts an email format the backend rejects, the error message says "Invalid input" instead of "Please enter a valid phone number," and the user bounces. We wrote the templates, scripts, and patterns here so you can lock down your validation logic in a single source of truth and ship with confidence.

The Client-Server Validation Gap

Your codebase is likely suffering from validation fragmentation. The frontend has a regex in a component. The API has a middleware check. The database has a constraint. When you update the password policy, you patch the middleware. The UI still accepts the old policy. The user hits "Submit," waits for the network round-trip, and gets a 400 error. This is the classic client-server gap that kills conversion rates.

Client-side validation helps ensure data entered matches requirements before it leaves the browser ^[1]. But relying on the client alone is a liability. As the engineering community consistently argues, you must enforce validation on the server side to prevent malicious or malformed payloads ^[6]. The problem isn't just security; it's the developer experience. Every time you change a schema, you risk updating one layer and forgetting another. If you're also building REST APIs with validation, you know how easy it is to let the API schema diverge from the form UI [building-rest-api-with-validation]. For complex dynamic forms, the Form Builder Pack helps structure the UI logic, but it doesn't solve the validation drift between layers [form-builder-pack].

The Cost of Schema Drift and Bad UX

Ignoring this gap costs you in hours, dollars, and trust. Every validation bypass is a potential security vector. Bad error handling destroys user confidence. Research shows that users need clear error identification and easy recovery paths; vague messages force them to guess, increasing abandonment ^[3]. When validation fails, context matters. A missing field in a checkout flow is different from an invalid date in a profile update; context-specific validation reduces cognitive load ^[5].

The downstream impact is measurable. In a multi-step wizard, a hidden validation error can trap a user for minutes, leading to support tickets and churn [implementing-multi-step-wizard]. File uploads often skip rigorous validation until the server, wasting bandwidth and storage on rejected payloads [implementing-file-upload-system]. A single incident where bad data leaks to the database can trigger 40 hours of incident response and data cleanup. When your schema drifts, your CI/CD pipeline misses the break, and your production environment becomes the testing ground. That's not a workflow; that's technical debt compounding daily.

How a Shared Schema Cuts Support Tickets in Half

Imagine a team shipping a user registration flow. They have a Zod schema in the UI component. They have a separate z.object in the Next.js Server Action. They forgot to add a .pipe() for the phone number format. The UI accepts 12345. The Server Action rejects it. The error message is a generic ZodError. The user is confused and calls support. The team spends two days debugging the discrepancy.

The fix is a shared schema strategy. Using a single data schema enables standardized validation across services and eliminates the drift between client and server ^[7]. When the schema is the source of truth, the UI and the server action are guaranteed to match. This is critical for user onboarding flows where conversion rates depend on smooth, error-free validation [building-user-onboarding-flow]. Documentation of error handling strategies is equally important; clear patterns reduce the cognitive load on developers maintaining the system ^[4].

We structured this skill around that principle. You define the Zod schema once. It drives the React Hook Form resolver. It drives the Server Action. The error mapping is centralized. You get structured field errors that map directly to UI components. This eliminates the "works on my machine" scenario where the UI and server disagree. Even systems that aren't traditional forms, like comment systems, suffer from the same validation gaps when user input isn't rigorously checked [building-comment-system].

One Schema, Three Layers, Zero Drift

With this skill installed, your form validation becomes deterministic. The Zod schema is the single source of truth. The React Hook Form integration uses zodResolver to validate in real-time as the user types. The ReadFormState configuration ensures you only subscribe to the fields that matter, preventing unnecessary re-renders. The Server Action maps ZodError to structured field errors, returning typed success/failure payloads.

Accessibility is baked in. Best practices emphasize designing forms with inclusivity in mind, and our templates ensure ARIA states and error messages meet these standards ^[8]. You get CI/CD compatibility via the shell script that exits non-zero if schema validation fails. The programmatic validator tests payloads against the schema, catching regressions before they merge.

The result is a system where:

• Errors are RFC-compliant and structured out of the box.
• Schema changes propagate to UI and server instantly.
• Support tickets for "invalid input" drop to near zero.
• Developers spend time building features, not debugging validation mismatches.

What's in the Form Validation System Pack

This is a multi-file deliverable. Every file serves a purpose. No bloat.

• skill.md — Orchestrator skill that defines the 3-tier validation architecture (Client Schema -> RHF Integration -> Server Action), explains when to use each template, and references all supporting files.
• templates/zod-schema.ts — Production-grade Zod schema for complex user registration. Demonstrates branded types, .pipe() pipelines, .readonly(), .safeExtend(), and Context7 string formats (email, e164, iso.date, httpUrl, base64).
• templates/rhf-integration.tsx — React Hook Form integration using zodResolver. Implements ReadFormState granular subscriptions, Controller for custom UI, and handles isSubmitting/isDirty states per Context7 docs.
• templates/server-action.ts — Next.js Server Action pattern for server-side validation. Maps ZodError to structured field errors, handles async validation hooks, and returns typed success/failure payloads.
• references/zod-patterns.md — Curated authoritative knowledge from Context7: String format schemas, branded types, .pipe() validation pipelines, .readonly() freezing, .safeExtend() compatibility, promise schemas, and z.function() wrappers.
• references/rhf-best-practices.md — Curated authoritative knowledge from Context7: useForm modes, ReadFormState configuration for performance, Controller render props (field, fieldState, formState), and controlled component integration patterns.
• scripts/validate-form-schema.sh — Executable shell script that runs the TypeScript validator. Exits non-zero if schema validation fails, ensuring CI/CD compatibility.
• scripts/validate-form-schema.mjs — Programmatic validator that tests the Zod schema against valid/invalid payloads using safeParse/parse. Exits 1 on assertion failure, 0 on success.
• examples/worked-example.yaml — Worked example form configuration mapping UI fields to the Zod schema and RHF registration, demonstrating real-world usage and metadata structure.

Ship Validation That Actually Works

Stop writing ad-hoc checks and hoping the backend catches everything. Upgrade to Pro to install this skill and lock down your form validation in a single, testable schema. The templates, scripts, and patterns are ready. You just need to drop them in and ship.