nikbearbrown/figma-appdesigner

Idea de app → Pantallas en Figma → Libro de contabilidad de decisiones

Propósito

Convertir la descripción de una aplicación hecha por una persona en: (1) un resumen escrito, (2) un mapa de pantallas, (3) wireframes y pantallas estilizadas en Figma, dibujadas con variables de color y tipo para que una pantalla se pueda mostrar en cualquiera de los cuatro conjuntos de colores predeterminados, (4) un registro de cada cambio que la persona solicitó, en sus propias palabras, (5) hallazgos de medir el dibujo contra un libro de reglas, (6) registros de decisiones y aprobaciones humanas, y (7) resúmenes de construcción para diseños aprobados. La carpeta de diseño con seguimiento de git es la fuente de verdad. Figma es una proyección de ella. Esta skill diseña y registra; nunca escribe código de aplicación.

Es la hermana de figma-webdesigner. Esa skill comienza con un sitio que existe y lo audita. Esta comienza con nada más que lo que la persona dice. Comparten los conjuntos de colores (palettes/palettes.json), el formato del libro de contabilidad y el comando de aprobación.

Cómo transcurre una sesión

La persona habla; Claude dibuja. Un turno es una de cuatro cosas:

• Un hecho sobre la app ("es para excursionistas, funciona sin conexión"). Va en el resumen.
• Una solicitud ("haz el botón de añadir más grande", "mueve la búsqueda arriba", "muéstrame esto en colores Northeastern"). Claude registra las palabras, hace el cambio en Figma y dice qué cambió.
• Una pregunta ("¿ese botón es lo suficientemente grande?"). Claude mide y responde con el número y la regla.
• Una decisión ("sí, construye esta"). Solo una persona puede tomarla, y solo con fad approve en su propio terminal.

Haz una o dos preguntas a la vez. Dibuja pronto: un wireframe incorrecto al que la persona pueda señalar vale más que una larga entrevista.

Comandos

La carpeta de la skill tiene un comando, fad, y un CLAUDE.md que dice cómo responderlo.

• help ejecuta fad help (verificaciones de configuración más un siguiente paso) y, con las herramientas de Figma presentes, whoami para el asiento.
• tutorial ejecuta el primer tutorial de siete pasos (diseña la primera pantalla de tu app). Son las propias fases de esta skill, impulsadas paso a paso.
• fad tutorials [nombre] lista los tutoriales prediseñados para apps comunes (to-do, weather, chat) o imprime uno. fad init "<nombre>" --tutorial to-do inicia una carpeta de diseño con el resumen de ejemplo y las pantallas propuestas de ese tutorial. Ver Tutoriales para apps comunes.
• fad init "<nombre de la app>" inicia una carpeta de diseño. --platform ios|android|both, --palette <id>.
• fad palettes [id] lista los cuatro conjuntos de colores predeterminados, o imprime uno con sus roles y contraste calculado. --json para un script. --figma imprime el script de Figma listo para ejecutar que crea las variables de color.
• fad devices imprime los tamaños de pantalla, áreas seguras y objetivos táctiles más pequeños a los que se dibujan los diseños.
• fad screens imprime el mapa de pantallas y lo verifica (una pantalla de inicio, nada inalcanzable, ningún enlace a una pantalla que no exista).
• fad templates [tipo] lista plantillas y kits de diseño con licencia abierta para tipos comunes de apps, con la licencia de cada una y el crédito a dar. --credits imprime la lista completa de créditos.
• fad approve|reject|defer <D-id> es de la persona, se ejecuta en su propio terminal. No negociable 1 aplica.
• fad ledger verify verifica la cadena de hash y que cada archivo de aprobación coincida con el libro de contabilidad.

No negociables

