StellaOps UI Accessibility Guide

Overview

StellaOps web interface aims for WCAG 2.1 AA compliance. This document outlines accessibility requirements, testing procedures, and implementation patterns.

WCAG 2.1 AA Compliance Checklist

Perceivable

Operable

Understandable

Robust

Color Contrast Requirements

Severity Colors (with sufficient contrast)

/* All severity colors meet 4.5:1 contrast on white background */
:root {
  --color-critical: #991b1b;      /* 7.8:1 on white */
  --color-critical-bg: #fef2f2;

  --color-high: #9a3412;          /* 7.5:1 on white */
  --color-high-bg: #fff7ed;

  --color-medium: #854d0e;        /* 7.2:1 on white */
  --color-medium-bg: #fefce8;

  --color-low: #166534;           /* 6.8:1 on white */
  --color-low-bg: #f0fdf4;

  --color-info: #1e40af;          /* 8.2:1 on white */
  --color-info-bg: #eff6ff;
}

Dark Mode Contrast

/* Dark mode maintains contrast ratios */
[data-theme="dark"] {
  --color-critical: #fca5a5;      /* 4.5:1 on dark background */
  --color-high: #fdba74;
  --color-medium: #fde047;
  --color-low: #86efac;
  --color-info: #93c5fd;
}

Keyboard Navigation

Global Shortcuts

List Navigation

Implementation Example

@Injectable({ providedIn: 'root' })
export class KeyboardShortcutService {
  private shortcuts = new Map<string, ShortcutHandler>();

  register(key: string, handler: ShortcutHandler): void {
    this.shortcuts.set(key.toLowerCase(), handler);
  }

  @HostListener('window:keydown', ['$event'])
  handleKeydown(event: KeyboardEvent): void {
    // Ignore when typing in inputs
    if (this.isTyping(event)) return;

    const key = this.normalizeKey(event);
    const handler = this.shortcuts.get(key);

    if (handler) {
      event.preventDefault();
      handler.execute();
    }
  }
}

Focus Management

Focus Trap for Modals

@Directive({ selector: '[appFocusTrap]' })
export class FocusTrapDirective implements AfterViewInit, OnDestroy {
  private focusableElements: HTMLElement[] = [];
  private previousActiveElement: HTMLElement | null = null;

  ngAfterViewInit(): void {
    this.previousActiveElement = document.activeElement as HTMLElement;
    this.focusableElements = this.getFocusableElements();
    this.focusFirst();
  }

  ngOnDestroy(): void {
    this.previousActiveElement?.focus();
  }

  @HostListener('keydown.tab', ['$event'])
  handleTab(event: KeyboardEvent): void {
    const first = this.focusableElements[0];
    const last = this.focusableElements[this.focusableElements.length - 1];

    if (event.shiftKey && document.activeElement === first) {
      event.preventDefault();
      last.focus();
    } else if (!event.shiftKey && document.activeElement === last) {
      event.preventDefault();
      first.focus();
    }
  }
}

Focus Visible Styles

/* Custom focus indicator */
*:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
  border-radius: var(--radius-sm);
}

/* Remove default outline for mouse users */
*:focus:not(:focus-visible) {
  outline: none;
}

/* High contrast mode focus */
@media (forced-colors: active) {
  *:focus-visible {
    outline: 3px solid CanvasText;
  }
}

Screen Reader Support

ARIA Attributes

<!-- Live regions for dynamic updates -->
<div aria-live="polite" aria-atomic="true" class="sr-only">
  {{ statusMessage }}
</div>

<!-- Loading states -->
<div aria-busy="true" aria-describedby="loading-message">
  <span id="loading-message" class="sr-only">Loading findings...</span>
</div>

<!-- Error announcements -->
<div role="alert" aria-live="assertive">
  {{ errorMessage }}
</div>

<!-- Navigation landmarks -->
<nav aria-label="Main navigation">...</nav>
<nav aria-label="Breadcrumb">...</nav>
<main aria-labelledby="page-title">...</main>

Screen Reader Announcements

@Injectable({ providedIn: 'root' })
export class AnnouncerService {
  private liveRegion: HTMLElement;

  constructor() {
    this.createLiveRegion();
  }

  announce(message: string, politeness: 'polite' | 'assertive' = 'polite'): void {
    this.liveRegion.setAttribute('aria-live', politeness);
    this.liveRegion.textContent = '';

    // Force reflow
    void this.liveRegion.offsetWidth;

    this.liveRegion.textContent = message;
  }

  private createLiveRegion(): void {
    this.liveRegion = document.createElement('div');
    this.liveRegion.setAttribute('aria-live', 'polite');
    this.liveRegion.setAttribute('aria-atomic', 'true');
    this.liveRegion.className = 'sr-only';
    document.body.appendChild(this.liveRegion);
  }
}

Form Accessibility

Input Labels

<!-- Visible label -->
<label for="cve-search">Search CVEs</label>
<input id="cve-search" type="text" aria-describedby="cve-search-hint">
<span id="cve-search-hint" class="hint">Enter CVE ID like CVE-2024-1234</span>

<!-- Hidden label for icon buttons -->
<button aria-label="Close dialog">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Group labels -->
<fieldset>
  <legend>Severity Filter</legend>
  <label><input type="checkbox" name="severity" value="critical"> Critical</label>
  <label><input type="checkbox" name="severity" value="high"> High</label>
</fieldset>

Error Messages

<div class="form-group" [class.has-error]="control.invalid && control.touched">
  <label for="policy-name">Policy Name</label>
  <input
    id="policy-name"
    [attr.aria-invalid]="control.invalid && control.touched"
    [attr.aria-describedby]="control.invalid ? 'policy-name-error' : null">
  <span id="policy-name-error" role="alert" *ngIf="control.invalid && control.touched">
    {{ getErrorMessage(control) }}
  </span>
</div>

Motion and Animation

Reduced Motion Support

/* Respect user preference */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

/* Safe animations (opacity, transform only) */
.fade-in {
  animation: fadeIn 200ms ease-out;
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

/* Alternative for reduced motion */
@media (prefers-reduced-motion: reduce) {
  .fade-in {
    animation: none;
    opacity: 1;
  }
}

Testing Procedures

Automated Testing

# axe-core CLI
npm run test:a11y

# Lighthouse accessibility audit
lighthouse --only-categories=accessibility https://localhost:4200

# Pa11y for CI
pa11y https://localhost:4200 --standard WCAG2AA

Manual Testing Checklist

• [ ] Tab through entire page - all interactive elements focusable
• [ ] Keyboard shortcuts work without mouse
• [ ] Focus indicator visible on all focusable elements
• [ ] Screen reader announces page changes
• [ ] Zoom to 200% - no horizontal scroll
• [ ] High contrast mode renders correctly
• [ ] Reduced motion preference respected

Screen Reader Testing

Related Documentation

• Information Architecture
• Component Library
• SPRINT_040 - Keyboard Accessibility