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 altamente personalizables. Sin embargo, cuando crees la interfaz de complementos, debes diseñarla de manera que ofrezca una excelente experiencia del usuario.

Los mejores complementos extienden cada editor de forma natural con controles y comportamientos conocidos. Cuando compilas un complemento nuevo:

Texto

Nombre del complemento

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

  • Usa mayúsculas en el título.
  • Evite los signos de puntuación, especialmente los paréntesis, a menos que sea parte de su marca.
  • Debe ser breve: lo mejor es usar 30 caracteres o menos. Los nombres largos pueden truncarse automáticamente.
  • No incluyas el nombre del producto de Google para el que es complemento (ni uses la palabra Google).
  • Omita 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 secuencia de comandos. El nombre del proyecto aparecerá en el cuadro de diálogo de autorización.
Qué no hacer Sugerencias
Nombres de complementos incorrectos Buen nombre de complemento

Estilo de escritura

No necesitas escribir mucho. La mayoría de las acciones deben dejarse en claro a través de la iconografía, el diseño y las etiquetas cortas. Si descubres que una parte de tu complemento necesita una explicación más extensa que la que pueden proporcionar las etiquetas cortas, se recomienda crear una página web separada que describa tu complemento y el vínculo a él.

Cuando se escribe texto en la IU:

  • Usa mayúscula inicial (en especial para botones, etiquetas y elementos de menú).
  • Prefiera los textos cortos y simples sin jerga ni acrónimos.
Qué no hacer Sugerencias

Sugerencia posterior a la instalación

La sugerencia posterior a la instalación aparecerá justo después de que alguien instale tu complemento y también aparecerá en la Ayuda. Tienes un par de oraciones para ayudar a los usuarios a comenzar rápidamente.

  • Comience con una palabra de acción.
  • Describa el primer paso para usar su complemento.
  • Si tienes una IU principal, como una barra lateral, explica cómo abrirla.
  • No promociones tu complemento aquí, ya está instalado.
Qué no hacer Sugerencias
Mala sugerencia después de la instalación Buena sugerencia después de la instalación

A diferencia de los proyectos normales de Apps Script, los complementos no aparecen en el editor de secuencias de comandos 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 tal vez un diálogo o 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 redacción cuidadosamente.
  • Evite los elementos del menú que simplemente repiten el nombre del complemento. En su lugar, comienza con una palabra de acción.
  • Si tu elemento de menú principal inicia un flujo de trabajo y no hay un solo verbo que describa lo que hace, llámalo "Start". Este patrón se usa en la guía de inicio rápido sobre el complemento de Documentos.
  • A menos que el menú tenga más de seis elementos, intenta no usar submenús. Pueden ser engorrosos y difíciles de seleccionar.
  • Describe la tarea, no el componente de la IU que muestra el elemento de menú.
Qué no hacer Sugerencias
Etiquetas incorrectas de elementos del menú Etiquetas de elementos del menú adecuadas

Mensajes de error

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

  • No permitas que el usuario vea las excepciones que arroja el código. En su lugar, usa las declaraciones try...catch para interceptar excepciones y, luego, muestra un mensaje de error del usuario con texto intercalado de estilo en la clase error del paquete de CSS de complementos o un diálogo de alerta.
  • Antes de publicar, verifica que tu complemento no registre información de depuración en la Consola de JavaScript; en su lugar, usa Stackdriver Logging.
Qué no hacer Sugerencias
Mensaje de error incorrecto Buen mensaje de error

Contenido de ayuda

