Page Summary

outlined_flag

• Google Workspace add-ons should seamlessly integrate with the host application's style and layout using familiar controls and behaviors.

• Add-on names should be concise, using title case, avoiding punctuation and Google product names, and kept to 15 characters or less.

• UI text should be minimal, using sentence case, simple language, and clear action verbs in menus and buttons.

• Branding should be subtle within the add-on, adhering to Google's branding guidelines, and avoiding Google product names or icons.

• Error messages should be user-friendly, providing clear explanations and solutions instead of technical jargon or exceptions.

Google Workspace add-ons should be consistent with thestyle and layout of thehost applicationthey extend. They should extend the UInaturally by using familiar controls and behaviors. The guidelines presentedhere describe ways of handling text, images, controls, and branding that promotea high-quality user experience.

If your add-on opens separate web pages that are an integral part of the add-on'soperation (such as a settings page for the add-on), make sure those web pagesalso follow these style guidelines.

Text and images

This section tells you how to properly use text and images in your add-on.

Add-on name

You must set your add-on's name in its projectmanifest and when youconfigure your add-on for publication.The name appears in many places, such as theGoogle Workspace Marketplacelisting and within menus. When choosing a name:

• Use title case.
• Avoid punctuation, especially parentheses, unless part of your brand.
• Keep it short—15 or fewer characters is best. Long names may beautomatically truncated in the Google Workspace Marketplace listing and elsewhere.
• Don’t include the words "Google", "Gmail", or other Google product namesin your add-on name.
• Don't include the word "add-on" in your add-on name.
• Leave out version information.

Writing style

You shouldn’t need to write much. Most actions should be made clear throughiconography, layout, and short labels. If you find a portion of your add-onneeds more extensive explanation than short labels can provide, it's a bestpractice to create a separate web page describing your add-on and link to it.

When writing UI text:

• Use sentence case (especially for buttons, labels, and card actions).
• Prefer short, simple text without jargon or acronyms.

Universal and card actions

If you useuniversal actionsorcard actions in youradd-on, they appear as menu items in thecardsyou define. You can choose the text that is used in these menus for theseactions. When choosing the text to use:

• Avoid menu text that simply repeats your add-on’s name.
• Start each menu item with an action word such as "Run", "Configure", or"Create".
• Describe the task, not the UI component that the action displays.
• If your action begins a workflow and there's no single verb that describeswhat it does, call it "Start".
• Keep the number of menu items small to avoid forcing the user to scrollthrough a large list. If you have more actions to implement, consider usingmultiple cards with different actions on each.

Error messages

When something goes wrong, it’s important to use plain language. Explain theproblem from the user’s standpoint, and suggest how to fix it.

• Don't allow the user to see any exceptions your code throws. Instead,usetry...catch statements to intercept exceptions, then displaya user-friendly error message.
• Before you publish, check that your add-on doesn't display debug informationin the UI.

Help content

You may wish to design cards that display help information or explain theoperation of the add-on to the user. If you do build help content for youradd-on, remember to:

• When possible, show instructions in a bulleted or numbered list. Walk usersthrough to the end result, with clear references to named UI elements.
• Make sure your instructions clearly explain any requirements, like setting upa spreadsheet in a certain way.
• Feel free to link to external help content, such as supporting web pages.

Images

Images used in your add-on are either one of thebuilt-in icon typesor a publicly hosted image specified by a URL. When using hosted images,be sure that they are accessible by everyone who may use your add-on.

Controls

This section provide user experience guidelines forinteractive widgets.

Buttons

Use buttons to control your user interface's main actions rather thanother widgets.

• Most text button labels should start with a verb.
• Button rows should be limited to three or fewer buttons in most cases.

DecoratedText

DecoratedText widgetslet you present text content with icons, buttons or switches.

• Use sentence case for the text content.
• The text of a DecoratedText widget is truncated if it cannot fit into theavailable space. For this reason, always try to keep the text content asshort as you can.

Selection inputs

You can use a variety ofselection input widgetsin your add-on: drop-down selection boxes, checkboxes, and radio buttons.

• Use checkboxes when people can select multiple options, or no option at all.Use radio buttons (or a select menu) when exactly one option must be selected.Use dropdowns when providing a short list of alternatives while trying tosave space in the UI.
• Use sentence case for the text that is assigned to each option.
• Avoid using selection changes to trigger major, hard-to-reverse actions,because people often make mistakes when making selections. Instead, consideradding a button that reads the current selection values and then triggersthe action.
• For dropdowns, sort the options alphabetically or by a logical schemethat all users can understand (such as presenting the days of the weekin order, starting from Sunday or Monday).
• Restrict the number of options in a given selection inputwidget to a reasonable number. If there are too many options, users may findit hard to use the widget. In those cases, consider breaking the optioninto different categories and multiple widgets.

Text inputs

Text inputs provide a place for users to enter string data.

• Don't use a text input to make the user type one of a specific set ofpossible entries. Use a dropdown select instead.
• Use hints and suggestions to help the user enter text with the correctformat and content.
• Use multiline text inputs if the text to be entered is more than a fewwords.

Branding

This section provide user experience guidelines for adding branding elementsto your add-on interface.

In your add-on

If you’d like to include branding in your add-on UI, keep it brief and light.This helps people focus on your add-on functionality.

• All aspects of your add-on must follow thebranding guidelines.
• Don’t include the word “Google”, "Gmail", or other Google product names.
• Don't include Google product icons, even if they are altered.
• Don't include the word "add-on" in your branding text.
• Branding text should be no more than a few words.

In the Google Workspace Marketplace

When you configure your add-on for publication,you provide a number of graphical and text assets to build theGoogle Workspace Marketplace listing.

All aspects of your store listing and these assets must follow thebranding guidelines.