Crear un pipeline de tokens con Figma, Git y Style Dictionary

Para crear un pipeline de tokens, elige una fuente aprobada para sus valores y genera los recursos de la biblioteca desde un commit revisado. Si Git es la autoridad, los cambios de Figma entran como propuestas. Conserva el mapa entre rutas y variables, comprueba alias y modos y publica la biblioteca de Figma por separado. Sincronizar debe reproducir una decisión aceptada, con responsables y versiones identificables.

Esta guía explica cómo crear un pipeline de tokens que conecte Figma Variables, Git, Style Dictionary y una biblioteca de componentes sin fuentes de verdad contradictorias. Usaremos el cambio de una superficie de aviso en un SaaS ficticio. Las reglas de responsabilidad y aceptación son recomendaciones de trabajo; los enlaces documentan las funciones reales de cada herramienta.

Elegir un único punto de aprobación

Empieza con un acuerdo escrito sobre la edición. En el modelo de esta guía, Git conserva los datos aprobados; Figma sirve para explorar el diseño y reflejar los valores publicados; Style Dictionary genera recursos para las plataformas. La biblioteca consume esos recursos. Una diseñadora puede proponer otro valor sin convertir automáticamente su prueba en la decisión que deben aplicar todos los productos.

También puedes elegir Figma como origen de autoría. En ese caso, una exportación revisada pasa a ser la entrada de una versión y se conserva en Git. Lo decisivo es qué acción aprueba el cambio, no la aplicación que el equipo utiliza más. Evita que importar CSS generado provoque otra exportación que sustituya el repositorio sin revisión.

Anota quién propone, quién revisa y quién publica. En nuestro aviso, diseño plantea el tratamiento, una persona responsable del sistema comprueba su función e ingeniería revisa los consumidores afectados. En un equipo pequeño, dos personas pueden cubrir esos papeles. Necesitas una decisión visible y alguien que responda por la versión, aunque no haya un departamento para cada paso.

Identifica las salidas generadas y explica cómo reconstruirlas. Si alguien necesita corregir una variable del CSS producido, lleva la corrección a la entrada aprobada: el siguiente build podría borrar el parche. Mantén las reglas de layout particulares en el producto. Compartir autoridad sobre tokens no significa que toda decisión de pantalla deba convertirse en una decisión central.

Definir un contrato de intercambio pequeño

Antes de conectar aplicaciones, define el conjunto mínimo de tokens: ruta, tipo, valor o referencia, descripción y contexto previsto. El informe de formato DTCG especifica datos JSON y alias; es un informe de Community Group, no un estándar W3C. Registra la versión del formato para saber qué compatibilidad debe mantener una actualización del adaptador.

Por ejemplo, color.notice.surface puede referenciar color.palette.blueSoft. El primer nombre expresa una función en el componente; el segundo proporciona el valor de paleta. Conserva esa relación en los datos aprobados aunque una salida la convierta en un color concreto. Revisar la relación semántica aporta más información que comparar dos valores literales idénticos.

Añade un manifiesto con colección, variable y modo de Figma y ruta del repositorio. Separa los nombres legibles de los identificadores de la herramienta. Un nombre puede cambiar y copiar un archivo puede introducir otra identidad. Revisa el mapa real después de una migración; dos etiquetas iguales no demuestran que sigan representando el mismo dato.

Comienza con una función del aviso y dos contextos. No intentes sincronizar a la vez todos los radios, sombras, tipografías compuestas y excepciones de producto. Nuestra guía de tokens en diseño web desarrolla los conceptos. Aquí interesa el límite que permite convertir una decisión compartida en una versión que otra persona pueda reconstruir.

Recibir cambios de Figma como propuestas

Elige una transferencia compatible con tu entorno. La guía de importación y exportación de modos documenta el intercambio JSON. La documentación de Variables REST API describe operaciones programáticas con requisitos de Enterprise, permisos de archivo y credenciales con scopes. Comprueba esas condiciones antes de basar un servicio desatendido en la API.

