Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
HTML widgets (MCP apps) allow partners to render custom HTML and JavaScript experiences inside a sandboxed <iframe> within Teams chat. Because these widgets appear inline with conversational content, they must meet a consistent accessibility bar so that all users, including those who use assistive technologies, can perceive, understand, and operate them.
This article describes the minimum accessibility requirements for HTML widgets and provides recommended best practices and testing guidance.
Scope
These guidelines apply to all partner-built HTML widgets (MCP apps) that are rendered inside an <iframe> in Teams chat. The requirements are in addition to general web accessibility standards such as WCAG 2.2 and the WAI-ARIA Authoring Practices.
Tip
If you are building your widget with React, we recommend using Fluent UI React v9 components and tokens. They implement accessible, Teams-compatible patterns out of the box and reduce the amount of custom accessibility work required. Fluent UI React v9 is not required — partners may use any framework or library as long as the accessibility requirements in this article are met.
Recommended best practices
The following practices aren't required but are strongly recommended to improve the overall experience.
- Skip links: Provide a "Skip to main content" link at the top of the widget to let keyboard and screen reader users bypass repeated navigation
- Headings: Use headings (
<h1>–<h3>) to structure content and make navigation easier for screen reader users - Simple interaction models: Prefer simple, predictable interaction patterns over highly custom or novel controls
- Scrolling: Avoid complex nested scroll regions. If a scrollable region is necessary, ensure it has a clear label and is keyboard accessible
- Tooltips: Implement accessible tooltips using
aria-describedbyand ensure they're available on focus as well as hover - Accessible components: Use Fluent UI React v9 components wherever possible — they implement accessible patterns out of the box and reduce the amount of custom accessibility work required
Responsibility model
Teams and partners share responsibility for accessibility. The following table clarifies what each party owns.
| Requirement | Teams | Partner |
|---|---|---|
| Widget container label (for example, "Scout widget") | ✅ | |
| Tab stop for widget container | ✅ | |
| Tab order of message elements | ✅ | |
| Focus into and out of the widget container | ✅ | |
| Widget-level loading and error states | ✅ | |
| Keyboard navigation inside the widget | ✅ | |
| ARIA labels for interactive elements | ✅ | |
| Screen reader support for widget content | ✅ | |
| Color contrast inside widget | ✅ | |
| High contrast support inside widget | ✅ | |
| Error handling for content inside the widget | ✅ |
Minimum accessibility bar for submission
Widgets must meet all of the following requirements to be accepted. Widgets that don't meet this bar may be rejected or require remediation before publishing.
| Requirements |
|---|
| ✅ Fully operable with a keyboard, with no focus traps inside the widget |
| ✅ Usable with screen readers, with meaningful roles, names, and states on all interactive elements |
| ✅ Meets WCAG 2.2 AA contrast ratios for text and essential UI elements |
| ✅ Provides accessible error handling and loading states for content inside the widget |
| ✅ Text and interactive controls remain readable and operable at 200% browser zoom (exceptions apply for fixed-aspect content such as charts, maps, and media) |
✅ Respects prefers-reduced-motion and avoids harmful flashing |
| ✅ Avoids horizontal scrolling for primary content — intentional horizontal scroll patterns such as wide tables or carousels are acceptable |
Warning
Widgets must meet all of the following requirements to be accepted by the Teams Store. Widgets that don't meet this bar may be rejected or require remediation before publishing to the Teams Store.
Keyboard accessibility
Note
Teams manages focus into and out of the widget container. The requirements below apply to keyboard navigation within the widget content only.
Keyboard operability: All interactive elements must be reachable and operable using standard keyboard input such as Tab, Shift+Tab, arrow keys, Enter, and Space, as appropriate for the control type.
No focus traps: Widgets must not trap focus. Users must be able to navigate through all interactive elements in a logical order and exit the widget without getting stuck.
Visible focus: All interactive elements must have a clear, visible focus indicator that meets contrast requirements and is not removed via CSS without an accessible replacement.
Custom controls: Custom widgets and controls must follow the keyboard interaction patterns defined in the ARIA Authoring Practices for their respective roles (for example, button, menu, dialog, listbox).
Dialogs and modals: Modal dialogs and overlays are possible within a widget but are not recommended. Because widgets render inside a small iframe, a modal will be constrained to that space and may feel disorienting to users. If your use case requires a modal, consider whether the expanded surface would be a better fit for that interaction. If you do implement a modal inside your widget, if you are using Fluent UI React v9 use the Dialog or Popover components rather than a custom implementation, as they handle focus trapping, focus restoration, and ARIA attributes correctly out of the box. For custom modal behavior, useModalAttributes is available.
Focus restoration: When an element is removed from the DOM after a user action (for example, after submitting a form or closing a panel), focus must be restored to a logical element rather than dropping to the document body. Use Fluent V9's useRestoreFocusSource and useRestoreFocusTarget hooks to handle this automatically.
| ✅ Do | ❌ Don't |
|---|---|
|
|
Screen reader semantics
Widgets must expose meaningful structure and semantics so that screen readers and other assistive technologies can correctly interpret and announce content.
Semantic HTML
Use native HTML elements whenever possible, such as <button>, <input>, <label>, <ul>, <li>, <nav>, and <form>.
Role, name, state
All interactive elements must have:
- A meaningful role (native or ARIA)
- An accessible name (visible text,
aria-label, oraria-labelledby) - Accurate state and property information (for example,
aria-expanded,aria-checked,aria-selected,aria-disabled)
Dynamic updates
Use live regions to announce important changes to screen readers:
aria-live="polite"for non-critical updates such as loading resultsaria-live="assertive"for critical updates such as errors
If you are using Fluent V9 and React, use AriaLiveAnnouncer with the useAnnounce hook rather than implementing raw aria-live regions. If your widget includes text inputs and needs to announce updates while the user is typing, use useTypingAnnounce instead.
Images
Images that convey meaning must include descriptive alt text. Decorative images should be marked with empty alt="" or hidden from assistive technologies.
| ✅ Do | ❌ Don't |
|---|---|
|
|
Focus management
Because widgets are embedded in a conversational experience, focus behavior within the widget must be predictable and must not disrupt the user's workflow in chat.
No focus stealing
Widgets must not automatically move focus within the iframe when they load. Focus should remain where Teams has placed it until the user explicitly interacts with the widget.
Initial focus
When the user moves focus into the widget, focus should land on the first meaningful interactive element, not on a hidden or non-interactive element.
Dialogs and overlays
If the widget opens a modal dialog:
- Move focus into the dialog when it opens
- Trap focus within the dialog while it's open
- Return focus to the triggering element when the dialog closes
Color, contrast, and high contrast mode
Widgets must remain perceivable in different contrast settings, including Windows High Contrast Mode.
Text contrast
Text and essential icons must meet WCAG 2.2 AA contrast ratios:
- At least 4.5:1 for normal text
- At least 3:1 for large text (18pt or 14pt bold and above)
High contrast mode
Test your widget in Windows High Contrast Mode and ensure that interactive elements, focus indicators, and key icons remain visible and understandable. While not required at submission, High Contrast support is strongly recommended to ensure your widget is usable by people who rely on this accessibility setting.
Color independence
Don't rely on color alone to convey meaning. Use text, icons, patterns, or other indicators in addition to color.
| ✅ Do | ❌ Don't |
|---|---|
|
|
Responsive layout and zoom
Widgets must adapt to the chat container and remain usable at different zoom levels and viewport sizes.
- Zoom support: Text and interactive controls must remain readable and operable at 200% browser zoom. Fixed-aspect content — such as data visualizations, embedded media, maps, or canvas-based rendering — is exempt where zoom would inherently distort the experience. In these cases, ensure the content remains accessible through alternative means such as descriptive alt text, data tables, or captions.
- Flexible layout: Avoid fixed pixel heights — allow the widget to grow vertically as needed so content isn't clipped.
- Horizontal scrolling: Avoid horizontal scrolling for primary widget content. Layout should adapt to the narrow widths typical of chat containers. Intentional horizontal scrolling for specific content types such as wide data tables or carousels is acceptable.
Motion, animation, and timing
Motion and animation must not cause discomfort or interfere with usability.
- Reduced motion: Respect the user's
prefers-reduced-motionsetting by reducing or disabling non-essential animations - Safe motion: Avoid flashing content or rapid animations that could trigger photosensitive reactions
- Auto-advancing content: Don't auto-advance carousels or content without user input. If auto-advance is necessary, provide controls to pause, stop, and manually navigate
Error handling inside the widget
Note
Teams handles renderer-level loading and error states — the outer states shown when the widget itself fails to load or render. Partners are responsible for accessible error handling within their own widget content.
Announcements
Use aria-live="assertive" or an appropriate live region to announce critical errors to screen readers. If using Fluent UI React v9, use useAnnounce with polite: false for error announcements.
Clear messaging
Error messages must:
- Describe what went wrong in clear, concise language
- Explain how the user can fix the issue or try again
Input errors
For invalid fields:
- Set
aria-invalid="true"on the input - Associate the error message with the input using
aria-describedbyor a similar mechanism
Loading states inside the widget
Note
Teams handles the widget-level loading state. The requirements below apply to any loading states that occur within your widget content after the initial render.
- Visible indicator: Show a clear loading indicator when your widget fetches or processes data after the initial render.
- Announcements: Use
aria-live="polite"to announce loading and completion states to screen readers. If using Fluent UI React v9, use useAnnounce withpolite: true. - Focus behavior: Don't trap focus during loading — users must still be able to move focus within the widget.
- Skeleton UI: If you use skeleton screens, either hide them from assistive technologies using
aria-hidden="true", or provide meaningful labels that describe the loading state.
Testing guidance
Partners should validate accessibility before submission using the three-step workflow below. Because widgets run inside a sandboxed iframe, open your widget content directly in a browser tab before running any automated tools — most tools cannot scan iframe content by default.
Step 1 — Run an automated scan
Start with an automated scan to catch the most common issues quickly. Automated tools typically identify 30–40% of accessibility issues, so manual testing is required in addition.
| Tool | Type | Notes |
|---|---|---|
| Lighthouse | Browser (Chrome DevTools) | Built into Chrome — a good starting point for catching missing labels, contrast failures, and structural issues. No install required. Run first. |
| axe DevTools | Browser extension | More detailed than Lighthouse. The free version covers a broader range of WCAG violations with clearer remediation guidance. |
| WAVE | Browser extension | Visual overlay that highlights issues directly on the page. Useful for quickly spotting missing alt text, form labels, and heading structure. |
Step 2 — Verify contrast manually
Automated tools don't always catch contrast failures reliably. After your automated scan, verify color contrast manually using either of these tools:
| Tool | Type | Notes |
|---|---|---|
| Colour Contrast Analyser | Desktop tool | Sample any two colors directly on screen and check against WCAG AA ratios. |
| WebAIM Contrast Checker | Web-based | Enter hex values to verify text and background combinations. No install required. |
Step 3 — Manual testing
Manual testing is required to verify keyboard behavior, screen reader output, and visual adaptability. Work through each test in order:
| Test type | What to verify |
|---|---|
| Keyboard-only | Navigate the entire widget using only Tab, Shift+Tab, arrow keys, Enter, and Space. Verify no focus traps and a logical tab order throughout. |
| Screen reader | Test with at least one screen reader — Narrator or NVDA on Windows, VoiceOver on Mac. Verify all elements are announced meaningfully. |
| Zoom | Increase browser zoom to 200% and confirm text and interactive controls remain fully usable. |
| Reduced motion | Enable reduced motion in OS settings and verify animations are minimized or disabled. |
| Responsive | Test at narrow viewport widths representative of Teams chat container widths. In Teams on iOS and Android, test both portrait and landscape orientations. Verify that primary content isn't clipped and actions are usable by touch without relying on hover. See Responsive scaling. |
| High Contrast | Enable Windows High Contrast Mode and verify content, controls, and focus indicators remain visible. |