Form System Skill

Purpose

This skill enforces the Head Shakers form system conventions automatically during form development. It ensures consistent patterns for form hooks, field components, focus management, validation, server action integration, and accessibility.

Activation

This skill activates when:

• Creating forms with useAppForm hook
• Using field components (TextField, TextareaField, SelectField, SwitchField, CheckboxField, ComboboxField, TagField)
• Implementing focus management with withFocusManagement
• Setting up form validation with Zod schemas
• Creating custom form dialogs or form-based features
• Using form.AppField for field rendering
• Using form.SubmitButton or form.AppForm wrappers
• Using useStore from @tanstack/react-form for form value access
• Using formOptions from @tanstack/form-core for reusable form configurations
• Implementing field listeners or programmatic field operations
• Integrating forms with useServerAction hook

Workflow

1. Detect form work (imports from @/components/ui/form or useAppForm)
2. Load references/Form-System-Conventions.md
3. Generate/modify code following all conventions
4. Scan for violations of form patterns
5. Auto-fix all violations (no permission needed)
6. Report fixes applied

Key Patterns

Form Setup

• Use useAppForm hook from @/components/ui/form
• Wrap form components with withFocusManagement HOC
• Configure validation with validators: { onSubmit: zodSchema }
• Use revalidateLogic for validation timing
• Handle invalid submissions with onSubmitInvalid and focusFirstError
• Always set canSubmitWhenInvalid: true

Field Rendering

• Use form.AppField with field components (TextField, etc.)
• Each field supports label, description, isRequired, focusRef, and testId props
• Use field listeners for side effects (onChange, onBlur)

Form Submission

• Wrap form.handleSubmit() in event handler with e.preventDefault() and e.stopPropagation()
• Integrate with useServerAction hook for server actions
• Use form.SubmitButton wrapped in form.AppForm for automatic loading state

Accessing Form Values

• Use useStore from @tanstack/react-form for reactive access
• Access via useStore(form.store, (state) => state.values.fieldName)
• Never access form values directly during render

Programmatic Operations

• Use form.setFieldValue() to update field values
• Use form.validateField() to trigger validation
• Use field listeners for dependent field updates

Server Action Options

• toastMessages for loading/success/error toasts
• isDisableToast: true for background operations
• onSuccess callback for post-submission logic

References

• references/Form-System-Conventions.md - Complete form system conventions