How to Build a 100% Accessible Cookie Banner (WCAG 2.2 AA & GDPR

/**
 * Accessible Consent Banner (WCAG 2.2 AA & GDPR Compliant)
 * CookieDetox Reference Implementation - 2026-09-05
 */
class AccessibleCookieBanner {
  constructor(options = {}) {
    this.storageKey = options.storageKey || 'cd_consent_state_v1';
    this.dialog = document.getElementById('cookie-consent-dialog');
    this.acceptBtn = document.getElementById('btn-consent-accept');
    this.rejectBtn = document.getElementById('btn-consent-reject');
    this.saveCustomBtn = document.getElementById('btn-consent-save');
    this.focusablesSelector = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
    this.previouslyFocusedElement = null;
    
    this.init();
  }

  init() {
    if (this.hasConsent()) {
      this.enforceStoredConsent();
      return;
    }
    this.show();
    this.bindEvents();
  }

  hasConsent() {
    return localStorage.getItem(this.storageKey) !== null;
  }

  show() {
    this.previouslyFocusedElement = document.activeElement;
    this.dialog.removeAttribute('hidden');
    
    // Support HTML5 dialog natively if available
    if (typeof this.dialog.showModal === 'function') {
      this.dialog.showModal();
    } else {
      this.dialog.setAttribute('aria-modal', 'true');
      this.dialog.setAttribute('role', 'dialog');
    }
    
    // Set initial focus to first operational element
    this.rejectBtn.focus();
    document.body.style.overflow = 'hidden';
  }

  hide() {
    if (typeof this.dialog.close === 'function') {
      this.dialog.close();
    }
    this.dialog.setAttribute('hidden', '');
    document.body.style.overflow = '';
    
    // Restore initial focus
    if (this.previouslyFocusedElement && typeof this.previouslyFocusedElement.focus === 'function') {
      this.previouslyFocusedElement.focus();
    }
  }

  bindEvents() {
    this.acceptBtn.addEventListener('click', () => this.handleConsent('accepted_all'));
    this.rejectBtn.addEventListener('click', () => this.handleConsent('rejected_all'));
    
    if (this.saveCustomBtn) {
      this.saveCustomBtn.addEventListener('click', () => this.handleCustomConsent());
    }

    // Keydown handlers: Focus Trap & Escape handler
    this.dialog.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') {
        e.preventDefault();
        // Default on dismiss/escape must legally be full rejection of non-essential trackers
        this.handleConsent('rejected_all');
        return;
      }

      if (e.key === 'Tab') {
        this.handleFocusTrap(e);
      }
    });
  }

  handleFocusTrap(e) {
    const focusables = Array.from(this.dialog.querySelectorAll(this.focusablesSelector))
      .filter(el => !el.hasAttribute('disabled') && el.offsetParent !== null);
    
    if (focusables.length === 0) return;

    const firstFocusable = focusables[0];
    const lastFocusable = focusables[focusables.length - 1];

    if (e.shiftKey) {
      if (document.activeElement === firstFocusable) {
        e.preventDefault();
        lastFocusable.focus();
      }
    } else {
      if (document.activeElement === lastFocusable) {
        e.preventDefault();
        firstFocusable.focus();
      }
    }
  }

  handleConsent(status) {
    const payload = {
      status: status,
      analytics: status === 'accepted_all',
      marketing: status === 'accepted_all',
      timestamp: new Date().toISOString(),
      version: '1.0'
    };
    localStorage.setItem(this.storageKey, JSON.stringify(payload));
    this.hide();
    this.dispatchConsentEvent(payload);
  }

  dispatchConsentEvent(payload) {
    window.dispatchEvent(new CustomEvent('cookieConsentUpdated', { detail: payload }));
  }

  enforceStoredConsent() {
    const stored = JSON.parse(localStorage.getItem(this.storageKey));
    this.dispatchConsentEvent(stored);
  }
}

document.addEventListener('DOMContentLoaded', () => {
  new AccessibleCookieBanner();
});

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

test.describe('Accessible Cookie Banner Quality Gate', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/');
  });

  test('should pass automated WCAG 2.2 Level AA audit via Axe', async ({ page }) => {
    const accessibilityScanResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
      .include('#cookie-consent-dialog')
      .analyze();

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

  test('should enforce strict keyboard focus trap cycling', async ({ page }) => {
    const rejectBtn = page.locator('#btn-consent-reject');
    const acceptBtn = page.locator('#btn-consent-accept');

    // Modal opens, focus should be on Reject button by design
    await expect(rejectBtn).toBeFocused();

    // Press Tab to traverse to Accept button
    await page.keyboard.press('Tab');
    await expect(acceptBtn).toBeFocused();

    // Press Tab again: Must cycle back to the first interactive element (Reject)
    await page.keyboard.press('Tab');
    await expect(rejectBtn).toBeFocused();

    // Shift+Tab backwards: Must cycle to the last interactive element (Accept)
    await page.keyboard.press('Shift+Tab');
    await expect(acceptBtn).toBeFocused();
  });

  test('should register full rejection on Escape key press and restore focus', async ({ page }) => {
    // Ensure dialog is visible
    const dialog = page.locator('#cookie-consent-dialog');
    await expect(dialog).toBeVisible();

    // Press Escape to dismiss
    await page.keyboard.press('Escape');

    // Dialog must be hidden
    await expect(dialog).toBeHidden();

    // Assert local storage holds strictly non-consented state
    const storedConsent = await page.evaluate(() => {
      return JSON.parse(localStorage.getItem('cd_consent_state_v1'));
    });

    expect(storedConsent.status).toBe('rejected_all');
    expect(storedConsent.analytics).toBe(false);
    expect(storedConsent.marketing).toBe(false);
  });
});