Communitygithub.com

figma-state-board

Inventario de todos los estados de interfaz de una funcionalidad a partir de su código, presentados en un lienzo de Figma (state board): pantallas reales para los estados que el prototipo ya maneja, más una verificación de estados faltantes (error, vacío, carga) dividida en requeridos por especificación y sugeridos. Úsalo cuando el usuario solicite un "state board", "todos los estados de esta funcionalidad en Figma", "qué pantallas de error faltan" o para actualizar un board existente.

¿Qué es figma-state-board?

Esta habilidad automatiza la creación y actualización de un "state board" en Figma, un lienzo que muestra cada estado de interfaz de una funcionalidad de producto. A partir del código del proyecto (repositorio, rama) y las fuentes de reglas (especificaciones, ACs de Jira, PRD), la habilidad primero ejecuta un descubrimiento de estados (basado en la habilidad `state-discovery`) para inventariar todos los estados posibles, etiquetándolos como "Prototype" (el prototipo lo construye), "In spec" (especificado pero no implementado) o "Suggested" (ni especificado ni implementado, pero inferido). Luego, construye la estructura del board en Figma usando scripts, reproduce las pantallas de los estados "Prototype" (ya sea copiando maquetas existentes, reconstruyendo desde código vía la habilidad `code-to-figma`, o insertando capturas de pantalla del navegador) y dibuja wireframes para los estados faltantes en una sección de "Gap check". Finalmente, audita el board para verificar consistencia. Soporta cualquier stack y producto, y se integra con habilidades complementarias como `figma-library-binding` para enlazar sistemas de diseño y `scale-guard` para gestionar límites de llamadas MCP. Es ideal para diseñadores, ingenieros, QA y PMs que necesitan una visión compartida y completa de todos los estados de una funcionalidad.

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

Preguntar en tu IA favorita

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

Documentación

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:

TareaUsarCuándo
Protección de escalascale-guard.mdLeer antes del paso 1
Vincular a un sistema de diseñofigma-library-bindingConfirmar en el paso 1, usar en el paso 5
Inventariar estados, encontrar brechasstate-discoveryPaso 2
Reconstruir pantallas desde códigocode-to-figmaPaso 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:

  1. Confirmar acceso de lectura y escritura: create_session, luego ejecuta un use_figma de solo lectura (lista páginas y nodos de nivel superior). Si informa "could not access the requested file", usa whoami para 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)
  2. 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 slotId a __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:

  1. 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_system y 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.
  2. 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.
  3. 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:

  1. Capturar: sigue web-capture.md pasos 1–3 con shotOnly: true en la configuración. Escribe capture/<ID>.jpg a 2x y omite el árbol de diseño. Lee stats.json: una advertencia sobre 4096px significa que la pantalla es demasiado larga para una imagen; captúrala como varias tarjetas de altura de viewport
  2. 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í
  3. Subir: llama a upload_assets con nodeIds establecido en los slotIds 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. Si upload_assets no llena las ranuras, llámalo con currentPageId y count en 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
  4. Ejecuta screenshot-slots.js con SECTION_ID reemplazado, en la misma llamada use_figma que audit.js (paso 6): envuelve cada uno en una función asíncrona, llámalos en orden, luego await 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 devuelve placed, missing y skipped. Sube de nuevo para las tarjetas en missing
  5. 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

  1. Ejecuta ambos scripts de auditoría, reemplazando SECTION_ID con la sección de destino. Pega ambos en la misma llamada use_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.

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-library-binding

Bind Figma screens to a design system library — tokens only on exact value matches, swap icons and components for library versions, and list unmatched values for designers instead of snapping to the nearest token. Use when the user asks to "bind tokens", "use library components" or "find unbound colors". 把 Figma 畫面綁到專案的 design system library:顏色、圓角、邊框、間距、字級完全相同才綁 token,圖示和元件換成 library 版本,沒有對應的值列給設計決定,不取最近值。Use when 使用者要「綁 library」「綁 token」「換成 design system 元件」「檢查沒綁 variable 的顏色」,或 code-to-figma、figma-state-board 的畫面要綁 design system。

Skills relacionados