OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add microsoft/vscode-cosmosdb --skill accessibility-aria-expert
Detects and fixes accessibility issues in React/Fluent UI webviews. Use when reviewing code for screen reader compatibility, fixing ARIA labels, ensuring keyboard navigation, adding live regions for status messages, or managing focus in dialogs.
npx skills add microsoft/vscode-cosmosdb --skill accessibility-aria-expert
Verify and fix accessibility in React/Fluent UI webview components.
aria-label to icon-only buttons or form inputsTooltips require aria-label + aria-hidden to avoid double announcements:
aria-label: Full context (visible text + tooltip)aria-hidden="true": Wraps visible text to prevent duplicationFor every interactive element with visible text, compare the rendered text with its computed accessible name. Check all
sources that can override descendant text, including aria-label, aria-labelledby, title, and Fluent UI tooltips with
relationship="label".
aria-description so
the visible label remains the name without adding hidden DOM content. Use aria-describedby when the description already
exists in the DOM, is shared by multiple controls, contains meaningful structure, or compatibility requirements demand it.
Add aria-label only when the accessible name itself needs clarification, and include the exact visible label when doing so.aria-label overrides descendant text. Seeing the visible label inside the component does not mean it is
included in the accessibility tree.For user-facing controls covered by Playwright, assert both the rendered label and computed accessible name:
Do not add an absolutely positioned screen-reader-only element just to name a nearby semantic element, especially inside a scrollable table, grid, list, or panel. VoiceOver may move the virtual cursor to the hidden element's layout box and scroll the visible content out of view.
Prefer setting the accessible name or description on a rendered element with useful on-screen bounds. For text controls, this is usually the semantic element itself. For an icon or symbol inside a table cell, use a visible inline wrapper as the named accessibility node and keep the visual-only child hidden from assistive technology:
Use hidden DOM text only when the semantic relationship cannot be expressed directly. When it is necessary, use an established shared utility, anchor it to an appropriate containing block, and manually navigate the control with VoiceOver or NVDA to verify that focus and the virtual cursor do not scroll the visible content away or lose the visual focus indicator. Playwright accessible-name assertions do not detect these screen-reader-driven visual regressions.
❌ Problem: Tooltip content inaccessible to screen readers
✅ Fix: Include tooltip in aria-label
❌ Problem: Screen reader says "Collection scan Collection scan"
✅ Fix: Wrap visible text
❌ Problem: aria-label identical to visible text adds no value
✅ Fix: Remove redundant aria-label OR make it more descriptive
Keep aria-label only when it adds information:
❌ Problem: No accessible name
✅ Fix: Add aria-label
❌ Problem: Progress bar announced unnecessarily
✅ Fix: Hide decorative elements
❌ Problem: SpinButton/Input without accessible name
✅ Fix: Add aria-label or associate with label element
❌ Problem: aria-label doesn't contain visible text (breaks voice control)
✅ Fix: Accessible name must contain visible label exactly
Voice control users say "click Refresh" – only works if accessible name contains "Refresh".
❌ Problem: Screen reader doesn't announce dynamic content
✅ Fix: Use the Announcer component
Use for: loading states, search results, success/error messages.
❌ Problem: Focus stays on trigger when modal opens
✅ Fix: Move focus programmatically
❌ Problem: Buttons share visual label but screen reader misses context
✅ Fix: Use role="group" with aria-labelledby
DO use on:
DO NOT use on:
For keyboard-accessible badges with tooltips:
Use the Announcer component for WCAG 4.1.3 (Status Messages) compliance.
when: Announces when this transitions from false to truemessage: The message to announce (use l10n.t() for localization)politeness: 'assertive' (default, interrupts) or 'polite' (waits for idle)documentCount) to derive dynamic messagesl10n.t() for messages - announcements must be localizedwhen goes back to false, it's ready for the next announcementaria-labelaria-labelaria-labelaria-hidden="true" when aria-label duplicates itaria-hidden={true}focusableBadge class + tabIndex={0}Announcer componentrole="group" with aria-labelledbysrc/webviews/components/focusableBadge/focusableBadge.md for the Badge patternconst moreLabel = page.getByRole('button', { name: /^More/ });
await expect(moreLabel).toHaveText('More…');
await expect(moreLabel).toHaveAccessibleName(/^More…/);
await expect(moreLabel).toHaveAccessibleDescription('Show full description');// ❌ VoiceOver may scroll to the hidden span when navigating the cell.
<td>
<span className={styles.srOnly}>{l10n.t('Yes')}</span>
<CheckmarkCircleFilled />
</td>
// ❌ The value is announced, but VoiceOver's visual focus indicator may disappear from the rendered symbol.
<td aria-label={l10n.t('Yes')}>
<CheckmarkCircleFilled aria-hidden={true} />
</td>
// ✅ The accessibility node uses the visible symbol's bounds; there is no off-screen layout box to reveal.
<td>
<span role="img" aria-label={l10n.t('Yes')} style={{ display: 'inline-flex' }}>
<CheckmarkCircleFilled aria-hidden={true} />
</span>
</td><Tooltip content="Save document to database">
<Button aria-label="Save">Save</Button>
</Tooltip><Tooltip content="Save document to database" relationship="description">
<Button aria-label="Save document to database">Save</Button>
</Tooltip><Badge aria-label="Collection scan. Query is inefficient">Collection scan</Badge><Badge aria-label="Collection scan. Query is inefficient">
<span aria-hidden="true">Collection scan</span>
</Badge><Button aria-label="Save">Save</Button>
<ToolbarButton aria-label="Validate" icon={<CheckIcon />}>Validate</ToolbarButton><Button>Save</Button>
<ToolbarButton icon={<CheckIcon />}>Validate</ToolbarButton><ToolbarButton aria-label="Save document to database" icon={<SaveIcon />}>
Save
</ToolbarButton><ToolbarButton icon={<DeleteRegular />} onClick={onDelete} /><Tooltip content="Delete selected items" relationship="description">
<ToolbarButton aria-label="Delete selected items" icon={<DeleteRegular />} onClick={onDelete} />
</Tooltip><ProgressBar thickness="large" /><ProgressBar thickness="large" aria-hidden={true} /><SpinButton value={skipValue} onChange={onSkipChange} />
<Input placeholder="Enter query..." /><SpinButton aria-label="Skip documents" value={skipValue} onChange={onSkipChange} />
<Label htmlFor="query-input">Query</Label>
<Input id="query-input" placeholder="Enter query..." /><ToolbarButton aria-label="Reload data" icon={<RefreshIcon />}>
Refresh
</ToolbarButton><ToolbarButton aria-label="Refresh data" icon={<RefreshIcon />}>
Refresh
</ToolbarButton><span>{isLoading ? 'Loading...' : `${count} results`}</span>import { Announcer } from '../../api/webview-client/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')}
/>{
isOpen && <Dialog>...</Dialog>;
}const dialogRef = useRef<HTMLDivElement>(null);
useEffect(() => {
if (isOpen) dialogRef.current?.focus();
}, [isOpen]);
{
isOpen && (
<Dialog ref={dialogRef} tabIndex={-1} aria-modal="true">
...
</Dialog>
);
}<span>How would you rate this?</span>
<Button>👍</Button>
<Button>👎</Button><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><Badge tabIndex={0} className="focusableBadge" aria-label="Visible text. Tooltip details">
<span aria-hidden="true">Visible text</span>
</Badge>import { Announcer } from '../../api/webview-client/accessibility';// 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" />