home / skills / velcrafting / codex-skills / form-validation

form-validation skill

safe

This skill implements consistent client-side form validation and accessible error UX aligned with repo conventions to prevent invalid submissions.

npx playbooks add skill velcrafting/codex-skills --skill form-validation

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.7 KB

---
name: form-validation
description: Add input validation rules and UX patterns for forms (client-side validation, errors, submit gating) consistent with repo conventions.
metadata:
  short-description: Form validation + UX
  layer: frontend
  mode: write
  idempotent: false
---

# Skill: frontend/form-validation

## Purpose
Implement consistent form validation and error UX:
- validation rules (required, format, ranges)
- error messaging and accessibility
- submit gating (disabled states, preventing double submit)
- server error handling and mapping where applicable

---

## Inputs
- Form location (route/component)
- Fields and constraints (required/optional, format, min/max)
- Submit behavior (create/update, optimistic allowed yes/no)
- Error handling expectations (inline vs toast vs summary)
- Repo profile (preferred): `<repo>/REPO_PROFILE.json` (form library, patterns)

---

## Outputs
- Validation rules aligned with repo conventions (schema-based or imperative)
- Error UI:
  - field-level errors
  - form-level errors (submit failures)
- Submit safety:
  - disable while submitting
  - prevent duplicate submissions
- Optional: tests for validation behavior (recommended)

---

## Non-goals
- Changing backend contracts
- Implementing domain rules that must be enforced server-side (only mirror client-side)
- Redesigning the form UI

---

## Workflow
1) Identify repo form pattern:
   - native, react-hook-form, formik, custom, schema validator
2) Implement validation:
   - prefer schema validation when repo uses it
   - keep rules close to field definitions
3) Wire error UX:
   - show field error near input
   - show submit error in a consistent location
4) Ensure accessibility:
   - label associations
   - aria-describedby for error text when appropriate
5) Ensure submit safety:
   - disable submit while pending
   - guard against double submit
6) Map server errors:
   - field errors vs global errors
   - do not leak raw server messages if unsafe
7) Run validations from profile and add tests if repo expects them.

---

## Checks
- Invalid inputs prevented or clearly errored
- All interactive fields have labels and accessible error text
- Submit cannot be double-fired
- Error states are deterministic (no flicker, no stale errors)
- Typecheck/lint/tests pass if configured

---

## Failure modes
- Validation source-of-truth unclear → recommend `shared/schema-types` and mirror rules.
- Conflicting UX patterns → follow existing repo standard and document deviation.
- Server error mapping unknown → handle as global error and log for follow-up.

---

## Telemetry
Log:
- skill: `frontend/form-validation`
- fields_count
- validation_style: `schema | imperative | library`
- tests_added: `yes | no`
- files_touched
- outcome: `success | partial | blocked`

Overview

This skill adds consistent client-side form validation rules and user-friendly error UX that align with repository conventions. It covers field-level constraints, accessible error messaging, submit gating to prevent duplicate submissions, and mapping of server-side errors to the form. The goal is deterministic, testable validation behavior that mirrors but does not replace server-side rules.

How this skill works

I detect the repository's preferred form pattern (native, react-hook-form, formik, schema-based, or custom) and implement validation close to field definitions, preferring schema validation when available. Error UI is wired so field errors appear near inputs, submit errors appear in a consistent location, and accessibility attributes (labels, aria-describedby) are applied. Submit safety is enforced by disabling the submit control while pending and guarding against double submits, with optional tests added when the repo expects them.

When to use it

New or updated forms that require consistent validation and error UX
When repository conventions prescribe a specific form library or schema approach
To add accessibility-compliant error messaging to existing forms
When preventing duplicate submits or handling server-side failures on the client
When you need deterministic, testable validation behavior across agents

Best practices

Prefer schema-based validation when the repo uses shared schemas to keep a single source of truth
Keep validation rules next to field definitions to reduce drift and improve readability
Show field-level errors inline and surface submit/global errors in a consistent place
Apply accessible attributes: proper labels, aria-describedby for error text, and focus management on errors
Disable submit while pending and implement idempotency checks or client-side guards against double submit
Map server errors to field or global errors and avoid exposing raw server messages if sensitive

Example use cases

Implement required/format/min-max rules for a registration form using the repo's schema validator
Add inline errors and a submit error summary for an account settings update form
Prevent double submissions on a payment or order form by disabling the submit and showing progress
Map 422 server validation responses to specific fields while treating unknown server failures as a global error
Add unit/integration tests that assert validation rules and submit-gating behavior

FAQ

Will this replace server-side validation?

No. Client-side validation improves UX and reduces round trips but should mirror—not replace—server-side checks.

What if the repo uses multiple form patterns?

Follow the dominant repo standard. If patterns conflict, implement the standard pattern and document any deviations for follow-up.