Accessible Component Library ♿

This package provides the core component library for a Web Accessibility-focused (WCAG) design system and automated code quality.

✨ Features

• ✅ WCAG 2.1 Level AA Compliant - All components meet accessibility standards
• ✅ Full Keyboard Navigation - Complete keyboard support for all interactive elements
• ✅ Screen Reader Optimized - Proper ARIA attributes and semantic HTML
• ✅ Internationalization Ready - All text strings are configurable via props
• ✅ TypeScript - Fully typed with strict type checking
• ✅ Zero Accessibility Violations - Tested with jest-axe (151 tests passing)

📦 Installation

npm install @carol8fml/a11y-core

🚀 Quick Start

import { Button } from '@carol8fml/a11y-core';
import '@carol8fml/a11y-core/dist/style.css';

function App() {
  return <Button variant="primary">Click me</Button>;
}

📋 Requirements

React: 18.2.0+ (uses useId hook)
TypeScript: 5.3+ (recommended)
Browsers: Modern browsers with ES6+ support

Compatible with: Next.js, Vite, Create React App, Remix, Gatsby, and any React 18.2.0+ project.

🎯 WCAG 2.1 Conformity

This library is WCAG 2.1 Level AA compliant. All components meet accessibility standards including:

• ✅ Keyboard navigation (2.1.1, 2.1.2)
• ✅ Focus management (2.4.3, 2.4.7)
• ✅ Semantic HTML and ARIA (1.3.1, 4.1.2)
• ✅ Error identification (3.3.1, 3.3.2)
• ✅ Status messages (4.1.3)

Verification: All components tested with jest-axe - 0 accessibility violations.

🌍 Internationalization

All text strings are configurable via props for full i18n support:

// TextField
<TextField
  showPasswordLabel="Mostrar senha"
  hidePasswordLabel="Ocultar senha"
/>

// Modal
<Modal.Root overlayAriaLabel="Fechar modal">
  <Modal.Content
    closeButtonAriaLabel="Fechar diálogo"
    closeButtonSrText="Fechar"
  >
    <Modal.Footer
      defaultCancelLabel="Cancelar"
      defaultConfirmLabel="Confirmar"
    />
  </Modal.Content>
</Modal.Root>

// Toast
<Toast
  closeButtonAriaLabel="Fechar notificação"
  closeButtonSrText="Fechar"
/>

// Link
<Link externalLinkSrText="(abre em nova aba)">
  External Link
</Link>

Note: English fallbacks provided for backward compatibility.

📚 Components

• Button - Accessible button with variants
• Link - Accessible link with external link support
• TextField - Text input with label, error, and helper text
• Checkbox - Checkbox with label, error, and indeterminate state
• Switch - Toggle switch with keyboard support
• Modal - Accessible modal with focus trap
• Toast - Accessible toast notifications

📖 Documentation

• Storybook: Live Documentation
• Components: See Storybook for all component APIs and examples

🛠️ Usage Examples

Button

<Button variant="primary" size="md">Primary</Button>
<Button variant="outline" size="sm">Outline</Button>

TextField

<TextField
  label="Email"
  type="email"
  error="Email is required"
  helperText="Enter your email address"
/>

Modal

const [isOpen, setIsOpen] = useState(false);

<Modal.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>
  <Modal.Content titleId="modal-title">
    <Modal.Header>
      <Modal.Title id="modal-title">Modal Title</Modal.Title>
    </Modal.Header>
    <div>Modal content</div>
    <Modal.Footer
      cancelButton={{ label: 'Cancel' }}
      confirmButton={{ label: 'Confirm', onClick: handleConfirm }}
    />
  </Modal.Content>
</Modal.Root>;

Toast

import { ToastContainer, useToast } from '@carol8fml/a11y-core';

function App() {
  const { toasts, addToast, removeToast } = useToast();

  return (
    <>
      <button
        onClick={() =>
          addToast({
            type: 'success',
            title: 'Success!',
            description: 'Operation completed',
          })
        }
      >
        Show Toast
      </button>
      <ToastContainer toasts={toasts} onClose={removeToast} />
    </>
  );
}

🛠️ Stack and Tools

| Technology | Purpose | | :--------------------------------- | :------------------------------------------------ | | React 18 | Core framework for building components | | TypeScript | Type safety and developer experience | | CSS Modules | Scoped styles to prevent conflicts | | CVA (Class Variance Authority) | Type-safe component variants management | | Vitest | Fast unit and integration testing | | React Testing Library | User-centric component testing | | Jest-Axe | Automated accessibility testing (WCAG compliance) | | Storybook | Component documentation and visual testing | | Vite | Fast build tool and development server | | ESLint | Code quality and accessibility linting | | Prettier | Code formatting consistency | | Husky | Git hooks for pre-commit quality checks |

🏗️ Engineering Highlights

| Concept | Approach | | :------------------- | :--------------------------------------------------------- | | Accessibility | Jest-Axe in CI/CD - Automated tests ensure WCAG compliance | | CSS Architecture | CSS Modules + CVA - Scoped styles with type-safe variants | | Type Safety | TypeScript Strict Mode - Full type coverage | | Testing | Vitest + RTL + Jest-Axe - 151 tests, 0 violations |

🧪 Development

# Clone and install
git clone https://github.com/carol8fml/a11y-core.git
cd a11y-core
npm install

# Run Storybook
npm run storybook

# Run tests
npm test

📄 License

MIT License

👤 Author

Carolina Gonçalves