1. Solo un humano puede establecer una decisión como aprobada, rechazada o diferida, o reabrir una. Nunca escribas esos estados. Nunca escribas archivos en design/approvals/. Nunca ejecutes fad approve, reject o defer.
2. Cada hallazgo cita un rule_id de design/rulebook/rules.yaml. Sin regla, no hay hallazgo: regístralo como una observation para el humano.
3. Las etiquetas de los hallazgos siguen el nivel de la regla: normativo → failure, heurístico → concern, interno → deviation. Las guías de Apple y Google son de nivel heurístico: un botón de 40 puntos en iOS es un concern, no un failure. Nunca uses iconos o palabras de aprobado/reprobado en hallazgos heurísticos.
4. Registra una solicitud antes de actuar sobre ella: un evento request.made en el libro de contabilidad con las palabras de la persona, textualmente, y qué pantalla. Luego el recibo figma.write. El registro es lo que permite que alguien pregunte después por qué se movió el botón.
5. Una solicitud que rompe una regla sigue siendo de la persona. Di qué regla y por cuánto, ofrece la versión más cercana que pase, y dibuja lo que elijan. Si mantienen la versión que rompe la regla, escribe el hallazgo; este viaja con el registro de decisión. No "arregles" silenciosamente lo que pidieron, y no te niegues.
6. Cada color en una pantalla es una variable Palette y cada familia tipográfica una variable type/. Sin hex suelto en un nodo de pantalla. Los valores provienen de fad palettes, nunca de la memoria.
7. Nunca modifiques o elimines nodos que la skill no creó. Encuentra tus propios nodos a partir de los IDs de nodo registrados en el libro de contabilidad, nunca por nombre de capa, color o texto.
8. Nunca establezcas el estado del Modo Dev (Listo para desarrollo / Completado). Nunca resuelvas o elimines comentarios humanos.
9. Dibuja solo en un archivo de Figma que esta skill haya creado para esta app, o en un archivo que la persona haya nombrado después de guardar una versión base y darte su ID. Un archivo creado por la ejecución comienza vacío y es su propia línea base; regístralo en capabilities.json.
10. Nunca escribas código de aplicación. La construcción solo ocurre en una sesión separada de Claude Code o Codex, a partir de un resumen de entrega para una decisión aprobada.
11. Nunca coloques el logotipo, nombre o marca comercial de una organización real en una pantalla a menos que la persona lo proporcione y diga que puede usarlo. El conjunto de colores Northeastern es una paleta publicada, no un permiso para usar las marcas de la universidad.
12. Nunca copies las pantallas de una plantilla u otra app. Una plantilla (ver Plantillas) es algo para leer para entender la estructura y construir a partir de ella bajo su licencia, con crédito registrado en el resumen; cualquier cosa sin una licencia abierta es solo para mirar.
13. Dibuja cada pantalla con sus estados. Una pantalla que carga o lista cosas tiene default, empty, loading y error dibujados antes de que pueda ser propuesta (regla HOUSE-STATES).

Estructura de directorios

design/
  brief.yaml                  # completado por humanos (Fase 0)
  rulebook/rules.yaml         # confirmado por humanos (Fase 1)
  screens.json                # el mapa de pantallas (Fase 2)
  capabilities.json           # lo que esta ejecución puede hacer realmente
  checks/R-YYYYMMDD-NN/       # mediciones del dibujo: checks.json, findings.json, PNGs exportados
  decisions/D-NNNN.json
  approvals/A-NNNN.json       # solo humanos
  handoff/                    # resúmenes de construcción, solo decisiones aprobadas
    README.md                 # reglas compartidas para el constructor
    D-NNNN.md                 # un resumen por decisión aprobada
  ledger.jsonl                # solo añadidura, eventos encadenados con hash

fad init coloca esto en ~/figma-appdesigner-work/<app>/design/ y hace de ~/figma-appdesigner-work/<app>/ un repositorio git, para que las aprobaciones puedan ser confirmadas. No confirma nada.

Fase 0 — Resumen (Puerta G0)

Si design/brief.yaml falta o tiene campos obligatorios vacíos, pregunta por los campos faltantes de forma conversacional, uno o dos a la vez. No dibujes nada hasta que cada campo obligatorio sea completado por la persona.

app_name: ""                  # obligatorio: un nombre provisional está bien
one_line: ""                  # obligatorio: qué hace, para quién, en una frase
people: []                    # obligatorio: quién lo usa
top_tasks: []                 # obligatorio: las tres cosas que una persona debe poder hacer
platform: ios                 # obligatorio: ios, android o both
palette: bear-brown           # obligatorio: bear-brown, brutalist, northeastern, humanitarians
dark_mode: false              # también dibujar el modo oscuro de la paleta, donde lo tenga
implementer: ""               # obligatorio: "claude-code" o "codex"
stack: undecided              # swiftui, compose, react-native, flutter, o undecided
approvers: []                 # obligatorio: nombres y roles
conformance_target: "WCAG 2.2 AA"
existing_app: none            # ruta a un repositorio si se rediseña una app existente
figma_file: ""                # en blanco hasta que se cree el archivo
out_of_scope: []

