gslvly/sketch-inspector

Sketch Inspector

Convierte diseños de Sketch en datos estructurados, recursos de imagen y secciones de página implementables.

Casos de uso

• Inspeccionar documentos de Sketch abiertos o capas específicas
• Extraer información de estructura, estilos, texto, colores, diseño y recursos
• Implementar HTML/CSS, React, Vue u otras páginas basadas en áreas de Sketch

Requisitos previos

• Sketch en ejecución, con el documento de destino abierto
• Sketch MCP habilitado: General -> Allow AI tools to interact with open documents
• Dirección del servicio MCP: http://localhost:31126/mcp
• Sketch Run Code se ejecuta en el entorno JavaScriptCore/CocoaScript, no en Node.js normal

Flujo obligatorio para la implementación de páginas

Al generar una página desde Sketch, se debe seguir estrictamente el siguiente flujo; es la única forma más rápida de completar la tarea. Saltarse cualquier paso se considera un fallo.

1. Escaneo

Extraer el contorno superficial de la página o del contenedor de destino, confirmando el layerId del nodo raíz.

2. Determinar rutas

• imageOutputDir: directorio de imágenes del proyecto, priorizando los existentes images/, assets/images/, public/images/, etc.
• workTmpDir: directorio temporal, que contenga al menos result.json; para archivos grandes también contendrá manifest.json, secciones JSON y secciones HTML

3. Exportación

Ejecutar el script de exportación en sketch_run_code.

const sketch = require('sketch');

// Preparación de parámetros
const layerId = '<layerId de la capa de destino>'; // ID del nodo raíz de destino obtenido del escaneo del paso 1
const outputDir = '<ruta absoluta de imageOutputDir>';  // Ej: '/Users/edy/project/images'
const outputJsonPath = '<ruta absoluta de workTmpDir/result.json>';  // Ej: '/Users/edy/project/tmp/result.json'

// Ejecutar el script de exportación
const exportScript = require('@scripts/export-text-split-assets.js');
const result = exportScript.runExportTextSplitAssets({
  layerId: layerId,
  outputDir: outputDir,
  outputJsonPath: outputJsonPath
});

// Mostrar el resultado para depuración
console.log(JSON.stringify(result, null, 2));

Resultados devueltos:

• Éxito: devuelve estadísticas de exportación
• Fallo: devuelve información de error; verificar si layerId es válido y si las rutas tienen permisos de escritura

Nota:

• El script se ejecuta en el entorno JavaScriptCore de Sketch, no en Node.js normal
• Las rutas deben ser absolutas
• El directorio de salida debe existir; el script no lo crea automáticamente

4. Inferencia de diseño y sobrescritura de result.json

Ejecutar en Shell:

npx tsx @scripts/sketch_layout_ir_inference.ts \
  <workTmpDir>/result.json \
  <workTmpDir>/result.json

Este paso convierte la estructura exportada original en un JSON de diseño unificado listo para implementar, sobrescribiendo el result.json original.

Estructura de result.json unificado de salida:

• kind: flex | grid | absolute | leaf
• direction: row | column (solo flex)
• gap: espacio entre elementos hijos
• padding: relleno interno { top, right, bottom, left }
• justifyContent: alineación flex
• alignItems: alineación en el eje cruzado
• hasAbsoluteChildren: true cuando un contenedor flex/grid tiene hijos directos absolute
• css.position: "relative": se genera explícitamente cuando un contenedor flex/grid tiene hijos directos absolute
• columns / rows: número de columnas/filas de la cuadrícula (solo grid)
• source: datos complementarios de implementación correspondientes al nodo de diseño actual; solo conserva campos no relacionados con el diseño como sourceClass / asset / background / style / decision / backgroundLayers / derivedFrom

5. Bifurcación obligatoria después de la inferencia de diseño

Una vez completada la inferencia de diseño, no se permite decidir el método de implementación por intuición; se debe bifurcar según el número real de líneas del result.json unificado:

• Si result.json tiene menos o igual a 3000 líneas: leer todo el result.json directamente y completar la implementación, sin dividir
• Si result.json tiene más de 3000 líneas: se debe ingresar al "flujo de división de archivos grandes"; está prohibido pasar todo el JSON directamente a los pasos de implementación posteriores

Ejemplo de verificación de líneas:

wc -l <workTmpDir>/result.json

6. Flujo principal para archivos pequeños: implementación directa

Condiciones aplicables: result.json tiene <= 3000 líneas

Reglas principales (DEBEN SEGUIRSE):

1. Prohibido usar absolute en diseños normales: solo los nodos con kind: "absolute" pueden tener posicionamiento absoluto
2. Cuando hay hijos directos absolute, se debe confiar en la señal de posicionamiento de result.json: si un nodo genera hasAbsoluteChildren: true o css.position: "relative", al implementar se debe establecer el estado de posicionamiento en el contenedor padre, sin ignorarlo

Flujo de generación:

1. Leer el result.json completo
2. Recorrer recursivamente el árbol de diseño
3. Según kind, generar el CSS correspondiente:
   • flex: display: flex; flex-direction: {direction}; gap: {gap}px; ...
   • grid: display: grid; grid-template-columns: repeat({columns}, 1fr); ...
   • absolute: position: relative; elementos hijos con position: absolute;
   • leaf: sin diseño, solo renderizar contenido
4. Usar directamente el source del nodo actual para implementar texto, imágenes, fondos, estilos y decisiones, sin volver a consultar el JSON de estructura anterior

7. Flujo principal para archivos grandes: división -> implementación de sección individual -> relleno y consolidación

Condiciones aplicables: result.json tiene > 3000 líneas

7.1 División del JSON

Ejecutar en Shell:

node @scripts/split-result-json.js \
  --inputJsonPath=<workTmpDir>/result.json \
  --outputDir=<workTmpDir> \
  --assetBasePath=images/ \
  --splitStrategy=auto

Salida:

• <workTmpDir>/manifest.json
• Varios JSON de sección
• implementationPath, htmlMarker, cssMarker acordados
• manifest.json.root.layoutIR: resumen semántico del diseño principal de la página
• manifest.json.sections[].layoutIR: resumen semántico del diseño del nodo de la sección en sí

7.2 Implementación de sección individual

Cada sección debe leer solo su propio jsonPath y escribir su propio implementationPath según el manifest.json.

Reglas obligatorias:

• El flujo de implementación de una sección individual se encuentra en @references/single-section-workflow.md
• El archivo de sección debe ser un fragmento: un <section> + un <style>
• Dentro de la sección, solo se escriben la estructura interna y los estilos internos; no se definen márgenes externos del contenedor de diseño principal
• Los selectores no raíz deben tener aislamiento de ámbito mediante className
• Si se necesita una verificación profunda, usar @scripts/inspect-single-section.js

7.3 Relleno y consolidación

Una vez completada la implementación de todas las secciones, se debe rellenar cada fragmento de sección en el archivo de diseño principal; no se permite copiar y pegar manualmente el contenido del marcador.

El archivo de diseño principal debe cumplir previamente:

• Colocar htmlMarker en la posición de la estructura de la página donde se debe insertar la sección
• cssMarker debe colocarse dentro del bloque <style> del archivo de diseño principal, no fuera de otras etiquetas, bloques de comentarios o en la estructura del cuerpo
• Si HTML y CSS están en archivos separados, cssMarker debe colocarse en el archivo CSS apuntado por cssLayoutPath

Ejecutar en Shell:

node @scripts/replace-section-placeholder.js \
  --layoutPath=/path/layout.html \
  --sectionPath=/path/01-section.html \
  --htmlMarker="<!-- 01-section HTML -->" \
  --cssMarker="/* 01-section CSS */"

Si HTML y CSS están en archivos diferentes, agregar --cssLayoutPath.

8. Lista de verificación de implementación

Antes de implementar, confirmar:

• Lectura completa de result.json
• Verificar el campo kind de cada nodo
• Verificar la información de la capa de fondo meta.background
• Verificar texto, imágenes y relaciones entre capas
• Identificar activos de marca y grupos visuales complejos

9. Entrega

Informar sobre los productos objetivos:

• Contorno del diseño e ID del área de destino
• Ruta de result.json y número real de líneas
• Si se utilizó el "flujo de implementación directa para archivos pequeños" o el "flujo de división para archivos grandes"
• Si se siguió el flujo de división: ruta de manifest.json, número de secciones, ruta del archivo de destino para el relleno
• Estadísticas de tipos de diseño (cantidad de flex/grid/absolute/leaf)
• Lista de recursos exportados
• Rutas de los archivos HTML/CSS generados

No emitir conclusiones que la máquina no pueda verificar, como "verificado visualmente".

Scripts fijos

Los parámetros de los scripts y la estructura de retorno se encuentran en @references/script-api.md.

• @scripts/export-text-split-assets.js: exporta imágenes y JSON. Requiere layerId y outputDir
• @scripts/sketch_layout_ir_inference.ts: inferencia de diseño y salida de result.json unificado
• @scripts/split-result-json.js: script del flujo principal para archivos grandes; genera manifest.json y varios JSON de sección
• @scripts/replace-section-placeholder.js: script del flujo principal para archivos grandes; rellena la implementación de la sección en el archivo de diseño principal
• @scripts/inspect-single-section.js: verificación profunda local cuando la información de la sección es insuficiente

Prohibido: generar scripts de exportación propios, copiar el código fuente de los scripts o reimplementar la lógica de recorrido.

Descripción de los tipos de LayoutIR

type LayoutKind = 'leaf' | 'flex' | 'grid' | 'absolute'

interface FlexIR {
  kind: 'flex'
  direction: 'row' | 'column'
  gap: number
  padding: { top, right, bottom, left }
  justifyContent: 'flex-start' | 'center' | 'flex-end' | 'space-between'
  alignItems: 'flex-start' | 'center' | 'flex-end' | 'stretch'
  children: LayoutIR[]
}

interface GridIR {
  kind: 'grid'
  columns: number
  rows: number
  columnGap: number
  rowGap: number
  padding: { top, right, bottom, left }
  children: LayoutIR[]
}

interface AbsoluteIR {
  kind: 'absolute'
  children: LayoutIR[]  // Los elementos hijos necesitan posicionamiento absoluto
}

interface LeafIR {
  kind: 'leaf'
  text?: string
  css: { width?, height? }
}

Reglas de exportación de recursos

• Las imágenes se exportan a imageOutputDir; el JSON temporal se coloca en workTmpDir
• Los nombres de archivo de imagen usan los primeros 8 caracteres del MD5; las imágenes iguales se reutilizan
• En asset/exports solo se conservan path, src, x, y, width, height. Al generar código se referencia src, no path
• En el JSON se eliminan los campos de estilo con valor nulo o 0
• Por defecto, se filtran las capas ocultas
• Los nodos que contienen texto real deben dividirse; no se pueden exportar enteros como imagen
• Los rectángulos de fondo normales se reconstruyen con código; los activos de marca y grupos visuales complejos se exportan con prioridad para mantener la fidelidad

Índice de referencias

• @references/export-assets.md: reglas de exportación de recursos
• @references/script-api.md: parámetros de scripts y estructura de retorno
• @references/single-section-workflow.md: flujo de implementación de una sección individual