sketch-inspector

AI-friendly Sketch design parser. Turn Sketch documents into structured JSON, exported assets, and an implementation-ready LayoutIR (flex / grid / absolute / leaf) so any LLM agent can faithfully convert Sketch designs into HTML/CSS, React, Vue or any other front-end code.

sketch-inspector is an agent skill / toolkit designed to be loaded by AI coding agents (Claude Code, Cursor, opencode, etc.). It pairs with the official Sketch MCP server to give agents a deterministic pipeline for inspecting layers, exporting images, inferring layouts, and splitting large designs into manageable sections.

Keywords: sketch, sketch-app, design-to-code, sketch-to-html, sketch-to-react, sketch-to-vue, figma-alternative, mcp, model-context-protocol, ai-agent, claude-code, claude-skill, agent-skill, cursor, opencode, layout-ir, sketch-export, sketch-parser, sketch-mcp.

---

Why

Raw Sketch JSON is too noisy for LLMs: it contains hidden layers, slice layers, redundant style data, and absolute coordinates everywhere. Agents that consume it directly tend to hallucinate layout decisions and over-use absolute positioning.

This skill solves three concrete problems:

1. Deterministic export – one fixed script that produces a clean result.json plus deduplicated image assets (MD5-named, reused across nodes).
2. Layout intent inference – turns absolute Sketch frames into a unified LayoutIR (flex / grid / absolute / leaf) with gap, padding, justifyContent, alignItems, etc. so the model writes idiomatic CSS instead of pixel-perfect absolute jails.
3. Big-design workflow – splits oversized result.json into per-section JSON + a manifest.json with markers, lets the agent implement one section at a time, then auto-replaces the markers in the main layout file.

---

Pipeline

Sketch (MCP)
    │  scan layers
    ▼
export-text-split-assets.js   ──►  images/*.png + result.json (raw)
    │
    ▼
sketch_layout_ir_inference.ts ──►  result.json (unified LayoutIR, in place)
    │
    ├── ≤ 3000 lines ──►  agent reads the whole file and implements directly
    │
    └── > 3000 lines  ──►  split-result-json.js
                              │
                              ├── manifest.json
                              ├── 01-section.json, 02-section.json, ...
                              │
                              ▼
                          agent implements each section file
                              │
                              ▼
                          replace-section-placeholder.js  ──►  layout.html / layout.css

inspect-single-section.js is an optional helper for deeper inspection of a specific layer when section JSON is not enough.

---

Requirements

Tool	Version	Why
Sketch (macOS)	99+ recommended	The design tool itself
Sketch MCP	enabled	Sketch → Settings → General → Allow AI tools to interact with open documents
Node.js	18+ (tested on 22)	runs the CLI scripts
npx / tsx	latest	runs the TypeScript layout inference script (npx tsx ...)

The export and inspection scripts run inside Sketch's JavaScriptCore / CocoaScript environment via sketch.run_code (NOT regular Node), so they intentionally avoid npm dependencies — the only require('sketch') is provided by Sketch itself.

The two pure-Node CLI scripts (split-result-json.js, replace-section-placeholder.js) only use fs and path — zero external dependencies.

The TypeScript layout inference script (sketch_layout_ir_inference.ts) is run via npx tsx, no install needed beyond Node:

npx tsx scripts/sketch_layout_ir_inference.ts <input.json> <output.json>

---

Install as an agent skill

Claude Code / opencode / Cursor (skill-based agents)

Clone into your skills directory:

# Claude Code (global)
git clone https://github.com/gslvly/sketch-inspector ~/.claude/skills/sketch-inspector

# opencode / generic agent
git clone https://github.com/gslvly/sketch-inspector ~/.agents/skills/sketch-inspector

The agent will pick up SKILL.md automatically and use the scripts in scripts/ and references in references/.

Standalone use (no agent)

git clone https://github.com/gslvly/sketch-inspector
cd sketch-inspector
# scripts are zero-install, just call them with node / npx tsx

---

Usage (manual / non-agent)

1. Export a layer from Sketch

In Sketch, run Plugins → Run Script… and paste:

const sketch = require('sketch')
const scriptPath = '/absolute/path/to/sketch-inspector/scripts/export-text-split-assets.js'
const source = String(NSString.stringWithContentsOfFile_encoding_error(scriptPath, 4, null))
const module = { exports: {} }
eval(source)

const result = module.exports.runExportTextSplitAssets({
  layerId: 'YOUR_LAYER_ID',
  outputDir: '/abs/path/to/project/images',
  outputJsonPath: '/abs/path/to/work-tmp/result.json',
  exportFormat: 'png',
})
console.log(JSON.stringify({ exported: result.exports.length }))

2. Infer LayoutIR

npx tsx scripts/sketch_layout_ir_inference.ts \
  /abs/path/to/work-tmp/result.json \
  /abs/path/to/work-tmp/result.json

3. (Optional) Split a large result

node scripts/split-result-json.js \
  --inputJsonPath=/abs/path/to/work-tmp/result.json \
  --outputDir=/abs/path/to/work-tmp \
  --assetBasePath=images/ \
  --splitStrategy=auto

Produces manifest.json plus one XX-section.json per section, each with its own htmlMarker, cssMarker, implementationPath, and layoutIR.

4. Replace section markers in the layout file

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

Pass --cssLayoutPath if your CSS lives in a separate file.

Full parameter reference: references/script-api.md.

---

LayoutIR

Every node in the inferred result.json has a kind:

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

• flex – direction, gap, padding, justifyContent, alignItems, hasAbsoluteChildren
• grid – columns, rows, columnGap, rowGap, padding, alignItems
• absolute – children are placed via absolute positioning
• leaf – terminal node, contains text, asset, background, style, etc. under source

When a flex / grid container has direct absolute children, the IR sets hasAbsoluteChildren: true and css.position: 'relative' so consumers don't lose the positioning context.

See references/layout-principles.md for coordinate-system and box-sizing guidance.

---

Files

sketch-inspector/
├── SKILL.md                              # the skill manifest (read by AI agents)
├── README.md                             # you are here
├── scripts/
│   ├── export-text-split-assets.js       # Sketch run-code: export layer → images + result.json
│   ├── sketch_layout_ir_inference.ts     # tsx CLI: infer LayoutIR
│   ├── split-result-json.js              # node CLI: split big result.json into sections
│   ├── replace-section-placeholder.js    # node CLI: backfill section files into layout
│   └── inspect-single-section.js         # Sketch run-code: deep-inspect a single layer
└── references/
    ├── script-api.md                     # full script API reference
    ├── export-assets.md                  # asset-export rules and decisions
    ├── layout-principles.md              # layout / coordinate / box-sizing rules
    └── single-section-workflow.md        # rules for implementing one section

---

License

MIT © 2026 gslvly

PRs welcome. If you build a Figma / XD equivalent on top of the same LayoutIR, please open an issue — happy to link to it from here.