Para una primera versión, exportar deliberadamente puede resultar más fácil de auditar que mantener una integración continua. Guarda por separado la exportación original y la propuesta normalizada. La primera permite entender qué entregó la aplicación; la segunda muestra qué datos quiere aceptar el pipeline. Que la transferencia termine correctamente no autoriza a sobrescribir la entrada aprobada.

Comprueba rutas esperadas, tipos declarados, destinos de alias, valores admitidos y colisiones de nombres. Informa de cualquier dato omitido o incompatible. Importar una parte del conjunto no demuestra que todos los tokens hayan completado el recorrido de ida y vuelta. Registra la versión del adaptador y el archivo de entrada para poder repetir la interpretación.

Ensaya un conflicto durante la configuración: diseño propone una superficie y un cambio del repositorio propone otra. Presenta ambas propuestas y el punto de partida aprobado que comparten. El responsable debe elegir o revisar la decisión, no aceptar automáticamente la última subida. Conserva el motivo junto al valor elegido para que el siguiente cambio tenga contexto.

Generar salidas desde una entrada fija

Style Dictionary transforma datos; no aprueba decisiones. Su documentación de configuración describe rutas de entrada y ajustes de salida por plataforma. Utiliza un glob limitado, un directorio de salida explícito y configuración versionada junto a los tokens. Deja las exportaciones de prueba fuera de ese glob para que un archivo temporal no entre por accidente en producción.

El script mínimo importa StyleDictionary, crea una instancia con el archivo de configuración y espera buildAllPlatforms(), como muestra la guía oficial del módulo. Fija la dependencia y registra el runtime del proyecto. Reconstruye una versión desde su commit, en vez de aplicar los valores predeterminados actuales a una entrada de hace meses.

Revisa deliberadamente el comportamiento de los alias. La documentación de utilidades de referencias explica su resolución y el tratamiento de conjuntos filtrados. Decide si cada salida conserva referencias o resuelve valores y comprueba esa elección. Un CSS filtrado no debería apuntar a una propiedad personalizada excluida del conjunto de recursos entregado.

En nuestra primera versión, genera los tokens del aviso, inspecciona el nombre producido y carga el resultado en una página de prueba. Compáralo con la función aprobada, no con una captura exportada sin contexto. Si utilizas Tailwind, la guía de variables a Tailwind explica ese mapeo posterior. La entrada de la versión sigue siendo el conjunto revisado.

Revisar el cambio en un componente real

El espécimen de alertas de EmviUI permite concretar la revisión: muestra superficies claras y tratamientos intensos con icono, texto y control de cierre. Úsalo para identificar funciones visuales que necesitan un mapeo deliberado. La imagen no demuestra qué tokens están vinculados en tu archivo, no acredita accesibilidad ni representa una integración con Style Dictionary.

El catálogo de componentes de EmviUI incluye foundations y alertas/toasts. Puedes empezar por un componente y vincular las propiedades pertinentes a tus propias funciones aprobadas. Inspecciona primero el archivo que utilizas. Esta guía no presupone que exista un adaptador de EmviUI a Git ni promete una sincronización automática del kit.

Prepara un caso pequeño de aceptación: aviso con mensaje largo, icono y acción de cierre disponible. Revisa superficie, texto, borde y tratamiento del foco en cada contexto compatible. Señala qué se comparte y qué pertenece al producto. La longitud particular de un mensaje no debería resolverse cambiando el token compartido de color.

Después del build, compara diseño e implementación. Registra juntos versión de tokens, versión del componente y contexto probado. Si la superficie coincide pero deja de funcionar el cierre, investiga el comportamiento del componente. Nuestra guía de variantes y overrides ayuda a separar los problemas de la estructura de Figma de los de entrega de valores.

Publicar código y Figma con registros separados

Fusionar un cambio en Git no completa toda la entrega. La guía de publicación de bibliotecas de Figma explica que las ediciones permanecen en el archivo de origen hasta publicarse y que los consumidores revisan actualizaciones. Conserva registros separados del build, del paquete de componentes y de la publicación de Figma; «sincronizado» resulta demasiado impreciso.

