@bernierllc/validators-a11y-name-role

v0.3.0

Published

15 days ago

Accessibility name-role-value validation for the BernierLLC validators ecosystem - validates ARIA labels, form controls, and semantic HTML

0High
0Medium
0Low

alikhan410

mkbernier

validation validators accessibility a11y wcag aria labels roles primitive

@bernierllc/validators-a11y-name-role

Accessibility name-role-value validation for the BernierLLC validators ecosystem - validates ARIA labels, form controls, and semantic HTML.

Installation

npm install @bernierllc/validators-a11y-name-role

Overview

This primitive validator checks HTML for WCAG 2.1 name-role-value accessibility requirements. It validates that interactive elements have accessible names, ARIA roles are valid, form controls are properly labeled, landmark regions are present, and live regions are correctly configured.

Features

Form Label Validation - Ensures all form controls have associated labels
ARIA Role Validation - Checks for valid ARIA 1.2 roles
Accessible Name Validation - Validates buttons, links, and images have accessible names
Landmark Validation - Ensures proper page structure with landmark regions
Live Region Validation - Validates ARIA live region configuration

Usage

Complete Validation

import { validateA11yNameRole } from '@bernierllc/validators-a11y-name-role';

const html = `
  <html>
    <body>
      <main>
        <label for="email">Email</label>
        <input type="text" id="email" />
        <button>Submit</button>
      </main>
    </body>
  </html>
`;

const problems = await validateA11yNameRole({
  html,
  checkFormLabels: true,
  checkAriaRoles: true,
  checkAccessibleNames: true,
  checkLandmarks: true,
  checkLiveRegions: true,
  requiredLandmarks: ['main'],
});

problems.forEach(problem => {
  console.log(`${problem.severity}: ${problem.message}`);
  if (problem.suggestion) {
    console.log(`  Suggestion: ${problem.suggestion}`);
  }
});

Quick Checks

import {
  checkFormLabels,
  checkAriaRoles,
  checkAccessibleNames,
  checkLandmarks,
  checkLiveRegions,
} from '@bernierllc/validators-a11y-name-role';

// Check form labels only
const labelProblems = await checkFormLabels('<input type="text" />');

// Check ARIA roles with allowed list
const roleProblems = await checkAriaRoles(
  '<div role="navigation"></div>',
  ['navigation', 'main', 'banner']
);

// Check accessible names
const nameProblems = await checkAccessibleNames('<button></button>');

// Check required landmarks
const landmarkProblems = await checkLandmarks(
  '<div>Content</div>',
  ['main', 'navigation']
);

// Check live regions
const liveProblems = await checkLiveRegions(
  '<div aria-live="polite">Updates</div>'
);

Individual Rules

import {
  missingFormLabel,
  invalidAriaRole,
  missingAccessibleName,
  missingLandmark,
  invalidLiveRegion,
} from '@bernierllc/validators-a11y-name-role';

// Use individual rules with custom runner
import { createRuleContext } from '@bernierllc/validators-core';
import { createSharedUtils } from '@bernierllc/validators-utils';

const utils = createSharedUtils();
const context = createRuleContext('test', input, utils);
const validator = missingFormLabel.create(context);
validator(input);

Validation Rules

missing-form-label

Validates that all form controls (input, select, textarea) have associated labels.

Severity: error Checks:

<label for="id"> associations
aria-label attributes
aria-labelledby references
Wrapped labels
Title attributes (with warning)

Examples:

// ✅ Valid - label[for] association
<label for="username">Username</label>
<input type="text" id="username" />

// ✅ Valid - aria-label
<input type="text" aria-label="Username" />

// ✅ Valid - wrapped label
<label>Username <input type="text" /></label>

// ❌ Invalid - no label
<input type="text" />

invalid-aria-role

Validates that ARIA roles are valid per ARIA 1.2 specification.

Severity: error Checks:

Role is in ARIA 1.2 specification
Role is allowed (if allowedRoles configured)
Role="none/presentation" not used on interactive elements

Examples:

// ✅ Valid - valid ARIA role
<nav role="navigation">Menu</nav>

// ✅ Valid - HTML5 semantic element
<main>Content</main>

// ❌ Invalid - invalid role
<div role="invalid"></div>

// ❌ Invalid - removes semantics from interactive element
<button role="none">Click</button>

missing-accessible-name

Validates that interactive elements have accessible names.

Severity: error Checks:

Buttons have text or aria-label
Links have text or aria-label
Images have alt attributes
Input buttons have value attributes

Examples:

// ✅ Valid - button with text
<button>Submit</button>

// ✅ Valid - button with aria-label
<button aria-label="Close dialog">×</button>

// ✅ Valid - link with text
<a href="/home">Home</a>

