Accessibility

SHARED RESPONSIBILITY

A strong foundation, not a compliance badge

NeuralNg is designed against WCAG 2.2 and WAI-ARIA Authoring Practices, but a component library cannot certify the finished application. Content, custom colors, page structure and end-to-end workflows remain part of the product team's accessibility responsibility.

Prefer native semantics

Button renders a real button; form controls keep native input semantics. Composite widgets add roles only where the platform has no equivalent, such as tablist, tree, listbox and calendar grid patterns.

<neural-button label="Save changes" />

<neural-button
  icon="nt nt-settings"
  ariaLabel="Open settings"
  rounded
/>

<neural-button
  label="Saving changes"
  [loading]="true"
  loadingLabel="Saving changes"
/>

Names, descriptions and errors

Visible text should be the accessible name whenever possible. Field assigns deterministic IDs and keeps for, aria-describedby, aria-invalid, aria-required and pending state synchronized as conditional hints and errors enter the composition.

<neural-field
  controlId="account-email"
  required
  [invalid]="email.touched() && email.invalid()"
>
  <label neuralFieldLabel>Email</label>
  <input neuralInput type="email" autocomplete="email" [formField]="email" />
  <small neuralFieldHint>Use your work address.</small>

  @if (email.touched() && email.invalid()) {
    <small neuralFieldError>Enter a valid email address.</small>
  }
</neural-field>

Keyboard contracts follow the widget pattern

Complex components do not invent one universal shortcut set. Each follows the interaction model users expect for its role, while logical directions adapt to orientation and RTL.

Focus belongs to the interaction

Dialog and modal Drawer contain keyboard focus, support an explicit initial focus target and restore focus to the opener after closing. Popover, Select and other non-modal overlays preserve their trigger relationship without trapping the rest of the document.

<neural-dialog #review ariaLabelledby="review-title">
  <neural-dialog-header>
    <h2 id="review-title">Review release</h2>
  </neural-dialog-header>
  <neural-dialog-body>
    <input neuralInput neuralDialogInitialFocus aria-label="Release name" />
  </neural-dialog-body>
</neural-dialog>

<neural-button label="Open review" (clicked)="review.open()" />

Never remove focus outlines without supplying an equally visible replacement. Neutral uses :focus-visible so pointer interaction does not create unnecessary rings while keyboard focus remains discoverable.

State must not depend on color alone

Motion, contrast and headless ownership

Component motion respects prefers-reduced-motion. Neutral is the recommended accessible baseline, but changing primary/surface scales or using unstyled transfers visual contrast, target size and focus-indicator ownership to the consumer.

RTL and localization are accessibility inputs

Logical start/end positions, directional keyboard behavior, localized control labels and calendar conventions resolve from configured direction and locale. Supply the same initial values on server and browser so users do not experience a direction or language shift during hydration.

Test behavior, not only markup

Automated rules catch missing names, invalid relationships and many contrast failures, but cannot judge content quality or complete keyboard flows. Pair component tests and axe checks with keyboard-only, zoom, forced-colors and screen-reader passes on critical journeys.

import AxeBuilder from '@axe-core/playwright';
import { expect, test } from '@playwright/test';

test('button example has no detectable violations', async ({ page }) => {
  await page.goto('/docs/components/button');
  await expect(page.getByRole('button', { name: 'Save changes' })).toBeVisible();

  const result = await new AxeBuilder({ page }).analyze();
  expect(result.violations).toEqual([]);
});