diff --git a/msteams-platform/TOC.yml b/msteams-platform/TOC.yml
index 0bb84f213b6..020ccac3231 100644
--- a/msteams-platform/TOC.yml
+++ b/msteams-platform/TOC.yml
@@ -877,6 +877,17 @@
       - name: Use dialogs from bots
         href: task-modules-and-cards/task-modules/task-modules-bots.md
         displayName: create dialogue box, invoke dialog, submit action 
+  - name: Build HTML widgets
+    items:
+    - name: Overview
+      href: html-widgets/integrate-web-apps-overview.md
+      displayName: widgets
+    - name: User experience guidelines
+      href: html-widgets/user-experience-guidelines.md
+      displayName: widgets
+    - name: Accessibility guidelines
+      href: html-widgets/accessibility-guidelines.md
+      displayName: widgets, WCAG, MCP apps, iframe, assistive, ARIA, fluent, screen reader, contrast
   - name: Integrate with Teams
     items:
     - name: Web app integration
diff --git a/msteams-platform/html-widgets/accessibility-guidelines.md b/msteams-platform/html-widgets/accessibility-guidelines.md
new file mode 100644
index 00000000000..8dfdbf633a4
--- /dev/null
+++ b/msteams-platform/html-widgets/accessibility-guidelines.md
@@ -0,0 +1,343 @@
+---
+title: Accessibility Guidelines for HTML Widgets in Teams
+author: Suzanne Tocco
+description: TODO
+ms.topic: article
+ms.date: 05/27/2026
+---
+
+
+# Accessibility guidelines for HTML widgets in Microsoft Teams 365
+
+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](https://www.w3.org/TR/WCAG22/) and the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/).
+
+> [!TIP]
+> If you are building your widget with React, we recommend using [Fluent UI React v9](https://storybooks.fluentui.dev/react/?path=/docs/concepts-introduction--docs) 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-describedby` and ensure they're available on focus as well as hover
+- **Tooltips:** Use [Fluent UI React v9 ](https://storybooks.fluentui.dev/react/?path=/docs/concepts-introduction--docs) 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 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Teams | Partner |
+|-------------------------------------------|:-----:|:-------:|
+| Widget container label (e.g. "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 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 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](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/deploy-and-publish/appsource/publish)
+
+
+
+### 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](https://www.w3.org/WAI/ARIA/apg/) 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](https://storybooks.fluentui.dev/react/?path=/docs/components-dialog--docs) or [Popover](https://storybooks.fluentui.dev/react/?path=/docs/components-popover--docs) 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](https://storybooks.fluentui.dev/react/?path=/docs/utilities-focus-management-usemodalattributes--docs)  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](https://storybooks.fluentui.dev/react/?path=/docs/utilities-focus-management-userestorefocussource--docs) hooks to handle this automatically.
+
+
+
+<table>
+<tr>
+<th align="left">✅ Do</th>
+<th align="left">❌ Don't</th>
+</tr>
+<tr>
+<td>
+
+- Use Fluent UI React v9 Dialog or Popover for modal experiences
+- Restore focus to the triggering element after a dialog or panel closes
+
+</td>
+<td>
+
+- Don't remove focus outlines without providing an accessible alternative
+- Don't auto-advance focus between controls without a clear user action
+
+</td>
+</tr>
+</table>
+
+## 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](https://storybooks.fluentui.dev/react/?path=/docs/utilities-aria-live-arialiveannouncer--docs) with the [useAnnounce](https://storybooks.fluentui.dev/react/?path=/docs/utilities-aria-live-useannounce--docs) 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](https://storybooks.fluentui.dev/react/?path=/docs/utilities-aria-live-usetypingannounce--docs) instead.
+
+**Images**
+
+Images that convey meaning must include descriptive `alt` text. Decorative images should be marked with empty `alt=""` or hidden from assistive technologies.
+
+
+<table>
+<tr>
+<th align="left">✅ Do</th>
+<th align="left">❌ Don't</th>
+</tr>
+<tr>
+<td>
+
+- 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
+
+</td>
+<td>
+
+- 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
+
+</td>
+</tr>
+</table>
+
+
+
+
+## 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](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html):
+
+- 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.
+
+<table>
+<tr>
+<th align="left">✅ Do</th>
+<th align="left">❌ Don't</th>
+</tr>
+<tr>
+<td>
+
+- 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](https://storybooks.fluentui.dev/react/?path=/docs/theme-colors--docs) for backgrounds, borders, and text
+
+</td>
+<td>
+
+- 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](https://storybooks.fluentui.dev/react/?path=/docs/theme-colors--docs) or CSS variables so your widget adapts to Teams themes
+
+</td>
+</tr>
+</table>
+
+
+## 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](https://storybooks.fluentui.dev/react/?path=/docs/utilities-aria-live-useannounce--docs) 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 initial render.
+
+- **Visible indicator:** Show a clear loading indicator when your widget fetches or processes data after initial render
+- **Announcements:** Use `aria-live="polite"` to announce loading and completion states to screen readers. If using Fluent UI React v9, use [useAnnounce](https://storybooks.fluentui.dev/react/?path=/docs/utilities-aria-live-useannounce--docs) 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](https://developer.chrome.com/docs/lighthouse) | Browser (Chrome DevTools) | Built into Chrome — good starting point for catching missing labels, contrast failures, and structural issues. No install required. Run first. |
+| [axe DevTools](https://www.deque.com/axe/devtools/) | Browser extension | More detailed than Lighthouse. Free version covers a broader range of WCAG violations with clearer remediation guidance. |
+| [WAVE](https://wave.webaim.org/extension/) | 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](https://www.tpgi.com/color-contrast-checker/) | Desktop tool | Sample any two colors directly on screen and check against WCAG AA ratios. |
+| [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) | 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. |
+| High contrast | Enable Windows High Contrast Mode and verify content, controls, and focus indicators remain visible. |
+
+## Related content
+
+- [HTML widgets overview for Microsoft Teams](#)
+- [UX guidelines for HTML widgets in Microsoft Teams](#)
+- [Teams store validation guidelines](#)
+- [Fluent UI React v9](https://storybooks.fluentui.dev/react/?path=/docs/concepts-introduction--docs)
+- [Fluent UI React v9 components](https://react.fluentui.dev/)
+- [WCAG 2.2 contrast requirements](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
diff --git a/msteams-platform/html-widgets/images/ThemeModes.png b/msteams-platform/html-widgets/images/ThemeModes.png
new file mode 100644
index 00000000000..7dbea8c697d
Binary files /dev/null and b/msteams-platform/html-widgets/images/ThemeModes.png differ
diff --git a/msteams-platform/html-widgets/images/borderRadiusStyles.png b/msteams-platform/html-widgets/images/borderRadiusStyles.png
new file mode 100644
index 00000000000..1f175ec5f2d
Binary files /dev/null and b/msteams-platform/html-widgets/images/borderRadiusStyles.png differ
diff --git a/msteams-platform/html-widgets/images/borderShapeExamples.png b/msteams-platform/html-widgets/images/borderShapeExamples.png
new file mode 100644
index 00000000000..4d44477e94f
Binary files /dev/null and b/msteams-platform/html-widgets/images/borderShapeExamples.png differ
diff --git a/msteams-platform/html-widgets/images/cardAnatomy.png b/msteams-platform/html-widgets/images/cardAnatomy.png
new file mode 100644
index 00000000000..e1669a1e786
Binary files /dev/null and b/msteams-platform/html-widgets/images/cardAnatomy.png differ
diff --git a/msteams-platform/html-widgets/images/container_accent.png b/msteams-platform/html-widgets/images/container_accent.png
new file mode 100644
index 00000000000..f3b47343d3e
Binary files /dev/null and b/msteams-platform/html-widgets/images/container_accent.png differ
diff --git a/msteams-platform/html-widgets/images/container_attention.png b/msteams-platform/html-widgets/images/container_attention.png
new file mode 100644
index 00000000000..31dec7d733e
Binary files /dev/null and b/msteams-platform/html-widgets/images/container_attention.png differ
diff --git a/msteams-platform/html-widgets/images/container_default.png b/msteams-platform/html-widgets/images/container_default.png
new file mode 100644
index 00000000000..60c59a8910e
Binary files /dev/null and b/msteams-platform/html-widgets/images/container_default.png differ
diff --git a/msteams-platform/html-widgets/images/container_emphasis.png b/msteams-platform/html-widgets/images/container_emphasis.png
new file mode 100644
index 00000000000..63e93dc4d42
Binary files /dev/null and b/msteams-platform/html-widgets/images/container_emphasis.png differ
diff --git a/msteams-platform/html-widgets/images/container_gallery.png b/msteams-platform/html-widgets/images/container_gallery.png
new file mode 100644
index 00000000000..70ece52c4f2
Binary files /dev/null and b/msteams-platform/html-widgets/images/container_gallery.png differ
diff --git a/msteams-platform/html-widgets/images/container_good.png b/msteams-platform/html-widgets/images/container_good.png
new file mode 100644
index 00000000000..a4acd98bed7
Binary files /dev/null and b/msteams-platform/html-widgets/images/container_good.png differ
diff --git a/msteams-platform/html-widgets/images/container_warning.png b/msteams-platform/html-widgets/images/container_warning.png
new file mode 100644
index 00000000000..5b037603caf
Binary files /dev/null and b/msteams-platform/html-widgets/images/container_warning.png differ
diff --git a/msteams-platform/html-widgets/images/expanded_surface.png b/msteams-platform/html-widgets/images/expanded_surface.png
new file mode 100644
index 00000000000..46cd98c562f
Binary files /dev/null and b/msteams-platform/html-widgets/images/expanded_surface.png differ
diff --git a/msteams-platform/html-widgets/images/icon-arrow.png b/msteams-platform/html-widgets/images/icon-arrow.png
new file mode 100644
index 00000000000..d380bbe345b
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-arrow.png differ
diff --git a/msteams-platform/html-widgets/images/icon-arrowUp.png b/msteams-platform/html-widgets/images/icon-arrowUp.png
new file mode 100644
index 00000000000..db5b7e37ce8
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-arrowUp.png differ
diff --git a/msteams-platform/html-widgets/images/icon-button.png b/msteams-platform/html-widgets/images/icon-button.png
new file mode 100644
index 00000000000..2280ee960a8
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-button.png differ
diff --git a/msteams-platform/html-widgets/images/icon-conversastion-bubble.png b/msteams-platform/html-widgets/images/icon-conversastion-bubble.png
new file mode 100644
index 00000000000..02a9401da23
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-conversastion-bubble.png differ
diff --git a/msteams-platform/html-widgets/images/icon-magnifyingGlass.png b/msteams-platform/html-widgets/images/icon-magnifyingGlass.png
new file mode 100644
index 00000000000..edeaa758341
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-magnifyingGlass.png differ
diff --git a/msteams-platform/html-widgets/images/icon-mouse.png b/msteams-platform/html-widgets/images/icon-mouse.png
new file mode 100644
index 00000000000..576da28d432
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-mouse.png differ
diff --git a/msteams-platform/html-widgets/images/icon-puzzle.png b/msteams-platform/html-widgets/images/icon-puzzle.png
new file mode 100644
index 00000000000..0e41595a330
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-puzzle.png differ
diff --git a/msteams-platform/html-widgets/images/icon-shield.png b/msteams-platform/html-widgets/images/icon-shield.png
new file mode 100644
index 00000000000..01bd7f93648
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon-shield.png differ
diff --git a/msteams-platform/html-widgets/images/icon_colorBrush.png b/msteams-platform/html-widgets/images/icon_colorBrush.png
new file mode 100644
index 00000000000..3c09ee3a8e8
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon_colorBrush.png differ
diff --git a/msteams-platform/html-widgets/images/icon_icon.png b/msteams-platform/html-widgets/images/icon_icon.png
new file mode 100644
index 00000000000..0cf169cec78
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon_icon.png differ
diff --git a/msteams-platform/html-widgets/images/icon_shapes.png b/msteams-platform/html-widgets/images/icon_shapes.png
new file mode 100644
index 00000000000..680e3ffead4
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon_shapes.png differ
diff --git a/msteams-platform/html-widgets/images/icon_spacing.png b/msteams-platform/html-widgets/images/icon_spacing.png
new file mode 100644
index 00000000000..362d2192451
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon_spacing.png differ
diff --git a/msteams-platform/html-widgets/images/icon_text.png b/msteams-platform/html-widgets/images/icon_text.png
new file mode 100644
index 00000000000..9cb407c7be4
Binary files /dev/null and b/msteams-platform/html-widgets/images/icon_text.png differ
diff --git a/msteams-platform/html-widgets/images/icons.png b/msteams-platform/html-widgets/images/icons.png
new file mode 100644
index 00000000000..9b58ef621d5
Binary files /dev/null and b/msteams-platform/html-widgets/images/icons.png differ
diff --git a/msteams-platform/html-widgets/images/icontext.png b/msteams-platform/html-widgets/images/icontext.png
new file mode 100644
index 00000000000..6e0d6ac357a
Binary files /dev/null and b/msteams-platform/html-widgets/images/icontext.png differ
diff --git a/msteams-platform/html-widgets/images/input_examples.png b/msteams-platform/html-widgets/images/input_examples.png
new file mode 100644
index 00000000000..354f7a8f2cc
Binary files /dev/null and b/msteams-platform/html-widgets/images/input_examples.png differ
diff --git a/msteams-platform/html-widgets/images/progressiveDisclosure.png b/msteams-platform/html-widgets/images/progressiveDisclosure.png
new file mode 100644
index 00000000000..0e5e1f48ae7
Binary files /dev/null and b/msteams-platform/html-widgets/images/progressiveDisclosure.png differ
diff --git a/msteams-platform/html-widgets/images/responsive.png b/msteams-platform/html-widgets/images/responsive.png
new file mode 100644
index 00000000000..5fa1c2de1df
Binary files /dev/null and b/msteams-platform/html-widgets/images/responsive.png differ
diff --git a/msteams-platform/html-widgets/images/spacing.png b/msteams-platform/html-widgets/images/spacing.png
new file mode 100644
index 00000000000..8bd648e8412
Binary files /dev/null and b/msteams-platform/html-widgets/images/spacing.png differ
diff --git a/msteams-platform/html-widgets/images/textColorExamples.png b/msteams-platform/html-widgets/images/textColorExamples.png
new file mode 100644
index 00000000000..1bcfabba8e1
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColorExamples.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_accent.png b/msteams-platform/html-widgets/images/textColor_accent.png
new file mode 100644
index 00000000000..d551af6710f
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_accent.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_attention.png b/msteams-platform/html-widgets/images/textColor_attention.png
new file mode 100644
index 00000000000..6d18c98bd1e
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_attention.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_dark.png b/msteams-platform/html-widgets/images/textColor_dark.png
new file mode 100644
index 00000000000..6105c279c95
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_dark.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_default.png b/msteams-platform/html-widgets/images/textColor_default.png
new file mode 100644
index 00000000000..6105c279c95
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_default.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_good.png b/msteams-platform/html-widgets/images/textColor_good.png
new file mode 100644
index 00000000000..394abca82bb
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_good.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_light.png b/msteams-platform/html-widgets/images/textColor_light.png
new file mode 100644
index 00000000000..526cd9f6547
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_light.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_subtle.png b/msteams-platform/html-widgets/images/textColor_subtle.png
new file mode 100644
index 00000000000..43c1ce02c4e
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_subtle.png differ
diff --git a/msteams-platform/html-widgets/images/textColor_warning.png b/msteams-platform/html-widgets/images/textColor_warning.png
new file mode 100644
index 00000000000..4c20e90a6eb
Binary files /dev/null and b/msteams-platform/html-widgets/images/textColor_warning.png differ
diff --git a/msteams-platform/html-widgets/images/themes.png b/msteams-platform/html-widgets/images/themes.png
new file mode 100644
index 00000000000..072cd57a6d9
Binary files /dev/null and b/msteams-platform/html-widgets/images/themes.png differ
diff --git a/msteams-platform/html-widgets/images/typography.png b/msteams-platform/html-widgets/images/typography.png
new file mode 100644
index 00000000000..73fbd82ec3e
Binary files /dev/null and b/msteams-platform/html-widgets/images/typography.png differ
diff --git a/msteams-platform/html-widgets/overview.md b/msteams-platform/html-widgets/overview.md
new file mode 100644
index 00000000000..d966b1acb9e
--- /dev/null
+++ b/msteams-platform/html-widgets/overview.md
@@ -0,0 +1,9 @@
+---
+title: TODO
+author: SuzanneTocco
+description: TODO
+ms.topic: article
+ms.date: 05/27/2026
+---
+
+TODO
diff --git a/msteams-platform/html-widgets/playground.md b/msteams-platform/html-widgets/playground.md
new file mode 100644
index 00000000000..880861e3256
--- /dev/null
+++ b/msteams-platform/html-widgets/playground.md
@@ -0,0 +1,334 @@
+---
+title: UX guidelines for HTML widgets in Microsoft Teams
+author: Suzanne Tocco
+description: UX guidance for partners building HTML widgets in Microsoft Teams chat, including design principles, visual design recommendations, and a minimum quality bar for submission.
+ms.topic: article
+ms.date: 06/01/2026
+---
+
+# UX guidelines for HTML widgets in Microsoft Teams
+
+This guide provides UX guidance for partners building HTML widgets in Microsoft Teams. It covers principles and recommendations for creating focused, high-quality widget experiences that integrate naturally into the Teams chat conversation. The goal is not to enforce a single visual style, but to ensure that widgets feel intentional and work well in the Teams context.
+
+---
+
+## UX principles
+
+Building a great widget for Teams means delivering a focused experience that surfaces the right information or action at the right time. HTML widgets should feel like a natural part of the Teams conversation — not an application embedded inside it.
+
+<table>
+<tr>
+<td width="50%">
+<img src="images/icon-conversation-bubble.png" alt="" width="48"><br><br>
+<b>Complement the conversation</b>
+- Widgets exist alongside agent-generated text in a chat thread and should always feel like a natural part of the conversation.
+- A widget may be display-only, interactive, or prompt the user for input.
+- Content should support the conversation, not feel like a separate or disconnected experience.
+</td>
+<td width="50%">
+<img src="images/icon-puzzle.png" alt="" width="48"><br><br>
+<b>Surface capabilities, not full apps</b>
+Avoid embedding your full application experience inside a widget. Instead, identify the single most valuable thing a user needs in this moment.
+- A widget should expose a focused, high-value capability — not your entire product.
+- Each widget should represent a single, focused interaction.
+</td>
+</tr>
+<tr>
+<td width="50%">
+<img src="images/icon-mouse.png" alt="" width="48"><br><br>
+<b>Be transparent and predictable</b>
+- Widget content should be clear and any interactions obvious.
+- Users should always understand what a widget is showing.
+- The expected outcome of any interaction should be obvious before the user acts.
+</td>
+<td width="50%">
+<img src="images/icon-arrowUp.png" alt="" width="48"><br><br>
+<b>Scale to the task</b>
+Match the visual footprint of your widget to what the user needs in the moment.
+- Widgets always appear inline in the chat.
+- If your widget contains rich content or a deeper workflow that would benefit from more space, consider building in an expand function to open the widget in a larger view.
+</td>
+</tr>
+<tr>
+<td width="50%">
+<img src="images/icon-shield.png" alt="" width="48"><br><br>
+<b>Preserve human control</b>
+Trust matters, especially when widget actions affect data or trigger external workflows.
+- Allow users to remain in control of their experience.
+- Make it clear what the widget is doing.
+- Confirm important actions before they happen.
+- Always communicate the expected outcome.
+</td>
+<td width="50%">
+</td>
+</tr>
+</table>
+
+---
+
+## Understanding the chat surface
+
+HTML widgets render inline inside a Teams chat message. Understanding this context is essential before making design decisions.
+
+When designing for Teams, follow these core principles:
+
+- **Conversation-first:** The chat remains the primary interaction model. The widget supports it.
+- **Progressive complexity:** Start lightweight. Move to the expanded surface only when needed.
+- **Context preservation:** Users should not lose conversational context when interacting with a widget.
+- **Clarity over duplication:** Widget content and agent body text should complement each other — not repeat the same information.
+
+Keep in mind:
+
+- The widget appears inside a chat thread, alongside the agent's text response and other messages
+- Users are in a conversational mindset — they expect lightweight, focused interactions
+- One or more widgets may appear in the same message, combined with optional body text in any order
+- The same widget may render across multiple platforms — Teams, ChatGPT, Claude, and others
+
+---
+
+## Widget anatomy
+
+Many widgets follow a common pattern that helps users orient quickly — but not every widget needs all of these elements, and some widgets (such as maps, charts, or forms) may not follow this structure at all.
+
+| Element | Description | Notes |
+|---|---|---|
+| **Title** | Identifies the widget or what it represents | Gives users an immediate sense of what the widget is and what to expect, helping it stand out clearly within the conversation |
+| **Body content** | The primary information, media, or interactive content | The core of most widgets — may be the only element present |
+| **Actions** | Buttons, links, or other interactive elements that let the user take the next step | Optional. Interactive elements may appear throughout the widget, not only at the bottom — but when a widget includes a dedicated action area, it's typically placed at the bottom |
+
+When a widget does follow this common pattern, content typically flows top to bottom:
+
+1. Title (if applicable)
+2. Primary content — key information, data, or media
+3. Secondary content — supporting details, metadata
+4. Action area (if present) — placed at the bottom
+
+---
+
+## Required
+
+The following requirements apply to all HTML widgets submitted to Teams. Widgets that don't meet these requirements may be rejected or require remediation before publishing.
+
+### Theme support (light and dark mode)
+
+Widgets must render correctly in both Teams light mode and dark mode.
+
+- Test your widget in both themes before submission
+- Use CSS variables or [Fluent 2](https://fluent2.microsoft.design/color) color tokens rather than hardcoded hex values so your widget adapts automatically to theme changes
+
+> [!NOTE]
+> Theme adaptation is not required for content where color is meaningful and should not be altered, such as design documents, branded presentations, data visualizations, or media where color carries specific meaning. In these cases, render the content as-is.
+
+### Responsive scaling
+
+Widgets must adapt to the width of the chat container.
+
+- Use flexible, fluid layouts rather than fixed pixel widths
+- Avoid fixed pixel heights — allow the widget to grow vertically as content requires
+- Test at multiple viewport widths representative of Teams chat on desktop and mobile
+
+### Horizontal scrolling
+
+Avoid horizontal scrolling for primary widget content. Layout should adapt to the narrow widths typical of chat containers.
+
+> [!NOTE]
+> Horizontal scrolling may be used intentionally for specific content types such as wide data tables, media carousels, or timelines where horizontal navigation is a meaningful part of the experience. These cases should be intentional, not a result of fixed-width layouts.
+
+### Feedback and confirmation
+
+Widgets must communicate the outcome of user actions clearly.
+
+- Confirm successful actions with a visible success state inside the widget
+- Show a clear error state with a recovery option when an action fails
+- Show a loading indicator when the widget is fetching or processing data internally
+- Do not rely on the agent's body text alone to communicate widget state
+
+> [!NOTE]
+> Teams handles the widget-level loading and error states. The requirements above apply to state handling within your widget content.
+
+---
+
+## Strongly recommended
+
+The following guidance is strongly recommended to help your widget feel at home in Teams. Partners may deviate for legitimate brand or design reasons, but should do so intentionally.
+
+### Visual design
+
+#### Colors and theming
+
+Use [Fluent 2](https://fluent2.microsoft.design/color) color tokens for backgrounds, borders, and text. This ensures your widget responds correctly to Teams themes without additional work.
+
+- Use your brand color sparingly — as an accent for primary actions and key elements, not as a dominant background color
+- Never rely on color alone to convey meaning — always pair color with a label, icon, or other indicator
+
+[Fluent 2 > Color](https://fluent2.microsoft.design/color)
+
+#### Typography
+
+Map your widget's text styles to the following recommended values, which align with Teams Adaptive Card host configuration styles.
+
+| Style | Size | Weight | Use for |
+|---|---|---|---|
+| Title | 16px | Semibold | Widget or entity title |
+| Subtitle | 14px | Semibold | Section headers, secondary titles |
+| Body | 14px | Regular | Primary content and descriptions |
+| Caption / metadata | 12px | Regular | Supporting details, timestamps, labels |
+
+- Use a maximum of three distinct text sizes in a single widget to maintain visual hierarchy
+- Allow text blocks to wrap by default — avoid truncating body content unless space is genuinely constrained
+
+[Fluent 2 > Typography](https://fluent2.microsoft.design/typography)
+
+#### Containers and borders
+
+- Use subtle background fills to group related content
+- Use border radius values consistent with [Fluent 2 shapes](https://fluent2.microsoft.design/shapes#corner-radius) for containers and images
+- Avoid deep nesting — limit container and column nesting to a maximum of two levels
+
+[Fluent 2 > Shapes](https://fluent2.microsoft.design/shapes#corner-radius)
+
+#### Spacing
+
+- Use 16px internal padding on all sides as a baseline for widget content
+- Use 8px spacing between related elements and 16px between distinct content sections
+- Give content room to breathe — overcrowded widgets feel lower quality and are harder to scan
+
+#### Iconography
+
+Use [Fluent 2 icons](https://fluent2.microsoft.design/iconography) rather than custom or third-party icon sets where possible. Fluent icons are recognized by Teams users and scale correctly at standard sizes.
+
+[Fluent 2 > Iconography](https://fluent2.microsoft.design/iconography)
+
+### Actions
+
+Actions allow users to take the next step without leaving the conversation.
+
+- **Limit to two primary actions** — use a primary button for the most important action and a secondary button for an alternative
+- **Use overflow for additional actions** — place additional actions in an overflow menu (`•••`) rather than adding more buttons
+- **Label actions clearly** — use outcome-oriented labels such as "Reserve now" rather than "Submit" or "OK"
+- **Disable, don't hide** — if an action is not available in the current state, disable the control rather than hiding it
+
+> [!TIP]
+> If you are building with React, [Fluent 2 button components](https://fluent2.microsoft.design/components/web/react/core/button/usage) implement the correct Teams-aligned button styles and states out of the box.
+
+[Fluent 2 > Button](https://fluent2.microsoft.design/components/web/react/core/button/usage)
+
+### Content and layout
+
+- **Be concise:** A widget should be glanceable. Users should understand the key information without scrolling within the widget
+- **Show summaries, not systems:** Surface the most relevant data for the current context rather than full data tables, dashboards, or navigation trees
+- **Avoid internal scrolling:** If content requires scrolling, consider whether it belongs in the expanded surface instead
+- **Avoid deep navigation:** Tabs, drill-down menus, and multi-level navigation are not appropriate for the inline widget
+- **Don't duplicate content:** Widget content and agent body text should complement each other — do not repeat the same information in both
+
+### Progressive disclosure
+
+Not all information needs to be visible at once. Use progressive disclosure to keep widgets concise while allowing users to access more detail when needed.
+
+- Use show/hide toggles for secondary or supporting information
+- Use scrolling within a defined container for longer content lists — ensure the container has a clear label and is keyboard accessible
+- Transition to the expanded surface for content that requires significant vertical space or multi-step interaction
+
+### Input gathering
+
+If your widget includes a form or input fields:
+
+- Label all fields clearly — use visible labels, not placeholder text alone
+- Indicate required fields
+- Validate input inline and surface error messages adjacent to the relevant field
+- Keep forms short — if a form requires more than four or five fields, consider moving it to the expanded surface
+
+---
+
+## Expanded surface
+
+The expanded surface opens as a modal above the chat when the user taps an expand button. Use it for content or workflows that require more space than the inline widget can reasonably provide.
+
+### When to use the expanded surface
+
+- Multi-step forms or configuration flows
+- Rich media that benefits from a larger canvas
+- Detailed data tables or comparison views
+- Iterative workflows with persistent state
+
+### Interaction guidelines
+
+- **Use expansion intentionally** — not every widget needs an expanded view. Reserve it for content that genuinely benefits from more space
+- **Don't replicate your full application** — the expanded surface is a focused workspace for a specific task, not a product shell. Avoid global navigation, settings panels, or unrelated features
+- **Scope to one task** — the expanded surface should support a single coherent workflow
+- **Preserve context** — the chat remains visible when the expanded surface is open. Design the expanded content to work alongside the conversation
+
+---
+
+## Best practices
+
+<table>
+<tr>
+<th align="left">✅ Do</th>
+<th align="left">❌ Don't</th>
+</tr>
+<tr>
+<td>
+- Keep widgets lightweight and action-oriented
+- Support up to two primary actions
+- Use the expanded surface for deep navigation or multi-step workflows
+- Use [Fluent 2](https://fluent2.microsoft.design/) components, spacing, typography, and tokens
+- Show loading indicators, success confirmations, and error states with recovery options
+- Allow text to wrap by default
+- Use outcome-oriented action labels such as "Reserve now" or "Approve request"
+</td>
+<td>
+- Don't embed a full application experience inside a widget
+- Don't recreate Teams chat capabilities such as prompt input or retry controls
+- Don't use multiple tabs or nested navigation — use separate messages or the expanded surface instead
+- Don't hardcode colors — use Fluent 2 tokens or CSS variables
+- Don't make widgets taller than the viewport
+- Don't repeat the same information in both the widget and the agent's body text
+- Don't use generic action labels like "Submit" or "OK"
+</td>
+</tr>
+</table>
+
+---
+
+## Nice to have
+
+The following items are optional but contribute to a higher-quality widget experience.
+
+- **Use Fluent 2 components**: [Fluent 2](https://fluent2.microsoft.design/) components implement Teams-aligned visual patterns and interactions out of the box. If building with React, [Fluent UI React v9](https://react.fluentui.dev/) is the recommended implementation.
+- **Support layout patterns**: Consider established layout patterns — hero (image at top, content below), article (text-heavy, hierarchical), form (input-focused), or list (repeating items) — and choose the pattern that fits your content type.
+- **Charts and data visualization**: Ensure axis labels and data points are clearly readable at widget width. Consider transitioning to the expanded surface for complex charts.
+- **Media elements**: For inline video or rich media, provide a clear play control and a static thumbnail. Autoplay is not recommended.
+- **Illustrations**: Use illustrations sparingly and purposefully. Avoid decorative illustrations that add height without adding value.
+
+---
+
+## Minimum UX bar for submission
+
+Widgets must meet all of the following requirements to be accepted.
+
+| Requirement |
+|:---|
+| ✅ Renders correctly in both Teams light mode and dark mode (exceptions apply for content where color is meaningful) |
+| ✅ Scales responsively to the chat container width without horizontal scrolling (exceptions apply for intentional horizontal scroll patterns) |
+| ✅ Provides visible feedback for loading, success, and error states within the widget |
+| ✅ Does not embed a full application experience or replicate Teams chat capabilities |
+| ✅ Limits primary actions to two buttons — additional actions placed in overflow |
+| ✅ Content and body text complement each other without duplication |
+| ✅ No placeholder, test, or broken content is visible |
+
+> [!WARNING]
+> Widgets that don't meet these requirements may be rejected or require remediation before they can be published.
+
+---
+
+## Related content
+
+- [HTML widgets overview for Microsoft Teams](#)
+- [Accessibility guidelines for HTML widgets in Microsoft Teams](#)
+- [Teams store validation guidelines](#)
+- [Fluent 2 design system](https://fluent2.microsoft.design/)
+- [Fluent UI React v9](https://react.fluentui.dev/)
+- [Fluent 2 color tokens](https://fluent2.microsoft.design/color)
+- [Fluent 2 typography](https://fluent2.microsoft.design/typography)
+- [Fluent 2 iconography](https://fluent2.microsoft.design/iconography)
diff --git a/msteams-platform/html-widgets/ux-guidelines.md b/msteams-platform/html-widgets/ux-guidelines.md
new file mode 100644
index 00000000000..40e58dfa8d1
--- /dev/null
+++ b/msteams-platform/html-widgets/ux-guidelines.md
@@ -0,0 +1,592 @@
+---
+title: UX guidelines for HTML widgets in Microsoft Teams
+author: Suzanne Tocco
+description: UX guidance for partners building HTML widgets in Microsoft Teams chat, including design principles, visual design recommendations, and a minimum quality bar for submission.
+ms.topic: article
+ms.date: 06/01/2026
+---
+
+# UX guidelines for HTML widgets in Microsoft Teams
+
+This guide provides UX guidance for partners building HTML widgets in Microsoft Teams. It covers principles and recommendations for creating focused, high-quality widget experiences that integrate naturally into the Teams chat conversation. The goal is not to enforce a single visual style, but to ensure that widgets feel intentional and work well in the Teams context.
+
+
+
+## UX principles
+
+Building a great widget for Teams means delivering a focused experience that surfaces the right information or action at the right time. HTML widgets should feel like a natural part of the Teams conversation — not an application embedded inside it.
+
+:::row:::
+  :::column:::
+    :::image type="icon" source="images/icon-conversastion-bubble.png":::
+
+    ### Complement the conversation
+
+    - Widgets exist alongside agent-generated text in a chat thread and should always feel like a natural part of the conversation.
+     - A widget may be display-only, interactive, or prompt the user for input.
+     - Content should support the conversation, not feel like a separate or disconnected experience.
+     - Design for the conversational context — a widget should provide value that is native to the moment, not simply replicate what already exists in your standalone application.
+     
+  :::column-end:::
+  :::column:::
+
+  
+    :::image type="icon" source="images/icon-puzzle.png":::
+
+    ### Surface capabilities, not full apps
+
+   Avoid embedding your full application experience inside a widget. Instead, identify the single most valuable thing a user needs in this moment.
+
+    - A widget should expose a focused, high-value capability — not your entire product.
+    - Each widget should represent a single, focused interaction.
+
+  :::column-end:::
+:::row-end:::
+
+
+
+:::row:::
+  :::column:::
+    :::image type="icon" source="images/icon-mouse.png":::
+
+    ### Be transparent and predictable
+
+     - Widget content should be clear and any interactions obvious.
+     - Users should always understand what a widget is showing.
+     - The expected outcome of any interaction should be obvious before the user acts.
+    
+  :::column-end:::
+
+  
+  :::column:::
+    :::image type="icon" source="images/icon-arrow.png":::
+
+    ### Scale to the task
+
+    Match the visual footprint of your widget to what the user needs in the moment.
+    
+     - Widgets always appear inline in the chat.
+     - Teams provides an expanded surface — a larger view that opens above the chat. If your widget contains rich content or a deeper workflow that would benefit from more space, add an expand icon to your widget's action area to enable this experience.
+
+  
+  :::column-end:::
+:::row-end:::
+
+
+:::row:::
+  :::column:::
+    :::image type="icon" source="images/icon-shield.png":::
+
+    ### Preserve human control
+
+    Trust matters, especially when widget actions affect data or trigger external workflows.
+- Allow users to remain in control of their experience.
+- Provide clear visibility into what the widget is doing and why.
+- Confirm important or sensitive actions before they happen.
+- Communicate the outcome transparently — what was created, changed, or sent.
+
+    
+  :::column-end:::
+  :::column:::
+  :::column-end:::
+:::row-end:::
+
+
+
+## Understanding the chat surface
+
+HTML widgets render inline inside a Teams chat message. Understanding this context is essential before making design decisions.
+
+When designing for Teams, follow these core principles:
+
+- **Conversation-first:** The chat remains the primary interaction model. The widget supports it.
+- **Progressive complexity:** Start lightweight. Move to the expanded surface only when needed.
+- **Context preservation:** Users should not lose conversational context when interacting with a widget.
+- **Clarity over duplication:** Widget content and agent body text should complement each other — not repeat the same information.
+
+Keep in mind:
+
+- The widget appears inside a chat thread, alongside the agent's text response and other messages
+- Users are in a conversational mindset — they expect lightweight, focused interactions
+- One or more widgets may appear in the same message, combined with optional body text in any order
+- While your widget may also render in other host platforms, use this guidance to ensure it feels intentional and native in Teams.
+
+
+> [!TIP]
+> If your widget also renders in Microsoft 365 Copilot, refer to the [UX guidelines for MCP apps in declarative agents](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/plugin-mcp-apps-ui-guidelines) for Copilot-specific guidance.
+
+
+
+
+
+## Widget anatomy
+
+Many widgets follow a common pattern that helps users orient quickly — but not every widget needs all of these elements, and some widgets (such as maps, charts, or forms) may not follow this structure at all.
+
+**Common elements**
+
+| Element | Description | Notes |
+|---|---|---|
+| **Title** | Identifies the widget or what it represents | Gives users an immediate sense of what the widget is and what to expect, helping it stand out clearly within the conversation |
+| **Body content** | The primary information, media, or interactive content | The core of most widgets — may be the only element present |
+| **Actions** | Buttons, links, or other interactive elements that let the user take the next step | Optional. Interactive elements may appear throughout the widget, not only at the bottom — but when a widget includes a dedicated action area, it's typically placed at the bottom |
+
+<p></p>
+
+<img src="images/cardAnatomy.png" alt="Diagram showing widget anatomy: title at top, body content in the middle, and action area at the bottom">
+
+When a widget does follow this common pattern, content typically flows top to bottom:
+
+1. Title (if applicable)
+2. Primary content — key information, data, or media
+3. Action area (if present) — placed at the bottom
+
+
+
+
+
+## Widget requirements
+
+The following requirements apply to all HTML widgets submitted to Teams. Widgets that don't meet these requirements may be rejected or require remediation before publishing.
+
+### Theme support (light and dark mode)
+
+Widgets must render correctly in both Teams light mode and dark mode.
+
+- Test your widget in both themes before submission
+- Use CSS variables or [Fluent 2](https://fluent2.microsoft.design/color) color tokens rather than hardcoded hex values so your widget adapts automatically to theme changes
+
+<img src="images/ThemeModes.png" alt="The same widget rendered in Teams light mode and dark mode, showing correct color adaptation in both themes">
+
+
+
+> [!NOTE]
+> Theme adaptation is not required for content where color is meaningful and should not be altered, such as design documents, branded presentations, data visualizations, or media where color carries specific meaning. In these cases, render the content as-is.
+
+
+
+
+### Responsive scaling
+
+Widgets must adapt to the width of the chat container. Teams chat containers vary in width depending on context — for example, mobile screens, a meeting chat pane, or a thread view open alongside the main chat. Unlike Adaptive Cards, which support discrete size variants that partners can customize independently, HTML widgets use a single fluid layout that scales continuously across widths. Your design should hold up gracefully at any width rather than targeting specific sizes.
+
+- Use flexible, fluid layouts rather than fixed pixel widths
+- Avoid fixed pixel heights — allow the widget to grow vertically as content requires
+- Test across a range of widths to ensure your layout holds up in common Teams contexts
+
+The widths shown below represent the most common scenarios to test against: wide, standard desktop, mobile, and meeting chat or side-by-side view. These are not breakpoints or size slots — they are reference points for evaluating how your single fluid layout scales across the range of contexts where your widget may appear.
+
+<img src="images/responsive.png" alt="A widget shown at four representative widths: wide, standard desktop, mobile, and meeting chat or side-by-side — demonstrating fluid layout scaling">
+
+
+
+
+### Horizontal scrolling
+
+Avoid horizontal scrolling for primary widget content. Layout should adapt to the narrow widths typical of chat containers.
+
+> [!TIP]
+> Horizontal scrolling may be used intentionally for specific content types such as wide data tables, media carousels, or timelines where horizontal navigation is a meaningful part of the experience. These cases should be intentional, not a result of fixed-width layouts.
+
+<br>
+
+### Feedback and confirmation
+
+Widgets must communicate the outcome of user actions clearly.
+
+- Confirm successful actions with a visible success state inside the widget
+- Show a clear error state with a recovery option when an action fails
+- Show a loading indicator when the widget is fetching or processing data internally
+- Do not rely on the agent's body text alone to communicate widget state
+
+> [!NOTE]
+> Teams handles the widget-level loading and error states. The requirements above apply to state handling within your widget content.
+
+<br>
+
+## Minimum UX bar for submission
+
+Widgets must meet all of the following requirements to be accepted by the Teams Store.
+
+| Requirement |
+|:---|
+| ✅ Renders correctly in both Teams light mode and dark mode (exceptions apply for content where color is meaningful) |
+| ✅ Scales responsively to the chat container width without horizontal scrolling (exceptions apply for intentional horizontal scroll patterns) |
+| ✅ Provides visible feedback for loading, success, and error states within the widget |
+| ✅ Delivers a focused, single-purpose experience |
+| ✅ Limits primary actions to two buttons — additional actions placed in overflow |
+| ✅ Content and body text complement each other without duplication |
+| ✅ No placeholder, test, or broken content is visible |
+
+> [!WARNING]
+> Widgets that don't meet these requirements may be rejected or require remediation before they can be published.
+
+<br>
+
+## Strongly recommended
+
+The following guidance is strongly recommended to help your widget feel at home in Teams. Partners may deviate for legitimate brand or design reasons, but should do so intentionally.
+
+### Visual design
+
+#### Colors and theming
+
+Use [Fluent 2](https://fluent2.microsoft.design/color) color tokens for backgrounds, borders, and text. This ensures your widget responds correctly to Teams themes without additional work.
+
+- Use your brand color sparingly — as an accent for primary actions and key elements, not as a dominant background color
+- Never rely on color alone to convey meaning — always pair color with a label, icon, or other indicator
+
+
+
+##### Container colors
+
+Use container color tokens to establish hierarchy and communicate status within your widget. Start with Default for your outer card surface, then nest containers inside it to group related content or surface status meaning.
+
+<table>
+<tr>
+<th>Style</th>
+<th></th>
+<th>Token</th>
+<th>Use for</th>
+</tr>
+<tr>
+<td>Default</td>
+<td><img src="images/container_default.png" alt="Default container color swatch — white background with light gray border"></td>
+<td><code>colorNeutralCardBackground</code><br><code>colorNeutralStroke2</code></td>
+<td><strong>Outer card surface</strong> — apply this token to your widget's base container to match the Teams-native card background</td>
+</tr>
+<tr>
+<td>Emphasis</td>
+<td><img src="images/container_emphasis.png" alt="Emphasis container color swatch — light gray background with medium gray border"></td>
+<td><code>colorNeutralBackground3</code><br><code>colorNeutralStroke1</code></td>
+<td>Grouped or secondary content areas — the most common inner container</td>
+</tr>
+<tr>
+<td>Accent</td>
+<td><img src="images/container_accent.png" alt="Accent container color swatch — light blue background with blue border"></td>
+<td><code>colorBrandBackground2</code><br><code>colorBrandStroke2</code></td>
+<td>Brand-accented highlights and callouts</td>
+</tr>
+<tr>
+<td>Good</td>
+<td><img src="images/container_good.png" alt="Good container color swatch — light green background with green border"></td>
+<td><code>colorPaletteLightGreenBackground1</code><br><code>colorStatusSuccessBorder1</code></td>
+<td>Confirmations and successful outcomes</td>
+</tr>
+<tr>
+<td>Warning</td>
+<td><img src="images/container_warning.png" alt="Warning container color swatch — light yellow background with yellow-brown border"></td>
+<td><code>colorPaletteMarigoldBackground1</code><br><code>colorPaletteMarigoldBorder1</code></td>
+<td>Cautions and time-sensitive alerts</td>
+</tr>
+<tr>
+<td>Attention</td>
+<td><img src="images/container_attention.png" alt="Attention container color swatch — light red background with red border"></td>
+<td><code>colorStatusDangerBackground1</code><br><code>colorStatusDangerBorder1</code></td>
+<td>Errors, failures, and critical alerts</td>
+</tr>
+</table>
+
+<br>
+
+Unlike Adaptive Cards, HTML widgets don't automatically inherit a card background. Apply `colorNeutralCardBackground` to your outer container to match the Teams-native card surface. Inside it, use Emphasis containers to group or separate content, and Good, Warning, or Attention containers when specific content areas carry status meaning.
+
+<br>
+
+
+<img src="images/container_gallery.png" alt="Three example widgets showing container color nesting: a time-off request card using an Accent container for balance summary, a travel expense card using a Good container for approval status, and a distribution center card using Good and Attention containers for inventory delta indicators">
+
+
+
+##### Text colors
+
+Use text color tokens to create hierarchy and communicate meaning in widget content. Pair status text colors with a matching container or icon — never rely on color alone.
+
+<table>
+<tr>
+<th>Style</th>
+<th></th>
+<th>Token</th>
+<th>Use for</th>
+</tr>
+  
+<tr>
+<td>Default</td>
+<td><img src="images/textColor_default.png" width="24" height="24" alt="Default text color swatch"></td>
+<td><code>colorNeutralForeground1</code></td>
+<td><strong>Primary text</strong> — titles, key values</td>
+</tr>
+  
+<tr>
+<td>Subtle</td>
+<td><img src="images/textColor_subtle.png" width="24" height="24" alt="Subtle text color swatch"></td>
+<td><code>colorNeutralForeground3</code></td>
+<td>Secondary text — supporting details, metadata</td>
+</tr>
+
+<tr>
+<td>Accent</td>
+<td><img src="images/textColor_accent.png" width="24" height="24" alt="Accent text color swatch"></td>
+<td><code>colorBrandForeground2</code></td>
+<td>Teams brand-accented text and inline links</td>
+</tr>
+
+<tr>
+  <td>Good</td>
+<td><img src="images/textColor_good.png" width="24" height="24" alt="Good text color swatch"></td>
+<td><code>colorStatusSuccessForeground1</code></td>
+<td>Success labels and status indicators</td>
+</tr>
+
+<tr>
+<td>Warning</td>
+<td><img src="images/textColor_warning.png" width="24" height="24" alt="Warning text color swatch"></td>
+<td><code>colorPaletteMarigoldForeground2</code></td>
+<td>Warning labels and status indicators</td>
+</tr>
+
+<tr>
+<td>Attention</td>
+<td><img src="images/textColor_attention.png" width="24" height="24" alt="Attention text color swatch"></td>
+<td><code>colorStatusDangerForeground3</code></td>
+<td>Error labels and status indicators</td>
+</tr>
+
+</table>
+
+<br>
+
+
+> [!NOTE]
+> **Overlay text** tokens are static colors for text rendered on top of images or background media. Unlike other text tokens, these do not adapt to theme changes — choose dark or light based on the luminosity of the underlying image.
+
+<table>
+<tr>
+<th>Style</th>
+<th></th>
+<th>Token</th>
+<th>Use for</th>
+</tr>
+<tr>
+<td>Overlay dark</td>
+<td><img src="images/textColor_dark.png" width="24" height="24" alt="Overlay dark text color swatch — near black"></td>
+<td><code>colorNeutralForeground1Static</code></td>
+<td>Text on light or mid-tone images</td>
+</tr>
+<tr>
+<td>Overlay light</td>
+<td><img src="images/textColor_light.png" width="24" height="24" alt="Overlay light text color swatch — white"></td>
+<td><code>colorNeutralForegroundStaticInverted</code></td>
+<td>Text on dark images</td>
+</tr>
+</table>
+
+<br>
+<img src="images/textColorExamples.png" alt="Example of cards showing different font colors">
+
+
+
+
+
+#### Typography
+
+Use the following base text styles to create clear visual hierarchy in your widget. These styles align with the Teams design system and cover the most common text roles in a widget.
+
+| Style | Fluent token | Size / Weight | Use for |
+|---|---|---|---|
+| **Header** | — * | 18px / 600 | Widget or card title |
+| **Label** | `Body1Strong` | 14px / 600 | Section headers, status labels |
+| **Body** | `Body1` | 14px / 400 | Primary content, descriptions |
+| **Caption Label** | `Caption1Strong` | 12px / 600 | Small labels, field values |
+| **Caption** | `Caption1` | 12px / 400 | Supporting details, timestamps |
+| **Caption Subtle Label** | `Caption1Strong` + `ColorNeutralForeground3` | 12px / 600 | Subtle section labels, metadata keys |
+| **Caption Subtle** | `Caption1` + `ColorNeutralForeground3` | 12px / 400 | De-emphasized text, secondary metadata |
+
+\* _Header is a custom size not included in the Fluent UI React v9 type ramp. Use 18px / 600 directly._
+
+- Use a maximum of three distinct text sizes in a single widget to maintain visual hierarchy
+- Allow text blocks to wrap by default — avoid truncating body content unless space is genuinely constrained
+
+<img src="images/typography.png" alt="Two example widget cards showing typographic hierarchy using Header, Label, Body, Caption Label, and Caption text styles">
+
+> [!TIP]
+> If you are building with React, use [Fluent UI React v9 typography tokens](https://react.fluentui.dev/?path=/docs/theme-typography--docs) rather than hardcoded pixel values. Tokens adapt automatically to theme changes and stay in sync with the Fluent design system.
+
+<img src="images/icon_text.png" alt="Typography icon" width="20"> [Typography](https://fluent2.microsoft.design/typography)
+
+<br>
+
+
+
+#### Containers and borders
+
+Use containers to group related content and create visual hierarchy within your widget.
+
+- Apply border radius values consistent with [Fluent 2 shapes](https://fluent2.microsoft.design/shapes#corner-radius) to keep containers feeling native to Teams
+- Add a border when you need extra separation or emphasis between content areas — use the border token paired with your container color
+- Use full-width (edge-to-edge) backgrounds sparingly — they work well for hero images or strong section dividers
+- Avoid deep nesting — limit container nesting to a maximum of two levels
+
+<img src="images/borderRadiusStyles.png" alt="Five container style variations: base, rounded corners, border, border with rounded corners, and full-width bleed">
+
+<img src="images/borderShapeExamples.png" alt="Variety of cards with varying container styles">
+
+<img src="images/icon_shapes.png" alt="Shapes icon" width="20"> [Shapes and corner radius](https://fluent2.microsoft.design/shapes#corner-radius)
+
+
+
+<br>
+
+#### Spacing
+
+The recommended global padding for a widget is 16px (`spacingHorizontalL` / `spacingVerticalL`) on all sides.
+
+The following are commonly used spacing values for widget layouts. These map to Fluent UI React v9 spacing tokens — swap `Vertical` for `Horizontal` for horizontal spacing equivalents.
+
+| Name | Token | Size | Common use |
+|---|---|---|---|
+| Extra Small | `spacingVerticalXS` | 4px | Between an icon and its label, inside a badge |
+| Small | `spacingVerticalS` | 8px | Between buttons or tightly grouped elements |
+| Medium | `spacingVerticalM` | 12px | Vertical rhythm between text blocks and inputs |
+| Large | `spacingVerticalL` | 16px | Standard internal padding for cards and containers |
+| Extra Large | `spacingVerticalXL` | 20px | Separation between distinct content sections |
+| Extra Extra Large | `spacingVerticalXXL` | 24px | Global card padding, generous breathing room |
+
+The following examples show how spacing tokens apply in real widget layouts.
+
+<img src="images/spacing.png" alt="Two widget layout examples with spacing annotations showing how Fluent spacing tokens apply to padding and gaps between elements">
+
+For the full spacing scale, see <img src="images/icon_spacing.png" alt="Spacing icon" width="20"> [Fluent 2 > Spacing](https://fluent2.microsoft.design/layout).
+
+
+#### Iconography
+
+Use [Fluent 2 icons](https://fluent2.microsoft.design/iconography) rather than custom or third-party icon sets where possible. Fluent icons are recognized by Teams users and scale correctly at standard sizes.
+
+<img src="images/icons.png" alt="Fluent 2 iconography examples">
+
+<img src="images/icon_icon.png" alt="Iconography icon" width="20"> [Iconography](https://fluent2.microsoft.design/iconography)
+
+
+
+### Actions
+
+Actions allow users to take the next step without leaving the conversation.
+
+- **Limit to two primary actions** — use a primary button for the most important action and a secondary button for an alternative
+- **Use overflow for additional actions** — place additional actions in an overflow menu (`•••`) rather than adding more buttons
+- **Label actions clearly** — Use outcome-oriented labels such as "Reserve now" or "Approve" rather than vague labels like "OK"
+- **Disable, don't hide** — if an action is not available in the current state, disable the control rather than hiding it
+
+> [!TIP]
+> If you are building with React, [Fluent 2 button components](https://fluent2.microsoft.design/components/web/react/core/button/usage) implement the correct Teams-aligned button styles and states out of the box.
+
+
+<img src="images/icon-button.png" alt="Button icon" width="20"> [Button](https://fluent2.microsoft.design/components/web/react/core/button/usage)
+
+### Content and layout
+
+- **Be concise:** A widget should be glanceable. Users should understand the key information without scrolling within the widget
+- **Show summaries, not systems:** Surface the most relevant data for the current context rather than full data tables, dashboards, or navigation trees
+- **Avoid internal scrolling:** If content requires scrolling, consider whether it belongs in the expanded surface instead
+- **Avoid deep navigation:** Tabs, drill-down menus, and multi-level navigation are not appropriate for the inline widget
+- **Don't duplicate content:** Widget content and agent body text should complement each other — do not repeat the same information in both
+
+  
+
+### Progressive disclosure
+
+Not all information needs to be visible at once. Use progressive disclosure to keep widgets concise while allowing users to access more detail when needed.
+
+- Use show/hide toggles to reveal secondary or supporting information inline — such as expanding a summary row to show full details, or revealing additional fields on demand
+- Use scrolling within a defined container for longer content lists — ensure the container has a clear label and is keyboard accessible
+- Transition to the expanded surface for content that requires significant vertical space or multi-step interaction
+
+
+<img src="images/progressiveDisclosure.png" alt="Examples of progressive disclosure in widgets">
+
+
+### Input gathering
+
+If your widget includes a form or input fields:
+
+- Label all fields clearly — use visible labels, not placeholder text alone
+- Indicate required fields
+- Validate input inline and surface error messages adjacent to the relevant field
+- Keep forms short — if a form requires more than four or five fields, consider moving it to the expanded surface
+
+<img src="images/input_examples.png" alt="Examples forms and inputs">
+
+
+
+## Expanded surface
+
+The expanded surface opens as a modal above the chat when the user taps an expand button. Use it for content or workflows that require more space than the inline widget can reasonably provide.
+
+### When to use the expanded surface
+
+- Multi-step forms or configuration flows
+- Rich media that benefits from a larger canvas
+- Detailed data tables or comparison views
+- Iterative workflows with persistent state
+
+<img src="images/expanded_surface.png" alt="Example of expanded card surface">
+
+
+
+### Interaction guidelines
+
+- **Use expansion intentionally** — not every widget needs an expanded view. Reserve it for content that genuinely benefits from more space
+- **Don't replicate your full application** — the expanded surface is a focused workspace for a specific task, not a product shell. Avoid global navigation, settings panels, or unrelated features
+- **Scope to one task** — the expanded surface should support a single coherent workflow
+- **Preserve context** — the chat remains visible when the expanded surface is open. Design the expanded content to work alongside the conversation
+
+
+
+## Best practices
+
+:::row:::
+  :::column:::
+    ### ✅ Do
+    - Keep widgets lightweight and action-oriented
+    - Support up to two primary actions
+    - Use the expanded surface for deep navigation or multi-step workflows
+    - Use [Fluent 2](https://fluent2.microsoft.design/) components, spacing, typography, and tokens
+    - Show loading indicators, success confirmations, and error states with recovery options
+    - Allow text to wrap by default
+    - Use outcome-oriented action labels such as "Reserve now" or "Approve request"
+  :::column-end:::
+  :::column:::
+    ### ❌ Don't
+    - Don't embed a full application experience inside a widget
+    - Don't recreate Teams chat capabilities such as prompt input or retry controls
+    - Don't hardcode colors — use Fluent 2 tokens or CSS variables
+    - Don't make widgets taller than the viewport
+    - Don't repeat the same information in both the widget and the agent's body text
+    - Avoid vague action labels like "OK" or "Click here" — use outcome-oriented labels where possible
+  :::column-end:::
+:::row-end:::
+
+
+## Nice to have
+
+The following items are optional but contribute to a higher-quality widget experience.
+
+- **Use Fluent 2 components**: [Fluent 2](https://fluent2.microsoft.design/) components implement Teams-aligned visual patterns and interactions out of the box. If building with React, [Fluent UI React v9](https://react.fluentui.dev/) is the recommended implementation.
+- **Support layout patterns**: Consider established layout patterns — hero (image at top, content below), article (text-heavy, hierarchical), form (input-focused), or list (repeating items) — and choose the pattern that fits your content type.
+- **Charts and data visualization**: Ensure axis labels and data points are clearly readable at widget width. Consider transitioning to the expanded surface for complex charts.
+- **Media elements**: For inline video or rich media, provide a clear play control and a static thumbnail. Autoplay is not recommended.
+- **Illustrations**: Use illustrations sparingly and purposefully. Avoid decorative illustrations that add height without adding value.
+
+
+
+## Related content
+
+- [HTML widgets overview for Microsoft Teams](#)
+- [Accessibility guidelines for HTML widgets in Microsoft Teams](#)
+- [Teams store validation guidelines](#)
+- [Fluent 2 design system](https://fluent2.microsoft.design/)
+- [Fluent UI React v9](https://react.fluentui.dev/)
+- [Fluent 2 color tokens](https://fluent2.microsoft.design/color)
+- [Fluent 2 typography](https://fluent2.microsoft.design/typography)
+- [Fluent 2 iconography](https://fluent2.microsoft.design/iconography)