Communitygithub.com

vinculación-de-biblioteca-figma

Vincula pantallas de Figma a una biblioteca de sistema de diseño: asigna tokens solo cuando los valores coinciden exactamente, intercambia iconos y componentes por versiones de la biblioteca, y lista los valores no coincidentes para que los diseñadores decidan, evitando ajustes automáticos.

¿Qué es vinculación-de-biblioteca-figma?

Esta skill automatiza la vinculación de pantallas de Figma a una biblioteca de sistema de diseño (design system) del proyecto, asegurando consistencia visual y evitando cambios no deseados. Funciona con asistentes de IA como Claude Code o Cursor, y utiliza preset JSON para configurar la vinculación. Las reglas son estrictas: colores, radios, trazos, espaciados y tamaños de texto solo se vinculan si coinciden exactamente, incluyendo opacidad; los iconos se intercambian solo si el nombre coincide exactamente, y los componentes se reemplazan solo si se ven igual. Los valores no vinculados se listan para que el equipo de diseño decida, en lugar de forzar una aproximación que podría diferir del código. La skill soporta vinculación automática durante la construcción de pantallas mediante `al-pack.py`, y también una vinculación independiente de tokens con `al-bind.js`. Incluye un proceso detallado para crear presets, mapear iconos y componentes, y generar reportes con métricas de vinculación, iconos intercambiados y valores no asignados.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/byby325/code-to-figma-ui-states/tree/HEAD/skills/figma-library-binding

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Vinculación a una biblioteca de sistema de diseño

Las pantallas del producto deben usar el sistema de diseño del proyecto, no solo capas locales.

Elegir un preset

Cada sistema de diseño tiene un preset, en presets/. Pregunta al usuario cuál usa el proyecto, o revisa las dependencias del proyecto (ej. si el proyecto depende de un paquete de tokens de diseño, usa el preset correspondiente). Consulta presets/README.md para conocer el formato. Si no hay preset, búscalo una vez siguiendo "Cómo funciona la vinculación automática" más abajo, luego guarda el resultado como un nuevo preset. Si el proyecto no tiene biblioteca, escribe "Ninguno" e indícalo en el informe.

Antes de comenzar, usa get_libraries para confirmar que cada biblioteca esté en libraries_added_to_file. Para las que falten, pide al usuario que las agregue en Figma en Assets › Libraries; no continúes hasta que estén agregadas.

Reglas de vinculación

Es mejor dejar algo sin vincular que cambiar la pantalla. La herramienta solo hace lo que se indica a continuación; todo lo demás permanece local y se reporta.

TipoReglaNo hacer
ColorVincular solo si hay coincidencia exacta, incluyendo opacidad. Los colores semitransparentes necesitan un token con esa transparencia, porque Figma restablece la opacidad a 1 al vincularNo ajustar al color más cercano
Radio, trazo, espaciado, tamaño de textoVincular solo cuando el valor sea exactamente igualNo cambiar 3px a 2px o 4px
Tokens aliasUn token que apunta a otro token (un token semántico sobre uno primitivo) cuenta con el valor al final de la cadena. Cuando un valor tiene ambos, gana el token con su propio valor; el alias se usa solo para valores que ningún otro tieneNo elegir entre dos tokens semánticos con el mismo valor adivinando; repórtalo
Estilo de textoVincular solo cuando fuente, tamaño y altura de línea sean igualesSi la fuente difiere, vincular solo el tamaño
IconoIntercambiar solo cuando la biblioteca tenga un componente con el mismo nombre; aceptar nombres antiguos solo para mapeos confirmados con el mismo propósitoNo usar un icono con significado similar pero apariencia diferente
ComponenteIntercambiar solo cuando el componente de la biblioteca se vea igual que el del producto; mantener el tamaño del productoSi se ve diferente, mantener el componente local y no cambiar la pantalla del producto

Por qué no ajustar al valor más cercano: un valor coincidente no significa un significado coincidente, y hace que el panel de estado discrepe del código. Un valor sin token coincidente es una brecha en el sistema de diseño; lístalo para que diseño decida, en lugar de dejar que la herramienta elija.

Cómo funciona la vinculación automática

Con un preset, establece preset en la configuración de al-capture.cjs y pasa el nombre del preset como cuarto argumento a al-pack.py; las pantallas se vinculan automáticamente cuando se construyen. Solo sin un preset, sigue el proceso a continuación, luego guarda el resultado como presets/<nombre>.json: libs es la configuración de vinculación, y extract es el mapeo de sprites usado durante la extracción.

  1. Después de extraer el árbol de diseño, lista cada lib (nombre de icono) en el JSON
  2. Para cada nombre, busca en el Sistema de Iconos con search_design_system: system:cross se mapea a icon / system / cross. Acepta solo coincidencias exactas de nombre
  3. Usa search_design_system para encontrar el conjunto de componentes, coloca algunas instancias, captúralas, compara su apariencia con el producto y decide buttons.rules
  4. Ensambla opts.libs. Construye 3-4 tarjetas primero y verifica log.drift y las capturas; procesa en lote solo si se ven correctas
