UI style guide for editor add-ons

Editor add-ons
build user interfaces (menus, sidebars, and dialogs) using Apps Script's
HTML service. Because the interfaces
are developed in HTML and CSS, they are highly customizable. However, when
building your add-on interface you should design it to provide a great user
experience.

The best add-ons extend each editor naturally by using familiar controls and
behaviors. When building a new add-on:

When in doubt about design, find a similar dialog or sidebar in the editor and
match it, or refer to an
add-on quickstart.

Follow this style guide to create a seamless experience.

Text

Add-on name

You must 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

Writing style

You shouldn’t need to write much. Most actions should be made clear through
iconography, layout, and short labels. If you find a portion of your add-on
needs more extensive explanation than short labels can provide, it's a best
practice 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 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.

If your main menu item begins a workflow and there's no single verb that
describes what it does, call it "Start". This pattern is used in the
Docs add-on 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 displays.

Don't

Do

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; use
Stackdriver logging
instead.

Don't

Do

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 links 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 editor 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 only read 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

Sidebars

Sidebars let people refer back to their document, spreadsheet, presentation,
or form 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 exits when done.

Users might have other add-ons with their own sidebars. If two add-ons try to
open sidebars simultaneously, only one is shown.

Don't display a sidebar or dialog when a document first opens.

Only add-ons operating in
AuthMode.FULL
can open sidebars or dialogs. You can use a menu item to open
a sidebar since this prompts the user to provide full authorization.

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 can
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 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 helps
people focus on your UI, and makes your add-on feel like part of the editor.

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 may 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,
making your add-on accessible is easier.