Guía de estilo de la IU para complementos de Editor

Los complementos del editor compilan interfaces de usuario (menús, barras laterales y diálogos) con el servicio HTML de Apps Script. Dado que las interfaces se desarrollan en HTML y CSS, son altamente personalizables. Sin embargo, cuando compiles la interfaz del complemento, debes diseñarla para proporcionar una excelente experiencia del usuario.

Los mejores complementos extienden cada editor de forma natural con controles y comportamientos conocidos. Cuando crees un complemento nuevo, haz lo siguiente:

Texto

Nombre del complemento

Debes establecer el nombre del complemento cuando lo publiques. El nombre aparece en muchos lugares, como en la tienda de complementos y en los menús.

  • Usa mayúsculas de título.
  • Evita la puntuación, en especial los paréntesis, a menos que sea parte de tu marca.
  • Hazlo breve. Lo mejor es que tenga 30 caracteres o menos. Es posible que los nombres largos se truncen automáticamente.
  • No incluyas el nombre del producto de Google para el que está diseñado el complemento (ni uses la palabra Google).
  • No incluyas información de la versión.
  • Asegúrate de que el nombre publicado del complemento sea el mismo que el nombre del archivo del proyecto de secuencia de comandos. El nombre del proyecto aparecerá en el diálogo de autorización.
Qué no debes hacer Qué debes hacer
Nombres de complementos incorrectos Buenos nombres para complementos

Estilo de escritura

No deberías tener que escribir mucho. La mayoría de las acciones deben quedar claras a través de la iconografía, el diseño y las etiquetas breves. Si consideras que una parte de tu complemento necesita una explicación más extensa de la que pueden proporcionar las etiquetas cortas, te recomendamos que crees una página web independiente para describir el complemento y que crees un vínculo a ella.

Cuando escribas texto de la IU, ten en cuenta lo siguiente:

  • Usa mayúsculas y minúsculas (especialmente para botones, etiquetas y elementos de menú).
  • Usa un texto breve y simple, sin jerga ni acrónimos.
Qué no debes hacer Qué debes hacer

Sugerencia posterior a la instalación

La sugerencia posterior a la instalación aparece justo después de que alguien instala tu complemento y también se muestra en Ayuda. Tienes algunas oraciones para ayudar a los usuarios a comenzar rápidamente.

  • Comienza con una palabra de acción.
  • Describe el primer paso para usar el complemento.
  • Si tienes una IU principal, como una barra lateral, explica cómo abrirla.
  • No promociones tu complemento aquí, ya que ya está instalado.
Qué no debes hacer Qué debes hacer
Sugerencia incorrecta posterior a la instalación Buena sugerencia posterior a la instalación

A diferencia de los proyectos normales de Apps Script, los complementos no aparecen en el editor ni en el administrador de secuencias de comandos. Los usuarios no pueden ejecutar secuencias de comandos de complementos directamente. En su lugar, cada complemento tiene un lugar en el menú de complementos. El menú (y, posiblemente, un diálogo o una barra lateral) permite que los usuarios interactúen con el complemento.

  • El menú es una parte clave de la forma en que los usuarios controlan tu complemento, así que diseña su estructura y redacción con cuidado.
  • Evita los elementos de menú que solo repiten el nombre del complemento. En su lugar, comienza con una palabra de acción.
  • Si el elemento del menú principal inicia un flujo de trabajo y no hay un solo verbo que describe lo que hace, llámalo "Iniciar". Este patrón se usa en la guía de inicio rápido de complementos de Documentos.
  • A menos que el menú tenga más de seis elementos, intenta no usar submenús. Pueden ser fastidiosos y difíciles de seleccionar.
  • Describe la tarea, no el componente de la IU que muestra el elemento de menú.
Qué no debes hacer Qué debes hacer
Etiquetas incorrectas de los elementos del menú Etiquetas de elementos de menú adecuadas

Mensajes de error

Cuando algo sale mal, es importante usar un lenguaje sencillo. Explica el problema desde el punto de vista del usuario y sugiere cómo solucionarlo.

  • No permitas que el usuario vea ninguna excepción que genere tu código. En su lugar, usa sentencias try...catch para interceptar excepciones y, luego, muestra un mensaje de error fácil de usar con texto intercalado con diseño de la clase error del paquete CSS de complementos o un diálogo de alerta.
  • Antes de publicarlo, verifica que el complemento no registre información de depuración en la consola de JavaScript. En su lugar, usa el registro de Stackdriver.
