Editor add-onsbuild user interfaces (menus, sidebars, and dialogs) using Apps Script'sHTML service. Because the interfacesare developed in HTML and CSS, they are highly customizable. However, whenbuilding your add-on interface you should design it to provide a great userexperience.

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

• Use theadd-ons CSS package in yourHTML service pages.
• When in doubt about design, find a similar dialog or sidebar in the editor andmatch it, or refer to anadd-on quickstart.
• Follow this style guide to create a seamless experience.

Text

Add-on name

You must set your add-on's name when youpublishit. 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 beautomatically truncated.
• Don’t include the name of the Google product the add-on is for (or use theword Google).
• Leave out version information.
• Make sure the add-on's published name is the same as the filename of thescript 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 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 menu items).
• Prefer short, simple text without jargon or acronyms.

Post-install tip

Your post-install tip pops up right after someone installs your add-on, and alsoshows 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

Menu items

Unlike regular Apps Script projects, add-ons don't appear in the script editoror script manager; users cannot run add-on scripts directly. Instead, everyadd-on gets a spot in theadd-ons menu.The menu (and possibly adialog or sidebar) letusers interact with the add-on.

• The menu is a key part of how users control your add-on, so design itsstructure and wording carefully.
• Avoid menu items that simply repeat your add-on’s name. Instead, start with anaction word.
• If your main menu item begins a workflow and there's no single verb thatdescribes what it does, call it "Start". This pattern is used in theDocs add-on quickstart.
• Unless your menu has more than six items, try not to use sub-menus. They canbe 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 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...catchstatements to intercept exceptions, then display a user-friendly error messagewith inline text styled in theerror class from the add-ons CSSpackage or analert dialog.
• Before you publish, check that your add-on doesn't log debug information tothe JavaScript console; useStackdriver logginginstead.

Don't	Do

Help content

Every add-on's menu includes an automatic Help dialog. If you provide a help URLwhen you publish, the "Learn more" button links to that page. Unless youradd-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 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 your help content from your main user interface as well.If your add-on creates a fresh document, you can also display instructions inthe body of the document.

Custom user interfaces

Some simple Editor add-ons can be controlled entirely by their menu, but mostdisplay asidebar or dialog with customcontent.

• Sidebars are best for persistent tools that people are likely to userepeatedly 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 youradd-on lets people insert a graphic, you might display a dialog with choices ofwhat to insert¸ then close the dialog when the graphic is inserted. Dialogs arealso helpful for displaying your add-on’s settings, or for communicating animportant message.

• Don't open a dialog (including analert or prompt) from another dialog—onlydisplay one at a time.
• For the dialog title, use a word or short phrase, leading with the mostimportant word.
• Button labels should relate to the dialog title.
• Prefer two buttons, usually a primary action and "Cancel". For special casesthat require a third button, consider the bottom-right corner.
• Put buttons in the bottom-left corner of the dialog. The blue primary buttonshould 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 toopen sidebars simultaneously, only one is shown.
• Don't display a sidebar or dialog when a document first opens.
• Only add-ons operating inAuthMode.FULLcan open sidebars or dialogs. You can use amenu item to opena sidebar since this prompts the user to provide full authorization.

Controls

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

The documentation for theadd-ons CSS packageprovides sample markup for each of the types of controls below.

Buttons

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

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

Checkboxes and radio buttons

Use checkboxes when people can select multiple options, or no option at all. Useradio 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. Waituntil 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 canunderstand (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 iteasier 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’tlook 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 helpspeople focus on your UI, and makes your add-on feel like part of the editor.

• All aspects of your add-on must follow thebranding guidelines.
• Don’t include the word “Google” or use Google product icons.
• Text should be no more than a few words and styled in thegray class from the add-ons CSSpackage.
• 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

In order to publish an Editor add-on, you need anumber of image assets.These assets are used to construct the add-on store listing.

• All aspects of your store listing must follow thebranding guidelines.
• For more details on the images you need to provide, see theimage guidelines.

Accessibility

Everyone should be able to enjoy your add-on, whether they see colorsdifferently, use a screen reader, or have other needs. Accessibility is a broadtopic that can’t be fully covered in this style guide. One helpful resource istheGoogle Accessibility site. But hereare a few tips to get started:

• Make sure you can navigate to all UI controls with the keyboard. Addtabindex=0 to custom controls (like those made with<div>) so people cantab to them. Consider if other keys should be supported too, such as arrowsfor a list.
• Some people may use a screen reader with your add-on. Thus, images shouldhave analt attribute,and custom controls should haveARIA 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.