El menú de todos los complementos 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" vincula a esa página. A menos que tu complemento sea evidente, proporciona una página que explique cómo usarlo.

  • Cuando sea posible, muestra las instrucciones en una lista numerada o con viñetas. Explica a los usuarios hasta el resultado final, con referencias claras a los elementos de IU con nombre.
  • Asegúrate de que las instrucciones expliquen con claridad cualquier requisito, como configurar una hoja de cálculo de una manera determinada.
  • También puedes incluir un vínculo a tu contenido de ayuda en 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 de Editor se pueden controlar por completo desde su menú, pero la mayoría muestra una barra lateral o diálogo con contenido personalizado.

  • Las barras laterales son mejores para las herramientas persistentes que es probable que las personas usen de forma reiterada mientras hacen referencia al contenido de su documento o de su hoja de cálculo.
  • Los diálogos son mejores para las herramientas de uso único, las páginas de configuración y los mensajes importantes.

Texto de la IU

En cualquier diálogo o barra lateral, supongamos que las personas solo leen el título y las etiquetas de los botones. ¿Puede determinar lo que hace su interfaz y tomar una buena decisión?

  • Usa etiquetas de título y botones independientes.
  • 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, continúan. Por ejemplo, si tu complemento permite que las personas inserten un gráfico, puedes mostrar un cuadro de 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 para comunicar un mensaje importante.

  • No abras un diálogo (incluidas una alerta o un mensaje) de 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 estar relacionadas con el título del diálogo.
  • Se prefieren dos botones, normalmente una acción principal y “Cancelar”. Para casos especiales que requieren un tercer botón, considera la esquina inferior derecha.
  • Coloca botones en la esquina inferior izquierda del cuadro de diálogo. El botón principal azul debe estar a la izquierda, con cualquier botón secundario gris a la derecha.
Qué no hacer Sugerencias
Título de diálogo erróneo Título del diálogo correcto

Las barras laterales permiten que las personas consulten sus documentos, hojas de cálculo, presentaciones o formularios mientras toman decisiones. También permiten que las personas usen tu 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 está listo.

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

Controles

Las IU de complementos geniales dejan sus controles en un espacio respiratorio. Con los márgenes adecuados y el relleno, 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 página, cuando crees el tuyo.

En la documentación del paquete de CSS de complementos, se proporciona lenguaje de marcado de muestra para cada uno de los tipos de controles que aparecen a continuación.

Botones

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

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

Casillas de verificación y botones de selección

Utilice casillas de verificación cuando los usuarios puedan seleccionar varias opciones o directamente no tengan opciones. Usa los botones de selección (o un menú de selección) cuando solo se deba seleccionar 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 tus usuarios hagan clic en un botón para confirmar sus elecciones.

Seleccionar menús

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

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

Áreas de texto

Si necesitas escribir más que unas pocas palabras, usa un área de texto.

  • Asegúrate de que las áreas de texto tengan 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 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 debería sugerir lo que esperas que las personas escriban en él.
  • Evita usar texto de marcador de posición como etiqueta, ya que desaparecerá en el enfoque. El texto del marcador de posición es útil para proporcionar ejemplos o información adicional.
  • Coloca las etiquetas en la parte superior, pero puedes ubicar campos de texto cortos uno al lado del otro.

Desarrollo de la marca

En su complemento

Si desea que se incluya el desarrollo de la marca, asegúrese de que sea breve y claro. Esto ayuda a que las personas se enfoquen en la IU y haga que el complemento se sienta como parte del editor.

  • Todos los aspectos de tu complemento deben seguir 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 correspondiente en la clase gray del paquete de complementos de CSS.
  • Los gráficos deben ser sobre un fondo blanco y no deben superar los 200 px × 60 px.
  • Para los diálogos, la marca debe estar en la esquina inferior derecha.
  • En las barras laterales, el desarrollo de la marca se puede colocar en la parte superior o inferior.

En la tienda

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

Accesibilidad

Todos deberían poder disfrutar de tu complemento, ya sea que vean colores de otra manera, usen un lector de pantalla o tengan otras necesidades. La accesibilidad es un tema amplio que no se puede abarcar por completo en esta guía de estilo. Un recurso útil es el sitio de Accesibilidad de Google. Aquí hay 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 crearon con <div>) para que las personas puedan acceder a las pestañas. Considera si otras claves también deben ser compatibles, 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 confíes solo 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.