const libs = {
  tokens: ['My DS - Foundation'],        // leer variables de estas bibliotecas
  icons: { 'system:cross': '<componentKey>' },
  buttons: {
    set: '<componentSetKey>',
    rules: { FFE13A: { Type: 'primary', Size: 'medium', Compact: 'false', Status: 'default' } }, // key es el color de fondo del botón
  },
  words: { value: 'Price' },             // renombrar propiedades de texto para que coincidan con los términos del equipo
};

La salida de al-capture.cjs incluye unmappedIcons, que lista los iconos usados en esta ocasión que el preset aún no mapea. Búscalos con search_design_system y agrega las coincidencias exactas de nombre al preset; la próxima vez se vincularán automáticamente, por lo que el preset se vuelve más completo con el uso.

El stat devuelto por __alBuild tiene los resultados de vinculación: boundColors, boundLayout, libIcons, dsButtons, unboundColors, localIcons.

Vincular pantallas existentes

al-bind.js se puede usar de forma independiente. Solo vincula tokens y no intercambia iconos ni componentes. Pega todo el script en use_figma (o cárgalo con eval), luego llama:

return await __alBind(['<id del frame>'], { tokens: ['<nombre de la biblioteca>'] });

Devuelve boundColors, boundLayout y unboundColors (colores sin token). skippedText cuenta el texto cuya fuente no pudo cargarse, por lo que su tamaño quedó sin vincular.

Cuando las pantallas se construyen con __alBuild, la tabla de tokens se almacena en caché en _registry para que pantallas posteriores no importen cada variable nuevamente. Se reconstruye cuando el preset lista bibliotecas de tokens diferentes. Después de que la biblioteca publique tokens nuevos o modificados, pasa refreshTokens: true a la siguiente llamada __alBuild.

Componentes

  • Centrar con Auto Layout: no con padding o ancho de caja de texto, para que cambiar el texto no lo desplace
  • Los contenedores no son componentes: una estructura repetida que ya contiene componentes es solo un contenedor
  • Los estados son variantes: seleccionado y deshabilitado deben poder cambiarse mediante propiedades, no sobrescribiendo colores de instancia
  • Dividir componentes pequeños en propiedades: dos propiedades de variante, Type y State; hacer que el texto sea una propiedad de componente
  • Los componentes principales deben estar completos: no convertir elementos recortados por el viewport en componentes

Informe

Siempre lista:

  • Proporción de vinculación: colores, valores de diseño
  • Número de iconos y componentes intercambiados por versiones de la biblioteca
  • Colores sin token (los primeros), para que diseño decida
  • Iconos y componentes mantenidos localmente, y por qué

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

code-to-figma

Rebuild screens from a running web app as native, editable Figma layers (Auto Layout, components, instances) and diff them against browser screenshots — not a screenshot import or a Code layer. Use when the user asks to "turn this page into Figma", "code to Figma", "push this screen to Figma" or "rebuild the UI in Figma". 把 Web 專案實際跑出來的畫面重建成 Figma 原生圖層:造狀態、抽 DOM 版面樹,建 Auto Layout 和 component/instance,再跟瀏覽器截圖比對。單一畫面或一批畫面都能用,不需要做情境稿。Use when 使用者要「code to figma」「把這頁轉成 Figma」「從程式重建畫面」「push 畫面到 Figma」,或 figma-state-board 走路線 B。產出是可編輯圖層,不是 Code layer 或截圖。

figma-state-board

Inventory every UI state of a feature from its code and lay them out on one Figma canvas (a state board) — real screens for states the prototype already handles, plus a gap check of missing error, empty and loading states, split into spec-required and suggested. Use when the user asks for a "state board", "all states of this feature in Figma", "which error screens are missing", or to update an existing board. 從任何產品專案的程式碼盤點一個功能的所有狀態,在 Figma 產出或更新「情境稿」:原型(通常是 mock data 做的)已經有的狀態畫真實畫面,原型缺的狀態全列進「缺漏檢查」,再分「規格有寫」(規格要求、原型漏做)和「建議補」(規格和原型都沒提的錯誤、空狀態、載入等)。Use when 使用者要「做情境稿」「把所有狀態/狀況畫到 Figma」「state board」「檢查缺了哪些 error 畫面」,或要依新規則增修既有情境稿。只要狀態清單用 state-discovery,只要把畫面轉進 Figma 用 code-to-figma。

Skills relacionados