sketch-inspector

Sketch 检查器

Converte designs do Sketch em dados estruturados, recursos de imagem e blocos de página implementáveis.

Cenários de uso

• Inspecionar documentos ou camadas específicas do Sketch abertos
• Extrair informações de estrutura, estilo, texto, cor, layout e recursos
• Implementar páginas em HTML/CSS, React, Vue ou outras tecnologias com base em áreas do Sketch

Pré-requisitos

• O Sketch está em execução e o documento alvo está aberto
• O Sketch MCP está ativado: General -> Allow AI tools to interact with open documents
• Endereço do serviço MCP: http://localhost:31126/mcp
• O Sketch Run Code executa no ambiente JavaScriptCore/CocoaScript, não no Node.js comum

Fluxo obrigatório para implementação de páginas

Ao gerar uma página a partir do Sketch, o fluxo a seguir deve ser rigorosamente executado. Esta é a única maneira mais rápida de concluir a tarefa; qualquer etapa faltando é considerada falha.

1. Varredura

Extraia o contorno superficial da página ou contêiner alvo e confirme o layerId do nó raiz.

2. Definir caminhos

• imageOutputDir: diretório de imagens do projeto, priorizando diretórios existentes como images/, assets/images/, public/images/ etc.
• workTmpDir: diretório temporário que deve conter pelo menos result.json; para arquivos grandes divididos, também conterá manifest.json, section JSON e section HTML.

3. Exportação

Execute o script de exportação no sketch_run_code.

const sketch = require('sketch');

// Preparação de parâmetros
const layerId = '<layerId da camada alvo>'; // Obtido na varredura da etapa 1
const outputDir = '<caminho absoluto do imageOutputDir>';  // Ex: '/Users/edy/project/images'
const outputJsonPath = '<caminho absoluto do workTmpDir/result.json>';  // Ex: '/Users/edy/project/tmp/result.json'

// Executar script de exportação
const exportScript = require('@scripts/export-text-split-assets.js');
const result = exportScript.runExportTextSplitAssets({
  layerId: layerId,
  outputDir: outputDir,
  outputJsonPath: outputJsonPath
});

// Exibir resultado para depuração
console.log(JSON.stringify(result, null, 2));

Resultados retornados:

• Sucesso: retorna estatísticas de exportação
• Falha: retorna mensagem de erro; verifique se layerId é válido e se o caminho tem permissão de gravação

Observações:

• O script é executado no ambiente JavaScriptCore do Sketch, não no Node.js comum
• Os caminhos devem ser absolutos
• O diretório de saída deve existir; o script não o criará automaticamente

4. Inferência de layout e sobrescrita de result.json

Execute no Shell:

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

Esta etapa converte a estrutura exportada bruta em um JSON de layout unificado diretamente implementável e sobrescreve o result.json original.

Estrutura unificada de saída result.json:

• kind: flex | grid | absolute | leaf
• direction: row | column (apenas flex)
• gap: espaçamento entre elementos filhos
• padding: preenchimento interno { top, right, bottom, left }
• justifyContent: alinhamento flex
• alignItems: alinhamento no eixo transversal
• hasAbsoluteChildren: true quando o contêiner flex/grid possui filhos diretos absolute
• css.position: "relative": gerado explicitamente quando o contêiner flex/grid possui filhos diretos absolute
• columns / rows: número de linhas/colunas da grade (apenas grid)
• source: dados complementares de implementação correspondentes ao nó de layout atual; mantém apenas campos não relacionados a layout como sourceClass / asset / background / style / decision / backgroundLayers / derivedFrom

5. Após a inferência de layout, é obrigatório dividir

Após a inferência de layout, não é permitido decidir a implementação por intuição. A divisão deve ser feita com base no número real de linhas do result.json unificado:

• Se result.json tiver <= 3000 linhas: leia todo o result.json e complete a implementação, sem divisão
• Se result.json tiver > 3000 linhas: é obrigatório entrar no "fluxo de divisão de arquivo grande"; é proibido passar o JSON inteiro diretamente para as próximas etapas de implementação

Exemplo de verificação de número de linhas:

wc -l <workTmpDir>/result.json

6. Fluxo principal para arquivo pequeno: implementação direta

Condição de aplicação: result.json com <= 3000 linhas

Regras principais (OBRIGATÓRIO SEGUIR):

1. Proibido usar absolute em layouts comuns: apenas nós com kind: "absolute" podem usar posicionamento absoluto
2. Quando houver filhos diretos absolute, confiar no sinal de posicionamento do result.json: se o nó gerou hasAbsoluteChildren: true ou css.position: "relative", a implementação deve definir o pai como posicionado, não ignore

Fluxo de geração:

