Guia de estilo da interface para complementos do Google Workspace
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Os complementos do Google Workspace precisam ser consistentes com o
estilo e o layout do
aplicativo host
que eles estendem. Eles precisam estender a interface
naturalmente usando controles e comportamentos familiares. As diretrizes apresentadas
aqui descrevem maneiras de lidar com texto, imagens, controles e branding que promovem
uma experiência do usuário de alta qualidade.
Se o complemento abrir páginas da Web separadas que são parte integrante da operação do complemento (como uma página de configurações), verifique se essas páginas da Web também seguem essas diretrizes de estilo.
Texto e imagens
Esta seção ensina a usar texto e imagens corretamente no seu complemento.
Evite usar pontuação, especialmente parênteses, a menos que faça parte da sua marca.
Mantenha-o curto: 15 caracteres ou menos é o ideal. Nomes longos podem ser
truncados automaticamente na página "Detalhes do app" do Google Workspace Marketplace e em outros lugares.
Não inclua as palavras "Google", "Gmail" ou outros nomes de produtos do Google
no nome do complemento.
Não inclua a palavra "complemento" no nome do complemento.
Não inclua informações de versão.
Estilo de escrita
Você não precisa escrever muito. A maioria das ações precisa ser clara por meio de
iconografia, layout e rótulos curtos. Se você achar que uma parte do seu complemento
precisa de uma explicação mais extensa do que os rótulos curtos podem oferecer, é recomendável
criar uma página da Web separada que descreva o complemento e criar um link para ele.
Ao escrever texto da interface:
Use letras maiúsculas e minúsculas (especialmente para botões, rótulos e ações de cartão).
Prefira textos curtos e simples, sem jargões ou acrônimos.
Ações universais e do card
Se você usar ações universais
ou ações de card no seu
complemento, elas vão aparecer como itens de menu nos cards
definidos. Você pode escolher o texto usado nesses menus para essas
ações. Ao escolher o texto a ser usado:
Evite textos de menu que simplesmente repetem o nome do complemento.
Comece cada item de menu com uma palavra de ação, como "Executar", "Configurar" ou
"Criar".
Descreva a tarefa, não o componente de interface que a ação mostra.
Se a ação iniciar um fluxo de trabalho e não houver um único verbo que descreva
o que ela faz, chame-a de "Start".
Mantenha o número de itens de menu pequeno para evitar que o usuário role
uma lista grande. Se você tiver mais ações para implementar, use
vários cards com ações diferentes em cada um.
Mensagens de erro
Quando algo dá errado, é importante usar linguagem simples. Explique o
problema do ponto de vista do usuário e sugira como corrigi-lo.
Não permita que o usuário veja as exceções geradas pelo código. Em vez disso,
use instruções try...catch para interceptar exceções e mostrar
uma mensagem de erro fácil de entender.
Antes de publicar, verifique se o complemento não mostra informações de depuração
na interface.
Conteúdo Help
Você pode projetar cards que mostram informações de ajuda ou explicam o
funcionamento do complemento ao usuário. Se você criar conteúdo de ajuda para seu
complemento, lembre-se de:
Quando possível, mostre as instruções em uma lista com marcadores ou numerada. Mostre aos usuários
o resultado final, com referências claras a elementos de interface nomeados.
As instruções precisam explicar claramente todos os requisitos, como configurar uma planilha de determinada maneira.
Você pode incluir links para conteúdo de ajuda externo, como páginas da Web de suporte.
Imagens
As imagens usadas no complemento são um dos
tipos de ícone integrados
ou uma imagem hospedada publicamente especificada por um URL. Ao usar imagens hospedadas,
verifique se elas são acessíveis por todos que podem usar seu complemento.
Controles
Esta seção fornece diretrizes de experiência do usuário para
widgets interativos.
Botões
Use botões para controlar as principais ações da interface do usuário em vez de
outros widgets.
A maioria dos rótulos de botões de texto precisa começar com um verbo.
Na maioria dos casos, as linhas de botões precisam ser limitadas a três botões ou menos.
DecoratedText
Os widgets DecoratedText
permitem apresentar conteúdo de texto com ícones, botões ou chaves.
Use letras maiúsculas apenas na primeira palavra.
O texto de um widget DecoratedText é truncado se não couber no
espaço disponível. Por isso, tente sempre manter o conteúdo do texto o mais
curto possível.
Entradas de seleção
Você pode usar vários
widgets de entrada de seleção
no seu complemento: caixas de seleção suspensas, caixas de seleção e botões de opção.
Use caixas de seleção quando as pessoas puderem selecionar várias opções ou nenhuma.
Use botões de opção (ou um menu de seleção) quando apenas uma opção precisa ser selecionada.
Use listas suspensas para fornecer uma lista curta de alternativas ao tentar
economizar espaço na interface.
Use letras maiúsculas apenas na primeira palavra do texto atribuído a cada opção.
Evite usar mudanças de seleção para acionar ações importantes e difíceis de reverter,
porque as pessoas costumam cometer erros ao fazer escolhas. Em vez disso, considere
adicionar um botão que leia os valores de seleção atuais e acione
a ação.
Para menus suspensos, classifique as opções em ordem alfabética ou por um esquema lógico
que todos os usuários possam entender (como apresentar os dias da semana
em ordem, começando pelo domingo ou segunda-feira).
Restringir o número de opções em um determinado widget de entrada de seleção
a um número razoável. Se houver muitas opções, os usuários podem
ter dificuldade para usar o widget. Nesses casos, considere dividir a opção
em diferentes categorias e vários widgets.
Entradas de texto
As entradas de texto oferecem um local para os usuários inserirem dados de string.
Não use uma entrada de texto para fazer o usuário digitar uma de um conjunto específico de
entradas possíveis. Use um menu suspenso.
Use dicas e sugestões para ajudar o usuário a inserir texto com o formato
e conteúdo corretos.
Use entradas de texto de várias linhas se o texto a ser inserido tiver mais de algumas
palavras.
Branding
Esta seção fornece diretrizes de experiência do usuário para adicionar elementos de marca
à interface do complemento.
No complemento
Se você quiser incluir a marca na interface do complemento, mantenha-a breve e leve.
Isso ajuda as pessoas a se concentrar na funcionalidade do seu complemento.
Todos os aspectos do seu complemento precisam seguir as
diretrizes de marca.
Não inclua as palavras "Google", "Gmail" ou outros nomes de produtos do Google.
Não inclua ícones de produtos do Google, mesmo que eles sejam alterados.
Não inclua a palavra "complemento" no texto de marca.
O texto de marca não pode ter mais do que algumas palavras.
No Google Workspace Marketplace
Ao configurar o complemento para publicação,
você fornece vários recursos gráficos e de texto para criar a
página do Google Workspace Marketplace.
Todos os aspectos da página "Detalhes do app" e esses recursos precisam seguir as
diretrizes de branding.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2024-12-22 UTC."],[[["\u003cp\u003eGoogle Workspace add-ons should seamlessly integrate with the host application's style and layout using familiar controls and behaviors.\u003c/p\u003e\n"],["\u003cp\u003eAdd-on names should be concise, using title case, avoiding punctuation and Google product names, and kept to 15 characters or less.\u003c/p\u003e\n"],["\u003cp\u003eUI text should be minimal, using sentence case, simple language, and clear action verbs in menus and buttons.\u003c/p\u003e\n"],["\u003cp\u003eBranding should be subtle within the add-on, adhering to Google's branding guidelines, and avoiding Google product names or icons.\u003c/p\u003e\n"],["\u003cp\u003eError messages should be user-friendly, providing clear explanations and solutions instead of technical jargon or exceptions.\u003c/p\u003e\n"]]],["Add-ons must match the host application's style and extend the UI naturally. Key actions include: using title case for the add-on's name (15 characters or less), and avoiding punctuation, Google product names, \"add-on\", and version info. UI text should be in sentence case, short, and jargon-free, with menu items starting with action words. Error messages should use plain language. Images should be accessible, buttons should primarily use verbs, and text inputs should employ hints. Branding must be brief, adhering to specific guidelines.\n"],null,["# UI style guide for Google Workspace add-ons\n\nGoogle Workspace add-ons should be consistent with the\nstyle and layout of the\n[host application](/workspace/add-ons/guides/glossary#host_or_host_application)\nthey extend. They should extend the UI\nnaturally by using familiar controls and behaviors. The guidelines presented\nhere describe ways of handling text, images, controls, and branding that promote\na high-quality user experience.\n\nIf your add-on opens separate web pages that are an integral part of the add-on's\noperation (such as a settings page for the add-on), make sure those web pages\nalso follow these style guidelines.\n\nText and images\n---------------\n\nThis section tells you how to properly use text and images in your add-on.\n\n### Add-on name\n\nYou must set your add-on's name in its project\n[manifest](/workspace/add-ons/concepts/workspace-manifests) and when you\n[configure your add-on for publication](/workspace/marketplace/sdk#text_assets).\nThe name appears in many places, such as the [Google Workspace Marketplace](https://workspace.google.com/marketplace/)\nlisting and within menus. When choosing a name:\n\n- Use title case.\n- Avoid punctuation, especially parentheses, unless part of your brand.\n- Keep it short---15 or fewer characters is best. Long names may be automatically truncated in the Google Workspace Marketplace listing and elsewhere.\n- Don't include the words \"Google\", \"Gmail\", or other Google product names in your add-on name.\n- Don't include the word \"add-on\" in your add-on name.\n- Leave out version information.\n\n### Writing style\n\nYou shouldn't need to write much. Most actions should be made clear through\niconography, layout, and short labels. If you find a portion of your add-on\nneeds more extensive explanation than short labels can provide, it's a best\npractice to create a separate web page describing your add-on and link to it.\n\nWhen writing UI text:\n\n- Use sentence case (especially for buttons, labels, and card actions).\n- Prefer short, simple text without jargon or acronyms.\n\n### Universal and card actions\n\nIf you use [universal actions](/workspace/add-ons/how-tos/universal-actions)\nor [card actions](/apps-script/reference/card-service/card-action) in your\nadd-on, they appear as menu items in the [cards](/workspace/add-ons/concepts/cards)\nyou define. You can choose the text that is used in these menus for these\nactions. When choosing the text to use:\n\n- Avoid menu text that simply repeats your add-on's name.\n- Start each menu item with an action word such as \"Run\", \"Configure\", or \"Create\".\n- Describe the task, not the UI component that the action displays.\n- If your action begins a workflow and there's no single verb that describes what it does, call it \"Start\".\n- Keep the number of menu items small to avoid forcing the user to scroll through a large list. If you have more actions to implement, consider using multiple cards with different actions on each.\n\n### Error messages\n\nWhen something goes wrong, it's important to use plain language. Explain the\nproblem from the user's standpoint, and suggest how to fix it.\n\n- Don't allow the user to see any exceptions your code throws. Instead, use `try...catch` statements to intercept exceptions, then display a user-friendly error message.\n- Before you publish, check that your add-on doesn't display debug information in the UI.\n\n### Help content\n\nYou may wish to design cards that display help information or explain the\noperation of the add-on to the user. If you do build help content for your\nadd-on, remember to:\n\n- When possible, show instructions in a bulleted or numbered list. Walk users through to the end result, with clear references to named UI elements.\n- Make sure your instructions clearly explain any requirements, like setting up a spreadsheet in a certain way.\n- Feel free to link to external help content, such as supporting web pages.\n\n### Images\n\nImages used in your add-on are either one of the\n[built-in icon types](/apps-script/reference/card-service/icon)\nor a publicly hosted image specified by a URL. When using hosted images,\nbe sure that they are accessible by everyone who may use your add-on.\n\nControls\n--------\n\nThis section provide user experience guidelines for\n[interactive widgets](/workspace/add-ons/concepts/widgets#user_interaction_widgets).\n\n### Buttons\n\nUse buttons to control your user interface's main actions rather than\nother widgets.\n\n- Most text button labels should start with a verb.\n- Button rows should be limited to three or fewer buttons in most cases.\n\n### DecoratedText\n\n[DecoratedText widgets](/workspace/add-ons/concepts/widgets#informational_widgets)\nlet you present text content with icons, buttons or switches.\n\n- Use sentence case for the text content.\n- The text of a DecoratedText widget is truncated if it cannot fit into the available space. For this reason, always try to keep the text content as short as you can.\n\n### Selection inputs\n\nYou can use a variety of\n[selection input widgets](/workspace/add-ons/concepts/widgets#user_interaction_widgets)\nin your add-on: drop-down selection boxes, checkboxes, and radio buttons.\n\n- 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 to save space in the UI.\n- Use sentence case for the text that is assigned to each option.\n- Avoid using selection changes to trigger major, hard-to-reverse actions, because people often make mistakes when making selections. Instead, consider adding a button that reads the current selection values and then triggers the action.\n- For dropdowns, sort the options alphabetically or by a logical scheme that all users can understand (such as presenting the days of the week in order, starting from Sunday or Monday).\n- Restrict the number of options in a given selection input widget to a reasonable number. If there are too many options, users may find it hard to use the widget. In those cases, consider breaking the option into different categories and multiple widgets.\n\n### Text inputs\n\nText inputs provide a place for users to enter string data.\n\n- Don't use a text input to make the user type one of a specific set of possible entries. Use a dropdown select instead.\n- Use hints and suggestions to help the user enter text with the correct format and content.\n- Use multiline text inputs if the text to be entered is more than a few words.\n\nBranding\n--------\n\nThis section provide user experience guidelines for adding branding elements\nto your add-on interface.\n\n### In your add-on\n\nIf you'd like to include branding in your add-on UI, keep it brief and light.\nThis helps people focus on your add-on functionality.\n\n- All aspects of your add-on must follow the [branding guidelines](https://developer.chrome.com/webstore/branding).\n- Don't include the word \"Google\", \"Gmail\", or other Google product names.\n- Don't include Google product icons, even if they are altered.\n- Don't include the word \"add-on\" in your branding text.\n- Branding text should be no more than a few words.\n\n### In the Google Workspace Marketplace\n\nWhen you configure your add-on for publication,\nyou provide a number of graphical and text assets to build the\nGoogle Workspace Marketplace listing.\n\nAll aspects of your store listing and these assets must follow the\n[branding guidelines](https://developer.chrome.com/webstore/branding)."]]
