Documentación

Una pequeña introducción

La razón principal para documentar diseño es mantener alineados a todos en el equipo, no solamente a los diseñadores. Teniendo un sitio de referencia donde todas las especificaciones de diseño, prácticas y flujos de trabajo estén explicados, puedes usarlo como una pieza central de consulta, evitando repetir conceptos o tenerlos repartidos por ahí en diferentes lugares.

La documentación va más allá de la interfaz. Hay tantas cosas alrededor del proceso de diseño que también son necesarias de comunicar: desde las ideas detrás de decisiones de diseño a comportamientos, de prácticas diarias a procesos de trabajo generales. Por ahora, el alcance de este artículo cubrirá solamente todo lo relacionado con el aspecto visual del producto.

Documentando en tus archivos de diseño

Hoy en día es más común que antes encontrar herramientas que ayuden a conectar tu software de diseño con otros sitios web que puedan contener la documentación. La mayoría de ellos funciona a través de plugins que te permiten tener tu diseño en un lugar central sincronizándolo a través de un programa externo. Hablaremos de esto más tarde (o puedes pasar directamente a la sección de Herramientas.)

Por desgracia, la madurez de tanto las herramientas de diseño como de documentación está un poco detrás de lo que nos gustaría encontrar en estos días. Por esa razón, y como veremos más adelante, todavía prefiero usar esas herramientas en combinación con documentación dentro del mismo archivo de diseño. Esto tiene la ventaja de refinar la comunicación de tu diseño con el nivel de detalle que quieras, pero requiere cierto trabajo manual para mantenerlo actualizado.

En las siguientes secciones veremos qué tienes que tener en cuenta cuando documentes las principales partes de tus diseños.

Colores

Para documentar colores necesitamos seguir una serie de pasos: declarar su anatomía (es decir, las diferentes partes de una muestra de color); definir cómo serán categorizados o divididos; y finalmente, cuál es la relación entre todos ellos, teniendo en mente que el mismo valor de color puede tener diferentes aplicaciones en la interfaz.

Anatomía

Un color es bastante simple, así que para definirlo solamente necesitamos un nombre y un valor, y una representación visual de ambas cosas. Para hacer esto en nuestro archivo de diseño, algo que será útil es tener un símbolo o componente con una estructura común, para más tarde documentar la paleta de colores usándolo.

Este es un ejemplo bastante simple, pero esta estructura común puede ser reutilizada para documentar cada color que tengamos en la interfaz. Hay algo más para considerar: los colores son generalmente parte de una escala, y tienen una posición en ella.

Sería raro tener solamente un color primario. En realidad, sería más probable que hubieran algunas variaciones de él que luego se aplicaran en diferentes situaciones, como lo que pasa cuando se pone el mouse sobre un botón. Todo esto tiene que estar definido y documentado, como veremos a continuación.

Definición

Para explicar visualmente cómo funciona la estructura o categorización, puedes disponerlos en una página especial dentro de tu Style Guide, además de crearlos como variables o estilos.

El color primario que acabamos de ver podría ser parte de la categoría principal, Main, donde tendremos los colores primarios y secundarios. Además de estos, un proyecto típicamente tiene otras divisiones dentro de la paleta.

Main
Neutrals
Backgrounds
Opacities
Icons
Texts

Tomaremos la categoría Neutral para definir un ejemplo de los distintos valores que contiene.

Aplicaciones

Lo normal sería reutilizar algunos de esos colores en otros lugares, como en textos, íconos y fondos. Por la misma razón que he comentado antes, crearemos los estilos de nuevo, aún si usan el mismo valor, para hacerlos fáciles de encontrar en nuestra lista de estilos.

Cuando diseñemos la documentación podemos aclarar que algunos de esos valores se repiten, y usan otros que ya han sido definidos antes.

Herramientas como Sketch y Figma permiten almacenar colores en estilos aislados y variables (es decir que guardas solamente el valor del color, sin otra propiedad visual).

Idealmente deberíamos ser capaces, desde nuestra misma herramienta de diseño, de anidar definiciones de color que comparten el mismo valor, para poder actualizarlo solamente en un lugar central. Este comportamiento podría ser similar al que muchas veces tenemos en código.

$colour-neutral-20: #cdcdcd;
$colour-neutral-60: #686868;
$colour-neutral-80: #282828;

$colour-icon-soft: $colour-neutral-20;
$colour-icon-medium: $colour-neutral-60;
$colour-icon-strong: $colour-neutral-80;

Por ahora, este nivel de anidado no es posible en nuestras herramientas de diseño y tendremos que basarnos en la documentación para comunicar claramente cómo se usan los colores en nuestro producto.

