compare_image
Compares a PNG screenshot of a built screen against the Figma node render to detect visual mismatches, reporting differing regions for layout, text, and image review.
Instructions
Compare a PNG screenshot of the built screen with the node as figlens renders it, to check visual fidelity with a tool instead of by eye. The node is drawn over its layout box at the screenshot's scale (screenshot width / node width, or scale), composited over white; a pixel differs when no pixel within one CSS pixel in the other image is within the threshold (48/255 per channel by default), so anti-aliasing does not count, but differences under it (light borders, subtle tints) are not seen. Differing pixels are grouped into regions on an 8 px grid; regions under 12 px² are dropped. Returns sizes, scale, mismatch (differing pixels / compared pixels), nonTextMismatch and textMismatch, nonImageMismatch and imageMismatch, and the largest regions in node pixels from its top-left, each with the deepest layers under it (id, name, type) and text: true when nearly all of it lies over TEXT layers (often font fallback or line breaks, but also a wrong text color, size or copy: review each) and image: true when nearly all of it lies only over image-filled layers (content such as banners or avatars, often from data). ignore leaves listed layers' render boxes out of every count and region, for content that differs by data rather than layout (their own size and position are then unmeasured); the reply lists them. threshold lowers the 48 default to see light borders and dividers, at the cost of more anti-aliasing noise. A screenshot taller than the node is compared over the node's height and the rest reported as uncompared; a shorter one, or a width that does not match scale, is refused, unless fullPage states the shorter one is the whole page: then its rows are compared and the node rows it lacks (past 1 px rounding) are reported as uncompared.missing and counted as one differing region over the layers there. warnings name what figlens skipped or approximated in the node, where a difference may be figlens's. out writes a diff PNG: the screenshot washed out, differing pixels red, ignored pixels gray, regions outlined red (layout), blue (text) or purple (image). Capture the screenshot at the node's size with fonts loaded; a viewport capture of a taller page needs a full-page screenshot.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"file": "<file>",
"node": "<node>",
"image": "<image>"
},
"name": "compare_image"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| out | No | diff PNG path ending in .png, in .figlens/exports/ under the project root unless the user names one; create the parent directory first; never the screenshot or the design | |
| file | Yes | the saved .fig: a local path (absolute recommended), or gs://bucket/object using gcloud; remote sources are unavailable with --root | |
| node | Yes | a stored node id (12:345 or 12-345), full instance sublayer id (I12:345;67:89) from inspect/nodes, or a Figma URL with ?node-id= | |
| image | Yes | PNG screenshot of the implemented screen, cropped to the node (a full-page capture may be taller); at most 64 MiB and 25,000,000 pixels | |
| limit | No | most regions listed, largest first, 1-50, default 10; counts cover all regions | |
| scale | No | screenshot pixels per node pixel, such as the device pixel ratio; default: the screenshot width / the node width | |
| ignore | No | comma-separated ids of layers inside node, such as data-driven images or user text, whose render boxes are left out of mismatch, its splits and regions; the reply lists them under ignored | |
| fullPage | No | the image is a full-page capture of the whole page: one shorter than the node is compared over its height and the missing rows reported as a differing region, a height finding; leave false for a viewport capture, which is then refused | |
| threshold | No | per-channel difference (of 255) above which pixels differ, 1-254, default 48; lower it (such as 16) to see a light border, divider or shadow the default misses |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | id, name and type of the compared node | |
| path | No | with out: the diff PNG written | |
| frame | Yes | the node's layout box width and height in node pixels | |
| scale | Yes | ||
| ignored | No | with ignore: nodes {id, name, type} and pixels, the screenshot pixels left out of every count | |
| regions | Yes | largest first, at most limit: x, y, width, height in node pixels from its top-left, pixels (differing screenshot pixels), text, image, and nodes: up to 3 deepest layers under it as {id, name, type}, most differing pixels first | |
| compared | Yes | width and height of the compared area in screenshot pixels | |
| mismatch | Yes | differing pixels / compared pixels, 0-1; with uncompared.missing, both include the missing rows as differing; ignored pixels are in neither | |
| warnings | Yes | known skipped or approximated rendering in the node, as export's | |
| threshold | Yes | per-channel difference (of 255) above which pixels differ | |
| screenshot | Yes | width and height in pixels | |
| uncompared | No | below: screenshot rows past the node's height, not compared; missing: with fullPage, node rows past the screenshot's bottom, counted as differing | |
| regionCount | Yes | ||
| textMismatch | Yes | differing pixels in regions' cells over text layers / compared pixels | |
| imageMismatch | Yes | differing pixels in regions' cells only over image-filled layers / compared pixels | |
| nonTextRegions | Yes | regions not marked text | |
| nonTextMismatch | Yes | differing pixels in regions' cells not over text layers / compared pixels | |
| nonImageMismatch | Yes | differing pixels in regions' cells not only over image-filled layers / compared pixels |