accessibility-compliance

Accessibility Compliance

Master accessibility implementation to create inclusive experiences for all users, with a focus on Angular and desktop-first patterns.

When to Use This Skill

• Implementing WCAG 2.2 Level AA or AAA compliance
• Building screen reader accessible interfaces
• Adding keyboard navigation to interactive components
• Implementing focus management and focus trapping
• Creating accessible forms with proper labeling
• Supporting reduced motion and high contrast preferences
• Conducting accessibility audits and fixing violations
• Testing with NVDA, JAWS, VoiceOver (macOS)

Core Capabilities

1. WCAG 2.2 Guidelines

• Perceivable: Content must be presentable in different ways
• Operable: Interface must be navigable with keyboard and assistive tech
• Understandable: Content and operation must be clear
• Robust: Content must work with current and future assistive technologies

2. ARIA Patterns

• Roles: Define element purpose (button, dialog, navigation)
• States: Indicate current condition (expanded, selected, disabled)
• Properties: Describe relationships and additional info (labelledby, describedby)
• Live regions: Announce dynamic content changes

3. Keyboard Navigation

• Focus order and tab sequence
• Focus indicators and visible focus states
• Keyboard shortcuts and hotkeys
• Focus trapping for modals and dialogs

4. Screen Reader Support

• Semantic HTML structure
• Alternative text for images
• Proper heading hierarchy
• Skip links and landmarks

Quick Reference

WCAG 2.2 Success Criteria Checklist

Level	Criterion	Description
A	1.1.1	Non-text content has text alternatives
A	1.3.1	Info and relationships programmatically determinable
A	2.1.1	All functionality keyboard accessible
A	2.4.1	Skip to main content mechanism
AA	1.4.3	Contrast ratio 4.5:1 (text), 3:1 (large text)
AA	1.4.11	Non-text contrast 3:1
AA	2.4.7	Focus visible
AA	2.5.8	Target size minimum 24x24px (NEW in 2.2)
AAA	1.4.6	Enhanced contrast 7:1
AAA	2.5.5	Target size minimum 44x44px

Key Patterns

Pattern 1: Accessible Button

import { Component, input, output, ChangeDetectionStrategy } from '@angular/core';
import { MatButtonModule } from '@angular/material/button';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-accessible-button',
  standalone: true,
  imports: [MatButtonModule, CommonModule],
  template: `
    <button
      mat-raised-button
      [color]="variant()"
      [disabled]="disabled() || isLoading()"
      [attr.aria-busy]="isLoading()"
      [attr.aria-disabled]="disabled() || isLoading()"
      (click)="handleClick()"
      class="accessible-button"
    >
      @if (isLoading()) {
        <span class="sr-only">Loading</span>
        <mat-spinner diameter="20" />
      } @else {
        <ng-content />
      }
    </button>
  `,
  styleUrl: './accessible-button.component.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AccessibleButtonComponent {
  readonly variant = input<'primary' | 'secondary'>('primary');
  readonly disabled = input<boolean>(false);
  readonly isLoading = input<boolean>(false);
  readonly clicked = output<void>();

  handleClick(): void {
    this.clicked.emit();
  }
}

SCSS:

:host {
  display: inline-block;
  min-height: 44px;
  min-width: 44px;
}

.accessible-button {
  // Visible focus ring
  &:focus-visible {
    outline: 2px solid var(--color-primary);
    outline-offset: 2px;
  }
}

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

Pattern 2: Accessible Modal Dialog

import {
  Component,
  input,
  output,
  effect,
  ChangeDetectionStrategy,
  inject,
  ViewChild,
  ElementRef,
} from '@angular/core';
import { CommonModule } from '@angular/common';
import { MatDialogModule } from '@angular/material/dialog';
import { MatButtonModule } from '@angular/material/button';
import { MatIconModule } from '@angular/material/icon';
import { A11yModule } from '@angular/cdk/a11y';

