forms

Forms — Form Architecture

Activate When

• User invokes /godmode:forms
• User says "form validation", "multi-step form", "wizard"
• When building any form beyond a simple single input
• When handling file uploads or auditing form a11y

Workflow

Step 1: Assess Form Requirements

# Detect form libraries
grep -l "react-hook-form\|formik\|@hookform" \
  package.json 2>/dev/null

# Detect validation libraries
grep -l "zod\|yup\|joi\|superstruct" \
  package.json 2>/dev/null

# Count existing form components
find src/ -name "*form*" -o -name "*Form*" \
  2>/dev/null | wc -l

FORM REQUIREMENTS:
Purpose: <registration/checkout/settings/survey>
Framework: <React/Vue/Angular/Svelte>
Fields: <N> total
Multi-step: YES/NO (<N> steps)
File uploads: YES/NO (<types, max size>)
Async validation: YES/NO (uniqueness checks)

IF fields > 5: use React Hook Form (not useState)
IF multi-step: persist state in sessionStorage
IF file uploads: validate MIME, size, count client-side

Step 2: Form State Management

DECISION MATRIX:
| Criterion     | RHF    | Formik | Native |
|--------------|--------|--------|--------|
| Re-renders   | Min    | Freq   | Min    |
| Bundle size  | ~9KB   | ~15KB  | 0KB    |
| TypeScript   | Excl.  | Good   | Manual |
| Complex forms| Excl.  | Good   | Verbose|

IF fields <= 3 AND no validation: native useState OK
IF fields > 3 OR has validation: React Hook Form
IF existing Formik codebase: keep Formik

Step 3: Validation Patterns

VALIDATION TIMING:
  On blur (first visit): show after user leaves field
  On change (after error): re-validate immediately
  On submit: validate all, focus first error
  Never on mount: no errors before interaction

CLIENT + SERVER SHARED SCHEMA (Zod):
  Single schema shared between client and server
  Client: fast UX feedback
  Server: security (never trust client)

ASYNC VALIDATION:
  Debounce: 500ms minimum
  Show loading indicator during check
  Cancel previous request on new input

THRESHOLDS:
  Debounce delay: 300-500ms for async validation
  Max file size: 10MB default (configurable)
  Max file count: 10 per upload field
  Form submission timeout: 30 seconds