building-forms

What this skill does

# Form Systems & Input Patterns

Build accessible, user-friendly forms with systematic component selection, validation strategies, and UX best practices.

## Purpose

Forms are the primary mechanism for user data input in web applications. This skill provides systematic guidance for:
- Selecting appropriate input types based on data requirements
- Implementing validation strategies that enhance user experience
- Ensuring WCAG 2.1 AA accessibility compliance
- Creating complex patterns (multi-step wizards, conditional fields, dynamic forms)

## When to Use This Skill

**Triggers:**
- Building contact forms, login/registration flows, checkout processes
- Implementing surveys, questionnaires, or settings pages
- Adding validation to user inputs
- Creating multi-step workflows or wizards
- Ensuring form accessibility
- Collecting structured data (addresses, credit cards, dates)

**Common Requests:**
- "Create a registration form with validation"
- "Build a multi-step checkout flow"
- "Add inline validation to email input"
- "Make this form accessible for screen readers"
- "Implement a survey with conditional questions"

## Universal Form Concepts

### Component Selection Framework

**The Golden Rule:** Data Type → Input Component → Validation Pattern

Start by identifying the data type to collect, then select the appropriate component:

**Quick Reference:**
- **Short text** (<100 chars) → Text input, Email input, Password input
- **Long text** (>100 chars) → Textarea, Rich text editor, Code editor
- **Numeric** → Number input, Currency input, Slider
- **Date/Time** → Date picker, Time picker, Date range picker
- **Boolean** → Checkbox, Toggle switch
- **Single choice** → Radio group (2-7 options), Select dropdown (>7 options), Autocomplete (>15 options)
- **Multiple choice** → Checkbox group, Multi-select, Tag input
- **File/Media** → File upload, Image upload
- **Structured** → Address input, Credit card input, Phone number input

**For detailed decision tree:** See `references/decision-tree.md`

### Validation Timing Strategies

**Recommended Default: On Blur with Progressive Enhancement**

```
Field pristine (never touched): No validation
User typing: No errors shown
On blur (field loses focus): Validate and show errors
After first error: Switch to onChange for that field
On fix: Show success immediately
```

**Validation Modes:**
1. **On Submit** - Validate when form submitted (simple forms)
2. **On Blur** - Validate when field loses focus (RECOMMENDED for most forms)
3. **On Change** - Validate as user types (password strength, availability checks)
4. **Debounced** - Validate after user stops typing (API-based validation)
5. **Progressive** - Start with on-blur, switch to on-change after first error

**For complete validation guide:** See `references/validation-concepts.md`

### Accessibility Requirements (WCAG 2.1 AA)

**Critical Accessibility Patterns:**

**Labels and Instructions:**
- Every input must have an associated `<label>` or `aria-label`
- Labels must be visible and descriptive
- Required fields clearly indicated (not by color alone)
- Never use placeholder text as label replacement
- Provide help text for complex inputs

**Keyboard Navigation:**
- Logical, sequential tab order
- All inputs keyboard accessible
- Custom components support arrow keys
- Escape key dismisses modals/popovers
- Focus visible (outline or custom indicator)

**Error Handling:**
- Errors programmatically associated with inputs (`aria-describedby`)
- Error messages clear and actionable
- Errors announced by screen readers (`aria-live`)
- Focus moves to first error on submit
- Errors not conveyed by color alone

**ARIA Attributes:**
- `aria-required="true"` for required fields
- `aria-invalid="true"` when validation fails
- `aria-describedby` linking to help/error text
- `role="group"` for related inputs
- `aria-live="polite"` for validation messages

**For complete accessibility checklist:** See `references/accessibility-forms.md`

### UX Best Practices

**Modern Form UX Principles (2024-2025):**

1. **Progressive Disclosure** - Show only essential fields initially, reveal advanced options on demand
2. **Smart Defaults** - Pre-fill known information, suggest values based on context
3. **Inline Validation with Positive Feedback** - Show green checkmark on valid input, provide helpful error messages
4. **Mobile-First** - Large touch targets (44px minimum), appropriate keyboard types
5. **Reduce Cognitive Load** - Group related fields, use clear labels, provide examples
6. **Error Prevention** - Constraints prevent invalid input, autocomplete reduces typos
7. **Autosave and Recovery** - Save draft state automatically, warn before losing data

**For detailed UX patterns:** See `references/ux-patterns.md`

### Error Message Best Practices

**Good Error Message Formula:**
1. **What's wrong** - "Email address is not valid"
2. **Why it matters** - "We need this to send your receipt"
3. **How to fix** - "Format: [email protected]"

**Examples:**

❌ **Bad:** "Invalid input"
✅ **Good:** "Email address must include @ symbol (e.g., [email protected])"

❌ **Bad:** "Error"
✅ **Good:** "Password must be at least 8 characters long"

❌ **Bad:** "Field required"
✅ **Good:** "Please enter your email address so we can send order confirmation"

**Tone Guidelines:**
- Conversational, not robotic
- Helpful, not blaming
- Specific, not generic
- Actionable, not just descriptive

## Language-Specific Implementations

This skill provides universal form concepts above, with language-specific implementations below.

### JavaScript/React (PRIMARY)

**Recommended Stack:**
- **React Hook Form** - Form state management (best performance, 8KB bundle)
- **Zod** - TypeScript-first schema validation
- **Radix UI** or **React Aria** - Accessible component primitives

**Quick Start:**
```tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';

// Define validation schema
const schema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

type FormData = z.infer<typeof schema>;

function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
    resolver: zodResolver(schema),
    mode: 'onBlur', // Validate on blur (recommended)
  });

  const onSubmit = (data: FormData) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label htmlFor="email">Email</label>
      <input id="email" {...register('email')} type="email" />
      {errors.email && <span role="alert">{errors.email.message}</span>}

      <label htmlFor="password">Password</label>
      <input id="password" {...register('password')} type="password" />
      {errors.password && <span role="alert">{errors.password.message}</span>}

      <button type="submit">Login</button>
    </form>
  );
}
```

**Detailed JavaScript/React Documentation:**
- `references/javascript/react-hook-form.md` - Complete React Hook Form guide
- `references/javascript/zod-validation.md` - Zod schema validation patterns
- `references/javascript/examples/` - Working code examples

### Python (PRIMARY)

**Recommended Stack:**
- **Pydantic** - Data validation and settings management (runtime validation, type-safe)
- **FastAPI** - Modern async web framework with automatic validation
- **WTForms** - Flask/Django form handling (when using traditional frameworks)

**Quick Start (FastAPI + Pydantic):**
```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr, Field, validator

app = FastAPI()

# Define validation schema
class LoginForm(BaseModel):
    email: EmailStr  # Validates email format
    password: str = Field(..., min_length=8, description="Password must be at least 8 characters")

    @validator('password')
    def validate_password_strength(cls, v):
        if not any(char.isdigit() for char in