/building-forms

name: building-forms
description: Builds form components and data collection interfaces including contact forms, registration flows, checkout processes, surveys, and settings pages. Includes 50+ input types, validation strategies, accessibility patterns (WCAG 2.1), multi-step wizards, and UX best practices. Provides decision trees from data type to component selection, validation timing guidance, and error handling patterns. Use when creating forms, collecting user input, building surveys, implementing validation, designing multi-step workflows, or ensuring form accessibility.

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: name@example.com"

**Examples:**

❌ **Bad:** "Invalid input" ✅ **Good:** "Email address must include @ symbol (e.g., name@example.com)"

❌ **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
• Ac