Prepara un registro breve: commit aprobado, configuración de build, identificador del recurso generado, versión del componente, archivo fuente de Figma y nota de publicación. Añade el archivo consumidor y los contextos probados. Si queda una fase pendiente, identifícala. Así podrás distinguir un despliegue gradual intencional de una transferencia que falló o quedó incompleta.

Publica primero un cambio delimitado. Por ejemplo, entrega la nueva superficie del aviso sin renombrar simultáneamente todas las funciones semánticas. Pide aceptar la actualización en un archivo consumidor y revisar el mismo caso usado durante la aprobación. Importar correctamente en el archivo fuente no demuestra que un diseño dependiente haya recibido esos valores.

Si varias bibliotecas de Figma dependen entre sí, revisa la cadena antes de declarar la entrega completa. Localiza el paso desactualizado mediante archivos y versiones registrados. Comunica qué aceptaciones deben realizar los equipos de producto. Coordinar la publicación sigue formando parte del proceso aunque hayas automatizado la transferencia y la transformación de datos.

Detener ambigüedades antes de fusionar

Convierte el acuerdo de edición en controles visibles. En GitHub, la protección de ramas permite exigir revisiones y comprobaciones antes de fusionar, según las funciones disponibles para el repositorio. Esos controles aplican un proceso; el equipo sigue definiendo qué validan las pruebas y quién puede aprobar una modificación semántica.

Recomendamos comprobar alias sin destino, nombres normalizados duplicados, contextos esperados ausentes, eliminaciones inesperadas y cambios en el manifiesto de mapeo. Adjunta un diff legible al informe automático. Quien revisa debe entender qué función del aviso cambió y por qué, en lugar de interpretar un JSON extenso cuyo orden se ha modificado.

Provoca errores en una propuesta desechable antes de confiar en la automatización. Elimina el destino de un alias y confirma que se detiene la entrega. Renombra una variable mapeada y verifica que se solicita revisar el vínculo. Introduce otra exportación sin aprobar y comprueba que no sustituye la base aceptada. Estas pruebas evalúan directamente el límite de edición.

Registra también las correcciones urgentes, con alcance reducido. Identifica consumidor afectado, responsable y excepción temporal. Integra esa excepción en los datos aprobados antes de volver a las entregas habituales. Parchear discretamente el CSS generado y el diseño deja dos arreglos sin documentación que pueden volver a separarse en cuanto alguien reconstruya una salida.

1. Validar rutas, tipos, alias y contextos esperados.
2. Revisar el diff semántico y los cambios del mapeo.
3. Generar desde el commit aprobado y la configuración registrada.
4. Registrar por separado entrega de componentes y publicación de Figma.
5. Verificar el consumidor y conservar las entradas de recuperación.

Ensayar la recuperación antes de ampliar

Conserva la entrada aprobada anterior y su registro de entrega. Si el aviso nuevo provoca una regresión, decide si recuperar sus valores o publicar una propuesta corregida. Reconstruye las salidas y coordina la publicación correspondiente de Figma. Revertir un archivo del repositorio no actualiza por sí solo los consumidores que ya recibieron una versión.

Ensáyalo con un componente de prueba. Parte de una versión A, aprueba B y recupera los valores previstos de A mediante una versión C documentada. Comprueba implementación y archivo consumidor. Verifica mapeo, recursos publicados y aceptaciones; no basta con que los datos del origen vuelvan a parecer conocidos o que una captura tenga el mismo aspecto.

Amplía el sistema cuando otra persona pueda repetir el build y explicar un conflicto sin depender del autor inicial. Añade una función, un modo o una plataforma cada vez. Cada ampliación necesita una comprobación de datos admitidos y un caso de aceptación en el consumidor. De ese modo el pipeline sigue siendo comprensible mientras crece la biblioteca.

El resultado útil es un recorrido trazable desde una propuesta de diseño hasta una versión aprobada. Las herramientas transportan y transforman valores; las personas definen significado, autoridad y aceptación. Con ese acuerdo, sincronizar se convierte en una entrega repetible con pruebas concretas, en lugar de una disputa entre copias que cualquiera puede editar.