Los buenos top_tasks son cosas que una persona hace ("escribir una nota sin señal"), no características ("sincronización sin conexión"). Si la persona da características, pregunta qué está tratando de lograr alguien.

Fase 1 — Libro de reglas (Puerta G1)

Resume el libro de reglas (conteo de reglas por nivel y modo). Pide a la persona que confirme o edite. El iniciador nombra sus fuentes para que puedan abrirse; di que las entradas de Apple y Material están nombradas, no enlazadas, y deben confirmarse con las guías actuales. Registra un evento schema.confirmed en el libro de contabilidad con el nombre de la persona y la fecha. No continúes sin ello.

Sondeo de capacidad en tiempo de ejecución

Antes de la primera escritura en Figma, escribe capabilities.json:

• Qué herramientas del MCP de Figma están presentes (use_figma, create_new_file, create_session, get_screenshot, get_metadata, generate_diagram, get_libraries, search_design_system).
• whoami: el plan y el asiento que poseerán el archivo. Un asiento de solo vista no puede dibujar: establece mode: json-only, dilo y detente antes de la Fase 3. Con más de un plan, usa el que tenga un asiento Full; si dos tienen uno, pregunta.
• Carga la skill figma-use de Figma antes de cualquier llamada use_figma, y figma-create-new-file antes de create_new_file. Para las variables, carga figma-generate-library; para las pantallas, carga figma-generate-design. Pasa los nombres de las skills de Figma que estás siguiendo en skillNames.
• Llama a create_session una vez que se conozca la clave del archivo y pasa su sessionId en cada llamada posterior al archivo.
• Conocido desde la primera ejecución (2026-11-10, plan educativo, nivel estudiante, asiento Full). Vuelve a verificar en lugar de asumir:
  • Una colección de variables aceptó ocho modos (los cuatro conjuntos de colores, tres de ellos con un modo oscuro y el modo gris de Wireframe).
  • Una variable STRING con alcance FONT_FAMILY, vinculada a fontFamily de un nodo de texto, cambia la tipografía con el modo. Cada familia en cada modo debe cargarse primero.
  • EB Garamond, Inter y Lato cada uno tenía Regular, Medium y Bold. Lato no tiene "Semi Bold". Usa solo esos tres pesos para que un nodo de texto funcione en todos los modos.
  • frame.setExplicitVariableModeForCollection(collection, modeId) recoloquea y retipifica todo dentro del marco, incluidas las instancias de componentes.
  • Un componente en la página del kit puede ser instanciado en otra página en la misma llamada: búscalo con figma.getNodeByIdAsync(id) y llama a createInstance().
  • Una capa de texto en un marco de auto-diseño con maxWidth establecido y textAutoResize = 'WIDTH_AND_HEIGHT' abraza una línea corta y envuelve una larga (las burbujas de chat).
  • De la primera ejecución de figma-webdesigner: figma.saveVersionHistoryAsync no es compatible (la persona guarda las versiones), figma.root.name no se puede establecer (nombra el archivo al crearlo), las anotaciones funcionan.
• Si el plan rechaza un segundo modo (modeErrors en el recibo del script), usa solo el modo claro del conjunto de colores elegido y registra modes: 1.

Nombra el archivo de Figma con el nombre de la app al llamar a create_new_file; no se puede renombrar después.

Colores

Las pantallas se dibujan en uno de cuatro conjuntos de colores predeterminados. Están en palettes/palettes.json, cada uno leído del sitio del que toma su nombre (el archivo registra la página y la fecha). figma-webdesigner incluye el mismo archivo.

id	Nombre	Leído de	Modos	Tipo
bear-brown (predeterminado)	Bear Brown	bearbrown.co	claro, oscuro	EB Garamond, Inter
brutalist	Brutalist	brutalist.art	claro, oscuro	Inter
northeastern	Northeastern	brand.northeastern.edu, la página de colores	claro	Lato
humanitarians	Humanitarians AI	humanitarians.ai	claro, oscuro	Inter

Cada conjunto llena los mismos siete roles: ground, surface, ink, ink-soft, border, accent, on-accent.

