# Extension Design Guidelines

> Interaction and style guidelines for extensions.

Design guidance. API behavior and product setup are in the other domain files.

## Design Guidelines for Dashboard Extensions

With the release of dashboard extensions in Tableau 2018.2, we're unleashing the creativity and problem-solving skills of passionate developers to make extensions for Tableau dashboards. Here’s your roadmap towards designing great extensions.

#### Who is this document for?

This document is focused on guiding developers towards best practices for designing extensions, including both user interaction and visual style guidelines. For more technical information about extensions, refer to our Extensions API Documentation.

#### What are Dashboard Extensions?

Tableau Dashboard Extensions are web applications that have two-way communication with the dashboard. Dashboard extensions enable all sorts of scenarios, like letting you integrate Tableau with custom applications, making possible for you to modify the data for a visualization, or even creating custom visualizations inside the dashboard. 

#### How to use this document

These guidelines cover the main things you need to know about designing a great extension experience. This document is organized in three parts. We suggest you follow the guidelines sequentially your first time through, so that you gain the broadest picture of the interactive experience before you dive into the details about using the interface controls and patterns.  

#### Interaction Guidelines

|  See      |     For information about   |
|:--------- |:------- |
|[Build, Test, Share](./Interaction_Guidelines/ux_build_test.md) | The developer's roadmap for how to get started developing and designing extensions.|
|[Extension Components and Modes](./Interaction_Guidelines/ux_components_modes.md)| The main user-facing components of an extension to create content for. Learn about modes for configuring extensions, viewing extensions, and dashboard user types. |
| [Controls and UI Patterns](./Interaction_Guidelines/ux_controls_ui_patterns.md)| Usage and design specifications for user interface controls and patterns in your extension. |

#### Style Guidelines

| See   |  For information about |
| :---------| :------- |
|[Branding your Extension](./Style_Guidelines/ux_branding.md) | How to style your extension in accordance with the Tableau brand and your personal/company brand.|
|[Layout](./Style_Guidelines/ux_layout.md)| Details about dashboard containers and spacing in the extension container. |
|[Color](./Style_Guidelines/ux_color.md)| Use color effectively in your extension, and an opportunity to use Tableau's colors. |
|[Fonts](./Style_Guidelines/ux_fonts.md)| Guidelines for using fonts in extensions. |

#### Deploying your Extension

| See       | For information about |
| :---------| :------- |
|[Submitting your Extension to the Tableau Exchange](ux_extension_gallery.md) | How to style your extension in accordance with the Tableau brand and your personal/company brand.|

---
 

