UI Style Guide for Add-ons

The best add-ons are consistent with the style and layout of the Google Sheets, Docs, Slides, and Forms editors. They extend each editor naturally by using familiar controls and behaviors. When building a new add-on:

  • Use the add-ons CSS package in your HTML service pages. (And don't use UI service to create a public add-on — it won't look as professional.)
  • When in doubt about design, find a similar dialog or sidebar in the editor and match it, or refer to the add-ons quickstart.
  • To maintain the style of the Google editors, please avoid using Material Design or Polymer elements in your add-on.
  • Follow this style guide to create a seamless experience.

Text

Add-on name

You'll set your add-on's name when you publish it. The name appears in many places, such as the add-on store and within menus.

  • Use title case.
  • Avoid punctuation, especially parentheses, unless part of your brand.
  • Keep it short — 30 or fewer characters is best. Long names may be automatically truncated.
  • Don’t include the name of the Google product the add-on is for (or use the word Google).
  • Leave out version information.
  • Make sure the add-on's published name is the same as the filename of the script project. (The project name appears in the authorization dialog.)
Don't Do
Bad add-on names Good add-on names

Writing style

You shouldn’t need to write much. Most actions should be made clear through iconography, layout, and short labels. When writing UI text:

  • Use sentence case (especially for buttons, labels, and menu items).
  • Prefer short, simple text without jargon or acronyms.
Don't Do

Post-install tip

Your post-install tip pops up right after someone installs your add-on, and also shows up in Help. You have a couple sentences to help users get started quickly.

  • Start with an action word.
  • Describe the first step for using your add-on.
  • If you have a main UI, such as a sidebar, explain how to open it.
  • Don’t promo your add-on here — it’s already installed.
Don't Do
Bad post-install tip Good post-install tip

Unlike regular Apps Script projects, add-ons don't appear in the script editor or script manager; users cannot run add-on scripts directly. Instead, every add-on gets a spot in the Add-ons menu. The menu (and possibly a dialog or sidebar) let users interact with the add-on.

  • The menu is a key part of how users will control your add-on, so design its structure and wording carefully.
  • Avoid menu items that simply repeat your add-on’s name. Instead, start with an action word.
  • If your main menu item begins a workflow and there's no single verb that describes what it does, call it "Start". You'll see this in the add-ons quickstart.
  • Unless your menu has more than six items, try not to use sub-menus. They can be finicky and hard to select.
  • Describe the task, not the UI component that the menu item will display.
Don't Do
Bad menu-item labels Good menu-item labels

Error messages

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

  • Don't allow the user to see any exceptions your code throws. Instead, use try...catch statements to intercept exceptions, then display a user-friedly error message with inline text styled in the error class from the add-ons CSS package or an alert dialog.
  • Before you publish, check that your add-on doesn't log debug information to the JavaScript console.
Don't Do
Bad error message Good error message

Help content

Every add-on's menu includes an automatic Help dialog. If you provide a help URL when you publish, the "Learn more" button will link to that page. Unless your add-on is self-explanatory, please provide a page that explains how to use it.

  • When possible, show instructions in a bulleted or numbered list. Walk users through to the end result, with clear references to named UI elements.
  • Make sure your instructions clearly explain any requirements, like setting up a spreadsheet in a certain way.
  • Feel free to link to your help content from your main user interface as well. If your add-on creates a fresh document, you can also display instructions in the body of the document.

Custom user interfaces

Some simple add-ons can be controlled entirely by their menu, but most display a sidebar or dialog with custom content.

  • Sidebars are best for persistent tools that people are likely to use repeatedly while referring to the content of their document or spreadsheet.
  • Dialogs are best for single-use tools, settings pages, and important messages.

UI text

In any dialog or sidebar, assume people will read only the title and button labels. Can they still figure out what your interface does and make a good choice?

  • Use a title and button labels that stand on their own.
  • Avoid long blocks of descriptive text.

Dialogs

Dialogs are great for tools people use once, then move on. For example, if your add-on lets people insert a graphic, you might display a dialog with choices of what to insert¸ then close the dialog when the graphic is inserted. Dialogs are also helpful for displaying your add-on’s settings, or for communicating an important message.

  • Don't open a dialog (including an alert or prompt) from another dialog — only display one at a time.
  • For the dialog title, use a word or short phrase, leading with the most important word.
  • Button labels should relate to the dialog title.
  • Prefer two buttons, usually a primary action and "Cancel". For special cases that require a third button, consider the bottom-right corner.
  • Put buttons in the bottom-left corner of the dialog. The blue primary button should be on the left, with any gray secondary buttons to the right.
