Beam logoBeam

CLI Command

beam compare

Compare a local rendered page with Figma visual ground truth using practical image signals.

beam compare helps users verify whether a local implementation is visually close to the Figma reference. It is useful after an agent builds a screen and the local app is running.

The v1 comparator is intentionally pragmatic. It can report screenshot dimensions, pixel differences, dominant mismatch signals, similarity score, local artifact paths, and structured differences.

It does not claim semantic design perfection. Typography meaning, responsive behavior, and component intent still need human or agent review when the visual signal is ambiguous.

Compare artifacts stay local. Results should follow Beam's Compare Result Contract so CLI JSON, MCP responses, and future history features share the same shape.

bash
1beam compare <figma-url> <local-url>2beam compare <figma-url> <local-url> --threshold 0.953beam compare <figma-url> <local-url> --json

Run Sequence

  1. Start the local application that contains the implemented screen.
  2. Confirm the target page loads in a browser, for example http://localhost:3000/pricing.
  3. Run beam compare <figma-url> <local-url>.
  4. Review the score, dimensions, artifact paths, and differences before iterating.

Expected Output

Beam should report a compare id, Figma snapshot id, target URL, score, screenshot paths, diff artifact path, and structured differences such as spacing, size, color, or image mismatch signals.

Files And Artifacts

  1. .beam/cache/compare/<compare-id>/local.png
  2. .beam/cache/compare/<compare-id>/figma.png
  3. .beam/cache/compare/<compare-id>/diff.png
  4. .beam/cache/compare/<compare-id>/result.json

Next Step

Fix the largest visual differences, rebuild the app, and run compare again.

Recovery Paths

  1. If the local URL is unreachable, start the app dev server and retry.
  2. If screenshots have different dimensions, match the viewport or frame size before trusting the score.
  3. If visual output is ambiguous, use the diff image plus the Beam implementation brief together.