@zisuzon/a11y-components

An accessibility-first React component library built with WCAG 2.1 Level AA compliance. Every component is designed with screen readers, keyboard navigation, and assistive technologies in mind.

Features

• ♿ WCAG 2.1 Level AA Compliant - All components meet accessibility standards
• ⌨️ Full Keyboard Navigation - Complete keyboard support out of the box
• 🔊 Screen Reader Friendly - Proper ARIA attributes and semantic HTML
• 🎨 Customizable - Built with Tailwind CSS v4
• 📦 Tree-shakeable - Import only what you need
• 🎯 TypeScript - Full type safety

Prerequisites

Before installing this library, ensure your project has:

• Node.js 18+ (20+ or 22+ recommended)
• React 19.1.1 or higher
• React DOM 19.1.1 or higher

Installation

1. Install the package

npm install @zisuzon/a11y-components

2. Install peer dependencies (if not already installed)

npm install react@^19.1.1 react-dom@^19.1.1

3. Import the styles

Add the CSS import to your application's entry point (e.g., main.tsx, App.tsx, or index.tsx):

import "@zisuzon/a11y-components/dist/index.css";

⚠️ Important: The CSS import is required for components to render correctly. Without it, components will have no styling.

Quick Start

import { Button, Input } from "@zisuzon/a11y-components";
import "@zisuzon/a11y-components/dist/index.css";

function App() {
  return (
    <form>
      <Input
        label="Email address"
        type="email"
        required
        helperText="We'll never share your email"
      />
      <Button variant="primary" type="submit">
        Subscribe
      </Button>
    </form>
  );
}

Usage Examples

Button

import { Button } from "@zisuzon/a11y-components";

// Basic button
<Button variant="primary">Click me</Button>

// Button variants
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Delete</Button>

// Button sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// Loading state
<Button isLoading>Submitting...</Button>

// With icons
<Button leftIcon={<SaveIcon />}>Save</Button>

// Icon-only button (aria-label required)
<Button aria-label="Close" leftIcon={<CloseIcon />} />

// Full width
<Button fullWidth>Full Width Button</Button>

Input

import { Input } from "@zisuzon/a11y-components";

// Basic input
<Input label="Username" />

// With validation error
<Input
  label="Email"
  type="email"
  error="Please enter a valid email address"
  isInvalid
/>

// With helper text
<Input
  label="Password"
  type="password"
  helperText="Must be at least 8 characters"
/>

// Required field
<Input label="Full Name" required />

// With icons
<Input
  label="Search"
  leftIcon={<SearchIcon />}
  placeholder="Search..."
/>

// Visually hidden label (still accessible to screen readers)
<Input
  label="Search"
  hideLabel
  placeholder="Search..."
/>

Available Components

| Component | Description | | ----------------- | ----------------------------------------------------------------- | | Button | Accessible button with variants, loading states, and icon support | | Input | Text input with validation and error handling | | Textarea | Multi-line text input | | Select | Custom dropdown with keyboard navigation and type-ahead | | NativeSelect | Native HTML select for maximum accessibility | | DatePicker | Native HTML5 date input | | DateRangePicker | Date range selection | | Card | Semantic container with header, content, and footer | | CardHeader | Card header section | | CardContent | Card main content section | | CardFooter | Card footer section | | Table | Accessible data table with sorting support | | TableHeader | Table header section | | TableBody | Table body section | | TableRow | Table row | | TableHead | Table header cell | | TableCell | Table data cell | | MenuBar | Navigation menubar with keyboard support | | MenuItem | Individual menu item | | MenuSeparator | Visual separator between menu items |

TypeScript Support

All components are fully typed. Import types alongside components:

import { Button, Input } from "@zisuzon/a11y-components";
import type { ButtonProps, InputProps } from "@zisuzon/a11y-components";

// Use types for custom wrappers
const MyButton = (props: ButtonProps) => {
  return <Button {...props} variant="primary" />;
};

Accessibility Features

Every component includes:

• ✅ Semantic HTML elements
• ✅ ARIA attributes (labels, descriptions, states)
• ✅ Full keyboard navigation
• ✅ Screen reader announcements
• ✅ Focus management
• ✅ Error handling with live regions
• ✅ High contrast focus indicators
• ✅ Minimum touch target sizes (44×44px)

Keyboard Navigation

| Component | Keyboard Support | | ------------------ | -------------------------------------------------------------- | | Button | Enter, Space to activate | | Input | Standard text input navigation | | Select | ↑/↓ to navigate, Enter to select, Escape to close | | MenuBar | ←/→ to navigate, Enter/Space to activate, Home/End | | Table | Tab for interactive rows | | Card (interactive) | Enter, Space to activate |

Customization

Using with Tailwind CSS

Components use Tailwind CSS classes. You can override styles using the className prop:

<Button className="bg-purple-600 hover:bg-purple-700">
  Custom Purple Button
</Button>

Using the utility function

The library exports a cn utility for merging class names:

import { cn } from "@zisuzon/a11y-components";

<div className={cn("base-styles", isActive && "active-styles")}>Content</div>;

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT License - see LICENSE for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/new-component)
3. Make your changes
4. Run tests (npm test)
5. Run linter (npm run lint)
6. Commit your changes (git commit -m 'Add new component')
7. Push to the branch (git push origin feature/new-component)
8. Open a Pull Request

Links

• GitHub Repository
• npm Package
• Storybook Documentation