Don't Do
Bad dialog title Good dialog title

Sidebars let people refer back to their document or spreadsheet while making choices. They also let people use your add-on repeatedly. Whenever a new sidebar is opened, any previous sidebar closes automatically. They’re best for temporary modes that the user will exit when done.

  • Don’t display a sidebar when a document first opens, unless a user indicates they want it to open automatically. For example, an add-on to manage document approval could open a sidebar automatically after someone starts the approval flow for that particular document.
  • Remember, people might have other add-ons with their own sidebars. If two add-ons try to open sidebars when a document opens, only one will show.
  • Also, if your sidebar opens automatically, calls to the server may fail for collaborators who haven't yet authorized the add-on. For more information, see the guide to the authorization lifecycle.

Controls

Great add-on UIs leave their controls some breathing room. Adequate margins and padding go a long way, whereas dense controls can seem overwhelming. When in doubt, borrow a layout from the editor itself. For example, review existing dialogs in Google Docs, such as File > Page setup, when creating your own.

The documentation for the add-ons CSS package provides sample markup for each of the types of controls below.

Buttons

Use buttons to control your user interface's main actions rather than plain links or other elements.

  • Avoid displaying more than one blue, red, or green button at a time. Gray buttons may appear repeatedly.
  • Most button labels should be in sentence case and start with a verb. Red buttons, usually for create actions, should use all caps.
Don't Do

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.

  • Don’t change checkboxes' behavior to mimic radio buttons.
  • Don’t do anything immediately when they’re checked. People make mistakes. Wait until your users click a button to confirm their choices.

Select menus

Selects are a great way to offer a short list of alternatives.

  • Sort the options alphabetically or by a logical scheme that all users will understand (like days of the week, starting from Sunday).
  • If the list grows too long, consider using a different control. For example, you might display a scrollable list to give the menu more space and make it easier to navigate.

Text areas

If people will need to type more than a few words, use a text area.

  • Make text areas at least two lines tall so they’re easier to use and don’t look like text fields.
  • Place labels on top.

Text fields

Use text fields if people only need to type a word or two.

  • A text field’s width should suggest what you expect people to type in it.
  • Avoid using placeholder text as a label, because it disappears on focus. Placeholder text is useful for giving examples or extra detail.
  • Place labels on top, but feel free to lay out short text fields side-by-side.

Branding

In your add-on

If you’d like to include branding, keep it brief and light. This will help people focus on your UI, and your add-on will feel like part of the editor.

  • All aspects of your add-on must follow the branding guidelines.
  • Don’t include the word “Google” or use Google product icons.
  • Text should be no more than a few words and styled in the gray class from the add-ons CSS package.
  • Graphics should be on a white background and no more than 200px × 60px.
  • For dialogs, branding should be in the bottom-right corner.
  • For sidebars, branding can be at the top or bottom.

In the store

As the publication instructions say, you'll need at least three visual assets for the store: a 128px × 128px icon, a 1280px × 800px screenshot, and a 440px x 280px tile image. (A 920px × 680px large tile is also recommended, since they are sometimes shown for popular add-ons, but the 1400px × 560px marquee tile is not used.)

Accessibility

Everyone should be able to enjoy your add-on, whether they see colors differently, use a screen reader, or have other needs. Accessibility is a broad topic that can’t be fully covered in this style guide. One helpful resource is the Google Accessibility site. But here are a few tips to get started:

  • Make sure you can navigate to all UI controls with the keyboard. Add tabindex=0 to custom controls (like those made with <div>) so people can tab to them. Consider if other keys should be supported too, such as arrows for a list.
  • Some people will use a screen reader with your add-on. Thus, images should have an alt attribute, and custom controls should have ARIA attributes to describe their use.
  • Don’t rely solely on color to communicate state. Use icons and text too.

If you use standard web controls, like those described earlier in this guide, it’ll be easier to make your add-on accessible.

发送以下问题的反馈:

此网页
Apps Script
Apps Script