Qué no debes hacer Qué debes hacer
Mensaje de error incorrecto Mensaje de error correcto

Contenido de ayuda

El menú de cada complemento incluye un diálogo de ayuda automático. Si proporcionas una URL de ayuda cuando publicas, el botón "Más información" se vinculará a esa página. A menos que el complemento sea intuitivo, proporciona una página que explique cómo usarlo.

  • Cuando sea posible, muestra las instrucciones en una lista con viñetas o numerada. Explica a los usuarios el resultado final, con referencias claras a los elementos de la IU nombrados.
  • Asegúrate de que tus instrucciones expliquen claramente los requisitos, como configurar una hoja de cálculo de una manera determinada.
  • No dudes en vincular tu contenido de ayuda desde la interfaz de usuario principal. Si tu complemento crea un documento nuevo, también puedes mostrar instrucciones en el cuerpo del documento.

Interfaces de usuario personalizadas

Algunos complementos simples del Editor se pueden controlar por completo desde su menú, pero la mayoría muestra una barra lateral o un diálogo con contenido personalizado.

  • Las barras laterales son ideales para herramientas persistentes que las personas pueden usar de forma repetida mientras consultan el contenido de su documento o hoja de cálculo.
  • Los diálogos son ideales para herramientas de un solo uso, páginas de configuración y mensajes importantes.

Texto de la IU

En cualquier diálogo o barra lateral, supone que las personas solo leen el título y las etiquetas de los botones. ¿Pueden averiguar qué hace tu interfaz y tomar una buena decisión?

  • Usa un título y etiquetas de botones que se destaquen por sí solos.
  • Evita los bloques largos de texto descriptivo.

Diálogos

Los diálogos son excelentes para las herramientas que las personas usan una vez y, luego, siguen adelante. Por ejemplo, si tu complemento permite que las personas inserten un elemento gráfico, puedes mostrar un diálogo con opciones para insertar y, luego, cerrarlo cuando se inserte el elemento gráfico. Los diálogos también son útiles para mostrar la configuración de tu complemento o para comunicar un mensaje importante.

  • No abras un diálogo (incluida una alerta o instrucción) desde otro diálogo; solo muestra uno a la vez.
  • Para el título del diálogo, usa una palabra o una frase corta, comenzando con la palabra más importante.
  • Las etiquetas de los botones deben estar relacionadas con el título del diálogo.
  • Se prefieren dos botones, por lo general, una acción principal y "Cancelar". En el caso de los casos especiales que requieren un tercer botón, considera la esquina inferior derecha.
  • Coloca los botones en la esquina inferior izquierda del diálogo. El botón principal azul debe estar a la izquierda, y los botones secundarios grises a la derecha.
Qué no debes hacer Qué debes hacer
Título incorrecto del diálogo Buen título del diálogo

Las barras laterales permiten que las personas consulten su documento, hoja de cálculo, presentación o formulario mientras toman decisiones. También permiten que las personas usen tu complemento de forma reiterada. Cada vez que se abre una barra lateral nueva, se cierra automáticamente la anterior. Son ideales para modos temporales que el usuario abandona cuando termina.

  • Los usuarios pueden tener otros complementos con sus propias barras laterales. Si dos complementos intentan abrir barras laterales de forma simultánea, solo se muestra una.
  • No mostrar una barra lateral ni un diálogo cuando se abre un documento por primera vez.
  • Solo los complementos que operan en AuthMode.FULL pueden abrir paneles laterales o diálogos. Puedes usar un elemento de menú para abrir una barra lateral, ya que le solicita al usuario que proporcione la autorización completa.

Controles

Las mejores IU de complementos dejan espacio para los controles. Los márgenes y los padding adecuados son muy útiles, mientras que los controles densos pueden parecer abrumadores. Cuando tengas dudas, toma prestado un diseño del editor. Por ejemplo, revisa los diálogos existentes en Documentos de Google, como Archivo > Configuración de página, cuando crees el tuyo.

La documentación del paquete de CSS de complementos proporciona un marcado de muestra para cada uno de los tipos de controles que se indican a continuación.

