UX design pattern templates for Office Add-ins
Use the UX design patterns project to:
- Apply solutions to common customer scenarios.
- Apply design best practices.
- Incorporate Office UI Fabric components and styles.
- Build add-ins that visually integrate with the default Office UI.
Using the UX design patterns
To use the specifications to build a mock-up of your own add-in UI:
- Download design assets files and begin designing your own UI:
- Refer to the following articles for guidance:
To add the source code:
- Clone the UX design patterns for Office Add-ins project repo.
- Copy the assets folder, and the code folder for the individual pattern you choose to your add-in project.
- Incorporate the individual pattern into your add-in. For example:
- Edit the source location or add-in command URL in the manifest.
- Use the UX design pattern as a template for other pages.
- Link to or from the UX design pattern.
Some UX pattern specifications do not match the source code. We're working hard to bring all assets into alignment. Also notice that some specifications are presented as archived. We're assessing these archived specifications for value to the platform. Each pattern aims to represent a unique template and pattern of interaction. The patterns should not overlap with each other and should be well differentiated from Office Fabric UI components.
Types of UX design patterns
Generic page templates can be applied to any page in your add-in and don't have a special purpose. An example of a special purpose page, would be any of the first-run patterns. The following list describes the generic pages available:
- Landing page - A standard add-in page, for example the page a user lands on after a first-run experience or sign-in process.
- Brand image in brand bar - The landing page with an image in the footer that represents your brand.
A first-run experience is the experience a user has when they open your add-in for the first time. The following first-run design pattern templates are available:
- Steps to start - Provides users with an ordered list of steps to perform to get started using your add-in.
- Value - Communicates your add-in's value proposition.
- Video - Shows users a video before they start using your add-in.
- Walkthrough - Takes users through a series of features or information before they start using the add-in.
The Office Store has a system that manages trial versions of an add-in, but if you want to control the UI of the trial experience for your add-in, use the following patterns:
- Trial - Shows users how to get started with a trial version of your add-in.
- Trial feature - Advises users that the feature they are trying to use is not available in the trial version of the add-in. Alternatively, if your add-in is free but it includes a feature that requires a subscription, consider using this pattern. You might also use this pattern to provide a downgraded experience after a trial has ended.
If you decide to manage your own trial, and not use the Office Store to manage the trial, make sure to include the Additional purchase may be required tag in the testing notes in the seller dashboard.
Consider whether showing users the first-run experience once or many times is important to your scenario. For example, if users use your add-in periodically, they might forget how to use it, and it might be helpful to see the first-run experience more than once.
|Steps to Start||Value||Video|
|Walkthrough first page||Trial||Trial feature|
Users need to navigate between the different pages of your add-in. The following navigation templates show different options you can use to organize pages and commands in your add-in.
- Back button and Next page - Shows a task pane with Back and Next page buttons. Use this pattern to ensure users follow an ordered series of steps.
- Navigation - Shows a menu, commonly referred to as the hamburger menu, with page menu items in a task pane.
- Navigation with commands - Shows the hamburger menu with command (or action) buttons in a task pane. Use this pattern when you want to provide navigation and command options together.
- Pivot - Shows Pivot navigation inside of a task pane. Use pivot navigation to allow users to navigate between different content.
- Tab bar - Shows navigation using buttons with vertically stacked text and icons. Use the tab bar to provide navigation using tabs with short and descriptive titles.
|Back button||Navigation||Navigation with commands|
Your add-in can notify users of events, such as errors, or of progress in a variety of ways. The following notification templates are available:
- Embedded dialog box - Shows a dialog box inside the task pane that provides information and, optionally, an interactive experience, using buttons or other controls. Consider using one to prompt a user to confirm an action. Use the Embedded dialog pattern when you want to keep the user experience in the task pane.
- Inline message - Indicates error, success, or information, and can appear at a specified location in the task pane. For example, if a user enters an incorrectly formatted email address in a text box, an error message appears just below the text box.
- Message banner - Provides information and, optionally, a simple call to action, in a banner that can be collapsed to a single line, expanded to multiple lines, or dismissed. Use message banners to report a service update or a helpful tip when the add-in starts.
- Progress bar - Indicates the progress of a long-running, synchronous process, such as a configuration task that must complete before the user can take any further action. It is a separate interstitial page that also reinforces the add-in brand. Use a progress bar when the process can send periodic measures of how far along it is back to the add-in.
- Spinner - Indicates that a long-running, synchronous process is underway, but provides no indication of how far along it is. It is a separate interstitial page that also reinforces the add-in brand. Use a spinner when the add-in cannot know reliably how far along a process is.
Toast - Provides a brief message that fades away after a few seconds. Because the user might not see the message, use toast only for nonessential information. It is a good choice for notifying users of an event in a remote system, such as the receipt of an email.
Embedded dialog Inline message Message banner Progress bar Spinner Toast
The following are general components that you can use in your add-ins in a variety of scenarios.
Client dialog boxes
Client dialog boxes provide another way for users to work with your add-in outside of a task pane. The following dialog box templates are available:
- Typeramp dialog box - Shows a dialog box with textual content. Use the typeramp dialog to display elaborative information to users.
- Alert dialog box - Shows an alert box with important information, such as errors or notifications, to users.
- Navigation dialog box - Shows a dialog box with navigation. Use the navigation dialog box to allow users to navigate between different content.
|Typeramp dialog||Alert dialog|
Feedback and ratings
To improve the visibility and adoption of your add-in, it is helpful to provide users with the ability to rate and review your add-in in the Office Store. This pattern shows two methods for presenting feedback and ratings from within the add-in:
- User-initiated feedback - A user chooses to send feedback by using either the navigation menu (for example, using the Send Feedback link) or an icon on the footer.
- System-initiated feedback - After the add-in runs three times, the user is prompted to provide feedback via a Message Banner.
Either method opens a dialog box that contains the Office Store page for the add-in.
- Feedback and ratings specification (This UX design pattern has been archived. As we assess its value, refer to this PDF.)
- Feedback and ratings code
This pattern currently points to the Office Store home page. Be sure to update this URL to the URL of your add-in's page in the Office Store.
|Feedback and ratings|
Settings and privacy
Add-ins may need a Settings page that allows users to configure settings that control the behavior of the add-in. Also, you may want to provide users with the privacy policies your add-in adheres to.
- Settings - Shows a task pane with configuration components that controls the behavior of the add-in. A settings page provides options for the user to choose.