// ✅ Valid - image with alt
<img src="photo.jpg" alt="Sunset" />

// ❌ Invalid - button without name
<button></button>

// ❌ Invalid - link without text
<a href="/home"></a>

// ❌ Invalid - image without alt
<img src="photo.jpg" />

missing-landmark

Validates that pages have appropriate landmark regions.

Severity: error for missing required landmarks, warn for unlabeled duplicates, info for suggestions Checks:

Required landmarks present (configurable)
Multiple landmarks of same type are labeled
Suggests semantic elements for divs with class/id hints

Examples:

// ✅ Valid - main landmark present
<main>Primary content</main>

// ✅ Valid - multiple labeled navigations
<nav aria-label="Primary">Menu</nav>
<nav aria-label="Footer">Links</nav>

// ⚠️ Warning - multiple unlabeled landmarks
<nav>Menu 1</nav>
<nav>Menu 2</nav>

// ℹ️ Info - suggest semantic element
<div class="header">Header content</div>

invalid-live-region

Validates that ARIA live regions are properly configured.

Severity: error for invalid values, warn for configuration issues, info for best practices Checks:

aria-live has valid value (off, polite, assertive)
aria-atomic is true or false
aria-relevant has valid tokens
Live attributes have corresponding aria-live or role
Warns about assertive live regions

Examples:

// ✅ Valid - polite live region
<div aria-live="polite">Status updates</div>

// ✅ Valid - with atomic and relevant
<div aria-live="polite" aria-atomic="true" aria-relevant="additions text">
  Updates
</div>

// ✅ Valid - alert role
<div role="alert">Error message</div>

// ❌ Invalid - invalid aria-live value
<div aria-live="invalid"></div>

// ❌ Invalid - invalid aria-relevant token
<div aria-live="polite" aria-relevant="invalid"></div>

// ⚠️ Warning - attributes without aria-live
<div aria-atomic="true">Content</div>

API Reference

validateA11yNameRole(input, utils?)

Main validation function that runs all enabled rules.

Parameters:

input: NameRoleInput - HTML content and validation options
utils?: SharedUtils - Optional shared utilities

Returns: Promise<Problem[]> - Array of validation problems

Quick Check Functions

checkFormLabels(html) - Check form label issues
checkAriaRoles(html, allowedRoles?) - Check ARIA role issues
checkAccessibleNames(html) - Check accessible name issues
checkLandmarks(html, requiredLandmarks?) - Check landmark issues
checkLiveRegions(html) - Check live region issues

Configuration

NameRoleInput

interface NameRoleInput {
  html: string;                      // HTML content to validate
  checkFormLabels?: boolean;         // Enable form label validation (default: true)
  checkAriaRoles?: boolean;          // Enable ARIA role validation (default: true)
  checkAccessibleNames?: boolean;    // Enable accessible name validation (default: true)
  checkLandmarks?: boolean;          // Enable landmark validation (default: true)
  checkLiveRegions?: boolean;        // Enable live region validation (default: true)
  allowedRoles?: string[];           // Restrict allowed ARIA roles
  requiredLandmarks?: string[];      // Required landmark types (default: ['main'])
}

Integration Status

Logger Integration: Not applicable - This is a primitive validator providing pure validation functions without side effects or external logging requirements. Consuming applications can implement their own logging around validator calls if needed.
Docs-Suite: Ready - Exports standard validator metadata with complete rule documentation
NeverHub Integration: Not applicable - As a primitive validator, this package provides atomic validation rules that can be used standalone or composed into higher-level validators. NeverHub integration would occur at the service or suite level when orchestrating multiple validators, not at the primitive level.

Dependencies

@bernierllc/validators-core - Core validation framework
@bernierllc/validators-utils - Shared utilities (HTML parsing)

Related Validators

@bernierllc/validators-a11y-contrast - Color contrast validation
@bernierllc/validators-a11y-focus-order - Focus order validation
@bernierllc/validators-html-syntax - HTML syntax validation

WCAG Compliance

This validator helps achieve compliance with:

WCAG 2.1 Level AA
- 1.3.1 Info and Relationships (A)
- 2.4.6 Headings and Labels (AA)
- 3.3.2 Labels or Instructions (A)
- 4.1.2 Name, Role, Value (A)
Best Practices
- Proper landmark structure
- Semantic HTML usage
- ARIA role usage
- Live region configuration

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@bernierllc/validators-a11y-name-role

Installation

Overview

Features

Usage

Complete Validation

Quick Checks

Individual Rules

Validation Rules

missing-form-label

invalid-aria-role

missing-accessible-name

missing-landmark

invalid-live-region

API Reference

validateA11yNameRole(input, utils?)

Quick Check Functions

Configuration

NameRoleInput

Integration Status

Dependencies

Related Validators

WCAG Compliance

License