@Component({
  selector: 'app-accessible-dialog',
  standalone: true,
  imports: [
    CommonModule,
    MatDialogModule,
    MatButtonModule,
    MatIconModule,
    A11yModule,
  ],
  template: `
    <div
      role="dialog"
      aria-modal="true"
      [attr.aria-labelledby]="titleId"
      [attr.aria-describedby]="descriptionId"
      cdkTrapFocus
      cdkTrapFocusAutoCapture
      class="dialog-container"
    >
      <h2 [id]="titleId" class="dialog-title">{{ title() }}</h2>
      
      <div [id]="descriptionId" class="dialog-content">
        <ng-content />
      </div>

      <div class="dialog-actions">
        <button mat-button (click)="close()">Close</button>
        <button mat-raised-button color="primary" (click)="confirm()">
          Confirm
        </button>
      </div>

      <button
        mat-icon-button
        aria-label="Close dialog"
        (click)="close()"
        class="dialog-close"
      >
        <mat-icon>close</mat-icon>
      </button>
    </div>
  `,
  styleUrl: './accessible-dialog.component.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AccessibleDialogComponent {
  readonly title = input<string>('');
  readonly closed = output<void>();
  readonly confirmed = output<void>();

  readonly titleId = `dialog-title-${Math.random().toString(36).slice(2)}`;
  readonly descriptionId = `dialog-desc-${Math.random().toString(36).slice(2)}`;

  close(): void {
    this.closed.emit();
  }

  confirm(): void {
    this.confirmed.emit();
  }
}

Pattern 3: Accessible Form

<form [formGroup]="form" (ngSubmit)="onSubmit()" novalidate>
  <!-- Error summary for screen readers -->
  @if (errors().length > 0) {
    <div
      id="form-errors"
      role="alert"
      aria-live="assertive"
      aria-atomic="true"
      class="error-summary"
    >
      <h2 class="error-summary__title">Please fix the following errors:</h2>
      <ul class="error-summary__list">
        @for (error of errors(); track error.field) {
          <li>
            <a [href]="'#' + error.field">{{ error.message }}</a>
          </li>
        }
      </ul>
    </div>
  }

  <!-- Email field with error -->
  <div class="form-field">
    <label for="email" class="form-label">
      Email address
      <span aria-hidden="true" class="required-indicator">*</span>
      <span class="sr-only">(required)</span>
    </label>

    <input
      id="email"
      formControlName="email"
      type="email"
      required
      [attr.aria-required]="true"
      [attr.aria-invalid]="hasError('email')"
      [attr.aria-describedby]="hasError('email') ? 'email-error' : 'email-hint'"
      class="form-input"
    />

    @if (hasError('email')) {
      <p id="email-error" class="error-message" role="alert">
        {{ getErrorMessage('email') }}
      </p>
    } @else {
      <p id="email-hint" class="form-hint">We'll never share your email.</p>
    }
  </div>

  <button type="submit" mat-raised-button color="primary">Submit</button>
</form>

Pattern 4: Skip Navigation Link

import { Component, ChangeDetectionStrategy } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-skip-link',
  standalone: true,
  imports: [CommonModule],
  template: `
    <a
      href="#main-content"
      class="skip-link"
    >
      Skip to main content
    </a>
  `,
  styleUrl: './skip-link.component.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SkipLinkComponent {}

SCSS:

.skip-link {
  position: absolute;
  left: -9999px;
  z-index: 999;
  padding: var(--spacing-xs) var(--spacing-sm);
  background: var(--color-primary);
  color: white;
  text-decoration: none;
  border-radius: var(--radius-md);

  &:focus {
    left: var(--spacing-sm);
    top: var(--spacing-sm);
  }
}

Pattern 5: Live Region for Announcements

import { Component, inject, ChangeDetectionStrategy } from '@angular/core';
import { LiveAnnouncer } from '@angular/cdk/a11y';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-search-results',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div role="status" aria-live="polite" aria-atomic="true" class="sr-only">
      @if (message()) {
        {{ message() }}
      }
    </div>

    @if (isLoading()) {
      <mat-progress-bar mode="indeterminate" />
    } @else if (results().length === 0) {
      <p>No results found.</p>
    } @else {
      <ul>
        @for (result of results(); track result.id) {
          <li>{{ result.title }}</li>
        }
      </ul>
    }
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SearchResultsComponent {
  private readonly liveAnnouncer = inject(LiveAnnouncer);

  readonly results = signal<SearchResult[]>([]);
  readonly isLoading = signal(false);
  readonly message = signal<string>('');

  async onSearch(query: string): Promise<void> {
    this.isLoading.set(true);
    this.message.set('');

    try {
      const results = await this.searchService.search(query).toPromise();
      this.results.set(results ?? []);
      
      const count = results?.length ?? 0;
      const msg = `${count} results found`;
      this.message.set(msg);
      await this.liveAnnouncer.announce(msg, 'polite');
    } finally {
      this.isLoading.set(false);
    }
  }
}

Angular CDK A11y Patterns

Focus Trapping (Dialogs, Drawers)

import { Component, ChangeDetectionStrategy } from '@angular/core';
import { A11yModule } from '@angular/cdk/a11y';

@Component({
  selector: 'app-modal',
  standalone: true,
  imports: [A11yModule],
  template: `
    <div cdkTrapFocus cdkTrapFocusAutoCapture role="dialog">
      <!-- Focus stays inside this element -->
      <ng-content />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ModalComponent {}

Focus Key Manager (List Keyboard Navigation)

import {
  Component,
  viewChildren,
  AfterViewInit,
  ChangeDetectionStrategy,
} from '@angular/core';
import { FocusKeyManager } from '@angular/cdk/a11y';

@Component({
  selector: 'app-campaign-list',
  standalone: true,
  template: `
    <div role="listbox" (keydown)="onKeydown($event)">
      @for (campaign of campaigns(); track campaign.id) {
        <app-campaign-row [campaign]="campaign" />
      }
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class CampaignListComponent implements AfterViewInit {
  @viewChildren(CampaignRowComponent) rows!: QueryList<CampaignRowComponent>;
  private keyManager!: FocusKeyManager<CampaignRowComponent>;

  ngAfterViewInit(): void {
    this.keyManager = new FocusKeyManager(this.rows).withWrap();
  }

  onKeydown(event: KeyboardEvent): void {
    this.keyManager.onKeydown(event);
  }
}

Angular Material A11y Built-Ins

Angular Material handles most ARIA automatically:

• mat-form-field wires aria-labelledby between mat-label and the input
• mat-dialog manages focus trap and role="dialog"
• mat-menu manages role="menu", role="menuitem", and arrow-key navigation
• mat-select manages role="listbox" and option selection
• mat-table provides keyboard navigation with proper ARIA

Trust these — don't add redundant ARIA.

Color Contrast Requirements

// Contrast ratio utilities
function getContrastRatio(foreground: string, background: string): number {
  const getLuminance = (hex: string) => {
    const rgb = hexToRgb(hex);
    const [r, g, b] = rgb.map((c) => {
      c = c / 255;
      return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
    });
    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
  };

  const l1 = getLuminance(foreground);
  const l2 = getLuminance(background);
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);

  return (lighter + 0.05) / (darker + 0.05);
}

// WCAG requirements
const CONTRAST_REQUIREMENTS = {
  // Normal text (<18pt or <14pt bold)
  normalText: {
    AA: 4.5,
    AAA: 7,
  },
  // Large text (>=18pt or >=14pt bold)
  largeText: {
    AA: 3,
    AAA: 4.5,
  },
  // UI components and graphics
  uiComponents: {
    AA: 3,
  },
};

Pangea Contrast Rule

When checking color contrast in Fastlane, report token-level fixes, not hex-level fixes:

Good: "Replace --pangea-text-tertiary on --surface (insufficient contrast at 3.5:1); use --pangea-text-secondary instead"

Bad: "Change hex #949494 to #4b5563"

This ensures fixes are maintainable and themed correctly.

Testing A11y in Angular

// Component-level (Jest + jest-axe)
import { render } from '@testing-library/angular';
import { axe, toHaveNoViolations } from 'jest-axe';

describe('MyComponent', () => {
  it('should have no accessibility violations', async () => {
    const { container } = await render(MyComponent, {
      providers: [provideAnimations()],
    });

    expect(await axe(container)).toHaveNoViolations();
  });
});

// E2E level (Playwright + @axe-core/playwright)
import { test, expect } from '@playwright/test';
import { AxeBuilder } from '@axe-core/playwright';

test('page should have no accessibility violations', async ({ page }) => {
  await page.goto('https://fastlane.local/campaigns');

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  expect(results.violations).toEqual([]);
});

Best Practices

1. Use Semantic HTML: Prefer native elements over ARIA when possible
2. Test with Real Users: Include people with disabilities in user testing
3. Keyboard First: Design interactions to work without a mouse
4. Don't Disable Focus Styles: Style them, don't remove them
5. Provide Text Alternatives: All non-text content needs descriptions
6. Support Zoom: Content should work at 200% zoom
7. Announce Changes: Use live regions for dynamic content
8. Respect Preferences: Honor prefers-reduced-motion and prefers-contrast

Common Issues

• Missing alt text: Images without descriptions
• Poor color contrast: Text hard to read against background
• Keyboard traps: Focus stuck in component
• Missing labels: Form inputs without associated labels
• Auto-playing media: Content that plays without user initiation
• Inaccessible custom controls: Recreating native functionality poorly
• Missing skip links: No way to bypass repetitive content
• Focus order issues: Tab order doesn't match visual order

Testing Tools

• Automated: axe DevTools, WAVE, Lighthouse
• Manual: VoiceOver (macOS), NVDA/JAWS (Windows)
• Simulators: NoCoffee (vision), WebAIM (various disabilities)

Cross-References

• web-component-design — Angular component patterns with a11y in mind
• responsive-design — desktop-first patterns with touch targets
• visual-design-foundations — contrast and color token usage