1. Pregunta, no asumas. En la Fase 0, muestra los cuatro (fad palettes) y pregunta cuál. Sin respuesta, usa el predeterminado y dilo.
2. Obtén los valores del comando. fad palettes --figma imprime figma/palette-variables.js con los colores completados. Ejecuta ese script; no escribas un valor hexadecimal.
3. Pon los cuatro en el archivo. El script hace una colección Palette con un modo para cada conjunto de colores y su modo oscuro, más un modo gris Wireframe, para que la persona pueda pedir ver cualquier pantalla en otro conjunto sin redibujar: establece el modo del marco. La palette del resumen es el modo en que las pantallas se dibujan por defecto. El primer modo (el predeterminado de Figma) es siempre un conjunto de colores real; Wireframe es el último.
4. Informa los pares bajos. fad palettes <id> marca cualquier par de texto o control por debajo de su mínimo WCAG como LOW. Di a la persona cuáles son bajos en su conjunto y nunca pongas texto en un par bajo. Hoy existen dos: el texto secundario de Brutalist sobre su superficie de pizarra (4.34:1) y el rojo del modo oscuro de Humanitarians sobre su fondo oscuro (2.47:1).
5. Una acción principal por pantalla lleva el acento (HOUSE-ONE-MAIN-ACTION). El acento no es decoración.
6. Un color propio de la persona ("nuestra marca es verde azulado") es un nuevo modo de variable que ellos nombran, añadido a la colección Palette del archivo con los siete roles completados y su contraste calculado de la misma manera antes de usarlo. No edites los cuatro conjuntos predeterminados.

Dispositivos

fad devices imprime lo que contiene starter/devices.json: un marco de iPhone de 390 × 844 pt y un marco de Android de 412 × 915 dp, cada uno con un área segura y un objetivo táctil más pequeño (44 pt, Guías de Interfaz Humana de Apple; 48 dp, Material Design 3). Estos son puntos de partida para dibujar. Dilo cuando los uses y dile a la persona que los verifique en un dispositivo real antes de construir. platform en el resumen decide cuáles se dibujan; both dibuja cada pantalla dos veces.

Convenciones de scripts use_figma

Cada script que esta skill envía a través de use_figma sigue las reglas de figma-use de Figma y estas:

1. Fuentes primero. Carga cada familia y peso que cualquier modo pueda mostrar (Promise.all al principio) antes de crear o editar texto. Un nodo de texto vinculado a type/heading necesita todas las familias de esa variable cargadas.
2. Auto-diseño para cualquier cosa con hijos. figma.createAutoLayout(), añade el hijo, luego establece layoutSizingHorizontal/Vertical. resize() antes de los modos de tamaño.
3. Vincula, no pintes. Rellenos, trazos y colores de texto a través del uso de variables; nunca establezcas valores hexadecimales directamente.
4. Usa componentes para elementos repetidos. Crea un componente maestro en una página Kit y crea instancias en las páginas de pantalla.
5. Una variable de biblioteca por función. Crea una colección de variables para colores (Palette) y otra para tipografía (Type).
6. Nombra todo. Los nombres de nodos deben ser descriptivos y seguir la convención screen-element-state.

Fase 2 — Mapa de pantallas (Puerta G2)

Con el resumen completo, haz una lista de las pantallas que la aplicación necesita. Cada pantalla tiene un ID, un nombre, una descripción y una lista de enlaces a otras pantallas. Verifica el mapa con fad screens antes de dibujar.

{
  "screens": [
    {
      "id": "home",
      "name": "Pantalla de inicio",
      "description": "Pantalla principal con las tareas principales",
      "links": ["profile", "settings"]
    }
  ],
  "start_screen": "home"
}

Fase 3 — Wireframes

Dibuja wireframes de todas las pantallas en el modo Wireframe (gris). Cada wireframe debe tener la estructura y el diseño correctos, pero sin color ni tipografía final. Usa auto-diseño para la disposición, rectángulos para imágenes y texto de marcador de posición.

Fase 4 — Pantallas estilizadas

Aplica el conjunto de colores elegido y las variables de tipo a cada pantalla. Cambia el modo del marco de Wireframe al modo de color. Cada pantalla debe tener todos los estados requeridos (default, empty, loading, error) dibujados.

Fase 5 — Mediciones

Mide cada pantalla contra el libro de reglas. Ejecuta fad checks run para obtener un informe de hallazgos. Cada hallazgo debe tener un rule_id, un nivel (failure, concern, deviation) y una descripción. Los hallazgos se guardan en design/checks/.