1. Leia o result.json completo
2. Percorra recursivamente a árvore de layout
3. Gere CSS correspondente com base no kind:
   • flex: display: flex; flex-direction: {direction}; gap: {gap}px; ...
   • grid: display: grid; grid-template-columns: repeat({columns}, 1fr); ...
   • absolute: position: relative; nos filhos position: absolute;
   • leaf: sem layout, apenas renderize o conteúdo
4. Use diretamente o source do nó atual para implementar texto, imagem, fundo, estilo e decisões; não consulte novamente o JSON de estrutura antigo

7. Fluxo principal para arquivo grande: divisão -> implementação de seção individual -> reunião

Condição de aplicação: result.json com > 3000 linhas

7.1 Dividir JSON

Execute no Shell:

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

Saída:

• <workTmpDir>/manifest.json
• Vários JSONs de seção
• implementationPath, htmlMarker, cssMarker conforme combinado
• manifest.json.root.layoutIR: resumo semântico do layout principal da página
• manifest.json.sections[].layoutIR: resumo semântico do layout do nó da seção em si

7.2 Implementação de seção individual

Cada seção deve ler apenas seu próprio jsonPath e escrever em seu próprio implementationPath de acordo com manifest.json.

Regras obrigatórias:

• O fluxo de implementação de seção individual está em @references/single-section-workflow.md
• O arquivo de seção deve ser um fragmento: uma <section> + um <style>
• Dentro da seção, escreva apenas a estrutura interna e os estilos internos; não defina margens externas do contêiner de layout principal
• Seletores não raiz devem ser isolados por escopo usando className
• Use @scripts/inspect-single-section.js apenas quando for necessária uma verificação profunda

7.3 Reunião

Após todas as seções serem implementadas, cada fragmento de seção deve ser reunido no arquivo de layout principal; não copie e cole manualmente o conteúdo do marcador.

O arquivo de layout principal deve atender previamente:

• htmlMarker colocado na posição da estrutura da página onde a seção deve ser inserida
• cssMarker deve estar dentro do bloco <style> do arquivo de layout principal; não pode estar fora de tags, blocos de comentário ou na estrutura do corpo
• Se HTML e CSS estiverem em arquivos separados, cssMarker deve estar no arquivo CSS apontado por cssLayoutPath

Execute no Shell:

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

Se HTML e CSS estiverem em arquivos diferentes, passe adicionalmente --cssLayoutPath.

8. Checklist de implementação

Antes de implementar, confirme:

• Leitura completa do result.json
• Verificação do campo kind de cada nó
• Verificação das informações de camada de fundo meta.background
• Texto, imagem, relações de camada já verificados
• Assets de marca e grupos visuais complexos identificados

9. Entrega

Relate os artefatos objetivos:

• Contorno do layout e ID da área alvo
• Caminho do result.json e número real de linhas
• Se foi usado "fluxo de implementação direta para arquivo pequeno" ou "fluxo de divisão para arquivo grande"
• Se for o fluxo de divisão: caminho do manifest.json, número de seções, caminho do arquivo de destino da reunião
• Estatísticas de tipo de layout (quantidade de flex/grid/absolute/leaf)
• Lista de recursos exportados
• Caminhos dos arquivos HTML/CSS gerados

Não produza conclusões que a máquina não possa verificar, como "visualmente verificado".

Scripts fixos

Parâmetros e estruturas de retorno dos scripts estão em @references/script-api.md.

• @scripts/export-text-split-assets.js: exporta imagens e JSON. Obrigatório layerId, outputDir
• @scripts/sketch_layout_ir_inference.ts: inferência de layout e geração do result.json unificado
• @scripts/split-result-json.js: script do fluxo principal para arquivo grande, gera manifest.json e múltiplos JSONs de seção
• @scripts/replace-section-placeholder.js: script do fluxo principal para arquivo grande, reúne a implementação da seção no arquivo de layout principal
• @scripts/inspect-single-section.js: verificação profunda local quando a informação da seção é insuficiente

Proibido: gerar scripts de exportação próprios, copiar o código-fonte dos scripts ou reimplementar a lógica de travessia.

Descrição dos tipos 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[]  // elementos filhos precisam de posicionamento absoluto
}

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

Regras de exportação de recursos

• Imagens são exportadas para imageOutputDir; JSON temporário fica em workTmpDir
• Nomes de arquivo de imagem usam os primeiros 8 caracteres do MD5; imagens idênticas são reutilizadas
• asset/exports mantém apenas path, src, x, y, width, height. O código gerado referencia src, não path
• O JSON remove campos de estilo com valor nulo ou 0
• Camadas ocultas são filtradas por padrão
• Nós com texto real devem ser divididos; não podem ser exportados como imagem inteira
• Retângulos de fundo comuns são recriados por código; ativos de marca e grupos visuais complexos têm prioridade de exportação com alta fidelidade

Índice de referência

• @references/export-assets.md: regras de exportação de recursos
• @references/script-api.md: parâmetros e estrutura de retorno dos scripts
• @references/single-section-workflow.md: fluxo de implementação de seção individual