Accessibility guidelines for HTML widgets in Microsoft Teams

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.

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-describedby and 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
  • Use Fluent UI React v9 Dialog or Popover for modal experiences
  • Restore focus to the triggering element after a dialog or panel closes
  • Don't remove focus outlines without providing an accessible alternative
  • Don't auto-advance focus between controls without a clear user action

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, or aria-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 results
  • aria-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
  • Use headings (<h1>–<h3>) to structure content and help screen reader users navigate
  • Treat the widget as a self-contained web application — don't rely on Teams to provide roles or labels for content inside the iframe
  • Don't use generic <div> or <span> elements as controls without roles and labels
  • Don't override correct native semantics with ARIA when native elements already provide the needed behavior

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
  • Test in Windows High Contrast Mode before submission
  • Pair color with a label or icon to communicate state
  • Use Fluent UI React v9 color tokens for backgrounds, borders, and text
  • Don't use low-contrast text or icons for critical information
  • Don't use placeholder text as the only label for an input
  • Don't hardcode color values — use Fluent UI React v9 color tokens or CSS variables so your widget adapts to Teams themes

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-motion setting 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-describedby or 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 with polite: 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.