@a11y-gate/core

Runtime React library for WCAG 2.1 Level AA compliance on legacy components.

Works as a non-invasive wrapper — no modifications to source files required.

Install

npm install @a11y-gate/core
# or
pnpm add @a11y-gate/core

Requirements

• React >= 17
• a11y-gate.config.json generated by @a11y-gate/cli

Usage

1. Wrap your app root with A11yGateProvider

// main.tsx or _app.tsx
import config from './a11y-gate.config.json';
import { A11yGateProvider } from '@a11y-gate/core';

export default function App() {
  return (
    <A11yGateProvider config={config}>
      {/* your app */}
    </A11yGateProvider>
  );
}

2. Wrap each legacy overlay component with Shield

import { Shield } from '@a11y-gate/core';

// Somewhere in your component tree
<Shield component="LegacyDrawer">
  <LegacyDrawer isOpen={open} onClose={close} title="Settings" />
</Shield>

The component prop must match a componentName in your a11y-gate.config.json.

What Shield does

| Feature | Behaviour | |---|---| | Focus trap | Traps Tab/Shift+Tab inside the overlay when triggerProp === true | | Escape key | Global listener calls closeHandler on the topmost active overlay | | Background inert | Applies aria-hidden + inert to rootSelector while any overlay is active | | Focus restore | Returns focus to the previously focused element when overlay closes | | Tab-order patching | Optionally adds reversible tabIndex=0 to legacy interactive elements | | Tab-order preview | Optionally shows numbered tab-order badges in development |

Tab-order preview and patching

Enable preview globally in a11y-gate.config.json:

{
  "version": "1",
  "tab_order_preview": true,
  "tab_order_preview_production": false,
  "tab_order_preview_scope": "both",
  "components": [
    {
      "componentName": "LegacyPopup",
      "componentType": "modal",
      "triggerProp": "isOpen",
      "closeHandler": "onClose",
      "rootSelector": "#root",
      "tabOrder": {
        "auto": true,
        "patches": [
          {
            "selector": "[data-action='close']",
            "role": "button",
            "label": "Close"
          }
        ]
      }
    }
  ]
}

tabOrder.auto uses conservative heuristics for legacy clickable markup such as [role="button"], [role="link"], [onclick], [data-action], [data-a11y-gate-tab], and visible pointer-style elements.

tabOrder.patches is the reliable path for ambiguous legacy DOM. It adds tabIndex=0 in DOM order, optional role, optional aria-label, and keyboard activation for Enter/Space. All changes are restored when the overlay closes.

The preview is development-only by default. Production preview requires both tab_order_preview: true and tab_order_preview_production: true.

tab_order_preview_scope controls where badges appear:

| Scope | Behaviour | |---|---| | overlay | Default. Show badges only inside active Shield overlays | | global | Show badges across the whole page, including header/footer links | | both | Show global page badges and active overlay badges |

Bundle size

~1.6kb gzipped (ESM). React is a peer dependency and not bundled.