Texto

Definir estilos de texto puede ser complejo porque involucra una combinación de propiedades como tamaño, color, familia y variantes de peso, por ejemplo. El desafío en este caso es documentarlo de una forma modular, así puedes tener en una misma página un mapa general de como estas combinaciones funcionan juntas.

Tamaño

El tamaño se basará generalmente en una escala tipográfica. Tener todo en un lugar común nos hará tener una idea de los diferentes tamaños que tenemos, para poder mantenerlos ordenados y reducir la cantidad total de opciones. Tendremos en cuenta las convenciones de nombres que usamos para tamaños a lo largo del proyecto, y también incluiremos valores de medidas en píxeles y REM.

Peso

Dependiendo de la familia tipográfica que elijamos tendremos acceso a distintas variantes de peso que podemos usar. Siguiendo el mismo principio de tener tan pocas opciones como necesitemos, las dispondremos en una página para visualizar cuáles son las que usaremos en nuestros diseños.

Juntando todo

En la herramienta de diseño de nuestra elección necesitaremos combinar tamaños, fuente, familia y peso para crear un estilo único para cada una de las aplicaciones principales y más comunes que tendremos en la interfaz. (Si usas Sketch, es preferible no crear varios estilos con diferente alineaciones, solamente los que uses más frecuentemente).

En cada caso podemos añadir algo de información debajo del estilo, para explicar un poco mejor el token que está usando de acuerdo al tamaño, peso, alto de línea y demás.

Los estilos de texto suelen dividirse en Desktop y Mobile. Los encabezados suelen verse muy grandes en pantallas pequeñas si solamente usáramos el mismo tamaño siempre, es por eso que necesitan ser adaptados. Considerando la escala de tamaños que hemos visto antes, podemos usar un escalón menos en la escala para teléfonos móviles y tabletas.

Después de cierto punto, no hay más necesidad de separar los estilos, por lo que podemos tener una sección común que es compartida por todas las plataformas. Esto nos ayudará a minimizar la cantidad de estilos diferentes, ya que no vale realmente la pena tener tantos estilos que apenas se diferencien.

Hay cosas más allá de esto. También están los estilos usados para enlaces -- que involucran diferentes estados, por ejemplo, cuando pasas el mouse sobre el texto, o el enlace está deshabilitado. Veremos algunos de estos en las próximas secciones, pero por ahora sólo tienes que saber que siempre se prefiere crear solamente los estilos que se usarán con seguridad en la interfaz, y no necesariamente todos los posibles.

Componentes

Incluso si nuestros símbolos en Sketch o componentes de Figma son relativamente simples, es necesario documentarlos teniendo en cuenta las diferentes limitaciones, comportamientos y resultados que puedan tener.

Anatomía

Empezaremos documentando la anatomía de los componentes, lo que identifica sus diferentes partes -- especialmente aquellas que podrán ser cambiadas más adelante de acuerdo a las propiedades que ofrecen.

Digamos que tenemos un componente bastante normal, una Card que, al mismo tiempo, contiene otros componentes más pequeños. La primera parte de documentar un componente está principalmente enfocada en visualizar un panorama general de su estructura.

Un glosario compartido

Un componente puede tener distintos comportamientos, contenido y diagramación dependiendo de su contexto y propósito. Esto (como ya habrás adivinado) también tiene que documentarse.

Herramientas como Figma tienen funciones llamadas variantes que permiten agrupar las variaciones de un componente con pequeños cambios visuales. En nuestro caso iremos un poco más allá y usaremos un nivel más profundo que nos permita documentar un componente definiendo sus Tipos, Variantes, Casos y Estados. En unos momentos veremos qué quiere decir cada uno de esos.

Esta división se mantendrá en todos los componentes, aunque no todos ellos necesiten todas las definiciones. Por ejemplo, quizás un campo de texto sólo tendrá un tipo, y un cuadro de diálogo no tendrá variantes. Así que no hay necesidad de forzar esto si no es completamente necesario. Se debe decidir caso por caso, y componente por componente.

Tipos

Los Tipos son la diferenciación de más alto nivel, o general, que un componente puede tener. Se refiere a cambios grandes en el layout que muestran al componente de distintas maneras, mientras se mantiene el mismo concepto y funcionalidad de base. Siguiendo con el mismo ejemplo de la Card de antes, podríamos decir que tendrá dos tipos diferentes: aquél por defecto o Default, y otra versión que se veráncomo una imagen con menos información.

Variantes

