detecting-accessibility-issues

Accessibility Expert for Webviews

Verify and fix accessibility in React/Fluent UI webview components.

When to Use

• Review webview code for accessibility issues
• Fix double announcements from screen readers
• Add missing aria-label to icon-only buttons or form inputs
• Make tooltips accessible to keyboard/screen reader users
• Announce status changes (loading, search results, errors)
• Manage focus when dialogs/modals open
• Group related controls with proper labels

Core Pattern: Tooltip Accessibility

For a badge whose tooltip must be reachable by keyboard, use the package component and keep the tooltip as a description:

<Tooltip content="Detailed explanation" relationship="description">
  <FocusableBadge>Badge text</FocusableBadge>
</Tooltip>

• The visible content is the name through aria-labelledby.
• Tooltip content is the supplementary description through aria-describedby.
• The badge carries role="group", because ARIA cannot name a role-less element.
• Browser-computed results do not prove what a real screen reader says.

Detection Rules

1. Tooltip Content Never Reaches the Accessibility Tree

❌ Problem: the tooltip declares no ARIA relationship, so its content is invisible to assistive technology — and the aria-label here only restates the visible text

<Tooltip content="Save document to database">
  <Button aria-label="Save">Save</Button>
</Tooltip>

✅ Fix: declare the relationship and let the tooltip be the description

<Tooltip content="Save document to database" relationship="description">
  <Button>Save</Button>
</Tooltip>

relationship="description" wires aria-describedby to the tooltip. Do not also copy the tooltip text into aria-label: that announces it twice (rule 2). Use relationship="label" only when the trigger has no visible text of its own.

2. Composed Badge Name Repeats Its Description

❌ Problem: Tooltip details occur in both the name and description

<Tooltip content="Query is inefficient" relationship="description">
  <Badge tabIndex={0} aria-label="Collection scan. Query is inefficient">
    <span aria-hidden="true">Collection scan</span>
  </Badge>
</Tooltip>

✅ Fix: Let visible content name FocusableBadge; keep details in the description

<Tooltip content="Query is inefficient" relationship="description">
  <FocusableBadge>Collection scan</FocusableBadge>
</Tooltip>

3. Redundant aria-label (NOT Needed)

❌ Problem: aria-label identical to visible text adds no value

<Button aria-label="Save">Save</Button>
<ToolbarButton aria-label="Validate" icon={<CheckIcon />}>Validate</ToolbarButton>

✅ Fix: Remove redundant aria-label OR make it more descriptive

<Button>Save</Button>
<ToolbarButton icon={<CheckIcon />}>Validate</ToolbarButton>

Keep aria-label only when it adds information:

<ToolbarButton aria-label="Save document to database" icon={<SaveIcon />}>
  Save
</ToolbarButton>

4. Icon-Only Button Missing aria-label

❌ Problem: No accessible name

<ToolbarButton icon={<DeleteRegular />} onClick={onDelete} />

✅ Fix: Add aria-label

<Tooltip content="Delete selected items" relationship="description">
  <ToolbarButton aria-label="Delete selected items" icon={<DeleteRegular />} onClick={onDelete} />
</Tooltip>

5. Decorative Elements Not Hidden

❌ Problem: Progress bar announced unnecessarily

<ProgressBar thickness="large" />

✅ Fix: Hide decorative elements

<ProgressBar thickness="large" aria-hidden={true} />

6. Input Missing Accessible Name

❌ Problem: SpinButton/Input without accessible name

<SpinButton value={skipValue} onChange={onSkipChange} />
<Input placeholder="Enter query..." />

✅ Fix: Add aria-label or associate with label element

<SpinButton aria-label="Skip documents" value={skipValue} onChange={onSkipChange} />
<Label htmlFor="query-input">Query</Label>
<Input id="query-input" placeholder="Enter query..." />

7. Visible Label Not in Accessible Name

❌ Problem: aria-label doesn't contain visible text (breaks voice control)

<ToolbarButton aria-label="Reload data" icon={<RefreshIcon />}>
  Refresh
</ToolbarButton>

✅ Fix: Accessible name must contain visible label exactly

<ToolbarButton aria-label="Refresh data" icon={<RefreshIcon />}>
  Refresh
</ToolbarButton>

Voice control users say "click Refresh" – only works if accessible name contains "Refresh".

8. Status Changes Not Announced

❌ Problem: Screen reader doesn't announce dynamic content

<span>{isLoading ? 'Loading...' : `${count} results`}</span>

✅ Fix: Use the Announcer component

import { Announcer } from '<relative-path>/components/accessibility';

