Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This guide provides user experience 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.
User experience 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.
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, support interactions, 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.
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.
Be transparent and predictable
- Widget content should be clear, and any interactions should be obvious.
- Users should always understand what a widget is showing.
- The expected outcome of any interaction should be obvious before the user acts.
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.
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.
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
- Depending on the user's message layout, your widget may sit inside a message bubble (Cozy mode) or directly on the chat canvas (Compact mode and Teams mobile). Make sure it looks good in both.
- 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 User experience guidelines for MCP apps in declarative agents for Copilot-specific guidance.
Widget anatomy
Many widgets follow a common pattern that helps users quickly understand the layout — 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 |
When a widget does follow this common pattern, content typically flows top to bottom:
- Title (if applicable)
- Primary content — key information, data, or media
- 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 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. 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
Design for narrow mobile containers first, then adapt the layout for wider containers. Keep primary content readable without clipping or unintended horizontal scrolling. Make every action available by touch without relying on hover. Test in Teams on iOS and Android in portrait and landscape orientations, and confirm that the layout also works at desktop widths.
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.
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.
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.
Minimum user experience 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.
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.
Tip
Start with Widget border and padding. It frames everything else in this section.
Widget border and padding
Teams provides the iframe that your widget renders in, but doesn't add a border, corner radius, or background to it. Add your own border and padding so your widget reads as a contained unit within the message.
This matters because the message bubble’s background normally frames a message and everything in it. In Cozy mode the bubble sits behind your widget and does that job. In Compact mode and on Teams mobile there’s no bubble, so your widget sits directly on the chat canvas. Without its own border and padding, it can appear to float.
- Add a border and padding around your widget's content
- Choose a border color, corner radius, and background that fit your design. Fluent 2 shapes and color tokens are a good starting point if you want your widget to feel native to Teams
- Use the recommended 16 px padding described in Spacing.
| Cozy (message bubble) | Compact and mobile (no bubble) | |
|---|---|---|
| With border and padding | ![]() |
![]() |
Visual design
Colors and theming
Use Fluent 2 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 if you want your outer card surface to match Teams, then nest containers inside it to group related content or surface status meaning.
| Style | Token | Use for | |
|---|---|---|---|
| Default | ![]() |
colorNeutralCardBackgroundcolorNeutralStroke2 |
Outer card surface — use this token if you want your widget’s base container to match the Teams-native card background |
| Emphasis | ![]() |
colorNeutralBackground3colorNeutralStroke1 |
Grouped or secondary content areas — the most common inner container |
| Accent | ![]() |
colorBrandBackground2colorBrandStroke2 |
Brand-accented highlights and callouts |
| Good | ![]() |
colorPaletteLightGreenBackground1colorStatusSuccessBorder1 |
Confirmations and successful outcomes |
| Warning | ![]() |
colorPaletteMarigoldBackground1colorPaletteMarigoldBorder1 |
Cautions and time-sensitive alerts |
| Attention | ![]() |
colorStatusDangerBackground1colorStatusDangerBorder1 |
Errors, failures, and critical alerts |
Unlike Adaptive Cards, HTML widgets don’t automatically inherit a card background. If you want to match the Teams-native card surface, apply colorNeutralCardBackground to your outer container. Inside it, use Emphasis containers to group or separate content, and Good, Warning, or Attention containers when specific content areas carry status meaning.
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.
| Style | Token | Use for | |
|---|---|---|---|
| Default | colorNeutralForeground1 |
Primary text — titles, key values | |
| Subtle | colorNeutralForeground3 |
Secondary text — supporting details, metadata | |
| Accent | colorBrandForeground2 |
Teams brand-accented text and inline links | |
| Good | colorStatusSuccessForeground1 |
Success labels and status indicators | |
| Warning | colorPaletteMarigoldForeground2 |
Warning labels and status indicators | |
| Attention | colorStatusDangerForeground3 |
Error labels and status indicators |
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.
| Style | Token | Use for | |
|---|---|---|---|
| Overlay dark | colorNeutralForeground1Static |
Text on light or mid-tone images | |
| Overlay light | colorNeutralForegroundStaticInverted |
Text on dark images |
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 | — * | 18 px / 600 | Widget or card title |
| Label | Body1Strong |
14 px / 600 | Section headers, status labels |
| Body | Body1 |
14 px / 400 | Primary content, descriptions |
| Caption Label | Caption1Strong |
12 px / 600 | Small labels, field values |
| Caption | Caption1 |
12 px / 400 | Supporting details, timestamps |
| Caption Subtle Label | Caption1Strong + ColorNeutralForeground3 |
12 px / 600 | Subtle section labels, metadata keys |
| Caption Subtle | Caption1 + ColorNeutralForeground3 |
12 px / 400 | De-emphasized text, secondary metadata |
* Header is a custom size not included in the Fluent UI React v9 type ramp. Use 18 px / 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
Tip
If you are building with React, use Fluent UI React v9 typography tokens rather than hardcoded pixel values. Tokens adapt automatically to theme changes and stay in sync with the Fluent design system.
Containers and borders
For the border and padding around your whole widget, see Widget border and padding.
Inside your widget's frame, use containers to group related content and create visual hierarchy.
- Apply border radius values consistent with Fluent 2 shapes 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
Spacing
The recommended padding inside your widget's border is 16 px (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 |
4 px | Between an icon and its label, inside a badge |
| Small | spacingVerticalS |
8 px | Between buttons or tightly grouped elements |
| Medium | spacingVerticalM |
12 px | Vertical rhythm between text blocks and inputs |
| Large | spacingVerticalL |
16 px | Standard internal padding for cards and containers |
| Extra Large | spacingVerticalXL |
20 px | Separation between distinct content sections |
| Extra Extra Large | spacingVerticalXXL |
24 px | Generous breathing room |
The following examples show how spacing tokens apply in real widget layouts.
For the full spacing scale, see
Fluent 2 > Spacing.
Iconography
Use Fluent 2 icons rather than custom or third-party icon sets where possible. Fluent icons are recognized by Teams users and scale correctly at standard sizes.
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 implement the correct Teams-aligned button styles and states out of the box.
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
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 selects 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
✅ Do
- Add a border and padding so your widget holds together with or without a message bubble
- 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 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"
❌ Don't
- Don't rely on the message bubble to separate your widget from the chat
- 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
Nice to have
The following items are optional but contribute to a higher-quality widget experience.
- Use Fluent 2 components: Fluent 2 components implement Teams-aligned visual patterns and interactions out of the box. If you're building with React, Fluent UI React v9 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.







