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.
| Tipo | Regla | No hacer |
|---|---|---|
| Color | Vincular solo si hay coincidencia exacta, incluyendo opacidad. Los colores semitransparentes necesitan un token con esa transparencia, porque Figma restablece la opacidad a 1 al vincular | No ajustar al color más cercano |
| Radio, trazo, espaciado, tamaño de texto | Vincular solo cuando el valor sea exactamente igual | No cambiar 3px a 2px o 4px |
| Tokens alias | Un 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 tiene | No elegir entre dos tokens semánticos con el mismo valor adivinando; repórtalo |
| Estilo de texto | Vincular solo cuando fuente, tamaño y altura de línea sean iguales | Si la fuente difiere, vincular solo el tamaño |
| Icono | Intercambiar solo cuando la biblioteca tenga un componente con el mismo nombre; aceptar nombres antiguos solo para mapeos confirmados con el mismo propósito | No usar un icono con significado similar pero apariencia diferente |
| Componente | Intercambiar solo cuando el componente de la biblioteca se vea igual que el del producto; mantener el tamaño del producto | Si 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.
- Después de extraer el árbol de diseño, lista cada
lib(nombre de icono) en el JSON - Para cada nombre, busca en el Sistema de Iconos con
search_design_system:system:crossse mapea aicon / system / cross. Acepta solo coincidencias exactas de nombre - Usa
search_design_systempara encontrar el conjunto de componentes, coloca algunas instancias, captúralas, compara su apariencia con el producto y decidebuttons.rules - Ensambla
opts.libs. Construye 3-4 tarjetas primero y verificalog.drifty 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,
TypeyState; 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é