@bacano/sdk 1.1.9 → 1.1.10

package/README.md

@@ -44,6 +44,42 @@ descubrimiento. `check` confirma que está vigente. Ninguno ejecuta la auditorí
 modifica el storefront ni despliega; esa revisión comienza únicamente cuando
 el usuario o agente invoca la skill.
 
+### Implementación desde Figma
+
+El SDK también incluye `bacano-figma-web`, la skill oficial para convertir un
+diseño Figma en una web informativa o tienda que conserve el cascarón, Static
+First y contratos públicos de Bacano:
+
+```bash
+pnpm exec bacano-figma-web install --agent all
+pnpm exec bacano-figma-web check
+pnpm exec bacano-figma-web doctor
+```
+
+Después invocarla como `$bacano-figma-web` en Codex, `/bacano-figma-web` en
+Claude Code o solicitar “usar Bacano Figma Web” en Antigravity. La skill guía la
+conexión al MCP remoto oficial, MCP local oficial de Figma Desktop, Desktop
+Bridge comunitario o REST autorizado. Prefiere siempre el MCP oficial y nunca
+guarda ni imprime tokens.
+
+`doctor` comprueba instalación, endpoint local, puertos del bridge y solamente
+la presencia del token REST. El OAuth del MCP remoto debe confirmarse dentro del
+agente con las herramientas de Figma. La extracción se conserva como snapshot
+normalizado. Cuando el equipo de Content y desarrollo trabajan en tiempos
+distintos, la skill genera un blueprint de entrega y permite fixtures locales
+con el mismo contrato de los componentes. Los tipos y entradas reales se crean
+desde Bacano; un fixture activo bloquea la aprobación de producción.
+
+El snapshot puede validarse con:
+
+```bash
+pnpm exec bacano-figma-web validate-snapshot .bacano/designs/<proyecto>/manifest.json
+```
+
+Las instrucciones completas viajan dentro de
+`skills/bacano-figma-web/references/`; no es necesario copiar documentación ni
+crear integraciones particulares en cada storefront.
+
 Every storefront must follow [`STOREFRONT_MARKETING.md`](./STOREFRONT_MARKETING.md)
 when instrumenting analytics, advertising signals, contact actions, ecommerce
 events, attribution, or preview behavior. It is the canonical implementation

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@bacano/sdk",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "TypeScript SDK for building websites on the Bacano ERP",
   "main": "./index.cjs",
   "module": "./index.js",
   "types": "./index.d.ts",
   "bin": {
+    "bacano-figma-web": "./skills/bacano-figma-web/scripts/cli.mjs",
     "bacano-web": "./skills/bacano-web/scripts/cli.mjs"
   },
   "scripts": {

package/skills/bacano-figma-web/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: bacano-figma-web
+description: Convierte diseños de Figma en webs y tiendas construidas con @bacano/sdk, preservando el cascarón, contratos, Static First y comportamiento oficial de Bacano. Usar al implementar una web desde enlaces, frames o archivos Figma; configurar o diagnosticar Figma MCP, Figma Desktop MCP, Desktop Bridge o REST; extraer un diseño por páginas; mapearlo a Content y componentes; o comparar visualmente la implementación con Figma.
+---
+
+# Bacano Figma Web
+
+Implementar Figma como fuente visual y Bacano como fuente funcional. No copiar
+una captura como HTML aislado ni reconstruir catálogo, carrito, checkout,
+autenticación, marketing o Content por fuera de `@bacano/sdk`.
+
+## 1. Confirmar el alcance
+
+Antes de extraer el diseño, identificar:
+
+- Web informativa o tienda virtual.
+- Enlace al archivo, página, sección o frame de Figma.
+- Rutas que se implementarán y sus frames desktop/mobile.
+- Repositorio y cascarón Bacano que se reutilizarán.
+- Fuente Figma disponible y política de fallback.
+
+Si falta una decisión que cambie materialmente el resultado, hacer una sola
+pregunta corta. No solicitar un token por chat ni pedir que se guarde en el
+repositorio.
+
+## 2. Resolver la conexión con Figma
+
+Ejecutar primero:
+
+```bash
+pnpm exec bacano-figma-web doctor
+```
+
+Leer [references/connection-official.md](references/connection-official.md) si
+falta instalar o autenticar el MCP oficial. Usar este orden:
+
+1. MCP remoto oficial de Figma.
+2. MCP local oficial de Figma Desktop.
+3. Desktop Bridge comunitario, local y con versión revisada/fijada.
+4. Snapshot mediante REST, únicamente con autorización explícita.
+
+No cambiar silenciosamente de fuente. Si la fuente seleccionada se agota,
+responde `429` o no expone una capacidad necesaria, conservar el avance y pedir
+permiso antes del fallback, salvo que el usuario haya aprobado modo automático.
+Leer la guía específica únicamente cuando se elija
+[Desktop Bridge](references/connection-desktop-bridge.md) o
+[REST](references/connection-rest-api.md).
+
+## 3. Extraer una vez y normalizar
+
+Leer [references/extraction-contract.md](references/extraction-contract.md).
+Crear o reutilizar un snapshot normalizado en `.bacano/designs/<proyecto>/`.
+No consultar cada sección por separado si una lectura de página/frame entrega
+el contexto suficiente.
+
+Evaluar y registrar como `DISPONIBLE`, `PARCIAL` o `AUSENTE`:
+
+- Variables y estilos.
+- Componentes y variantes.
+- Auto Layout, constraints y geometría.
+- Nombres de capas.
+- Frames desktop/mobile.
+- Estados e interacciones.
+
+La ausencia de variables o componentes no bloquea por sí sola. Inferir desde
+geometría y evidencia visual, pero registrar cada inferencia. Nunca incluir PAT,
+cookies, secretos, correos privados ni contenido no necesario en el snapshot.
+
+Validar el manifiesto:
+
+```bash
+pnpm exec bacano-figma-web validate-snapshot .bacano/designs/<proyecto>/manifest.json
+```
+
+## 4. Mapear a Bacano antes de programar
+
+Leer [references/bacano-mapping.md](references/bacano-mapping.md) y
+[references/content-workflow.md](references/content-workflow.md). Preparar una
+matriz ruta → frame → componente → fuente de datos → estado responsive y
+determinar si el trabajo comienza desde Figma, desde Bacano Content o desde
+ambas fuentes.
+
+- Reutilizar el starter, tokens y componentes existentes.
+- Consumir Bacano y Content mediante `@bacano/sdk`.
+- Mantener un solo `BacanoProvider` y un solo cliente por árbol.
+- Preservar Static First: estructura estática y estado comercial vivo mediante
+  los contratos específicos del SDK.
+- No usar GraphQL directo, endpoints internos ni lógica comercial duplicada.
+- No codificar textos editables si pertenecen a Bacano Content.
+- No alterar Baby Rex u otra referencia salvo que ese sea el proyecto indicado.
+
+Si Content todavía no existe, generar un blueprint de entrega y fixtures
+temporales fieles al contenido visible de Figma. Los fixtures deben usar el
+mismo view model que consumen los componentes y entrar por un único adaptador;
+nunca repartir datos de prueba dentro de la UI. Si Content ya existe, mapearlo
+sin sobrescribir estructuras o entradas. En esta versión la skill no crea ni
+modifica contenido en Bacano: esas acciones permanecen en el backoffice y
+requieren autorización independiente.
+
+Antes de modificar código, indicar brevemente qué rutas y componentes se
+implementarán y qué decisiones de diseño son inferidas.
+
+## 5. Implementar por cortes verificables
+
+Trabajar por página o conjunto pequeño de secciones:
+
+1. Estructura semántica y responsive.
+2. Tokens, tipografía, espacios y media.
+3. Estados interactivos y accesibilidad.
+4. Integración Bacano real.
+5. Comparación visual y correcciones.
+
+No añadir paquetes, fuentes, iconos o assets si el proyecto ya ofrece un
+equivalente. Descargar assets mediante la fuente Figma autorizada; no incrustar
+URLs temporales ni construir transformaciones de Storage manualmente.
+
+## 6. Validar diseño y contrato
+
+Leer [references/visual-validation.md](references/visual-validation.md).
+Comparar con evidencia desktop y mobile, incluyendo viewport, captura y
+diferencias relevantes. Probar además typecheck, lint, tests y build del
+proyecto.
+
+Antes de aprobar producción, comprobar que la fuente editorial efectiva sea
+Bacano Content. Un fixture, placeholder o fallback temporal accesible en el
+build de producción es un bloqueo, aunque visualmente coincida con Figma.
+
+Al finalizar, invocar `$bacano-web` si está disponible para la auditoría de
+producción completa. Esta skill valida fidelidad y correcta integración desde
+Figma; `bacano-web` valida que el sitio pueda publicarse profesionalmente.
+
+## 7. Entregar un cierre claro
+
+Reportar:
+
+- Fuente Figma y fallback usados.
+- Páginas/frames extraídos e implementados.
+- Snapshot y versión/fecha de extracción.
+- Componentes Bacano reutilizados.
+- Inferencias y diferencias aprobadas.
+- Validaciones ejecutadas y pendientes reales.
+- Brechas del SDK, sin workarounds directos a API o GraphQL.

package/skills/bacano-figma-web/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bacano Figma Web"
+  short_description: "Convierte diseños Figma en sitios Bacano"
+  default_prompt: "Usa $bacano-figma-web para implementar este diseño de Figma con el cascarón y los contratos oficiales de Bacano."

package/skills/bacano-figma-web/references/bacano-mapping.md

@@ -0,0 +1,38 @@
+# Mapeo de Figma a Bacano
+
+Figma decide presentación. Bacano decide datos, permisos, estados y reglas de
+negocio.
+
+## Matriz obligatoria
+
+Antes de programar, registrar por ruta:
+
+| Ruta | Frame | Componente | Fuente | Responsive | Estado |
+| --- | --- | --- | --- | --- | --- |
+| `/` | Home desktop/mobile | `Hero` | Content | 2 frames | pendiente |
+
+Fuentes posibles: Content, catálogo estático, live state, public config,
+checkout, auth u otra operación documentada del SDK.
+
+## Reglas
+
+- Usar componentes y tokens existentes antes de crear otros.
+- Mapear textos/imágenes editoriales a Content cuando deban ser administrables.
+- Si el equipo de Content y desarrollo trabajan en tiempos distintos, seguir
+  [content-workflow.md](content-workflow.md) y mantener un único contrato de
+  datos entre fixtures temporales y Bacano real.
+- Usar `responsiveSources` y helpers oficiales para media; no construir URLs de
+  Storage manualmente.
+- Mantener HTML semántico, canonical, metadata, JSON-LD y sitemap.
+- En tiendas, conservar rutas de producto y `product_variant_id` definidos por
+  el contrato del SDK.
+- La estructura del catálogo puede venir del build; precio, disponibilidad y
+  límites se actualizan con live state/cart oficial.
+- Montar proveedores globales una sola vez.
+- Preview reutiliza los mismos componentes y cliente; no crear un storefront
+  paralelo para “parecerse” a Figma.
+- Marketing se emite mediante el runtime/hook oficial, nunca desde clicks
+  duplicados escritos solo para una página.
+
+Si el SDK no ofrece una capacidad, documentar la brecha. No llamar GraphQL o
+endpoints internos como workaround.

package/skills/bacano-figma-web/references/connection-desktop-bridge.md

@@ -0,0 +1,45 @@
+# Desktop Bridge comunitario
+
+“Figma Desktop Bridge” no es el MCP local oficial de Figma. Esta guía se refiere
+al bridge incluido por el proyecto comunitario `southleft/figma-console-mcp`,
+que conecta un plugin de Figma Desktop con su servidor MCP.
+
+Usarlo solo cuando el MCP oficial no exponga datos locales necesarios, por
+ejemplo determinadas variables o descripciones accesibles mediante Plugin API.
+
+## Reglas de seguridad
+
+- Preferir modo local.
+- Revisar el repositorio y fijar una versión o commit aprobado; no depender de
+  `@latest` en automatizaciones reproducibles.
+- Mantener Figma Desktop abierto y el plugin activo durante la extracción.
+- No exponer ni redirigir a Internet los puertos locales `9223`–`9232`.
+- Guardar el PAT en el almacén de secretos o entorno del cliente MCP, nunca en
+  `.mcp.json`, el repositorio, el snapshot o los logs.
+- No habilitar cloud relay o escritura sin autorización explícita.
+
+## Instalación orientativa
+
+El proyecto upstream publica instrucciones actualizadas en:
+
+- https://github.com/southleft/figma-console-mcp
+- https://github.com/southleft/figma-console-mcp/blob/main/figma-desktop-bridge/README.md
+
+Seguir la versión revisada de esas instrucciones para:
+
+1. Instalar/configurar el servidor MCP comunitario.
+2. Importar el manifest del plugin generado por el servidor.
+3. Abrir el plugin dentro del archivo Figma.
+4. Confirmar la conexión local del bridge.
+5. Ejecutar una lectura mínima antes de extraer todas las páginas.
+
+El comando `pnpm exec bacano-figma-web doctor` solo detecta puertos locales
+compatibles. No demuestra que el plugin esté conectado, que el archivo sea el
+correcto ni que el servidor sea confiable; esas tres condiciones deben
+verificarse dentro del agente.
+
+## Salida esperada
+
+Normalizar la respuesta del bridge al mismo manifiesto definido en
+`extraction-contract.md`. No permitir que detalles propios del bridge se filtren
+a los componentes React ni a los contratos públicos de Bacano.

package/skills/bacano-figma-web/references/connection-official.md

@@ -0,0 +1,127 @@
+# Conexión oficial con Figma
+
+Elegir preferiblemente el MCP remoto oficial. Requiere autorización de la
+cuenta Figma, pero no mantener Figma Desktop abierto.
+
+## MCP remoto oficial
+
+Endpoint oficial:
+
+```text
+https://mcp.figma.com/mcp
+```
+
+### Codex CLI
+
+```bash
+codex mcp add figma --url https://mcp.figma.com/mcp
+```
+
+Completar OAuth cuando Codex lo solicite. En la aplicación Codex también puede
+instalarse/conectarse el plugin oficial de Figma desde Plugins.
+
+### Claude Code
+
+Figma recomienda primero su plugin oficial:
+
+```bash
+claude plugin install figma@claude-plugins-official
+```
+
+Configuración manual equivalente:
+
+```bash
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+Usar `--scope user` únicamente si la conexión debe estar disponible en todos
+los proyectos de ese usuario.
+
+### VS Code y clientes MCP compatibles
+
+```json
+{
+  "inputs": [],
+  "servers": {
+    "figma": {
+      "url": "https://mcp.figma.com/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+No copiar tokens dentro del archivo. El cliente debe realizar OAuth.
+
+### Cursor
+
+Figma recomienda instalar su plugin oficial desde el chat del agente:
+
+```text
+/add-plugin figma
+```
+
+En otros agentes, comprobar primero que aparezcan en el catálogo de clientes
+admitidos por Figma. No asumir que cualquier cliente MCP puede completar el
+OAuth del servidor remoto.
+
+## MCP local oficial de Figma Desktop
+
+Usarlo cuando se necesite trabajar con la selección actual del archivo o el MCP
+remoto no sea apropiado para la organización.
+
+1. Actualizar y abrir Figma Desktop.
+2. Abrir un archivo Design.
+3. Activar Dev Mode con `Shift+D`.
+4. En el panel Inspect, habilitar Desktop MCP.
+5. Mantener Figma Desktop y el archivo abiertos.
+
+Endpoint local:
+
+```text
+http://127.0.0.1:3845/mcp
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+```
+
+Configuración genérica:
+
+```json
+{
+  "servers": {
+    "figma-desktop": {
+      "url": "http://127.0.0.1:3845/mcp",
+      "type": "http"
+    }
+  }
+}
+```
+
+## Verificación dentro del agente
+
+La CLI de Bacano no puede inspeccionar el registro MCP ni el OAuth privado de
+todos los agentes. Dentro de la conversación, comprobar:
+
+1. Que exista una herramienta Figma disponible.
+2. Ejecutar `whoami` cuando el servidor la exponga.
+3. Leer un frame pequeño mediante su enlace exacto.
+4. Confirmar que el agente recibe contexto de diseño, no solo una captura.
+
+El servidor remoto trabaja mediante un enlace exacto al frame/capa. La
+selección actual sin enlace está disponible únicamente con el servidor Desktop.
+
+Según Figma, los límites dependen del plan y asiento. Actualmente un asiento Dev
+o Full en Professional admite hasta 200 lecturas diarias y 10 por minuto; Figma
+puede modificar esos límites. Ante `429`, conservar el snapshot y reanudar
+después, sin repetir nodos ya extraídos.
+
+Fuentes oficiales:
+
+- https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/
+- https://developers.figma.com/docs/figma-mcp-server/local-server-installation/
+- https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/
+- https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/

package/skills/bacano-figma-web/references/connection-rest-api.md

@@ -0,0 +1,35 @@
+# REST API como respaldo
+
+Usar REST solamente cuando el usuario autorice crear un snapshot y el MCP
+oficial/Desktop/Bridge no estén disponibles. REST entrega datos más crudos y no
+reemplaza el contexto preparado por `get_design_context`.
+
+## Autenticación
+
+Figma admite OAuth y personal access tokens. Para una tarea local controlada,
+inyectar el token mediante el entorno del proceso:
+
+```bash
+export FIGMA_ACCESS_TOKEN="..."
+```
+
+No escribirlo en `.env` versionado, argumentos de terminal persistidos,
+manifiestos, código cliente, capturas o registros. `doctor` informa únicamente
+si la variable existe; nunca lee ni muestra su valor.
+
+## Extracción responsable
+
+1. Obtener el file key desde el enlace autorizado.
+2. Consultar solo páginas/nodos necesarios.
+3. Registrar versión/fecha del archivo en el snapshot.
+4. Descargar imágenes/assets una vez y conservar su procedencia.
+5. Respetar `429` y encabezados de espera; no crear reintentos agresivos.
+6. No guardar el JSON completo si contiene páginas ajenas al alcance.
+
+El snapshot resultante debe seguir `extraction-contract.md`. Nunca incluir el
+token ni URLs firmadas temporales como contrato permanente.
+
+Fuentes oficiales:
+
+- https://developers.figma.com/docs/rest-api/authentication/
+- https://developers.figma.com/docs/rest-api/rate-limits/

package/skills/bacano-figma-web/references/content-workflow.md

@@ -0,0 +1,158 @@
+# Flujo de contenido entre Figma, desarrollo y Bacano
+
+Diseño, programación y gestión editorial pueden comenzar en cualquier orden.
+La coordinación se hace mediante un blueprint de contenido; Figma no se
+convierte en base de datos y los componentes no dependen de datos temporales.
+
+## 1. Clasificar la propiedad de cada dato
+
+Antes de crear campos o fixtures, asignar cada valor a una fuente:
+
+| Información | Fuente habitual |
+| --- | --- |
+| Títulos, textos, banners y bloques editoriales | Bacano Content |
+| Productos, variantes, precios y disponibilidad | Catálogo y live state del SDK |
+| Legal, branding y configuración del sitio | `publicConfig` |
+| Carrito, checkout, cliente y pedidos | Módulo correspondiente del SDK |
+| Etiquetas permanentes de interfaz | Código e i18n del storefront |
+
+No duplicar en Content información que ya tiene una fuente funcional. Un valor
+visible en Figma no implica que sea editorial.
+
+## 2. Elegir el punto de partida
+
+### Figma primero
+
+1. Extraer el contenido público visible y sus assets autorizados.
+2. Proponer tipos, keys, campos y entradas en `content-blueprint.json`.
+3. Crear fixtures locales que implementen el view model de la página.
+4. Implementar y validar el diseño contra esos fixtures.
+5. Entregar el blueprint al equipo de Content para crearlo en Bacano.
+6. Conectar las keys reales sin modificar los componentes visuales.
+
+### Bacano Content primero
+
+1. Inventariar tipos, campos, keys y entradas existentes mediante contratos
+   públicos documentados.
+2. Mapear los frames de Figma al contenido real.
+3. Señalar incompatibilidades de estructura antes de programar.
+4. Reutilizar las keys existentes; no crear aliases o estructuras paralelas
+   únicamente para hacer coincidir un frame.
+
+### Fuentes en paralelo
+
+Comparar el blueprint propuesto con Bacano. Clasificar cada sección como
+`ready`, `missing`, `needs-mapping` o `blocked` y asignar responsable. No
+sobrescribir datos reales ni asumir que el diseño más reciente autoriza una
+migración editorial.
+
+## 3. Blueprint de entrega
+
+Guardar el archivo junto al snapshot:
+
+```text
+.bacano/designs/<proyecto>/content-blueprint.json
+```
+
+Estructura recomendada:
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "mi-storefront",
+  "source": "figma",
+  "routes": [
+    {
+      "route": "/",
+      "sections": [
+        {
+          "sectionKey": "home-hero",
+          "figmaNodeId": "1:20",
+          "component": "HomeHero",
+          "ownership": "content",
+          "contentTypeKey": "home_hero",
+          "entryKey": "home-main-hero",
+          "status": "missing",
+          "fields": [
+            {
+              "key": "title",
+              "type": "text",
+              "required": true,
+              "sampleValue": "Compra para cada etapa"
+            }
+          ],
+          "fixture": "fixtures/home-hero.json"
+        }
+      ]
+    }
+  ]
+}
+```
+
+El blueprint es una propuesta y una evidencia de coordinación, no una orden de
+escritura. No incluir IDs internos innecesarios, secretos, datos personales ni
+respuestas crudas de GraphQL. Mantener keys estables y registrar cambios que
+rompan el contrato.
+
+## 4. Fixtures temporales
+
+- Usar contenido real del diseño cuando esté disponible; evitar Lorem ipsum.
+- Guardarlos en un único directorio y cargarlos mediante un adaptador explícito.
+- Hacer que implementen el view model que consumen los componentes, no una
+  copia inventada de respuestas GraphQL ni de internals del SDK.
+- Mantener el mapper de Bacano separado: `Content` real y fixture deben terminar
+  en el mismo view model.
+- Incluir estados vacío, incompleto y contenido largo en pruebas separadas; no
+  convertirlos en el contenido principal de la página.
+- No crear fixtures para precios, stock, autenticación, carrito, checkout,
+  pedidos o atribución.
+
+Una forma válida de separación es:
+
+```text
+fixture ───────┐
+               ├─> PageContentViewModel ─> componentes
+Bacano mapper ─┘
+```
+
+El cambio de fuente debe ocurrir en el loader o repositorio de contenido, nunca
+mediante condicionales repartidos por los componentes.
+
+## 5. Entrega al equipo de Content
+
+Entregar una tabla legible con:
+
+- Ruta y sección visible.
+- Tipo y entry key sugeridos.
+- Campos, tipo, obligatoriedad y ejemplo tomado de Figma.
+- Assets desktop/mobile, proporción y uso esperado.
+- Estado y responsable.
+- Dependencias entre componentes, listas y entradas.
+
+El equipo de Content crea o ajusta la estructura desde Bacano. En esta versión
+la skill no ejecuta escrituras, importaciones ni cargas de media en Bacano. Si
+la creación real es necesaria para continuar, solicitar confirmación al usuario
+en vez de simular que ocurrió.
+
+## 6. Cambio a Bacano real
+
+Antes de retirar el fixture:
+
+1. Confirmar que las keys reales coinciden con el blueprint.
+2. Validar campos requeridos, media y contenido largo.
+3. Comparar la página con Figma usando Content real.
+4. Verificar preview si la capacidad está activa.
+5. Eliminar el fixture del camino de ejecución, no necesariamente de los tests.
+
+En producción no se permite fallback silencioso a fixtures. Si una página
+depende de contenido temporal, reportar `❌ NO LISTO` con las rutas y secciones
+afectadas. Los fixtures pueden conservarse como datos de pruebas unitarias o
+visuales siempre que no entren en el bundle o loader de producción.
+
+## 7. Automatización futura
+
+La creación automática debe pertenecer a una herramienta administrativa
+separada del SDK público del storefront. Requiere autenticación con alcance por
+empresa/website, previsualización de cambios, idempotencia, auditoría y
+confirmación antes de escribir. Nunca exponer esas credenciales en el navegador
+ni convertir el blueprint en una importación implícita.

package/skills/bacano-figma-web/references/extraction-contract.md

@@ -0,0 +1,102 @@
+# Contrato de extracción normalizado
+
+Cada fuente Figma debe producir el mismo checkpoint para que cambiar de MCP a
+Desktop o REST no obligue a rehacer la implementación.
+
+## Estructura sugerida
+
+```text
+.bacano/designs/<proyecto>/
+├── manifest.json
+├── tokens.json
+├── content-blueprint.json
+├── fixtures/
+├── assets/
+└── screenshots/
+```
+
+`content-blueprint.json` y `fixtures/` son necesarios únicamente cuando el
+diseño contiene información editorial que todavía no existe o no está lista en
+Bacano. Su contrato se define en
+[content-workflow.md](content-workflow.md). No crear fixtures para catálogo,
+precios, inventario, checkout, identidad ni otras fuentes funcionales del SDK.
+
+No modificar `.gitignore` automáticamente. Preguntar o seguir la política del
+proyecto antes de versionar imágenes o archivos grandes.
+
+Una política opcional, sin secretos, puede guardarse en
+`.bacano/designs/config.json`:
+
+```json
+{
+  "preferredSource": "figma-official",
+  "fallbackSources": [
+    "figma-desktop",
+    "desktop-bridge",
+    "rest-snapshot"
+  ],
+  "fallbackMode": "ask",
+  "reuseCachedExtraction": true
+}
+```
+
+`fallbackMode` debe ser `ask` por defecto. Usar `auto` únicamente cuando el
+usuario haya autorizado expresamente todas las fuentes declaradas.
+
+## Manifiesto mínimo
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "mi-storefront",
+  "source": {
+    "adapter": "figma-official",
+    "fileKey": "opcional",
+    "fileVersion": "opcional",
+    "extractedAt": "2026-08-24T12:00:00.000Z"
+  },
+  "capabilities": {
+    "variables": "partial",
+    "components": "available",
+    "autoLayout": "available",
+    "responsiveFrames": "partial",
+    "interactions": "partial"
+  },
+  "pages": [
+    {
+      "route": "/",
+      "name": "Home",
+      "status": "extracted",
+      "desktop": { "nodeId": "1:2", "url": "https://figma.com/..." },
+      "mobile": { "nodeId": "1:3", "url": "https://figma.com/..." }
+    }
+  ],
+  "assumptions": []
+}
+```
+
+Valores de `adapter`:
+
+- `figma-official`: MCP remoto oficial.
+- `figma-desktop`: MCP local oficial.
+- `desktop-bridge`: bridge comunitario.
+- `rest-snapshot`: REST autorizado.
+
+Capacidades: `available`, `partial` o `missing`.
+Estado de página: `pending`, `extracted`, `implemented` o `validated`.
+
+Cada página requiere `route`, `name`, `status` y al menos un frame desktop o
+mobile con `nodeId` o `url`. No guardar secretos ni respuestas MCP completas.
+
+## Estrategia de consultas
+
+- Obtener metadata suficiente para construir el mapa de páginas.
+- Extraer cada frame principal una vez.
+- Solicitar subnodos solo si el contexto principal es incompleto.
+- Reutilizar tokens/assets comunes entre páginas.
+- Al reanudar, comparar `fileVersion` y repetir únicamente nodos cambiados.
+- Conservar las inferencias en `assumptions` para revisión humana.
+
+Para sitios medianos, una extracción organizada suele requerir decenas de
+lecturas, no una consulta por cada capa. La cifra exacta depende de la calidad y
+estructura del archivo, no únicamente del número de páginas.

package/skills/bacano-figma-web/references/visual-validation.md

@@ -0,0 +1,39 @@
+# Validación visual y funcional
+
+Validar por cortes para evitar corregir 70 secciones al final.
+
+## Evidencia mínima por página
+
+- URL/ruta implementada.
+- Frame y node ID de referencia.
+- Viewport desktop y mobile utilizados.
+- Captura de referencia y captura de implementación.
+- Diferencias intencionales e inferencias.
+- Resultado de accesibilidad/interacción aplicable.
+
+## Orden de revisión
+
+1. Estructura, jerarquía y contenido.
+2. Breakpoints, anchuras y flujo responsive.
+3. Tipografía, color, espacios y radios.
+4. Imágenes, recortes, densidad y estado de carga.
+5. Hover, focus, teclado, formularios y navegación.
+6. Estados loading, vacío, error y contenido largo.
+7. Integración Bacano y ausencia de datos inventados.
+8. Contenido editorial real o fixture temporal claramente identificado.
+
+Usar Playwright o la herramienta de navegador disponible para capturas y
+traces. Una comparación pixel a pixel puede ayudar, pero no debe ocultar fallos
+semánticos o funcionales.
+
+## Cierre técnico
+
+- Typecheck, lint, tests y build del proyecto.
+- Rutas generadas y sitemap esperado.
+- Sin errores de consola/recurso.
+- Sin GraphQL directo ni solicitudes duplicadas evitables.
+- HTML estático presente cuando el contrato es Static First.
+- Media responsive sin upscale visible.
+- Ningún fixture, placeholder o fallback editorial temporal en el build de
+  producción.
+- `$bacano-web` ejecutado al final cuando corresponda.

package/skills/bacano-figma-web/scripts/cli.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { connect } from "node:net";
+import { dirname, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { validateSnapshot } from "./snapshot.mjs";
+
+const skillName = "bacano-figma-web";
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+const sourceSkill = resolve(scriptDirectory, "..");
+const projectRoot = process.cwd();
+const canonicalSkill = resolve(projectRoot, ".agents", "skills", skillName);
+
+const adapterPaths = {
+  antigravity: canonicalSkill,
+  claude: resolve(projectRoot, ".claude", "skills", skillName),
+  codex: resolve(projectRoot, ".codex", "skills", skillName),
+};
+
+function usage() {
+  console.log(`Bacano Figma Web
+
+Uso:
+  bacano-figma-web install [--agent antigravity|claude|codex|all] [--force]
+  bacano-figma-web check
+  bacano-figma-web doctor [--json]
+  bacano-figma-web validate-snapshot <ruta/manifest.json>
+
+La copia canónica vive en .agents/skills/${skillName}.
+Claude y Codex reciben enlaces a esa misma copia.`);
+}
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+function relativeDisplay(path) {
+  const value = relative(projectRoot, path);
+  return value || ".";
+}
+
+function listFiles(directory, base = directory) {
+  return readdirSync(directory, { withFileTypes: true })
+    .flatMap((entry) => {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) return listFiles(path, base);
+      if (!entry.isFile()) return [];
+      return [{ path, name: relative(base, path) }];
+    })
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function skillDigest(directory) {
+  const hash = createHash("sha256");
+  for (const file of listFiles(directory)) {
+    hash.update(file.name);
+    hash.update("\0");
+    hash.update(readFileSync(file.path));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function isSkillDirectory(directory) {
+  return existsSync(resolve(directory, "SKILL.md"));
+}
+
+function removeExisting(path, force) {
+  if (!existsSync(path)) return;
+  if (!force) {
+    throw new Error(
+      `${relativeDisplay(path)} ya existe. Usa --force para reemplazarlo.`,
+    );
+  }
+  rmSync(path, { recursive: true, force: true });
+}
+
+function installCanonical(force) {
+  if (resolve(sourceSkill) === canonicalSkill) return;
+
+  if (isSkillDirectory(canonicalSkill)) {
+    if (skillDigest(canonicalSkill) === skillDigest(sourceSkill)) return;
+    removeExisting(canonicalSkill, force);
+  } else if (existsSync(canonicalSkill)) {
+    removeExisting(canonicalSkill, force);
+  }
+
+  mkdirSync(dirname(canonicalSkill), { recursive: true });
+  cpSync(sourceSkill, canonicalSkill, { recursive: true });
+}
+
+function installAdapter(agent, force) {
+  const target = adapterPaths[agent];
+  if (!target || target === canonicalSkill) return;
+
+  if (existsSync(target)) {
+    const stat = lstatSync(target);
+    if (stat.isSymbolicLink()) {
+      const resolvedLink = resolve(dirname(target), readlinkSync(target));
+      if (resolvedLink === canonicalSkill) return;
+    }
+    removeExisting(target, force);
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  const targetReference =
+    process.platform === "win32"
+      ? canonicalSkill
+      : relative(dirname(target), canonicalSkill);
+  symlinkSync(
+    targetReference,
+    target,
+    process.platform === "win32" ? "junction" : "dir",
+  );
+}
+
+async function chooseAgent() {
+  const explicit = option("--agent");
+  if (explicit) return explicit;
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      "Indica --agent antigravity, --agent claude, --agent codex o --agent all.",
+    );
+  }
+
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const answer = await prompt.question(
+    "¿Qué agente usará la skill? [1] Antigravity [2] Claude Code [3] Codex [4] Todos: ",
+  );
+  prompt.close();
+
+  return (
+    { 1: "antigravity", 2: "claude", 3: "codex", 4: "all" }[answer.trim()] ??
+    answer.trim().toLowerCase()
+  );
+}
+
+function validateAgent(agent) {
+  if (!["antigravity", "claude", "codex", "all"].includes(agent)) {
+    throw new Error(`Agente no reconocido: ${agent || "(vacío)"}.`);
+  }
+}
+
+async function installSkill() {
+  const agent = await chooseAgent();
+  validateAgent(agent);
+  const force = process.argv.includes("--force");
+
+  installCanonical(force);
+  if (agent === "all") {
+    installAdapter("claude", force);
+    installAdapter("codex", force);
+  } else {
+    installAdapter(agent, force);
+  }
+
+  console.log("Skill Bacano Figma Web instalada.");
+  console.log(`Fuente canónica: ${relativeDisplay(canonicalSkill)}`);
+  if (agent === "claude" || agent === "all") {
+    console.log(`Claude Code: ${relativeDisplay(adapterPaths.claude)}`);
+  }
+  if (agent === "codex" || agent === "all") {
+    console.log(`Codex: ${relativeDisplay(adapterPaths.codex)}`);
+  }
+  console.log("Ejecuta bacano-figma-web doctor para revisar la conexión.");
+}
+
+function checkPath(name, path) {
+  if (!existsSync(path)) {
+    return { name, path: relativeDisplay(path), status: "missing" };
+  }
+  if (!isSkillDirectory(path)) {
+    return { name, path: relativeDisplay(path), status: "invalid" };
+  }
+  return {
+    name,
+    path: relativeDisplay(path),
+    status:
+      skillDigest(path) === skillDigest(sourceSkill) ? "current" : "outdated",
+    link: lstatSync(path).isSymbolicLink(),
+  };
+}
+
+function skillStatus() {
+  const results = [
+    checkPath("canonical", canonicalSkill),
+    checkPath("antigravity", adapterPaths.antigravity),
+    checkPath("claude", adapterPaths.claude),
+    checkPath("codex", adapterPaths.codex),
+  ];
+  return results.filter(
+    (result, index) =>
+      results.findIndex((candidate) => candidate.path === result.path) ===
+      index,
+  );
+}
+
+function check() {
+  const results = skillStatus();
+  console.table(results);
+  if (results[0]?.status !== "current") {
+    console.error(
+      "Bacano Figma Web no está instalada o está desactualizada. Ejecuta bacano-figma-web install.",
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (results.slice(1).some((result) => result.link === false)) {
+    console.warn(
+      "Hay copias físicas en adaptadores. Reinstala con --force para evitar divergencias.",
+    );
+  }
+  if (results.some((result) => result.status === "outdated")) {
+    process.exitCode = 1;
+  }
+}
+
+function canConnect(port, timeout = 250) {
+  return new Promise((finish) => {
+    const socket = connect({ host: "127.0.0.1", port });
+    const close = (available) => {
+      socket.destroy();
+      finish(available);
+    };
+    socket.setTimeout(timeout);
+    socket.once("connect", () => close(true));
+    socket.once("timeout", () => close(false));
+    socket.once("error", () => close(false));
+  });
+}
+
+async function doctor() {
+  const bridgeChecks = await Promise.all(
+    Array.from({ length: 10 }, (_, index) => 9223 + index).map(
+      async (port) => ({
+        port,
+        available: await canConnect(port),
+      }),
+    ),
+  );
+  const report = {
+    skill: skillStatus()[0]?.status ?? "missing",
+    officialRemoteMcp: "verify-in-agent",
+    officialDesktopMcp: (await canConnect(3845))
+      ? "detected-on-127.0.0.1:3845"
+      : "not-detected",
+    communityBridgePorts: bridgeChecks
+      .filter((result) => result.available)
+      .map((result) => result.port),
+    restToken: process.env.FIGMA_ACCESS_TOKEN ? "configured" : "not-configured",
+  };
+
+  if (process.argv.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log("Diagnóstico Bacano Figma Web");
+  console.table([
+    { control: "Skill instalada", result: report.skill },
+    {
+      control: "MCP remoto oficial",
+      result: "Verificar OAuth y whoami dentro del agente",
+    },
+    { control: "MCP local oficial", result: report.officialDesktopMcp },
+    {
+      control: "Desktop Bridge comunitario",
+      result: report.communityBridgePorts.length
+        ? `Puerto(s) detectado(s): ${report.communityBridgePorts.join(", ")}`
+        : "No detectado",
+    },
+    { control: "Token REST (solo presencia)", result: report.restToken },
+  ]);
+  console.log(
+    "Este diagnóstico no lee secretos ni puede certificar el OAuth del cliente MCP.",
+  );
+}
+
+const command = process.argv[2] ?? "help";
+
+try {
+  if (command === "install") await installSkill();
+  else if (command === "check") check();
+  else if (command === "doctor") await doctor();
+  else if (command === "validate-snapshot")
+    validateSnapshot(process.argv[3], projectRoot);
+  else usage();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/skills/bacano-figma-web/scripts/snapshot.mjs

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+function object(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateFrame(frame, path, errors) {
+  if (!object(frame)) {
+    errors.push(`${path} debe ser un objeto.`);
+    return;
+  }
+  if (typeof frame.nodeId !== "string" && typeof frame.url !== "string") {
+    errors.push(`${path} requiere nodeId o url.`);
+  }
+}
+
+function inspectSecrets(value, errors, path = "manifest") {
+  const secretNames = new Set([
+    "accesstoken",
+    "authorization",
+    "cookie",
+    "password",
+    "personalaccesstoken",
+    "secret",
+  ]);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      inspectSecrets(item, errors, `${path}[${index}]`),
+    );
+    return;
+  }
+  if (!object(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (secretNames.has(key.toLowerCase())) {
+      errors.push(`${path}.${key} no puede contener secretos.`);
+    }
+    inspectSecrets(child, errors, `${path}.${key}`);
+  }
+}
+
+export function validateManifest(manifest) {
+  const errors = [];
+  const adapters = new Set([
+    "figma-official",
+    "figma-desktop",
+    "desktop-bridge",
+    "rest-snapshot",
+  ]);
+  const capabilities = new Set(["available", "partial", "missing"]);
+  const pageStatuses = new Set([
+    "pending",
+    "extracted",
+    "implemented",
+    "validated",
+  ]);
+
+  if (!object(manifest)) return ["El manifiesto debe ser un objeto JSON."];
+  if (manifest.schemaVersion !== 1) errors.push("schemaVersion debe ser 1.");
+  if (typeof manifest.project !== "string" || !manifest.project.trim()) {
+    errors.push("project es obligatorio.");
+  }
+  if (!object(manifest.source)) {
+    errors.push("source es obligatorio.");
+  } else {
+    if (!adapters.has(manifest.source.adapter)) {
+      errors.push("source.adapter no es compatible.");
+    }
+    if (
+      typeof manifest.source.extractedAt !== "string" ||
+      Number.isNaN(Date.parse(manifest.source.extractedAt))
+    ) {
+      errors.push("source.extractedAt debe ser una fecha ISO válida.");
+    }
+  }
+  if (manifest.capabilities !== undefined) {
+    if (!object(manifest.capabilities)) {
+      errors.push("capabilities debe ser un objeto.");
+    } else {
+      for (const [name, status] of Object.entries(manifest.capabilities)) {
+        if (!capabilities.has(status)) {
+          errors.push(`capabilities.${name} no tiene un estado válido.`);
+        }
+      }
+    }
+  }
+  if (!Array.isArray(manifest.pages) || manifest.pages.length === 0) {
+    errors.push("pages requiere al menos una página.");
+  } else {
+    const routes = new Set();
+    manifest.pages.forEach((page, index) => {
+      const path = `pages[${index}]`;
+      if (!object(page)) {
+        errors.push(`${path} debe ser un objeto.`);
+        return;
+      }
+      if (typeof page.route !== "string" || !page.route.startsWith("/")) {
+        errors.push(`${path}.route debe comenzar por /.`);
+      } else if (routes.has(page.route)) {
+        errors.push(`${path}.route está duplicada.`);
+      } else {
+        routes.add(page.route);
+      }
+      if (typeof page.name !== "string" || !page.name.trim()) {
+        errors.push(`${path}.name es obligatorio.`);
+      }
+      if (!pageStatuses.has(page.status)) {
+        errors.push(`${path}.status no es válido.`);
+      }
+      if (!page.desktop && !page.mobile) {
+        errors.push(`${path} requiere un frame desktop o mobile.`);
+      }
+      if (page.desktop) validateFrame(page.desktop, `${path}.desktop`, errors);
+      if (page.mobile) validateFrame(page.mobile, `${path}.mobile`, errors);
+    });
+  }
+  inspectSecrets(manifest, errors);
+  return errors;
+}
+
+export function validateSnapshot(path, projectRoot) {
+  if (!path) throw new Error("Indica la ruta de manifest.json.");
+  const manifestPath = resolve(projectRoot, path);
+  if (!existsSync(manifestPath) || !statSync(manifestPath).isFile()) {
+    throw new Error(`No existe el manifiesto: ${path}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const errors = validateManifest(manifest);
+  if (errors.length) {
+    console.error("Snapshot inválido:");
+    for (const error of errors) console.error(`- ${error}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Snapshot válido: ${relative(projectRoot, manifestPath)}`);
+  console.log(
+    `${manifest.pages.length} página(s), fuente ${manifest.source.adapter}.`,
+  );
+}

package/skills/bacano-web/scripts/postinstall.mjs

@@ -4,5 +4,9 @@ if (!process.env.CI && process.env.BACANO_SDK_HIDE_SKILL_NOTICE !== "1") {
 Instálala una vez:       pnpm exec bacano-web install --agent all
 Verifica su estado:      pnpm exec bacano-web check
 Luego invócala desde tu agente para iniciar la auditoría.
+
+Para implementar un diseño Figma con el cascarón Bacano:
+Instala la skill:        pnpm exec bacano-figma-web install --agent all
+Revisa la conexión:      pnpm exec bacano-figma-web doctor
 `);
 }