Durante mucho tiempo, el código en Vanilla se estableció simplemente en una fuente monoespaciada y vimos una oportunidad para mejorar la forma en que entregamos ejemplos de código a los usuarios.
Un objetivo clave es la claridad del código: el código no es particularmente resistente a los errores: un carácter faltante (o en algunos idiomas, un espacio o una pestaña) puede generar problemas y usuarios frustrados, por lo que el usuario debería poder seleccionar y copiar el código fácilmente . El resaltado de sintaxis va más allá para hacer que el código sea legible y pensamos que era importante incluirlo a través de una biblioteca de terceros.
Muchos ejemplos de código para aplicaciones modernas y API pueden tener diferentes versiones del mismo fragmento, por ejemplo, para diferentes idiomas o versiones de la API. Queríamos permitir esto para que los usuarios puedan cambiar fácilmente entre ejemplos del fragmento de código en sí.
Tabla de Contenidos
Investigación y prototipos de UX
Realizamos algunas investigaciones sobre las historias de usuarios que rodean los fragmentos de código, incluida la evaluación comparativa de otros sitios de documentación y la conversación con los usuarios.
Asignamos nuestras historias de usuario a prototipos de ejemplo y los probamos de forma interactiva. Queríamos proporcionar un alto nivel de familiaridad a los usuarios. Sabíamos que una gran cantidad de usuarios acceden directamente a las páginas de ejemplos desde una página de resultados de búsqueda, por lo que el fragmento de código debe ser intuitivo y de fácil comprensión.
Producimos wireframes de mayor fidelidad para probarlos con usuarios internos antes de pasar el trabajo al diseño visual.
Diseño visual
En términos de diseño visual, queríamos lograr 2 cosas:
- Desacoplar el estilo de los elementos de código del de las entradas de formulario
- Introducir el resaltado de sintaxis
Desacoplar el estilo de los elementos de código del de las entradas de formulario
Antes de esta actualización, los fragmentos de código en Vanilla tenían un estilo demasiado cercano a los campos / áreas de texto. Para comparacion:
Diseño anterior de un fragmento de código de una o varias líneas:
Esto fue engañoso, ya que no se puede escribir en un fragmento de código. También es inconsistente con un fragmento de código en línea:
Para solucionar esto, derivamos el nuevo diseño del fragmento de código haciendo cambios incrementales mínimos en el fragmento de código en línea:
Un fragmento de una sola línea a nivel de bloque simplemente agrega relleno y comportamiento a nivel de bloque:
Los casos de uso especializados, como un comando de terminal o un enlace, agregan un icono y una sangría:
Un fragmento de código de varias líneas simplemente aumenta el número de filas:
Un fragmento de código modular utiliza el estilo de título h5 como estilo de título de sección sobre un fondo ligeramente más oscuro:
Implementación del componente
El fragmento de código fue diseñado para reemplazar en última instancia los patrones de código existentes de Vanilla, como el código numerado y el código copiable. Tomamos la decisión de desaprobar estos patrones y, al mismo tiempo, actualizarlos para darles un aspecto coherente con el fragmento de código, sin cambiar la estructura HTML utilizada y romper las implementaciones existentes.
Una característica clave del diseño fue la capacidad de cambiar entre diferentes ejemplos de código dentro de una sola instancia de fragmento de código. Nuestro primer pensamiento fue aprovechar la patrón de menú contextual ya presente en Vanilla, pero en la práctica descubrimos que no era tan adecuado como habíamos pensado al principio y, en particular, no era accesible. En su lugar, optamos por un elemento de selección simple, con una pequeña cantidad de JavaScript para manejar alternar entre ejemplos de código visibles.
El patrón permite incluir varios elementos seleccionados, ya sea en línea con un título o, si el usuario lo prefiere, debajo del título usando una clase de utilidad «.is-apilada». El comportamiento de las selecciones múltiples fue un punto de debate: ¿debería cada selección determinar únicamente qué ejemplo estaba visible actualmente? ¿Debe uno seleccionar controlar las opciones presentes en otro?
Al final, y por simplificar el ejemplo, optamos por no hacer suposiciones sobre cómo debería comportarse un fragmento de código con múltiples selecciones, en lugar de eso, dejamos que la implementación decida la solución que mejor se adapte a sus propósitos.
Otra característica opcional que incluimos fue el resaltado de sintaxis. Decidimos desde el principio optar por una solución estándar, y finalmente nos decidimos por Prism.js. Ninguno de sus temas proporciona suficiente contraste para cumplir con los requisitos de contraste de AA. Para solucionarlo, reemplazamos los colores originales con versiones que cumplen con los requisitos:
Intentamos evitar las dependencias externas siempre que sea posible en Vanilla, por lo que en este caso lo único que realmente se agrega al marco es un tema CSS personalizado, con instrucciones sobre cómo incluir Prism.js en un proyecto determinado.
Además de la implementación del estilo del fragmento de código en el marco de Vanilla, agregamos un componente React para que nuestra biblioteca también. Esto nos permite hacer que el nuevo componente esté disponible para nuestras aplicaciones React.
