# Form Accessibility

> WCAG 2.2 AA compliance for forms, ARIA patterns, focus management, keyboard navigation, and screen reader support. Use when implementing accessible forms in any framework. The compliance foundation that ensures forms work for everyone.

- **Type:** Skill
- **Install:** `agentstack add skill-bbeierle12-skill-mcp-claude-form-accessibility`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Bbeierle12](https://agentstack.voostack.com/s/bbeierle12)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Bbeierle12](https://github.com/Bbeierle12)
- **Source:** https://github.com/Bbeierle12/Skill-MCP-Claude/tree/main/skills/form-accessibility

## Install

```sh
agentstack add skill-bbeierle12-skill-mcp-claude-form-accessibility
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Form Accessibility

WCAG 2.2 AA compliance patterns for forms. Ensures forms work for keyboard users, screen reader users, and users with cognitive or motor disabilities.

## Quick Start

```tsx
// Accessible form field pattern

  {/* 1. Visible label (never placeholder-only) */}
  
    Email
    *
  
  
  {/* 2. Hint text (separate from label) */}
  
    We'll send your confirmation here
  
  
  {/* 3. Input with full ARIA binding */}
  
  
  {/* 4. Error message (announced by screen readers) */}
  {hasError && (
    
      Please enter a valid email address
    
  )}

```

## WCAG 2.2 Form Requirements

### Critical Criteria

| Criterion | Level | Requirement | Implementation |
|-----------|-------|-------------|----------------|
| 1.3.1 Info & Relationships | A | Structure conveyed programmatically | ``, ``, `aria-describedby` |
| 1.3.5 Identify Input Purpose | AA | Input purpose identifiable | `autocomplete` attributes |
| 2.1.1 Keyboard | A | All functionality via keyboard | Tab order, focus management |
| 2.4.6 Headings & Labels | AA | Labels describe purpose | Descriptive, visible labels |
| 2.4.11 Focus Not Obscured | AA | Focus not hidden by other content | Scroll behavior, sticky elements |
| 2.5.8 Target Size | AA | 24×24px minimum touch target | Button/input sizing |
| 3.3.1 Error Identification | A | Errors identified and described | `aria-invalid`, error messages |
| 3.3.2 Labels or Instructions | A | Labels provided | Visible labels, not just placeholders |
| 3.3.3 Error Suggestion | AA | Suggestions for fixing errors | Actionable error messages |
| 3.3.7 Redundant Entry | A | Don't re-ask for info already provided | Form state management |
| 3.3.8 Accessible Authentication | AA | No cognitive function tests | No CAPTCHAs requiring text recognition |

### New in WCAG 2.2 (October 2023)

**2.4.11 Focus Not Obscured (AA)**
```css
/* Ensure focus is never hidden by sticky headers */
.sticky-header {
  position: sticky;
  top: 0;
}

input:focus {
  /* Browser should scroll input into view above sticky elements */
  scroll-margin-top: 80px; /* Height of sticky header */
}
```

**2.5.8 Target Size (AA)**
```css
/* Minimum 24×24px touch targets */
button,
input[type="submit"],
input[type="checkbox"],
input[type="radio"] {
  min-width: 24px;
  min-height: 24px;
}

/* Better: 44×44px for comfortable touch */
.touch-friendly {
  min-width: 44px;
  min-height: 44px;
}
```

**3.3.7 Redundant Entry (A)**
```tsx
// ❌ BAD: Asking for email twice

// ✅ GOOD: Ask once, show confirmation

Confirmation will be sent to: {email}
```

**3.3.8 Accessible Authentication (AA)**
```tsx
// ❌ BAD: CAPTCHA requiring text recognition

// ✅ GOOD: Alternative verification methods

  Send verification code to email

```

## ARIA Patterns

### Error Message Binding

```tsx
// Pattern: aria-describedby links input to error

{hasError && (
  
    {errorMessage}
  
)}
```

### Multiple Descriptions

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

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 */}

// Alternative: Required in label (simpler)
Name (required)

```

### Field Groups

```tsx
// Pattern: fieldset + legend for related fields

  Shipping Address
  
  Street
  
  
  City
  

```

### Radio/Checkbox Groups

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

  Preferred contact method
  
  
    
    Email
  
  
  
    
    Phone
  

```

## Focus Management

### 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

  {/* Form content */}

// 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 {children};
}
```

## Color & Contrast

### 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 (
    
      {state === 'valid' && '✓'}
      {state === 'invalid' && '✗'}
    
  );
}
```

## Keyboard Navigation

### 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 {children};
}
```

### 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:
 {
    if (e.key === 'Enter') {
      e.preventDefault();
      // Do something else
    }
  }}
/>
```

## Live Regions

### Error Announcements

```tsx
// Announce errors when they appear

  {errorCount > 0 && `${errorCount} errors in form`}

// 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 && (
  
    Form submitted successfully!
  
)}
```

## Screen Reader Only Content

```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;
}
```

## Testing Accessibility

### 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();
});
```

## File Structure

```
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
```

## Reference

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Bbeierle12](https://github.com/Bbeierle12)
- **Source:** [Bbeierle12/Skill-MCP-Claude](https://github.com/Bbeierle12/Skill-MCP-Claude)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bbeierle12-skill-mcp-claude-form-accessibility
- Seller: https://agentstack.voostack.com/s/bbeierle12
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.