As a visually impaired user
I want to use the Admin UI with a screen reader
So that I can manage the gateway independently

Acceptance Criteria:

Feature: Screen Reader Support

  Scenario: Navigate with screen reader
    Given I am using NVDA/VoiceOver
    When I navigate the Admin UI
    Then all elements should be announced correctly
    And form labels should be associated with inputs

As a user with motor impairments
I want to navigate entirely with keyboard
So that I don't need to use a mouse

Acceptance Criteria:

Feature: Keyboard Navigation

  Scenario: Complete workflow with keyboard only
    Given I am using only keyboard
    When I login, navigate to gateways, and add a new gateway
    Then I should complete the entire workflow
    And focus should be visible at all times

Automated Testing:

# Run Lighthouse accessibility audit
lighthouse $GATEWAY_URL/ui/ --only-categories=accessibility --output=html

# Or use axe-core CLI
axe $GATEWAY_URL/ui/ --tags wcag2aa

Manual Testing:

1. Open browser DevTools
2. Use Color Contrast Analyzer extension
3. Check each text/background combination

Checklist:

Expected Result:

• All text meets 4.5:1 contrast ratio (AA)
• Large text (18pt+) meets 3:1 ratio
• UI elements meet 3:1 against adjacent colors

Steps:

1. Navigate to Admin UI
2. Press Tab to move through elements
3. Verify focus indicator visible on each element

Checklist:

CSS Check:

/* Focus styles should NOT be removed */
/* BAD: *:focus { outline: none; } */
/* GOOD: */
:focus {
  outline: 2px solid #0066cc;
  outline-offset: 2px;
}

Expected Result:

• Focus indicator visible on all interactive elements
• Focus style has sufficient contrast
• Focus not hidden via CSS

Steps:

1. Start at login page
2. Tab through all elements
3. Verify order is logical (left-to-right, top-to-bottom)
4. Check for focus traps

Record Tab Order:

Login Page:
1. Username input
2. Password input
3. "Remember me" checkbox
4. Login button
5. "Forgot password" link

Dashboard:
1. Skip link (if present)
2. Logo/Home link
3. Navigation items (in order)
4. Main content area
5. Footer links

Expected Result:

• Tab order follows visual layout
• No elements skipped
• No focus traps (except modals)
• Shift+Tab reverses order

Steps:

# Check for associated labels
# In browser console:
document.querySelectorAll('input, select, textarea').forEach(el => {
  const id = el.id;
  const label = document.querySelector(`label[for="${id}"]`);
  const ariaLabel = el.getAttribute('aria-label');
  const ariaLabelledby = el.getAttribute('aria-labelledby');
  console.log({
    id,
    hasLabel: !!label,
    hasAriaLabel: !!ariaLabel,
    hasAriaLabelledby: !!ariaLabelledby
  });
});

Form Audit:

Expected Result:

• Every input has associated label
• Labels are visible (not just aria-label)
• Required fields indicated accessibly

Steps with Screen Reader:

1. Enable NVDA/VoiceOver
2. Submit login form with empty fields
3. Listen for error announcement
4. Verify error describes the problem

Test Scenarios:

HTML Check:

<!-- Errors should have role="alert" or aria-live -->
<div role="alert" class="error">
  Username is required
</div>

<!-- Or be associated with input -->
<input aria-describedby="username-error" />
<span id="username-error" class="error">Username is required</span>

Expected Result:

• Errors announced automatically by screen reader
• Error text is descriptive
• Focus moves to first error (optional)

Page Titles (A11Y-06):

// Check each page has unique, descriptive title
// Navigate through app and record:
console.log(document.title);
// Should be: "Gateways - MCP Gateway Admin" not just "MCP Gateway"

Heading Hierarchy (A11Y-07):

// Check heading levels
document.querySelectorAll('h1, h2, h3, h4, h5, h6').forEach(h => {
  console.log(`${h.tagName}: ${h.textContent}`);
});
// Should have exactly one h1, h2s under h1, h3s under h2s, etc.

Image Alt Text (A11Y-08):

// Check all images have alt text
document.querySelectorAll('img').forEach(img => {
  console.log({
    src: img.src.substring(0, 50),
    alt: img.alt || 'MISSING',
    isDecorative: img.alt === ''
  });
});

Skip Link (A11Y-09):

• First tab stop should be "Skip to main content"
• Link should jump to main content area
• Should be visible on focus

ARIA Usage (A11Y-10):

// Check for proper ARIA
document.querySelectorAll('[role]').forEach(el => {
  console.log({ role: el.getAttribute('role'), element: el.tagName });
});
// Verify roles are correct and necessary