form-accessibility

```tsx

// Accessible form field pattern

```

Critical Criteria

| Criterion | Level | Requirement | Implementation |

|-----------|-------|-------------|----------------|

| 1.3.1 Info & Relationships | A | Structure conveyed programmatically | ,

Error Message Binding

```tsx

// Pattern: aria-describedby links input to error

id="email"

aria-invalid={hasError ? "true" : "false"}

aria-describedby={hasError ? "email-error" : undefined}

/>

{hasError && (

{errorMessage}

)}

```

Multiple Descriptions

```tsx

// Pattern: Combine hint + error in aria-describedby

id="password"

aria-describedby={[

"password-hint",

hasError && "password-error"

].filter(Boolean).join(" ")}

/>

Must be at least 8 characters

{hasError && {error}}

```

Required Fields

```tsx

// Pattern: Announce required status

Name

*

{/ Visual indicator hidden from SR, aria-required announces it /}

id="name"

aria-required="true"

/>

// Alternative: Required in label (simpler)

Name (required)

```

Field Groups

```tsx

// Pattern: fieldset + legend for related fields

```

Radio/Checkbox Groups

```tsx

// Pattern: fieldset groups options, legend is the question

```

Focus on First Error

```tsx

// On form submit with errors, focus first invalid field

function handleSubmit(e: FormEvent) {

e.preventDefault();

const firstError = formRef.current?.querySelector('[aria-invalid="true"]');

if (firstError) {

(firstError as HTMLElement).focus();

return;

}

// Submit if valid

submitForm();

}

```

Focus on Step Change (Multi-step)

```tsx

// Move focus to step heading when changing steps

function goToStep(stepNumber: number) {

setCurrentStep(stepNumber);

// Wait for render, then focus

requestAnimationFrame(() => {

const heading = document.getElementById(step-${stepNumber}-heading);

heading?.focus();

});

}

// Heading must be focusable

Shipping Address

```

Skip Links

```tsx

// Allow skipping to form

Skip to form

// CSS for skip link

.skip-link {

position: absolute;

top: -40px;

left: 0;

z-index: 100;

}

.skip-link:focus {

top: 0;

}

```

Focus Trap (Modals)

```tsx

// Keep focus within modal form

function FocusTrap({ children }) {

const trapRef = useRef(null);

useEffect(() => {

const trap = trapRef.current;

if (!trap) return;

const focusableElements = trap.querySelectorAll(

'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'

);

const firstElement = focusableElements[0] as HTMLElement;

const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;

function handleKeyDown(e: KeyboardEvent) {

if (e.key !== 'Tab') return;

if (e.shiftKey && document.activeElement === firstElement) {

e.preventDefault();

lastElement.focus();

} else if (!e.shiftKey && document.activeElement === lastElement) {

e.preventDefault();

firstElement.focus();

}

}

trap.addEventListener('keydown', handleKeyDown);

firstElement?.focus();

return () => trap.removeEventListener('keydown', handleKeyDown);

}, []);

return

}

```

Error States (Colorblind-Safe)

```css

/ ❌ BAD: Color only /

.error {

border-color: red;

}

/ ✅ GOOD: Color + icon + text /

.field-error {

border-color: #dc2626;

border-width: 2px;

}

.field-error::after {

content: "";

background-image: url("data:image/svg+xml,..."); / Error icon /

}

.error-message {

color: #dc2626;

font-weight: 500;

}

.error-message::before {

content: "⚠ "; / Text indicator /

}

```

Focus Indicators

```css

/ Focus must have 3:1 contrast ratio /

input:focus {

outline: 2px solid #2563eb;

outline-offset: 2px;

}

/ For dark backgrounds /

input:focus {

outline: 2px solid #60a5fa;

outline-offset: 2px;

}

/ Never remove outline without replacement /

/ ❌ BAD /

input:focus {

outline: none;

}

/ ✅ GOOD: Custom focus style /

input:focus {

outline: none;

box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.5);

}

```

