# pixelpact

> Measurement for coding agents building UI. pixelpact reads a reference page and records
> every value it renders, then measures an implementation against that file and reports one
> line per property that drifted. Open source, MIT licensed, no service and no account.

A coding agent writes the CSS and says it is done. It never sees the result. Nothing hands it
a number, so the loop cannot close: the agent guesses, a person opens the page, sends it back,
and the agent guesses again. pixelpact closes that loop by turning the reference page into a
committed JSON file called a contract, then checking any implementation against it.

This is not visual regression testing. Percy, Chromatic, Applitools and BackstopJS compare a
page against a snapshot approved earlier, which assumes the page is already correct. pixelpact
compares against the reference design itself, which is what exists while the page is still
being built. The two are complementary.

## What a contract records

- Geometry: position and size of every visible box
- Colour and typography: computed values, colours compared by perceptual distance
- Hover and focus: only the properties that actually change
- Design tokens: custom properties declared on the root element
- Keyframes: named animations, compared by timing rather than by string equality

## Commands

- `pixelpact extract <url>`: reads the reference and writes a contract file
- `pixelpact check <contract> <url>`: measures an implementation, prints deviations, sets the exit code
- `pixelpact diff <contract> <url>`: pixel comparison against the screenshot stored in the contract
- `pixelpact side <reference> <url>`: section by section side by side images with the differences boxed

Exit codes: `0` inside tolerance, `1` deviations found or pixel threshold exceeded, `2` usage
error, `3` runtime failure such as no browser available.

## Quickstart

```bash
pnpm add -D pixelpact playwright
pnpm exec playwright install chromium
npx pixelpact extract https://reference.example.com --selector "main" -o contract.json
npx pixelpact check contract.json http://localhost:3000 --viewport desktop
```

## For coding agents

`pixelpact-mcp` is an MCP server that exposes the same measurements over stdio, so an agent can
check its own work. Tools: `extract_contract`, `check_implementation`, `diff_pixels`,
`read_contract_summary`. It works with Claude Code, Cursor and anything else that speaks stdio MCP.

```jsonc
// .mcp.json
{ "mcpServers": { "pixelpact": { "command": "npx", "args": ["-y", "pixelpact-mcp"] } } }
```

## Requirements

Node.js 22.12 or newer. Chromium through Playwright, which is a peer dependency so the browser
download stays under your control. It measures the rendered DOM, so React, Vue, Svelte, Astro
and hand written HTML are all the same to it. A Figma frame can be used as the reference
through the REST API.

## Links

- [Site](https://pixelpact.dev/): overview, quickstart and FAQ
- [Source](https://github.com/jamalkamaladdin/pixelpact): full documentation and issues
- [pixelpact on npm](https://www.npmjs.com/package/pixelpact): the command line tool
- [pixelpact-core on npm](https://www.npmjs.com/package/pixelpact-core): extraction, checking and reporting as a library
- [pixelpact-mcp on npm](https://www.npmjs.com/package/pixelpact-mcp): the MCP server for coding agents
- [License](https://github.com/jamalkamaladdin/pixelpact/blob/main/LICENSE): MIT