Cómo documentar componentes de Figma

Hoy te voy a explicar cómo documentar componentes de Figma. Este artículo es la continuación del post donde te conté los pasos que doy para informar a mi equipo UX/UI sobre las tareas que realizo para construir y mantener un design system.

Usaré otra vez el ejemplo del componente botón.

Los beneficios de documentar

Documentar componentes ofrece una serie de beneficios clave para el proceso de diseño y desarrollo.

La documentación es un recurso esencial para garantizar la consistencia en todo el proyecto. Documentar información detallada de un componente ayuda a establecer un estándar claro que todos los miembros del equipo pueden seguir.

Esto es especialmente valioso en equipos grandes o en proyectos a largo plazo, donde la coherencia visual es esencial para mantener una experiencia de usuario unificada.

Además, la documentación facilita la colaboración entre diseñadores y desarrolladores.

La acción de detallar las interacciones, los tamaños, los estilos y las variaciones de un componente, reduce la probabilidad de malentendidos y se mejora la eficiencia en la implementación.

Los equipos de product designers, UX y UI, front-end y back-end ahorran muchísimo tiempo si pueden acceder fácilmente a información crítica sobre todos los componentes. El resultado que obtenemos es una comunicación fluida y un desarrollo más ágil.

¿Qué debes documentar?

Aquí te dejo una lista detallada de todos los aspectos que estoy documentando en el proyecto que puse de ejemplo la semana pasada.

En este caso utilizo las bases de datos de Notion, en otros proyectos me apoyo en Storybook. Recuerda que también dije que no hay proyectos iguales.

Volvamos al ejemplo del componente botón.

En la página dedicada a cada uno de los componentes combino bloques de texto, imágenes con capturas de pantallas y una base de datos integrada con la siguiente información:

Nombre

Proporcionar un nombre claro y descriptivo para el componente es muy importante. La nomenclatura que utilizo sigue el estilo propuesto por la empresa. En otros proyectos soy yo el lo propone.

Descripción

Siempre escribo una descripción corta explique la función principal de, en este caso, el botón.

Variantes

Con este tipo de información me gusta explayarme, especifico cuándo y cómo se deben utilizar cada una de las variantes del componente.

• Tipo de botón (dónde y para qué se va a utilizar, también dejo claro dónde y cuándo no se debe utilizar)
• Estados (Default, Hover, Active, Disabled, Selected, Skeleton, etc)
• Tamaños (SM, MD, LG y XL, y si hay alguna restricción en su escalabilidad)
• Colores (fondo, bordes, texto e iconos)
• Modos (Light y Dark)
• Textos (familias de de fuentes, tamaños, alto de líneas, espacio entre caracteres, etc)
• Bordes y esquinas (tamaño del trazo. de radios o cualquier propiedad relacionada con su apariencia)
• Iconos (Left y right y tamaños de cada uno de ellos)

Tokens de diseño

Las Variables de Figma (en fase beta) tienen mucha presencia en los puntos de la lista anterior, pero ahora mismo no hay soporte para todos los tokens.

Para solventar esta limitación dejo notas indicando qué valores están definidos «a mano».

Entonces, cuando las Variables se puedan usar en todos los valores de un componente sabremos que hay que actualizar esos datos.

Interacciones

Las documento todas, animaciones, transiciones, eventos, etc. Me aseguro de explicar cómo se debe comportar el botón en diferentes situaciones.

Accesibilidad

Incluyo detalles sobre la accesibilidad del botón, etiquetas ARIA y otras consideraciones que mejoren la accesibilidad del mismo. En este apartado casi siempre añado links a otras páginas de Notion o a documentos de FigJam con más información.

Notas de uso

Escribo instrucciones claras sobre cómo y cuándo se debe utilizar el botón. Incluyo cualquier contexto importante para su implementación.

Ejemplos de uso

Siempre muestra ejemplos visuales de cómo se debe utilizar el botón en diferentes situaciones. Para ello incrusto capturas de pantalla o vídeos de Loom con movimientos de ratón, mi propia voz ofreciendo más información, etc. No exagero si te digo que mi cuenta de Loom tiene horas y horas de contenidos audiovisual.

Recursos externos

Aunque en algunos apartados añado links externos siempre mantengo un bloque con más información fuera de Notion, como guías de estilos, alguna biblioteca o documento de Figma, etc. La idea es ofrecer a la persona interesada en el componente toda la información que le pueda interesar y servir para hacer mejor su trabajo.

Versión

También incluyo información sobre la versión del componente para facilitar el seguimiento de cambios y las actualizaciones.

Comentarios

Siempre añado una pequeño “CTA” invitando a la persona que aterriza en la documentación a dejar comentarios de Notion. Me gusta y me ayuda muchísimo conocer la opinión de la gente que va a usar cada uno de los componentes que construyo.

También recomiendo que me contacten vía Slack por si tienen alguna duda o quieren hacer algún comentario.

Y aquí me quedo por ahora.

¿Echas en falta algo?

Si necesitas más información deja tu comentario y te respondo, muchas gracias.