Guía de estilo de IU para complementos de Editores

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

Los mejores complementos amplían cada editor de forma natural mediante el uso de controles y comportamientos conocidos. Cuando crees un complemento nuevo, ten en cuenta lo siguiente:

Texto

Nombre del complemento

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

  • Usa mayúsculas de título.
  • Evita los signos de puntuación, especialmente los paréntesis, a menos que sea parte de tu marca.
  • Sea breve; es mejor usar 30 caracteres o menos. Los nombres largos pueden truncarse automáticamente.
  • No incluyas el nombre del producto de Google para el que es el complemento (ni uses la palabra Google).
  • No incluyas la información de la versión.
  • Asegúrate de que el nombre publicado del complemento sea el mismo que el nombre de archivo del proyecto de la secuencia de comandos. El nombre del proyecto aparecerá en el diálogo de autorización.
Qué no debes hacer Sugerencias
Nombres de complementos incorrectos Nombres de complementos correctos

Estilo de escritura

No deberías tener que escribir mucho. La mayoría de las acciones deben aclararse mediante la iconografía, el diseño y las etiquetas cortas. Si crees que una parte de tu complemento necesita una explicación más extensa que las que ofrecen las etiquetas cortas, se recomienda crear una página web independiente que describa tu complemento y agregar un vínculo a él.

Cuando escribas texto de la IU:

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

Sugerencia posterior a la instalación

Tu sugerencia posterior a la instalación aparece justo después de que alguien instala tu complemento y también aparece en Ayuda. Tienes un par de 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 el complemento aquí, ya está instalado.
Qué no debes hacer Sugerencias
Mala sugerencia 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 cambio, cada complemento obtiene un lugar en el menú de complementos. El menú (y, posiblemente, un diálogo o una barra lateral) permite a los usuarios interactuar con el complemento.

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

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 arroja tu código. En su lugar, usa declaraciones try...catch para interceptar excepciones y, luego, muestra un mensaje de error específico para el usuario con texto intercalado con estilo en la clase error del paquete de CSS de complementos o un diálogo de alerta.
  • Antes de publicar, comprueba que tu complemento no registre información de depuración en la Consola de JavaScript. En su lugar, usa Stackdriver Logging.
Qué no debes hacer Sugerencias
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 realizas la publicación, el botón “Más información” vinculará a esa página. A menos que se explique claramente, proporciona una página donde se explique cómo usarlo.

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

Interfaces de usuario personalizadas

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

  • Las barras laterales son mejores para herramientas persistentes que es probable que las personas usen repetidamente mientras hacen referencia al contenido de un documento o de una hoja de cálculo.
  • Los diálogos son mejores 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, imagina que las personas solo leen las etiquetas de título y botón. ¿Es posible que entiendan lo que hace la interfaz y tomarán una buena decisión?

  • Usa etiquetas de título y botón que sean independientes.
  • Evita 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 gráfico, podrías mostrar un diálogo con opciones de qué insertar y, luego, cerrar el diálogo cuando se inserte el gráfico. Los diálogos también son útiles para mostrar la configuración de tu complemento o comunicar un mensaje importante.

  • No abras un diálogo (lo que incluye una alerta o solicitud) desde otro diálogo; solo muestra uno a la vez.
  • Para el título del diálogo, usa una palabra o frase corta que comience con la palabra más importante.
  • Las etiquetas de los botones deben relacionarse con el título del diálogo.
  • Opta por dos botones, que por lo general son una acción principal y “Cancelar”. Para casos especiales que requieren un tercer botón, considera la esquina inferior derecha.
  • Coloca los botones en la esquina inferior izquierda del cuadro de diálogo. El botón principal azul debe estar a la izquierda, con los botones secundarios grises a la derecha.
Qué no debes hacer Sugerencias
Título del cuadro de diálogo incorrecto 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 los usuarios usen el complemento varias veces. Cada vez que se abre una barra lateral nueva, se cierra automáticamente cualquier barra lateral anterior. Son mejores para los modos temporales que el usuario cierra cuando termina.

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

Controles

Las IU complementarias de calidad dejan un poco de espacio a sus controles. Los márgenes y el padding adecuados son de gran ayuda, mientras que los controles densos pueden parecer abrumadores. Si tienes dudas, usa un diseño del editor. Por ejemplo, revisa los diálogos existentes en Documentos de Google, como Archivo > Configuración de la página, cuando crees uno propio.

La documentación del paquete de complementos de CSS proporciona lenguaje de marcado de muestra para cada uno de los siguientes tipos de controles.

Botones

Usa botones para controlar las acciones principales de la interfaz de usuario en lugar de vínculos sin formato ni otros elementos.

  • Evita mostrar más de un botón azul, rojo o verde a la vez. Los botones grises pueden aparecer repetidamente.
  • La mayoría de las etiquetas de los botones deben estar en mayúscula inicial y comenzar con un verbo. Los botones rojos, por lo general, para crear acciones, deben usar mayúsculas.
Qué no debes hacer Sugerencias

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 debas seleccionar solo 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 verifiquen. Las personas cometen errores. Espera hasta que los usuarios hagan clic en un botón para confirmar sus elecciones.

Seleccionar menús

Seleccionar es una excelente manera de ofrecer una breve lista de alternativas.

  • Ordena las opciones alfabéticamente o por un esquema lógico que todos los usuarios puedan comprender (como días de la semana, a partir del domingo).
  • Si la lista es demasiado larga, considere utilizar otro control. 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 que unas pocas palabras, utilice un área de texto.

  • Haz que las áreas de texto sean de al menos dos líneas de altura para que sean más fáciles de usar y no parezcan campos de texto.
  • Coloca las etiquetas arriba.

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 texto de marcador de posición como etiqueta, ya que desaparece cuando se enfoca. El texto del marcador de posición es útil para brindar ejemplos o detalles adicionales.
  • Coloca las etiquetas en la parte superior, pero siéntete libre de distribuir campos de texto cortos lado a lado.

Desarrollo de la marca

En tu complemento

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

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

En la tienda

Si deseas publicar un complemento del editor, necesitarás una cantidad de recursos de imagen. Estos recursos se usan para crear la ficha de Play Store complementaria.

Accesibilidad

Todos deberían poder disfrutar de tu complemento, ya sea que vean colores de manera diferente, usen un lector de pantalla o tengan otras necesidades. La accesibilidad es un tema amplio que no se puede tratar completamente en esta guía de estilo. Un recurso útil es el sitio de Accesibilidad de Google. Sin embargo, estas son 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 creados con <div>) para que las personas puedan usar Tabulador. Considera si también se deberían admitir otras teclas, como flechas para una lista.
  • Es posible que algunas personas usen un lector de pantalla con el 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 confíes únicamente en el color para comunicar el estado. También puedes usar íconos y texto.

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