// Announces when `when` transitions from false to true
<Announcer when={isLoading} message={l10n.t('Loading...')} />

// Dynamic message based on state
<Announcer
    when={!isLoading && documentCount !== undefined}
    message={documentCount > 0 ? l10n.t('Results found') : l10n.t('No results found')}
/>

Use for: loading states, search results, success/error messages.

9. Dialog Opens Without Focus Move

❌ Problem: Focus stays on trigger when modal opens

{
  isOpen && <Dialog>...</Dialog>;
}

✅ Fix: Move focus programmatically

const dialogRef = useRef<HTMLDivElement>(null);

useEffect(() => {
  if (isOpen) dialogRef.current?.focus();
}, [isOpen]);

{
  isOpen && (
    <Dialog ref={dialogRef} tabIndex={-1} aria-modal="true">
      ...
    </Dialog>
  );
}

10. Related Controls Without Group Label

❌ Problem: Buttons share visual label but screen reader misses context

<span>How would you rate this?</span>
<Button>👍</Button>
<Button>👎</Button>

✅ Fix: Use role="group" with aria-labelledby

<div role="group" aria-labelledby="rating-label">
  <span id="rating-label">How would you rate this?</span>
  <Button aria-label="I like it">👍</Button>
  <Button aria-label="I don't like it">👎</Button>
</div>

When to Use aria-hidden

DO use on:

• Decorative icons, spinners, progress bars
• Visual separators (`|`, `—`)

Last resort only: visible text that a composed aria-label already covers. Prefer naming the element from its visible content with aria-labelledby, which needs no hiding at all — that is what FocusableBadge and MetricCard do.

DO NOT use on:

• The only accessible content (hides it completely)
• Interactive/focusable elements
• Error messages or alerts

FocusableBadge Pattern

For keyboard-accessible badges with tooltips:

1. Import FocusableBadge from @microsoft/vscode-ext-webview-fluentui/components.
2. Keep Tooltip at the call site with relationship="description".
3. Use focusable={false} only for plain badges in a mixed list; never infer focusability from an accessible-name override.

<Tooltip content="Tooltip details" relationship="description">
  <FocusableBadge>Visible text</FocusableBadge>
</Tooltip>

For rich tooltip content that visually repeats the badge name, set the content slot's aria-label to only the supplementary details. For truncated values, keep the visible label and truncated value as the badge name and the full value as the description; do not use relationship="label".

When you name a focusable container yourself rather than using these components, give it a role. ARIA forbids naming the generic role, so aria-labelledby on a bare div (or on Fluent's Badge or Card, neither of which sets a role) is a name a conforming screen reader may discard. role="group" is usually the least-weight role that makes the name legitimate.

Screen Reader Announcements

Use the Announcer component for WCAG 4.1.3 (Status Messages) compliance.

import { Announcer } from '<relative-path>/components/accessibility';

Basic Usage

// Announces "AI is analyzing..." when isLoading becomes true
<Announcer when={isLoading} message={l10n.t('AI is analyzing...')} />

// Dynamic message based on state (e.g., query results)
<Announcer
    when={!isLoading && documentCount !== undefined}
    message={documentCount > 0 ? l10n.t('Results found') : l10n.t('No results found')}
/>

// With assertive politeness (default is polite)
<Announcer when={hasError} message={l10n.t('Error occurred')} politeness="assertive" />

Props

• when: Announces when this transitions from false to true
• message: The message to announce (use l10n.t() for localization)
• politeness: 'assertive' (default, interrupts) or 'polite' (waits for idle)

Key Points

• Placement doesn't matter - screen readers monitor all live regions regardless of DOM position; place near related UI for code readability
• Store relevant state (e.g., documentCount) to derive dynamic messages
• Use l10n.t() for messages - announcements must be localized
• Condition resets automatically - when when goes back to false, it's ready for the next announcement
• Prefer 'assertive' for user-initiated actions, 'polite' for background updates

Quick Checklist

• Icon-only buttons have aria-label
• Form inputs have associated labels or aria-label
• Tooltips declare a relationship; their text is not also copied into aria-label
• Visible text is not hidden with aria-hidden to make room for a composed aria-label
• Redundant aria-labels removed (identical to visible text)
• Visible button labels are contained in the accessible name (for voice control)
• Decorative elements have aria-hidden={true}
• Badges with keyboard-reachable tooltips use FocusableBadge + relationship="description"
• Focusable elements carrying aria-labelledby have a role (ARIA cannot name generic)
• Status updates use Announcer component
• [ ]

---

Content truncated.