Validation States (Colorblind-Friendly)

```tsx

// Use icons + text, not just color

function ValidationIndicator({ state }: { state: 'valid' | 'invalid' | 'idle' }) {

if (state === 'idle') return null;

return (

indicator ${state}} aria-hidden="true">

{state === 'valid' && '✓'}

{state === 'invalid' && '✗'}

);

}

```

Tab Order

```tsx

// Natural tab order (no positive tabindex needed)

// ❌ BAD: Manual tab order

// ✅ GOOD: Natural DOM order

{/ tabIndex implicitly 0 /}

```

Escape Key Handling

```tsx

// Allow Escape to close dropdowns, cancel modals

function Modal({ onClose, children }) {

useEffect(() => {

function handleEscape(e: KeyboardEvent) {

if (e.key === 'Escape') {

onClose();

}

}

document.addEventListener('keydown', handleEscape);

return () => document.removeEventListener('keydown', handleEscape);

}, [onClose]);

return

}

```

Enter to Submit

```tsx

// Forms submit on Enter by default

// For buttons that shouldn't submit:

Add Item

// For preventing Enter submit on specific fields:

onKeyDown={(e) => {

if (e.key === 'Enter') {

e.preventDefault();

// Do something else

}

}}

/>

```

Error Announcements

```tsx

// Announce errors when they appear

// Or use role="alert" for immediate announcement

{hasError && (

{errorMessage}

)}

```

Loading States

```tsx

// Announce loading state

{isLoading ? (

<>

Loading...

Submitting form, please wait

) : (

'Submit'

)}

// Or use aria-busy

```

Success Messages

```tsx

// Announce successful submission

{isSuccess && (

)}

```

```css

/ Visually hidden but announced by screen readers /

.sr-only {

position: absolute;

width: 1px;

height: 1px;

padding: 0;

margin: -1px;

overflow: hidden;

clip: rect(0, 0, 0, 0);

white-space: nowrap;

border: 0;

}

/ Allow focus for skip links /

.sr-only-focusable:focus {

position: static;

width: auto;

height: auto;

overflow: visible;

clip: auto;

white-space: normal;

}

```

Automated Tools

```bash

# axe-core (recommended)

npm install @axe-core/react

# In development

import React from 'react';

import ReactDOM from 'react-dom';

import axe from '@axe-core/react';

if (process.env.NODE_ENV !== 'production') {

axe(React, ReactDOM, 1000);

}

```

Manual Testing Checklist

1. Keyboard only: Can you complete the form using only Tab, Enter, Space, and Arrow keys?
2. Screen reader: Does VoiceOver/NVDA announce labels, errors, and required status?
3. Zoom 200%: Is the form usable at 200% browser zoom?
4. High contrast: Is everything visible in Windows High Contrast mode?
5. Focus visible: Can you always see which element is focused?

Testing Script

```typescript

// Automated accessibility test

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('form is accessible', async () => {

const { container } = render();

const results = await axe(container);

expect(results).toHaveNoViolations();

});

test('error state is accessible', async () => {

const { container } = render();

// Trigger error

fireEvent.blur(screen.getByLabelText(/email/i));

const results = await axe(container);

expect(results).toHaveNoViolations();

});

```

```

form-accessibility/

├── SKILL.md

├── references/

│ ├── wcag-2.2-forms.md # Full WCAG criteria breakdown

│ └── aria-patterns.md # Complete ARIA reference

└── scripts/

├── aria-form-wrapper.tsx # Automatic ARIA binding

├── focus-manager.ts # Focus trap, error focus

├── error-announcer.ts # Live region management

└── accessibility-validator.ts # Runtime a11y checks

```

• references/wcag-2.2-forms.md — Complete WCAG 2.2 criteria for forms
• references/aria-patterns.md — Detailed ARIA implementation patterns