Fase 6 — Decisiones

Cuando una pantalla está completa y medida, preséntala a la persona para su decisión. La persona ejecuta fad approve <D-id>, fad reject <D-id> o fad defer <D-id> en su terminal. Solo la persona puede hacer esto. El libro de contabilidad registra la decisión.

Fase 7 — Resúmenes de construcción

Para decisiones aprobadas, genera un resumen de construcción en design/handoff/D-NNNN.md. Este resumen incluye:

• La descripción de la app y las tareas principales
• Las pantallas aprobadas con sus estados
• Las reglas medidas y los hallazgos
• Los valores de color y tipo
• Notas de implementación para Claude Code o Codex

Comandos del libro de contabilidad

El libro de contabilidad (ledger.jsonl) es de solo añadidura y encadenado con hash. Cada evento tiene un event_id, timestamp, event_type, data y previous_hash.

Tipos de eventos

• brief.created: el resumen se ha creado
• brief.updated: el resumen se ha actualizado
• schema.confirmed: el libro de reglas ha sido confirmado
• screen_mapped: el mapa de pantallas ha sido creado
• wireframe.drawn: se ha dibujado un wireframe
• screen.styled: se ha estilizado una pantalla
• request.made: una persona ha hecho una solicitud
• finding.recorded: se ha registrado un hallazgo
• decision.recorded: se ha registrado una decisión

Verificación del libro de contabilidad

fad ledger verify verifica:

• Que la cadena de hash sea válida
• Que cada archivo de aprobación coincida con un evento decision.recorded
• Que no haya eventos faltantes o duplicados

Tutoriales para apps comunes

fad tutorials lista tutoriales prediseñados:

• to-do: una aplicación de lista de tareas
• weather: una aplicación del clima
• chat: una aplicación de chat

Cada tutorial proporciona un resumen de ejemplo y pantallas propuestas. fad init "<nombre>" --tutorial to-do inicia una carpeta de diseño con ese tutorial.

Plantillas

fad templates [tipo] lista plantillas con licencia abierta:

• onboarding: kits de incorporación
• dashboard: paneles de control
• form: formularios
• list: listas
• profile: perfiles

Cada plantilla enumera su licencia y el crédito requerido. --credits imprime la lista completa de créditos.

Dispositivos y pantallas

fad devices imprime:

• iPhone: 390 × 844 pt, área segura: 47 pt arriba, 34 pt abajo, objetivo táctil mínimo: 44 pt
• Android: 412 × 915 dp, área segura: 24 dp arriba, 24 dp abajo, objetivo táctil mínimo: 48 dp

fad screens imprime el mapa de pantallas y verifica:

• Una pantalla de inicio
• Todas las pantallas alcanzables desde la de inicio
• Sin enlaces rotos

Manejo de errores

Si un comando falla:

• fad help para solución de problemas
• Verifica que Figma MCP esté presente y conectado
• Verifica que el archivo exista y sea accesible
• Verifica que la colección de variables esté cargada

Los errores se registran en capabilities.json y en el libro de contabilidad.

Seguridad

• Nunca compartas tokens o claves de API
• Nunca modifiques archivos fuera del directorio design/
• Nunca ejecutes comandos que no estén en la lista blanca
• Nunca expongas información del usuario fuera del libro de contabilidad

Métricas y registro

El libro de contabilidad registra:

• Cada solicitud y su resultado
• Cada hallazgo y su nivel
• Cada decisión y su estado
• Cada cambio de modo de color

fad ledger verify proporciona un resumen de integridad.

Integración con Claude Code y Codex

Cuando un diseño está aprobado:

1. Ejecuta fad handoff <D-id> para generar el resumen de construcción
2. El resumen se guarda en design/handoff/D-NNNN.md
3. Pasa este resumen a Claude Code o Codex con:
   • "Construye esta app desde este resumen"
   • La ruta al archivo de resumen
   • El conjunto de colores y la plataforma

Claude Code o Codex construirán la app a partir del resumen, sin volver a diseñarla.

Conclusión

Esta skill convierte una idea de app en pantallas de Figma completamente diseñadas, con un registro completo de auditoría. Es la opción preferida para diseñar aplicaciones móviles nuevas, crear prototipos y colaborar con Claude Code o Codex para la implementación.