Building a tab integration for Microsoft Teams — UI/UX Best Practices

Microsoft Teams is Microsoft’s new group chat-based collaboration tool and Slack competitor. One notable feature of the platform is that it provides a rich integration API for third-party developers, including a unique feature called tabs which allows developers to surface their entire app on a dedicated canvas within Teams. Polyscribe is one of the first tab integrations for Teams and was built from the ground up specifically for Teams. In this series of posts, we describe some of the lessons and strategies we learned building an integration for this unique platform.

Living your life purely within a Microsoft Teams tab exposes you to different constraints than you’d face within a standalone website or app. While it’s certainly possible to simply embed a standard website as an IFrame within the tab (a tab is really just an IFrame + Teams SDK), we discovered that a lot of the UI/UX paradigms that work on a standalone website can be confusing or look “off” when applied directly in the context of a Teams tab. Here are some of the lessons and best practices for UI/UX within a tab that we learned while building Polyscribe.

Think in terms of teams and channels, not individuals

Teams tabs are contexts that are shared across an entire channel. If one person adds a tab to a channel, every other member of the channel will see it. This feature has a few implications for how you design your product.

For example, in a standalone app, when a user creates a new document, that document is generally visible only to that user. To share it with other members of their team they might go through a “share” dialog where they select the specific individuals they want to grant additional permissions for the document.

In contrast, in Polyscribe meeting notes users create are automatically shared with the team that tab is in. This keeps the shared tab context consistent across the team and minimizes confusion. Note that since Microsoft Teams doesn’t have private channels within a team there’s no need to make the permissions channel-specific.

This is one example, but the idea of modeling our user in terms of teams and channels instead of individuals came up repeatedly while we were building Polyscribe and is fundamental to keeping a consistent view of the shared space across a team.

Decide whether it makes sense to show a single or multiple “entities” in a tab

Tabs come with a configuration page that allow the team to set settings on the tab when it’s being created. This allows for an interesting dichotomy: some tabs allow the user to determine which of the “entities” (documents, dashboards etc) that tab points to (making the tab more about sharing that single entity with the team rather than sharing the app) whereas other tabs embed the app with all its entities into the tab.

The Planner tab’s configuration page

For example, the Planner tab lets the user select the specific Planner plan that they’d like to share in the tab. This makes sense as it’s likely that a given channel is only working on one plan. On the other hand, in Polyscribe, multiple meeting notes are accessible within a tab since a given channel will typically have multiple meetings. Users shouldn’t have to remove and create a new tab for each new meeting, so this approach made sense for Polyscribe.

Whether a single or multiple entity tab makes sense for your integration depends on how you imagine users within a team want to access your app — both options exist and the decision will determine the install flow for your tab.

Remember that space is limited

Unlike within a standalone website, within a Teams tab some of the space on the user’s screen is occupied by the Teams chrome — the tab bar, navigator and teams list. This is something you have to design around to avoid making your tab look cluttered.

With Teams chrome and comment panel open, space is limited

For instance, we decided not to add a permanent left-side navigation pane as Teams already has two left-side panes visible at all times (the navigator and teams/channel list view). Adding a third pane made our integration look cluttered and visually confusing, so instead we opted for a collapsible left nav (another alternative is to move the nav to the right side of the tab).

Also keep in mind that the space available can shrink further as users can open a tab-specific comment pane to the right of your tab. Tab integrations need to be responsive to these changes, and the result is that you often have to be picky or creative about what you display within your tab.

Make your integration feel native

Between the Teams Tabs SDK and the Microsoft Graph API, there are a lot of opportunities to make your tab feel like a native part of the Teams platform. Here are a few possibilities:

1. Use Azure AD single sign-on and the Teams SDK’s silent authentication flow for a seamless log in experience. This allows users to be automatically signed in to your application when they’re signed in to Teams — no additional sign ins required. (The devil is in the details here so this is a topic for a future blog post)
2. Use the Teams SDK to respond to events and integrate with other parts of Teams. For example, the Teams SDK can let you know when the user changes their theme from “Default” to “Dark” so you can change your color scheme accordingly. You can also use the Teams SDK to create deep links into your app’s content that can be pasted into other conversations
3. Mirror Teams’ UI conventions. Teams has UI conventions that you may want to reuse in your own integration. For example, Teams’ avatars are round (the profile picture is accessible through the Graph API) and online presence is displayed with Skype’s styling. You can also use Microsoft Office’s component library Fabric to make your UI components closely match those used by Teams and Office 365.

Polyscribe changes its colors to match the Teams “Dark” theme

These are some of our ideas for making integrations in Teams feel native and intuitive to help reduce friction for users installing and using tabs. If you’re considering building a tab, we hope you found this helpful. It’s still early days on the platform and the platform itself is evolving rapidly, so we’re looking forward to seeing how other developers integrate and the new experiences we can build.