A continuación tenemos las Variantes, pequeñas variaciones del componente en un plano visual, no de comportamiento. El layout permanecerá bastante igual, pero se ajustará para responder a las necesidades de distintos escenarios. Por ejemplo, podríamos tener la variante Default que usaremos la mayoría de las veces, pero también una variante Preview que mantendrá la misma estructura principal, pero sin los botones de acción al pie.

Casos

Los Casos se refieren a distintos escenarios en los que podría estar un componente. Hasta ahora, hemos usado una Card llena de contenido, pero también tenemos que definir cómo se verá en el caso de que no tenga imagen, por ejemplo. Así que además del escenario ideal cuando está con su contenido final, también deberíamos diseñar al componente con piezas que faltan, y presentarlo como uno de los posibles casos.

Estados

Y finalmente, tenemos los Estados que usualmente son provocados por el usuario, y generalmente son los mismos: Up, Hover, Focus y Down. Puede pasar también que haya otros diferentes, dependiendo de lo que requiera el componente.

En lo que se refiere al archivo de diseño, no es necesario crear símbolos o componentes para esos estados que no se usarán frecuentemente en nuestro día a día, como los estados de Hover. Estos realmente tienen que estar documentados en alguna parte, pero no necesariamente tienen que estar como símbolos de Sketch o componentes de Figma.

Antes de acabar esta sección, tienes que saber que esta no es una clasificación rígida. A veces puede ser difícil decidir si una definición de diseño debería ser un Caso o una Variante, por ejemplo. Idealmente, eso no tiene que ser algo que te detenga a la hora de documentarlo, es preferible que esté en alguna parte a que no esté en ninguna.

Documentando propiedades

Los componentes están formados por propiedades que pueden y no pueden ser cambiadas cuando se usan en código. Por ejemplo, un cuadro de diálogo puede tener un título, un texto y un botón de acción principal con valores de texto que cambiarán dependiendo de la ocasión. Todo lo demás (color de fondo, márgenes, separaciones) se mantendrá siempre igual.

Entonces, ¿tiene sentido diseñar un diálogo y especificarlo para implementación cada vez que se usará uno? Yo digo que no, no hace falta. Hay una forma de evitar hacer diseños repetitivos para esos componentes que tienen propiedades definidas de antemano, con valores que se puedan modificar al momento de usarlos.

Usando una simple tabla en la documentación de nuestro producto podemos indicar para cada diálogo los valores de cada una de las propiedades que soporta. De esta forma nos evitamos tener que diseñar un diálogo cada vez que haga falta. En su lugar, podemos usar la tabla, que es más fácil de mantener y especialmente propicia para diseñadores holgazanes como yo.

Para contenido de texto que pueda variar dinámicamente, puedes acordar cómo indicar variables para esas partes del texto que serán diferentes. Por ejemplo, puedes definir cómo incluir un nombre de usuario, como pasa en la imagen de ejemplo.

Herramientas

En mi opinión las herramientas de documentación para diseñadores están aún en su infancia. Posiblemente con la creciente popularidad de design systems y la consecuente mejora en DesignOps y la colaboración entre diseñadores y desarrolladores, encontremos más y mejores herramientas enfocadas en acortar la brecha entre diseño e implementación.

Posiblemente ya has escuchado hablar de Zeplin, una herramienta especialmente útil para el traspaso de especificaciones de diseño (tal como espacios, tamaños, colores y descarga de recursos visuales). Tengo que mencionar que tanto Sketch como Figma tienen su propia manera de inspeccionar y comentar que se superpone con algunas de las funciones de esta herramienta, así que podrías, en principio, prescindir de ella y usar solamente tu software de diseño.

Una opción interesante para documentar es Zeroheight. Te deja sincronizar tus diseños desde Sketch o Figma, y fácilmente extraer estilos para documentar tu Style Guide. Ofrece más que eso, también puedes subir tus artboards o frames, símbolos y componentes para documentarlos. Puedes incluso añadir páginas estáticas para tener una wiki más completa. También tiene integraciones (por ejemplo con Storybook) que te darán la posibilidad de juntar ejemplos de diseño y código en el mismo lugar.

Finalmente, Specify está consiguiendo un progreso interesante en su camino a convertirse una API de diseño que te ayudará a sincronizar diseño con código, teniendo un lugar central donde se almacenan los recursos visuales de diseño y los tokens. Vale la pena estar pendiente de cómo va avanzando.

Unas palabras finales: hay muchas herramientas, y no importa cuál uses. Incluso podrían ser Notion, Google Docs o lo que prefieras. La parte importante es que la documentación sea accesible, actualizada y amigable para todos los miembros del equipo, incluso quienes no son diseñadores.