Figma State Board
Un state board es una sección de Figma que presenta todos los estados en los que puede estar una funcionalidad en un solo lienzo. Los grupos se dividen por dispositivo, pestaña o tema. Cada tarjeta tiene "ID · nombre", "desencadenante; resultado" y una pantalla del producto. El último grupo, Gap check (en chino tradicional: 缺漏檢查), enumera los estados que el prototipo aún no tiene pero la funcionalidad debería tener. Diseñadores, ingenieros, QA y PMs lo utilizan como su lista compartida de estados.
El código del proyecto suele ser un prototipo basado en datos simulados (mock data), no conectado a un backend real. Por lo tanto, no dividas los estados en "implementados / no implementados aún". Haz solo una pregunta: ¿el prototipo construye este estado? Las tarjetas tienen solo tres etiquetas:
- Prototype (en chino tradicional: 原型): el prototipo tiene esta rama. Dibuja la pantalla real; sin etiqueta
- In spec (en chino tradicional: 規格有寫): mencionado en ACs, especificaciones, maquetas o texto i18n no utilizado, pero el prototipo no lo construye. Va en el gap check
- Suggested (en chino tradicional: 建議補): ni la especificación ni el prototipo lo mencionan; se infiere de la evidencia del código o del tipo de funcionalidad. Va en el gap check
Funciona para cualquier stack y cualquier producto. board-format.md es la fuente de verdad para las especificaciones del board.
Idioma. Escribe la matriz, los nombres de las tarjetas, las descripciones, el texto de los wireframes y el informe en el idioma del usuario. Las etiquetas fijas del board (etiquetas, Gap check, resumen de cobertura, encabezados de wireframes, nombres de capas) provienen de BOARD.lang: 'zh-TW' cuando el usuario trabaja en chino tradicional, 'en' en caso contrario. Otros idiomas mantienen las etiquetas en inglés con el texto de las tarjetas en el idioma del usuario.
Esta habilidad posee el flujo general, el board y la auditoría. Otro trabajo se deriva a otras habilidades en el mismo plugin:
| Tarea | Usar | Cuándo |
|---|---|---|
| Protección de escala | scale-guard.md | Leer antes del paso 1 |
| Vincular a un sistema de diseño | figma-library-binding | Confirmar en el paso 1, usar en el paso 5 |
| Inventariar estados, encontrar brechas | state-discovery | Paso 2 |
| Reconstruir pantallas desde código | code-to-figma | Paso 5, en la Ruta B |
Archivos propios de esta habilidad:
- board-format.md: diseño del board, tamaños de fuente, etiquetas y reglas de ID de tarjetas. Leer antes de dibujar cualquier cosa
- board-skeleton.js: construye el esqueleto del board y los wireframes de brechas a partir de la matriz. Se usa en el paso 4
- screenshot-slots.js: ajusta las capturas de pantalla del navegador subidas en las tarjetas. Se usa en el paso 5 en la Ruta C
- audit.js: auditoría del board. Se usa en el paso 6
Si el proyecto tiene su propia habilidad de reglas de UI (por ejemplo, la habilidad de pautas de UI del proyecto), síguela para los tokens de las pantallas del producto, nombres y aceptación.
Pasos
1. Confirmar las entradas
Pregunta por cualquier cosa faltante:
- Fuente de código: repositorio, rama, punto de entrada de la funcionalidad (ruta, página, pantalla o componente)
- Fuente de reglas: ACs de Jira, PRD, Confluence, documentación de códigos de error. Si no hay ninguna, escribe "Ninguna"; el gap check tendrá más tarjetas
- Destino: archivo y página de Figma; una sección nueva, o una actualización de un state board existente. Para boards de práctica, o boards para compartir con otros, usa el archivo de práctica compartido del equipo (reglas en board-format.md "Shared practice file"). Si el destino es un archivo existente, también pide al usuario que informe su uso actual de memoria (scale-guard.md)
- Dimensiones: los ejes a lo largo de los cuales varían los estados (ancho del dispositivo, estado de inicio de sesión, rol, pestaña, volumen de datos, secuencia de interacción…), y el ancho del viewport para cada dispositivo
- Fuente de pantallas del producto: componentes en el archivo de destino o una biblioteca, o un prototipo en ejecución / servidor de desarrollo. Si no hay ninguna, solo se pueden dibujar wireframes; díselo de antemano
- Biblioteca del sistema de diseño: a qué bibliotecas deben vincularse las pantallas del producto (figma-library-binding). Si ninguna, escribe "Ninguna"
Tan pronto como tengas el enlace de Figma, haz dos cosas primero. No esperes hasta que el inventario esté terminado para descubrir que no puedes dibujar en el archivo:
- Confirmar acceso de lectura y escritura:
create_session, luego ejecuta unuse_figmade solo lectura (lista páginas y nodos de nivel superior). Si informa "could not access the requested file", usawhoamipara ver con qué cuenta MCP ha iniciado sesión, y da al usuario dos opciones: compartir el archivo con esa cuenta con permiso de edición, o iniciar sesión con una cuenta que tenga acceso en la configuración del conector (después de cambiar, los archivos de la cuenta original no se pueden abrir) - Estimar el presupuesto de llamadas: sigue scale-guard.md "MCP call budget" para estimar cuántas llamadas necesita esta ejecución, y compáralo con los asientos del plan del archivo de destino en
whoami. Si no es suficiente, dilo primero y deja que el usuario elija: Ruta C (capturas de pantalla del navegador en las tarjetas, aproximadamente 3 llamadas para todo el board; paso 5), dividir en lotes, cambiar de archivo, o hacer menos comparaciones
Hecho cuando: los seis elementos tienen un valor claro, o el usuario ha dicho explícitamente que no aplican; el archivo de destino es legible; el presupuesto de llamadas es suficiente, o el usuario ha elegido cómo dividir el trabajo.
2. Inventariar estados y construir la matriz de estados
Construye la matriz con state-discovery. Asigna los IDs de las tarjetas de antemano, siguiendo las reglas en board-format.md.
No dibujes hasta que el usuario haya confirmado la matriz. Cómo se dividen los grupos, qué tarjetas fusionar y qué tarjetas Suggested conservar se resuelven en este paso; cambiarlos después de dibujar cuesta mucho más. Si hay más de 150 tarjetas Prototype, sigue scale-guard.md y pide al usuario que decida si fusionar tarjetas, dividir páginas o dividir archivos. No dibujes hasta que decidan.
3. Preparar datos para cada tarjeta
- Prototype: reprodúcelo con datos simulados fijos o una historia de Storybook. Añade los datos faltantes en la capa de simulación; no añadas ramas a los componentes solo para las capturas de pantalla.
- In spec, Suggested: el prototipo no tiene pantalla, por lo que no se necesitan datos; dibuja un wireframe. Para las tarjetas In spec, escribe en el wireframe qué requiere la especificación y dónde lo dice.
Hecho cuando: cada tarjeta Prototype tiene datos reproducibles, o está claramente marcada como "Illustrative in Figma only".
4. Construir el esqueleto del board
Primero carga las dos habilidades del plugin de Figma, figma-use y figma-generate-design (en Claude Code: figma:figma-use / figma:figma-generate-design; sin el plugin de Figma, usa get_figma_skill para leer skill://figma/figma-use/SKILL.md y así sucesivamente, con un prefijo resource: en skillNames).
Si el destino es un archivo existente, pide al usuario que guarde una versión antes de escribir. Lo mismo se aplica antes de eliminar o reconstruir tarjetas que tú mismo hayas construido. Si la página de destino no tiene nada más que lo que tú has construido (un archivo nuevo, una página en blanco), puedes omitir el guardado; dilo en el informe.
Para un nuevo state board, usa board-skeleton.js: completa la matriz confirmada en el paso 2 en BOARD en la parte superior, y pega todo el script en una llamada use_figma. Siguiendo board-format.md, construye la sección (nombrada "-", colocada a la derecha del contenido existente en la página) → título del board, subtítulo, resumen de cobertura (calculado automáticamente) → grupos → Escenarios → tarjetas. El último grupo es el gap check, con sus wireframes dibujados. Las pantallas de las tarjetas Prototype comienzan como ranuras de marcador de posición con placeholder = true; el script devuelve el slotId de cada tarjeta, que pasas al construir las pantallas en el paso 5. En un archivo compartido, usa una página por funcionalidad y establece BOARD.pageName al nombre de la página. Establece BOARD.lang según "Idioma" arriba, y el tag de cada tarjeta de brecha a 'spec' (In spec) o 'suggested' (Suggested).
Al actualizar un state board existente, no ejecutes el script del esqueleto. En su lugar, usa estas reglas:
- Vuelve a leer el nodo de destino antes de cada mutación; el diseñador puede haber movido o dividido cosas manualmente
- Cambia solo las tarjetas afectadas. Mantén sus IDs; las tarjetas nuevas continúan después del último número en su grupo
- Una vez que el prototipo construye el estado de una tarjeta de gap check, mueve la tarjeta al grupo al que pertenece, elimina la etiqueta, dale un nuevo ID, y anota el antiguo ID G en la descripción
- Recalcula los números en el resumen de cobertura
- Mantén el idioma existente del board para las etiquetas que añadas, incluso si el usuario ahora escribe en otro idioma; un board con etiquetas mixtas es difícil de leer
- No toques el área de notas del diseñador a la derecha ni la sección de Feedback
Hecho cuando: cada tarjeta Prototype tiene una ranura de marcador de posición y un slotId; todos los wireframes del gap check están dibujados.
5. Construir las pantallas en Figma
Usa use_figma para construir capas nativas y colocarlas en las ranuras de marcador de posición del paso 4. send_code_to_figma importa una capa de Código y no produce capas de Diseño editables, por lo que no funciona para state boards.
En la Ruta B, sigue code-to-figma "Hard rules for writing to Figma" y envía solo una pantalla a la vez. Con más de 100 tarjetas Prototype o más de 20 imágenes únicas, pide al usuario que informe el uso de memoria después de cada grupo, siguiendo scale-guard.md. Si llegas a una condición de parada de scale-guard.md mientras escribes (incluyendo límite de llamadas alcanzado), detente y no reintentes.
Elige una ruta primero y confírmala con el usuario:
- Ruta A: copiar las maquetas (por defecto). Úsala cuando el archivo de destino o la biblioteca tengan pantallas de maqueta completas. Puedes vincular variables y mantener Auto Layout.
- Ruta B: reconstruir desde el código del proyecto. Úsala cuando el archivo de destino no tenga maquetas para copiar, o cuando el usuario pida reconstruir desde código en lugar de pegar maquetas. Sigue code-to-figma y pasa
slotIda__alBuild; la pantalla del producto se coloca en la ranura de marcador de posición de la tarjeta. Actualmente solo para frontends web. - Ruta C: capturas de pantalla del navegador. Cada tarjeta Prototype muestra una captura de pantalla de la aplicación en ejecución; no se reconstruye nada. Todo el board requiere aproximadamente 3 llamadas contadas, sin importar cuántas tarjetas tenga, así que ofrécela cuando el presupuesto de llamadas no pueda cubrir la Ruta B (planes Starter, asientos View y Collab), o cuando el usuario solo necesite la lista de estados y el gap check. Las pantallas son imágenes, no capas editables; dilo cuando la ofrezcas y de nuevo en el informe. Solo frontends web. Los pasos están debajo de "Ruta C".
En las Rutas A y B, las pantallas del producto deben seguir screen-structure.md: el marco raíz de la pantalla con ancho Fijo = W; Auto Layout para contenedores cuyos hijos están organizados; sin Grupos; UI repetida como componentes (variantes para diferentes estados); los contenedores de carrusel recortan y nunca están en Hug; texto largo con Fill + altura automática. Las tarjetas de gap check (In spec, Suggested) siguen la especificación de wireframe en board-format.md; no dibujes UI de producto falsa.
Los pasos 1–3 a continuación son para la Ruta A:
- Encontrar pantallas y componentes: si el archivo de destino ya tiene pantallas de maqueta completas, prefiere copiarlas y cambiar el estado (cambiar variantes, ocultar capas); eso es lo más cercano al producto. A continuación, usa
search_design_systemy componentes locales. Solo si ninguno existe, construye capas locales a partir de la estructura y los estilos del código. Vincula colores, tamaños de fuente y espaciado a las variables del proyecto. Cuando las maquetas y el código no estén de acuerdo, sigue el código y anótalo en la descripción.- Si la fuente del producto no se puede cargar en el tiempo de ejecución de Figma (por ejemplo, Arial), no cambies el texto existente. Para texto nuevo, usa una fuente con anchos compatibles (Arial → Arimo), y enumera dónde la usaste en el informe.
- Construye una pantalla representativa por dispositivo primero, y compara su captura de pantalla con el prototipo o la pantalla en vivo: continúa solo una vez que el texto, el espaciado, el radio de las esquinas y los tokens sean correctos. Si no hay nada con qué comparar, di en el informe que estas pantallas no se compararon.
- Genera las tarjetas Prototype restantes a partir de la pantalla representativa mediante clonación o instancia más anulaciones, cambiando solo lo que difiere en este estado.
Ruta C:
- Capturar: sigue web-capture.md pasos 1–3 con
shotOnly: trueen la configuración. Escribecapture/<ID>.jpga 2x y omite el árbol de diseño. Leestats.json: una advertencia sobre 4096px significa que la pantalla es demasiado larga para una imagen; captúrala como varias tarjetas de altura de viewport - Mira cada captura de pantalla localmente antes de subirla. Este es el paso de comparación en la Ruta C: un estado incorrecto, un spinner que nunca terminó o una barra de herramientas de desarrollo dejada en la captura no cuesta nada arreglarlo aquí
- Subir: llama a
upload_assetsconnodeIdsestablecido en losslotIds de las tarjetas en orden de tarjetas (máximo 60 por llamada). Escribe las submitUrls en un archivo, una por línea, y envía las capturas de pantalla en el mismo orden:python3 al-upload.py urls.txt capture/shot/C01.jpg capture/shot/C02.jpg. Siupload_assetsno llena las ranuras, llámalo concurrentPageIdycounten su lugar; las capturas de pantalla aterrizan en la página como capas nombradas<ID>.jpg, y el siguiente paso las mueve a sus tarjetas. No renombres los archivos - Ejecuta screenshot-slots.js con
SECTION_IDreemplazado, en la misma llamadause_figmaque audit.js (paso 6): envuelve cada uno en una función asíncrona, llámalos en orden, luegoawait section.screenshot()en la sección del board antes de devolver ambos resultados, para que la imagen del board regrese con la misma llamada. Ajusta cada ranura a su captura de pantalla y devuelveplaced,missingyskipped. Sube de nuevo para las tarjetas enmissing - Para convertir una tarjeta de captura de pantalla en capas editables más tarde, reconstruye esa tarjeta con la Ruta B y pasa el mismo
slotId; la reconstrucción reemplaza la imagen
Hecho cuando: has visto una captura de pantalla de cada pantalla representativa del dispositivo, y coincide con el prototipo, o has notado que no había nada con qué comparar. La Ruta B también debe cumplir los criterios de finalización en code-to-figma. En la Ruta C, cada tarjeta Prototype está en placed, o el informe enumera las que no lo están.
6. Auditoría
- Ejecuta ambos scripts de auditoría, reemplazando
SECTION_IDcon la sección de destino. Pega ambos en la misma llamadause_figma(envuelve cada uno en una función asíncrona, llámalos en orden y devuelve ambos resultados) para ahorrar una llamada del presupuesto:- audit.js: el board. Si los grupos tienen un título y una descripción, IDs de tarjetas duplicados, si los carruseles recortan correctamente, si las fuentes coinciden, si el diseño es consistente con board-format.md. Devuelve un informe de auditoría.
- (El segundo script de auditoría no está definido en el original, pero se asume que es parte del flujo)
Hecho cuando: el informe de auditoría se ha presentado al usuario y se han abordado los problemas encontrados.
7. Informe final
Escribe un resumen de lo que se ha hecho, incluyendo:
- Número de tarjetas Prototype, In spec y Suggested
- Ruta utilizada (A, B o C)
- Cualquier problema encontrado durante el proceso
- Enlaces a las secciones del board en Figma
- Instrucciones para futuras actualizaciones
Hecho cuando: el informe se ha presentado al usuario y se ha confirmado que todo está correcto.