![Extensions are made using a manifest file called a .trex! FreLard stands for the Seattle neighborhoods of Fremont and Wallingford, where Tableau's headquarters stands.](./imgs/trex.png)

>*This document is a work-in-progress. To give feedback, ask questions, or if you have technical questions about extensions, contact [devplat@tableau.com](mailto:devplat@tableau.com).*

---

## Submitting your Extension to the Tableau Exchange

You may be interested in sharing your extension for others to download and use in their dashboards. To submit your extension to the [Tableau Exchange](https://extensiongallery.tableau.com/) online, make sure you have the following components gathered.

**[Exchange Card](#exchange-card-example)**

* Extension Name
* Extension Icon
* Tagline

**[Exchange Page](#exchange-page-example)**

* Description
* Developer Info
* Featured Images

**[How to Submit your Extension](#how-to-submit-your-extension)**

 

---

### Exchange Card Example
This is what an extension looks like to a user while browsing the Tableau Exchange. 

![exchange card example](./imgs/gallery_card_example.png)

|     | Details | 
| --- | ------- | 
| **Extension Name**  | The name of your extension must clearly communicate what it does in one to three words. Use title case, making sure that each word starts with a capital letter. The name you use here must match the name you specified in the extension manifest file (`.trex`).|
| **Extension Icon**  | The icon for your extension will be displayed at a small size, so ensure that all the important visual elements of your icon are easily visible. Dimensions for the icon must be 280x280 pixels and uploaded as a `.png` file with transparency. Learn more about branding at [Branding your Extension](./Style_Guidelines/ux_branding.md). Note that the icon you use here must look like the icon you include in the extension manifest file (`.trex`). The icon in the manifest file is used in the **About** dialog box for your extension. The icon in the manifest file is a 70x70 pixel `.png` file that is Base64 encoded.   |
| **Tagline**         | The tagline is one sentence that explains what the extension does. The maximum length is 96 characters. This tagline is also used within the extension configuration dialog. Learn more at [Extension Components and Modes](./Interaction_Guidelines/ux_components_modes.md).|

  

### Exchange Page Example
Users reach pages like this when they want to know more about a particular extension. 

![exchange page example](./imgs/gallery_page_example.png)

|     | Details | 
| --- | ------- | 
| **Description**  | Describe what your extension does in one paragraph. The description must describe how your extension works, how it might help with one’s workflow, or how it might enhance data insights. |
| **Developer Info**  | Take credit for your work. Gather links, files, and/or contact info for the following items: **Policy**: Privacy Policy (website link or PDF) **Usage**: Terms of Service (website link or PDF), and terms of service **Support**: Personal or company website, FAQ, PDF, and contact info for feedback and inquires **Version**: Current version of your extension. |
| **Featured Images** | You can upload one to three images of your extension in action. Dimensions for the screenshots must be 1200x680 pixels and uploaded as `.png` files. Take caution that screenshots do not reveal any sensitive or confidential data. |

 

### How to Submit your Extension

To submit your extension to the Tableau Exchange, you must be added as a contributor on the Exchange. Contact the Tableau Exchange at [extensiongallery@tableau.com](mailto:extensiongallery@tableau.com) for more information.

After completing your extension,  you will need to provide the Exchange with your information and extension details. The extension name in the template needs to match the name you specified for your extension in the manifest file (`.trex`). The 280x280 pixel `.png` icon that you attach with your submission must look like the icon you included in your manifest file (they just have different dimensions). If you have any questions about the Tableau Exchange please send them to [extensiongallery@tableau.com](mailto:extensiongallery@tableau.com).

---

## Build, Test, Share

This section serves as a broad overview of the developer experience and considerations of making extensions. 

 

![lifecycle](./imgs/1-lifecycle.png)

 

### Build

The first thing to do is start running sample extension code from the Extensions API Documentation. **Make sure that your sample code works** and your environment is set up properly before jumping into building a new extension.

Once you're ready to go, you can start building and customizing your extension. Expect to iterate through cycles of developing and designing your extension using our API documentation and these design guidelines.

#### Get started with these resources

* [Extensions API Documentation](https://tableau.github.io/extensions-api/)
The Extensions API includes all the information you need to build an extension.

* [Community Forums](https://community.tableau.com/s/topic/0TO4T000000QFALWA4/extensions-api)
  Participate in a community of developers that are passionate about creating extensions.

* [Tableau Exchange](https://exchange.tableau.com/)
  Explore and use some of the extensions our partners have created.

* [Tableau Developer Program](https://www.tableau.com/developer)
  Participate in the Tableau Developer Program. Be invited to monthly sprint demos with Tableau's development team and have the opportunity to give ongoing feedback.

 

### Test

Ensure that your extension works properly for different test cases. Try it on your own dashboards, test it with others, and uncover possible edge cases. 

Consider that dashboard extensions can be both **configured** and **viewed** in Tableau. These terms refer to two usage modes we recommend for extensions. To read about these modes and their audiences, learn more at **[Extension Components and Modes](./ux_components_modes.md)**.

  

### Share

After you've completed making your extension, you may want to share your extension for others to use. Here are some places you might think about sharing your extension.

##### Tableau Exchange

Tableau has created the [Tableau Exchange](https://exchange.tableau.com/), a place to explore and download some extensions that our partners have created. If you would like to share your extension on the Tableau Exchange, see [Submitting your Extension to the Tableau Exchange](../ux_extension_gallery.md).

##### Community Forums

Tableau also has a [Community Forum](https://community.tableau.com/s/topic/0TO4T000000QFALWA4/extensions-api) for developers to discuss extensions and the Extensions API.

-----  

While you might not choose to share your extension directly with Tableau, we encourage you to share your extension through other platforms of your choice! Use it internally at your company or for yourself, consider open source platforms, share over social media channels. How you go about sharing your extension with the world is entirely up to you.

---

## Extension Components and Modes

This section outlines the overall experience of using an extension in a dashboard.

 

---
### Foundation

Every dashboard extension has two general user experiences (or *user types*) and three main components. 

### User Types

Extensions must be designed with two types of dashboard users in mind: authors and viewers (consumers). 

##### Dashboard Author

Dashboard Authors are users that create dashboards and work directly with data in Tableau, both on Desktop and Online authoring modes. Authors get full editing capability over an extension’s configuration settings. 

On dashboards, authors primarily use **[Configuration Mode](#configuration-mode)** and can access **[Viewing Mode](#viewing-mode)**.

##### Dashboard Viewer

Dashboard Viewers are users that can only use dashboards with extensions on Tableau Cloud. Viewers usually don't set up a workbook or extension themselves, so they don’t have editing capability over an extension’s configuration settings.

On dashboards, viewers interact with extensions only in **[Viewing Mode](#viewing-mode)**. 

 

 

### Extension Container

The extension container lives in a dashboard, and is the primary place to display content for both dashboard authors and viewers. For example, this area could be used for displaying a custom visualization or user input controls to further customize dashboard data. 

This is where authors can access the dropdown menu for more options, such as configuration and information about the extension.

![extension container](./imgs/2-chrome_menu.png)

*Learn more about branding your extension container at [Branding your Extension](../Style_Guidelines/ux_branding.md#extension-container).*

 

 

### Configuration Dialog
The configuration dialog is the primary way that dashboard authors can customize an extension in their dashboards. 

This dialog is only available to dashboard authors, It is primarily accessible through the dropdown menu present on the Extension Container. It is not visible to regular dashboard viewers. Learn more below at **[Configuration Mode](#configuration-mode)**.

![configuration dialog](./imgs/2-config_dialog.png)

*Learn more about branding your configuration dialog at [Branding your Extension](../Style_Guidelines/ux_branding.md#configuration-dialog).*

 

 

### About Extension Dialog

The about extension dialog exists for dashboard authors to access support and version information about the extension in the dashboard. Currently, this dialog is not available for regular dashboard viewers on Tableau Cloud. Learn more below at **[Configuration Mode](#configuration-mode)**

![about extension dialog](./imgs/2-about_dialog.png)

 

 

 

## Modes
After acquainting yourself with the user types and components, read about use modes for extensions.

 

### Configuration Mode
This mode is available only to dashboard authors. Here, we describe how configuration mode works across the extension components.

##### Extension Container
The extension container offers a high level of functionality for dashboard authors. This is where authors can access the extension menu to reach the configuration dialog and other information about the extension.

![extension container](./imgs/2-chrome_menu_annotated.png)

 

##### Configuration Dialog
The configuration dialog allows dashboard authors to customize extensions in their dashboards. These are some general components that a configuration dialog should ideally include.

![config dialog example](./imgs/2-config_dialog_annotated.png)

|     | Details |
| --- | ------- |
| **Extension Name** | The name of the extension is clearly displayed at the top of the configuration dialog in title case. |
| **Instructions** (optional) | Write 1-2 lines of simple instructions for a user to successfully set up the extension. |
| **User Input Sections** | This is the main zone where user input fields and controls live. You can create multiple sections to separate content from each other. Ensure that sections are clearly titled and spaced apart from each other. |
| **Help Tag** | This dialog is activated by hovering one's cursor over the icon, and helps the user learn more about the extension.|
| **Tagline**  | The tagline is one sentence in the help tag that explains what the extension does. The maximum character limit is 96 characters.|
| **Confirmation** | Make sure there is a clear way for users to apply changes made while configuring the extension. |

Learn more about [Controls and UI Patterns](./ux_controls_ui_patterns.md) to use in your configuration dialog.

 

###### Automatic Configuration Popup

Many extensions require an author to configure the extension before using it in the dashboard. The configuration dialog is accessible through the extension dropdown menu, but to speed up the process, you can skip directly to the configuration dialog. You can set a configuration dialog to pop up automatically after an author adds your extension into their dashboard. 

![automatic configuration popup](./imgs/gifs/2-config_popup.gif)

While this is optional, **we strongly recommend using this popup pattern** because when an author is configuring the extension for the first time, there often isn't any content present in the extension container until the extension has been configured. Using this popup pattern will allow authors to start configuring the extension right away.

*Learn more about how to implement this popup at [Add a Configuration Popup Dialog (Extensions API Documentation)](../core/trex_configure.md).*

 

##### About Extension Dialog

The About Extension Dialog is automatically created using the content from your .trex manifest, which includes items such as your extension’s name, developer info, support, source ID, version info, etc. This is also accessible through the dropdown menu in the extension container.

![about extension dialog](./imgs/2-about_dialog_annotated.png)

*Learn more about the dashboard extension manifest file at [Tableau Extension Manifest File (Extensions API Documentation)](../dashext/trex_manifest.md)*.

### Viewing Mode

This mode is available to both dashboard authors and viewers. 

* **Authors** have access to configuration mode and viewing mode in both Tableau Desktop and Online.
* **Viewers** only have access to viewing mode on Tableau Cloud. Viewers can't access configuration and about dialogs, but can use an extension as it appears in a dashboard on Tableau Cloud.

##### Extension Container

Viewers can only interact with dashboard extensions in Tableau Cloud. When viewing, there are no settings around containers or zones that viewers can access. The extension container appears just as other containers in the dashboard.

However, if viewers have permission to edit the workbook on Tableau Cloud or download the workbook to their local machine, they can access all of the same settings described above in **[Configuration Mode](#configuration-mode)**. 

---

---

## Controls and UI Patterns

Controls and UI patterns help users interact with your extension and customize their experience. 

We've provided examples of controls that are used in Tableau. Using the exact styling of these components is optional.

* [Activity Indicators](#activity-indicators)
* [Buttons](#buttons)
* [Dialogs](#dialogs)
* [Dropdowns](#dropdowns)
* [Selectors](#selectors)
* [Text Fields](#text-fields)
* [Tooltips](#tooltips)

The controls described here use Tableau branding, accessible from the **[Color](../Style_Guidelines/ux_color.md)** and **[Fonts](../Style_Guidelines/ux_fonts.md)** sections of these design guidelines.

*At this time, we are only able to provide surface-level usage and design specifications for controls. We are working to make code for Tableau controls accessible to developers in the future.*

---

 

### Activity Indicators 
When performing an action, let users know that your extension is currently doing something and isn’t static or stalled. Make sure your extension acknowledges the user’s interactions by providing some form of tangible feedback.

An activity indicator appears when a task is performed that will take an unknown amount of time, such as loading or synchronizing complex data. It disappears when the task is complete.

![activity spinner](./imgs/3-activity_spinner-cover.png)

#### Usage
These activity spinners used in Tableau run at one rotation per second, and are non-interactive. 

Using this exact spinner in your extension is optional. For alternate options, we recommend using activity indicators of similar sizes and variety to ensure that it works on varying background elements.

| Variations | Preview | SVG Code | How to use |
|---------------------|:---------:|:---:|---|
| **Large** (50x50 px) | ![large gif](./imgs/gifs/3-Large.gif) | [SVG](xml/large.xml) | Use only on light backgrounds |
| **Large with underlay** (65x65 px) | ![large with underlay gif](./imgs/gifs/3-Large_with_Underlay.gif) | [SVG](xml/large-with-underlay.xml) | Use on light or complex backgrounds to provide better contrast |
| **Large on dark background** (50x50 px) | ![large on dark background gif](./imgs/gifs/3-Large_on_Dark_Background.gif) | [SVG](xml/large-on-dark-background.xml) | Use only on dark backgrounds |
| **Small on dark background** (14x14 px) | ![small on dark background gif](./imgs/gifs/3-Small_on_Dark_Background.gif) | [SVG](xml/small-on-dark-background.xml) | Use only on small elements with dark backgrounds |
| **Small** (14x14 px) | ![small gif](./imgs/gifs/3-Small.gif) | [SVG](xml/small.xml) | Use only on small elements with light backgrounds

 

 

 

---

### Buttons
A button communicates what happens when a user touches it. Button labels can consist of text, an icon, or a combination of both.

![buttons](./imgs/3-buttons-cover.png)

#### Usage

| Button | How to use |
|----|:-----|
| **Call-to-Action                                                 **  | These buttons are primarily used in dialogues to indicate an action. Use colors to communicate function–for example, green is commonly used for confirmation buttons. Learn more about color usage at **[Colors](../Style_Guidelines/ux_color.md)**. You may also want to utilize branding practices on buttons. Learn more at **[Branding your Extension](../Style_Guidelines/ux_branding.md)**. |
| **Greyscale** | Greyscale buttons are used either to indicate a secondary action, or a button that has been disabled and a particular action needs to be taken before proceeding. |
| **Text Button            ** | This is a low-attention button, and should only be used to provide a secondary option in the case that the user wants to perform an action that isn’t the primary action. |
| **Icon** | Buttons can have icons to add a helpful visual. If you use icons, include a text label or a help tag that is activated on hover. |

 

**Button Placement**

Button placement guidelines apply to Call-to-Action and Greyscale buttons.

![buttons placement](./imgs/3-buttons-button_placement.png)

 

**One Primary Button**

Primary buttons apply only to Call-to-Action buttons.

![buttons primary](./imgs/3-buttons-one_primary_button.png)

 

 

#### Specifications

![button specs](./imgs/3-buttons-specs.png)

 

 

 

---

### Dialogs

A dialog is a “conversation” between the system and the user, which often requests information or action from the user. For info about the extension configuration dialog, learn more at **[Extension Components and Modes](ux_components_modes.md)**.

#### Standard Dialog
These dialogs are non-modal, meaning they can be used when the requested information is not essential to continue. The dialog can be left open while the user interacts with other components in the extension. 

![standard dialog](./imgs/3-dialogs-standard.png)

 

#### Tab Dialogs
If you’d like to have multiple sections to your dialogs, you may use tabs to separate content. 

##### Top Tabs
Top tabs allow a dialog to contain several pages of content in one place. Use this variation to have 3 distinct sections of content. Do not exceed 3 top tabs.

![top tabs labeled](./imgs/3-top_tabs_labeled.png)

 

##### Side Tabs
If you need more tabs in a dialog than the top tab system can accommodate, it is appropriate to utilize the side tab style of navigation. Use this tab variation if you need 3 or more sections of content. Do not exceed 5 side tabs. 

![side tabs labeled](./imgs/3-side_tabs_labeled.png)

 

 

#### Specifications
Dialog content can vary widely, but consists of specific textual or UI elements that should meet some of the following standards.

###### Standard Dialog

![standard dialog specs](./imgs/3-dialogs-standard_specs.png)

 

###### Top Tab Dialog

![top tab dialog specs](./imgs/3-dialogs-top_tabs_specs.png)

![top tab header specs](./imgs/3-dialogs-top_tabs_header_specs.png)

 

###### Side Tab Dialog

![side tab specs](./imgs/3-dialogs-side_tabs_specs.png)

 

###### Dialog Widths
Dialog height will vary based on content but width will fit into one of these standard sizes. 

![standard dialog widths](./imgs/3-standard_dialog_widths.png)

 

 

 

---

### Dropdowns

Dropdown controls allow multiple options to be expanded from a menu. Dropdowns have two main components: **Control and Menu**. 

![dropdowns cover](./imgs/3-dropdowns-cover.png)

#### Usage

|  | How to use |
| --- | --- |
| **Controls            ** | Dropdown controls have an arrow on the right side, which indicates the control is actionable. This button is primarily used in dialogues to indicate an action.  |
| **Menu** | A dropdown menu contains a group of selections. When a menu item is selected, the dropdown control is updated to reflect the user's new choice. |

 

###### Control Variations

![control variations](./imgs/3-dropdowns-control_variations.png)

|  | How to use |
| --- | --- |
| **Outline** | The outline style is the primary variation that should be used. It can be used by itself, on forms, or within dialogues.  |
| **Line** (label optional)                 | Line style dropdowns are useful in areas that have cramped vertical space. This dropdown style can be stacked within panels to avoid a boxy wireframe feel. While the label is optional, we encourage using it to better inform users about the category of items. |
| **Text** | This style allows the user to access options from a dropdown or flyout menu. This style works well in tool and start bars, as well as in dialogs and menus. |
| **Icon** | The icon style works best in small regions such as tool bars, and is great for switches that have several options. |

 

###### Menu Variations

![menu variations](./imgs/3-dropdowns-menu_variations.png)

|  | How to use |
| --- | --- |
| **Standard** | This is the primary dropdown menu style. If your dropdown menu has many items or needs more classification, consider implementing some of the other options pictured. |
| **Nested Flyout** | If your menu needs more broad categories to choose specific items from, it can have a nested flyout menu. |
| **Search** | Search can be added to dropdown menus. Use this variation if your menu may have many items in the list to allow users to easily search for a specific item.  |
| **Checkbox** | Checkboxes can be used for multi-select dropdowns. |
| **Compound** | Compound menus allow for items to be grouped by separate types. |

 

###### Stacking Dropdowns

Use the line style when stacking several dropdowns on top of each other to avoid a boxy wireframe look and feel. 

![stacking dropdowns](./imgs/3-dropdowns-stacking.png)

###### Dropdown Menus

There is no space between the control and the menu. The minimum menu width is 40px, and the maximum is 260px. Menus can be wider than the control, but should not be narrower.

![align control and menus](./imgs/3-dropdowns-menu_align.png)

 

 

#### Specifications
Design specifications are grouped by the type of control and their corresponding control states, then menu variations. 

###### Controls

![default controls+menu spec](./imgs/3-dropdowns-controls_and_standard_menu_spec.png)

![line controls spec](./imgs/3-dropdowns-line_controls_spec.png)

![icon control](./imgs/3-dropdowns-icon_controls_spec.png)

###### Menus

![menu and flyout spec](./imgs/3-dropdowns-menu_and_flyout_spec.png)

![menu variations spec](./imgs/3-dropdowns-menu_variations_spec.png)

 

 

 

---

### Selectors
Selectors are a broad family of controls within the interface. This family has been broken down into four categories: **Pickers, Sliders, Steppers, and Toggles**.

![selectors](./imgs/3-selectors-cover.png)

 

#### Usage

|     | How to use    |
| --- | --- | 
| **Pickers** | Pickers enable users to make a selection from a list of options. Each picker has an icon control such as a checkbox or radio button. |
| **Sliders** | Sliders enable users to adjust totals without inputs via the keyboard. They are a convenient choice for selecting a value when there are known maximum and minimum values. |
| **Steppers** | Steppers enable users to click or tap on a control to change values. They often have a text input allowing the user to choose between keyboard input and mouse/tap input. |
| **Toggles** | Toggles are the simplest picker. They enable users to choose one item, while one or more items are off.  |

 

#### Specifications

###### Pickers

![pickers spec](./imgs/3-selectors-pickers_spec.png)

###### Sliders

![sliders spec](./imgs/3-selectors-sliders_spec.png)

###### Steppers

![steppers spec](./imgs/3-selectors-steppers_spec.png)

###### Toggles

![toggle spec](./imgs/3-selectors-toggle_spec.png)

 

 

 

---

### Text Fields
Text fields are places in the user interface where users enter text or phrases, such as on a form or sign in page.

![text fields cover](./imgs/3-text_fields_cover.png)

 

#### Usage

|                                             | How to use    |
| --- | --- | 
| **Outline Text** | The outline style has a prominent appearance that can be used by itself, on forms, or within dialogues. |
| **Line Text** | The line text field can be used for stacking multiple fields within a panel to avoid a boxy wireframe feel. Line style text fields are useful in areas that have extremely limited vertical space.  |
| **Search** | Search boxes allow users to search for terms, and appear at the top of a page or dialog. |

  

###### Stacking Text Fields

Always use the line text field style in forms, or when fields are stacked.

![text fields stacking](./imgs/3-text_fields_stacking.png)

  

#### Specifications

###### Default

![text field specs](./imgs/3-text_field_default_specs.png)

###### Search

![search field](./imgs/3-text_field_search_specs.png)

 

 

 

---

### Tooltips
Ideally, your users should be able to figure out how to use your extension without needing a guide. But to help users understand more context to the task they’re performing, you may utilize tooltips.

In general, tooltips are general small boxes that contain information about the item. When the user places their cursor over an item without clicking it (hover), a tooltip may appear.

![tooltips cover](./imgs/3-tooltips.png)

 

#### Usage
Descriptive tooltips are always anchored to the element with which they are associated. Tooltips can help further describe controls without shifting the user’s attention away from the primary interface. You may want to put tooltips in some parts of your extension if you want to briefly explain the use of a particular control or section. 

###### Placement

Tooltips should not cover other icons in the toolbar, or block related content.

![tooltips placement](./imgs/3-tooltips_placement.png)

###### Content

Include succinct copy that helps the user take their next step. 

![tooltips content](./imgs/3-tooltips_content.png)

 

#### Specifications

![tooltips spec](./imgs/3-tooltips_spec.png)

---

## Branding your Extension

Whether you’re a developer from one of our partners or an independent developer, you may want to brand your extension to visually distinguish it as your extension. You also have the option of styling your extension to look native to Tableau. 

* [Branding Principles](#branding-principles)
* [Styling Options](#styling-options)
* [Configuration Dialog](#configuration-dialog)
* [Extension Container](#extension-container)
* [Media and External Links](#media-and-external-links)

### Branding Principles

There are two fundamental principles to consider when branding your extension.

**Celebrate content** 
Your extension is designed to give users eye room to focus and plenty of negative space to help quickly parse the tools. Colors and tones don’t stress the eye. The UI is muted, and takes a back seat, allowing the content to be the hero.

**Focus on functionality**
Fun and delightful, but never at the expense of functionality or utility. Enough focus to find what you need, but not so much that it visually interferes with your content. Everything has a visual purpose.

Proper extension branding means that brand elements are subtle enough to let the function and content of the extension shine, but are also present enough to be noticed and recognized. Function and content come first, brand comes second. 

 

### Styling Options
You have the option of using Tableau's visual styling or your personal/company branding on your extension. 

**You might style your extension like Tableau if...**

* You want your extension to match the visual style of Tableau’s workbooks, making it feel like it fits naturally into Tableau.
* You don’t have a style guide to work with currently, and want to use a generic one for extensions.

**You might style your extension with personal or company branding if...**

* You want more visibility, exposure, or recognition for your personal/company work.
* You have an existing style to work with.

Either option offers flexibility in the styling and content of your extension. In the end, it's up to you to decide the best direction for your extension.

 

### Placement
Your extension can be branded through two components: the **configuration dialog** and the **extension container**. Here's how to place brand elements in each of these areas. 

Links to review component usage and controls specifications:

* **[Extension Components and Modes](../Interaction_Guidelines/ux_components_modes.md)**
* **[Controls and UI Patterns](../Interaction_Guidelines/ux_controls_ui_patterns.md)**

 

#### Configuration Dialog
Configuration dialogs act as the main point of brand communication with dashboard authors.

 

##### Headers
One place to put brand elements in a configuration dialog is the header region. Upon opening configuration, dashboard authors will naturally view the top of the dialog. 

The recommended height for the branded header is **50px** with vertical margins of **12px** and horizontal margins of **18px**. In this brand header, a logo/wordmark is **26px**. Because the header is also where the extension name is displayed, headers are limited in size as to not distract from the main content of the extension dialog. This is the preferred header styling for configuration dialogs.

![branded headers for configuration dialogs](./imgs/4-config_headers.png)

If your extension's configuration dialog is large and includes more content and controls, your brand elements may benefit from being larger. This header styling should only be used if the configuration dialog is **larger than 375px in height**. 

![alternative brand headers - larger configuration dialogs](./imgs/4-large_config_headers.png)

 

##### Footers
Another place to put brand elements in a configuration dialog is the footer region. The footer is less obtrusive than a header, allowing your extension content to come first and foremost. Sizing for the branded footer is more flexible than the branded header because it comes after the main extension content. 

**If you have brand elements that must be displayed at larger than 40px in height, it is preferable to use a branded footer.** The branded footer can accommodate variable heights of elements, small or large. However, still ensure that the branded footer elements do not visually overwhelm the main extension content that lives above it.

![branded footers for configuration dialogs](./imgs/4-config_footers.png)

 

 

#### Extension Container
Extension containers are visible to both dashboard authors and viewers. **We recommend that extensions in the dashboard should align with Tableau’s visual style** to allow extensions to feel like they naturally belong in Tableau dashboards and worksheets. For example, controls should be styled to look like Tableau's controls.

However, there are still small opportunities to increase visibility of your company and brand. Here are some guidelines for including brand elements in your extension container.

 

##### Corners
Space is limited in extension containers because the content should be mainly focused on the extension. The suggested brand elements to use in extension containers are brand colors and small logos/wordmarks.

Brand elements must be minimal and limited to the corners of headers and footers. We recommend placing logos in the corners of the container because this placement will allow for a brand presence to be noticed, but is still separate enough from the content. 

![branded header for extension container](./imgs/4-container_header.png)

The max height of header and footer zones should be **50px or less**. Content in the extension container should maintain a minimum of **12px** from the tops and bottoms (vertical margins), and **15px** from the left and right sides (horizontal margins). 

![branded footer for extension container](./imgs/4-container_footer.png)

  

##### Empty Container State
While a user is initially configuring the extension, the extension container doesn’t have anything in it yet. Rather than simply showing it as empty or blank, you may use this opportunity to provide feedback to the user that the system is doing its job. Feedback in this context can help users understand what the extension is currently doing. 

Here are some examples of things you can do with this empty space.

![empty container state](./imgs/4-empty_container_state.png)

| | Description |
| --- | --- |
| **Branded launch screen**         | Much like a static splash screen that simply presents your company/personal branding logos/etc. |
| **Loading graphic or animation** | Use to give the appearance of preparing content in the background as the user configures your extension. This could also be a graphic or animation based on your existing branding. |
| **Preview or placeholder UI** | Using neutral and basic visual styling, you can show a preview of where elements will show up once the extension is done being configured.  |

  

 

### Media and External Links
Headers and footers in configuration dialogs and extension containers can contain media and external links, but it is recommended that you use a **branded footer** as the primary place to put these elements. 

Headers must be restricted in size to prioritize the extension content below it, so footers usually offer the most flexibility in adding additional brand elements other than a logo or wordmark. 

Here are some items you might choose to include:

- Link to company or developer website
- Link to extension support/documentation
- Common social media icons

Any external links must open in the user's OS browser, not within Tableau's extension container or dialogs.

  

 

---

## Color

Use of color is essential for communication. Color is one of the first visual elements people notice, and it’s the most easily remembered.

 

### Color Principles

**Use colors with purpose and clarity.** Your color choices should highlight your extension's content, while also communicating its function. You should be able to justify the colors used on your extension: why did you choose that specific color, and what does it communicate to your user? Color is also an opportunity to showcase your brand. Learn more at **[Branding your Extension](ux_branding.md)**.

**Less is more.** Refrain from using too many colors, which could blur the focus. Try to avoid using color applied to text, which can make words difficult to distinguish and decrease legibility. 

**Consider vision accessibility.** Some part of the population have varying levels of color-vision deficiencies. Choose color palettes that can work well universally. This typically means avoiding reds and greens, or at least choosing reds and greens that can be seen by people with CVD.

 

 

### Tableau System Colors

If you don’t have a brand or personal color palette to work off of, you may choose to use Tableau’s standard system colors. The Tableau color palette provides the flexibility to communicate both simple and complex concepts and actions. 

 

##### Functional Colors

Colors are a key piece of the visual design language. Colors allow for quick and easy recognition of different element types.

| Dimension  |  Measure | Confirmation | Attention |  Action |
|---|---|---|---|---|
| ![Discrete Blue](./imgs/6-discrete_blue.png) **Discrete Blue** 73, 150, 178 #4996B2 | ![Continuous Green](./imgs/6-continuous_green.png) **Continuous Green** 0, 177, 128 #00B180 | ![Go Green](./imgs/6-go_green.png) **Go Green** 45, 204, 151 #2DCC97 | ![Attention Red](./imgs/6-attention_red.png)**Attention Red** 235, 68, 84 #EB4454 | ![Action Orange](./imgs/6-action_orange.png) **Action Orange** 235, 143, 80 #EB8F50 | 
| ![Discrete Dark](./imgs/6-discrete_dark.png) **Discrete Dark** 54, 126,156 #367E9C | ![Continuous Dark](./imgs/6-continuous_dark.png) **Continuous Dark** 0, 151, 104 #009768 | ![Go Green Dark](./imgs/6-go_green_dark.png) **Go Green Dark** 47, 163, 125 #2FA37D | ![Attention Red Dark](./imgs/6-attention_red_dark.png) **Attention Red Dark** 201, 58, 71 #C93A47 | ![Action Orange Dark](./imgs/6-action_orange_dark.png) **Action Orange Dark** 222, 107, 54 #DE6B36 |

 

##### Fills and Lines

Colors used for lines, fills, and other non-functional elements consist of this array of gray tones, which accentuate the functional colors.

|   |   |   |   |   |
|---|---|---|---|---|
| ![F1](./imgs/6-F1.png) **F1** 250, 250, 250 #FAFAFA | ![F2](./imgs/6-F2.png) **F2** 245, 245, 245 #F5F5F5 | ![F2.5](./imgs/6-F2.5.png) **F2.5** 235, 235, 235 #EBEBEB | ![F3](./imgs/6-F3.png) **F3** 230, 230, 230 #E6E6E6 | ![F4](./imgs/6-F4.png) **F4** 225, 225, 225 #E1E1E1 |
| ![F5](./imgs/6-F5.png) **F5** 212, 212, 212 #D4D4D4 | ![F6](./imgs/6-F6.png) **F6** 203, 203, 203 #CBCBCB | ![F7](./imgs/6-F7.png) **F7** 180, 180, 180 #B4B4B4 | ![F8](./imgs/6-F8.png) **F8** 102, 102, 102 #666666 | ![F9](./imgs/6-F9.png) **F9** 51, 51, 51 #333333 |

 

##### Fonts

Fonts in Tableau range from black to white and a variety of opacities. Primary, secondary, and other fonts all have specified opacity.

|   |   |   |   |   |   |
|---|---|---|---|---|---|
| ![100% Black](./imgs/6-100_black.png) **100% Black** Focused | ![80% Black](./imgs/6-80_black.png) **80% Black** Primary | ![70% Black](./imgs/6-70_black.png) **70% Black** Secondary | ![60% Black](./imgs/6-60_black.png) **60% Black** Tertiary | ![56% Black](./imgs/6-56_black.png) **56% Black** Tertiary | ![35% Black](./imgs/6-35_black.png) **35% Black** Disabled
| ![100% White](./imgs/6-100_white.png) **100% White** Primary | ![56% White](./imgs/6-56_white.png) **56% White** Secondary | ![35% White](./imgs/6-35_white.png) **35% White** Disabled

---

## Fonts

Fonts and typography are essential to how we communicate with our users. When text is used effectively, it grabs attention, evokes emotion, and emphasizes tone and voice.

> **Note:** Starting with the Dashboard Extensions API v1.7 library, and supported with Tableau 2021.4 or later, you can apply workbook formatting on the HTML elements in your extension. For more information, see [Add Tableau Workbook Formatting](../core/trex_format.md).

 

### Typography Principles

**Highlight important information through hierarchy**. Let users know what content is important by having a simple and clear hierarchy of type. This is achievable through variations in font size, weight, color and spacing.

**Less is more**. Fewer words and less variation in hierarchy reduces confusion by allowing users to focus their attention on only the most necessary content.  

**Limit font and weight variations.** Mixing too many different fonts and font weights can confuse the type hierarchy. In fonts, mediums and bolds should be used sparingly to indicate headers or important content.

 

 


We recommend that you use a **sans serif font family** in your extension. Here, we provide guidance and options that are compatible with Tableau dashboards. Using these exact fonts is optional. 

 

##### Benton Sans
Benton Sans Book is the default font for the Tableau UI elements. To learn more about Tableau font colors, see [Color](./ux_color.md).

Other weight variations of Benton Sans should be used infrequently. For example, Benton Sans Medium is typically used for section titles in dialogs. Benton Sans Light and Book Italic are used in more specific cases like lightweight captions and should not be overused. 

###### Font Size
For Tableau Desktop, the default size for Benton Sans on Mac OS X is **12pt**. The default size for Benton Sans on Windows is **10pt**. 

![benton sans weights](./imgs/7-benton_sans.png)

You may use Benton Sans if you want your extension to look and feel natural to Tableau. Tableau is a licensed commercial user of Benton Sans–so if there are potential conflicts or liabilities with using Benton Sans due to your company branding, we have listed several alternative fonts below.

 

##### Alternative Fonts
Using some of these common fonts that are likely available on your user's machine can improve performance and load times for your extension. Here are some recommendations for common sans serif font families. 

* Helvetica
* Arial
* Open Sans
* Segoe UI (Windows system font)
* San Francisco (Mac OS X system font)
* Helvetica Neue, Lucida Grande (older Max OS X)

###### Font Size
It is important to compensate for OS and device specific DPI and font rendering. Since these are alternative fonts that aren't directly used in Tableau, you may choose to use different font sizes and weights based on your extension's design needs.

---

## Layout

To encourage consistency across the design of extensions, we’ve outlined some important aspects about dashboard containers and spacing of elements for your **extension container**. 

### Dashboard Containers
When designing an extension container's contents and controls, consider the common sizes of containers in a dashboard. Containers and objects are added to the dashboard via drag-and-drop. Containers can be manually resized and made to be floating. You will have to ensure that the content of your extension container will resize and display properly. It is recommended to use common responsive web design practices, such as use of breakpoints and percent-based widths.

Generally, dashboard containers will automatically size to one of these formats:

#### Horizontal Span

Your extension content should consider how it would display properly when the container spans wide or horizontally.

![container size - full horizontal width](./imgs/5-full_width.png)

 

#### Vertical Span

Your extension content should also consider how it would display properly when the container spans tall or vertically. 

![container size - full vertical height](./imgs/5-full_height.png)

 

#### Quadrant/Section

It is common for extensions to take up a smaller size due to most of the functionality taking place in the configuration dialog rather than the extension container. Your extension should properly resize to accomodate for smaller areas like quadrants and sections. 

![container size - quadrant or section](./imgs/5-section.png)

 

 

### Spacing

Specifications about spacing have been detailed in **[Controls and UI Patterns](../Interaction_Guidelines/ux_controls_ui_patterns.md)** and **[Branding your Extension](ux_branding.md)**.

Here are some links to specific parts of your extension that you may need spacing guidance on:

* [**Dialogs** (Controls and UI Patterns)](../Interaction_Guidelines/ux_controls_ui_patterns.md#dialogs)
* [**Configuration Dialog** (Branding your Extension)](../Style_Guidelines/ux_branding.md#configuration-dialog)
* [**Extension Container** (Branding your Extension)](../Style_Guidelines/ux_branding.md#extension-container)