Botones

Usa botones para controlar las acciones principales de tu interfaz de usuario en lugar de vínculos simples o de otros elementos.

  • Evita mostrar más de un botón azul, rojo o verde a la vez. Es posible que los botones grises aparezcan varias veces.
  • La mayoría de las etiquetas de botones deben estar en mayúsculas y comenzar con un verbo. Los botones rojos, que suelen usarse para acciones de creación, deben escribirse en mayúsculas.
Qué no debes hacer Qué debes hacer

Casillas de verificación y botones de selección

Usa casillas de verificación cuando las personas puedan seleccionar varias opciones o ninguna. Usa botones de selección (o un menú de selección) cuando se deba seleccionar exactamente una opción.

  • No cambies el comportamiento de las casillas de verificación para imitar los botones de selección.
  • No hagas nada de inmediato cuando se marquen. Las personas cometen errores. Espera hasta que los usuarios hagan clic en un botón para confirmar sus elecciones.

Selecciona los menús

Las selecciones son una excelente manera de ofrecer una lista breve de alternativas.

  • Ordena las opciones en orden alfabético o por un esquema lógico que todos los usuarios puedan entender (como los días de la semana, a partir del domingo).
  • Si la lista crece demasiado, considera usar un control diferente. Por ejemplo, puedes mostrar una lista desplazable para darle más espacio al menú y facilitar la navegación.

Áreas de texto

Si las personas necesitan escribir más de unas pocas palabras, usa un área de texto.

  • Haz que las áreas de texto tengan al menos dos líneas de altura para que sean más fáciles de usar y no se vean como campos de texto.
  • Coloca las etiquetas en la parte superior.

Campos de texto

Usa campos de texto si las personas solo necesitan escribir una o dos palabras.

  • El ancho de un campo de texto debe sugerir lo que esperas que las personas escriban en él.
  • Evita usar el texto del marcador de posición como etiqueta, ya que desaparece cuando se enfoca. El texto de marcador de posición es útil para dar ejemplos o detalles adicionales.
  • Coloca las etiquetas en la parte superior, pero no dudes en diseñar campos de texto cortos uno al lado del otro.

Desarrollo de la marca

En tu complemento

Si quieres incluir desarrollo de la marca, hazlo de forma breve y ligera. Esto ayuda a las personas a enfocarse en tu IU y hace que tu complemento se sienta como parte del editor.

  • Todos los aspectos del complemento deben cumplir con los lineamientos de desarrollo de la marca.
  • No incluyas la palabra "Google" ni uses íconos de productos de Google.
  • El texto debe tener unas pocas palabras y tener el estilo de la clase gray del paquete CSS de complementos.
  • Los elementos gráficos deben tener un fondo blanco y no deben tener más de 200 px × 60 px.
  • En el caso de los diálogos, el desarrollo de la marca debe estar en la esquina inferior derecha.
  • En el caso de las barras laterales, el desarrollo de la marca puede estar en la parte superior o inferior.

En la tienda

Para publicar un complemento de Editor, necesitas una cantidad de recursos de imagen. Estos recursos se usan para crear la ficha de Play Store del complemento.

Accesibilidad

Todas las personas deben poder disfrutar de tu complemento, ya sea que vean los colores de manera diferente, usen un lector de pantalla o tengan otras necesidades. La accesibilidad es un tema amplio que no se puede abordar por completo en esta guía de estilo. Un recurso útil es el sitio Accesibilidad de Google. Sin embargo, aquí tienes algunas sugerencias para comenzar:

  • Asegúrate de poder navegar a todos los controles de la IU con el teclado. Agrega tabindex=0 a los controles personalizados (como los que se crean con <div>) para que los usuarios puedan acceder a ellos con la tecla Tab. Considera si también se deben admitir otras teclas, como las flechas para una lista.
  • Es posible que algunas personas usen un lector de pantalla con tu complemento. Por lo tanto, las imágenes deben tener un atributo alt y los controles personalizados deben tener atributos ARIA para describir su uso.
  • No dependas únicamente del color para comunicar el estado. Usa íconos y texto.

Si usas controles web estándar, como los que se describieron antes en esta guía, será más fácil hacer que tu complemento sea accesible.