# Aria-Ease
### Accessibility infrastructure for the entire frontend engineering lifecycle.
Stop treating accessibility as an afterthought. Aria-Ease engineers accessibility integrity into every phase of frontend development lifecycle โ from local development to production monitoring โ so accessibility violations never reach your users.
[](https://www.npmjs.com/package/aria-ease)
[](https://opensource.org/licenses/ISC)
[](https://bundlephobia.com/package/aria-ease)
[](https://www.npmjs.com/package/aria-ease)
## ๐๏ธ Infrastructure, Not Just Utilities
Aria-Ease isn't a utility library. **It's an accessibility infrastructure** that integrates into every phase of your frontend engineering lifecycle:
| Phase | Feature | Impact |
| ------------------ | --------------------------------------------- | --------------------------------------------- |
| **๐ง Development** | Component utilities for accessible patterns | Build it right from the start |
| **๐ Pre-Deploy** | Axe-core powered static accessibility audit | Verify before it ships |
| **๐งช Testing** | WAI-ARIA APG contract testing with Playwright | Fast, deterministic component accessibility test |
| **๐ CI/CD** | Accessibility as deployment gatekeeper | Block inaccessible code from production |
---
## ๐ฏ The Complete Lifecycle
### From Development to Production
**Traditional approach:** Build features โ Manual testing โ Find accessibility issues โ Fix them โ Manual testing again โ Ship
**Aria-Ease approach:** Build with accessible baseline utilities โ Automated audits catch issues โ Contract tests verify consistent component behaviors โ CI/CD gates deployment โ Ship with confidence
### What Makes This Different?
#### 1. **Component Utilities**
Reusable accessible interaction patterns based on Aria-Ease's baseline interpretation of WAI-ARIA APG guidance. Not the only valid implementation, but a proven, consistent place to start. Tree-shakable, framework-agnostic, production-ready.
```javascript
// Instead of 50+ lines managing ARIA accessibility states and interactions...
import { makeMenuAccessible } from "aria-ease/menu";
const menu = makeMenuAccessible({
menuId: "user-menu",
triggerId: "profile-button",
menuItemsClass: "menu-item",
}); // Arrow keys, Escape, focus management โ all handled
```
#### 2. **Static Audit**
Axe-core powered CLI that scans your entire site and generates multi-format reports in HTML, CSV or JSON. Run it locally or in CI/CD.
```bash
npx aria-ease audit --url https://yoursite.com
```
#### 3. **Contract Testing**
This is the game-changer. Encode a deterministic, testable interpretation of WAI-ARIA APG guidance into JSON "contracts" using Aria-Ease DSL API, and validate your contract against your component using Aria-Ease's Playwright runner with isolated test-harness architecture. Run it locally or in CI/CD.
Teams and experts can enforce their own standards, maintain reusability and consistency, and prevent regression.
**The result?** Component interaction testing that feels closer to unit testing than manual QA.
```bash
npx aria-ease test
# โ 26 assertions in ~2 seconds
# โ 26 assertions in ~1 second in CI
```
**Why this matters:** Before, testing for regression in combobox meant testing every interaction manually. Now, Aria-Ease automates the repeatable, deterministic aspects of testing a combobox: keyboard interaction, ARIA state updates, visibility, and semantic attributes.
#### 4. **CI/CD Integration**
Turn accessibility into a deployment invariant. Add audit and test commands to your pipeline โ if they fail, deployment is blocked.
```yaml
# .github/workflows/deploy.yml
jobs:
accessibility-gate:
runs-on: ubuntu-latest
steps:
- run: npm run build
- run: npx aria-ease audit # Static checks
- run: npx aria-ease test # Interaction tests
# Only deploy if both pass โ๏ธ
```
Real example from our docs site: Push to branch โ Accessibility checks run โ Green check mark โ Deploys to Prod. Red X โ Deploy blocked.
**No one has any excuse to ship inaccessible code anymore.**
---
## โจ Features
- ๐ฏ **Tree-shakable** - Import only what you need (1.4KB - 3.7KB per component)
- โฟ **WCAG Compliant** - Follows WAI-ARIA best practices
- โจ๏ธ **Keyboard Interaction** - Full keyboard support out of the box
- ๐งช **Contract Testing** - Built-in accessibility interaction testing framework
- ๐ญ **Framework Agnostic** - Works with React, Vue, vanilla JS, etc.
- ๐ **CLI Audit Tool** - Automated static accessibility testing for your sites
- ๐ฆ **TypeScript Support** - Full type definitions included
## ๐ฆ Installation
```bash
npm i aria-ease
# or
yarn add aria-ease
# or
pnpm add aria-ease
```
## ๐ Quick Start
### Automated Accessibility Audits (CLI)
Run axe-core powered automated accessibility audits on your website with one command:
```bash
npx aria-ease audit --url https://yoursite.com
```
This generates comprehensive reports in JSON, CSV, and HTML formats showing all accessibility violations detected by axe-core.
**Create a config file** for multiple pages and custom settings:
```javascript
// ariaease.config.js (or .mjs, .cjs, .json, .ts)
export default {
audit: {
urls: [
"https://yoursite.com",
"https://yoursite.com/about",
"https://yoursite.com/contact",
],
output: {
format: "html", // 'json' | 'csv' | 'html' | 'all'
out: "./accessibility-reports",
},
},
test: {...},
};
```
Then run:
```bash
npx aria-ease audit
```
**Supported config formats:**
- `ariaease.config.js` (ES modules)
- `ariaease.config.mjs` (ES modules explicit)
- `ariaease.config.cjs` (CommonJS)
- `ariaease.config.json` (JSON)
- `ariaease.config.ts` (TypeScript - experimental)
The CLI will automatically find and load your config file, with validation to catch errors early.
### Contract DSL Build Workflow
You can author custom component interaction contracts as readable DSL files and compile them with a built-in CLI command.
1. Create one or more `*.contract.mjs` files that export a contract built with `contract("component.name", ...)`.
2. Configure contract sources in `ariaease.config.js`.
3. Run `npx aria-ease build contracts`.
4. Run `npx aria-ease test`.
Example config with multiple contract sources:
```javascript
export default {
test: {...},
contracts: [
{
src: "./tests/external-contracts/**/*.contract.mjs",
// optional: out: "./tests/external-contracts"
},
{
src: "./tests/client-a/**/*.contract.mjs",
out: "./tests/client-a",
},
],
};
```
Example `package.json` scripts:
```json
{
"scripts": {
"build:contracts": "npx aria-ease build contracts",
"test:a11y": "npx aria-ease build contracts && npx aria-ease test"
}
}
```
During build, Aria-Ease validates:
- contract schema shape
- selector references in static/dynamic targets
- relationship references (`aria-reference`, `contains`)
At runtime, relationship invariants are executed and reported alongside static assertions and dynamic tests.
**Perfect for CI/CD pipelines** to catch accessibility issues before production!
#### ๐ Show Your Accessibility Commitment
After auditing your project, show the world you care about accessibility! Add a badge to your README:
**For projects audited with aria-ease:**
[](https://github.com/aria-ease/aria-ease)
```markdown
[](https://github.com/aria-ease/aria-ease)
```
**For projects with tested components:**
[](https://github.com/aria-ease/aria-ease)
```markdown
[](https://github.com/aria-ease/aria-ease)
```
**For projects using both audits and component tests:**
[](https://github.com/aria-ease/aria-ease)
```markdown
[](https://github.com/aria-ease/aria-ease)
```
**Why add the badge?**
- โ Shows your commitment to accessibility
- ๐ Helps us discover projects using aria-ease
- ๐ Promotes accessibility best practices in the community
- ๐ Free marketing for both your project and aria-ease!
> **Tip:** The CLI will prompt you to add the appropriate badge automatically after running audits or tests!
---
## ๐ Component API
### ๐ Menu (Dropdowns)
Creates accessible menus with aria attribute management, focus trapping, and keyboard interaction. Works for dropdowns that toggles display with interactive items.
**Features:**
- Arrow key navigation
- Escape key closes menu and restores focus
- Focus trap within menu
- Submenu support
```javascript
import * as Menu from "aria-ease/menu";
// React Example
useEffect(() => {
menuRef.current = Menu.makeMenuAccessible({
menuId: "menu-div",
menuItemsClass: "profile-menu-items",
triggerId: "display-button",
callback: {
onExpandedChange: (expanded) => {
// Side effect
},
},
});
return () => menuRef.current.cleanup(); // Clean up on unmount
}, []);
// Programmatically control
menuRef.current.openMenu(); // Open the menu
menuRef.current.closeMenu(); // Close the menu
menuRef.current.refresh(); // Refresh the cache after dynamically adding/removing a menu item
// Vanilla JS Example
const menu = Menu.makeMenuAccessible({
menuId: "dropdown-menu",
menuItemsClass: "menu-item",
triggerId: "menu-button",
callback: {
onExpandedChange: (expanded) => {
// Side effect
},
},
});
// Programmatically control
menu.openMenu();
menu.closeMenu();
// If you dynamically add/remove menu items, refresh the cache
menu.refresh();
```
**Required HTML structure:**
```html