The gap pixelpact fills
pixelpact is an MCP server and CLI that measures a UI against its reference. It extracts a contract of rendered sizes, colors, spacing and states, then checks an implementation and returns expected, actual and difference values. A coding agent uses those numbers to fix its own code.
A coding agent writes CSS and reports it is done without ever seeing the page. pixelpact reads the reference page, records what it actually renders as a contract file, and answers an implementation check with one line per property that drifted.
The contract holds sizes, colors, spacing, typography, hover and focus states, animation keyframes and design tokens as plain JSON. It runs on Playwright, reads the rendered DOM, and needs no account or service.
The measure and fix loop
- Extract a contract from the reference URL with
npx pixelpact extract <url> -o contract.json. - Check the implementation with
npx pixelpact check contract.json <url>. - Read the deviation list, which gives the selector, property, expected value, actual value and difference.
- Fix the code and run the check again. Exit code 0 means everything is inside tolerance.
Not a visual regression tool
Regression tools such as Percy or Chromatic compare against a snapshot you approved earlier. pixelpact compares against the reference design itself, so it is useful while the page is still being built. The README calls the two complementary.
Who it suits
- Developers whose coding agent builds UI from a reference page and needs numbers back.
- Builders starting from a screenshot or a Figma frame. Related: image-to-code, figma-mcp and framelink-figma-mcp.
- Teams that want a contract committed to the repository and one pull request comment from a GitHub Action.
Skip it if
- You need a finished page protected over time. The README points to a regression tool for that.
- You cannot run Node 22.12 or newer with a Playwright browser.
Use it with UiChemy
pixelpact only measures and never generates a page. Figma to WordPress is UiChemy's converter for turning a Figma frame into WordPress pages, and because pixelpact reads the rendered DOM, you can point its check at the converted page URL. Click Get Started on uichemy.com.
Connect pixelpact MCP Server: Measure a Built UI Against Its Reference to your AI client
npx -y pixelpact-mcpAdd the server
Put the block above in .mcp.json. The README lists Claude Code and Cursor as MCP clients, and any client that speaks stdio MCP works.
Install the browser engine
Playwright is a peer dependency. Install pixelpact and playwright as dev dependencies, then run
pnpm exec playwright install chromium. Node 22.12 or newer is required.Extract a contract
Ask the agent to call extract_contract on the reference URL, or run
npx pixelpact extract <url> -o contract.jsonyourself.Let the agent check its work
check_implementation returns the deviation list. The agent fixes the code and checks again until the numbers pass.
Client configuration
{
"mcpServers": {
"pixelpact": { "command": "npx", "args": ["-y", "pixelpact-mcp"] }
}
}Endpoints and ports
https://github.com/jamalkamaladdin/pixelpactSource, README and examplesWhat you can do with it
- Contract from the referenceThe page you are building toward is read once and every rendered value is written down. Nothing has to be approved first.
- Measured values per propertyEach deviation carries the expected value, the measured value and the difference between them.
- Hover and focus statesInteractive elements are hovered and focused, and only the properties that actually change are stored.
- Tokens and keyframesCustom properties on the root element and named animation keyframes travel inside the contract.
- Pixel comparisonWhen every value passes and it still looks wrong, compare the screenshots and get a percentage.
- Side by side sectionsThe side command splits both pages into sections, shows them next to each other and boxes what differs.
- Pull request checksA composite GitHub Action runs the check and keeps one comment on the pull request up to date.
- Figma frame as referenceA Figma url is read through the REST API, and the contract binds to your markup with data-contract attributes.
Tools it exposes
extract_contract
Reads a reference page and writes the contract.
check_implementation
Measures an implementation against a contract and returns the deviations.
diff_pixels
Compares screenshots and returns a percentage of changed pixels.
read_contract_summary
Summarizes a contract file.
Frequently asked questions
What is the pixelpact MCP server?
It is an MCP server and CLI that gives a coding agent a measurement of the UI it built. The agent extracts a contract from a reference page, checks its implementation against it, and reads a list of deviations with numbers.
How do I install it?
Add the npx -y pixelpact-mcp server to your MCP client config. For the CLI, install pixelpact and playwright as dev dependencies and then run pnpm exec playwright install chromium. The README requires Node 22.12 or newer.
Which AI clients work with it?
The README names Claude Code and Cursor, and says any client that speaks stdio MCP can use it. Because the server only needs to be launched with npx, the same config block works across those clients.
How is it different from visual regression testing?
Regression tools compare against a baseline you approved earlier, so their first run on a new page only records what you built. pixelpact measures against the reference design from the first run and returns a value per property.
Can it use a Figma frame as the reference?
Yes. Give extract a Figma url and it reads the frame through the REST API without launching a browser. It needs a FIGMA_TOKEN environment variable, and your markup binds to layers with data-contract attributes.
Can it run in CI?
Yes. The check exits 0 when everything is inside tolerance and 1 when it is not, so it fits a script. A composite GitHub Action also keeps a single comment on the pull request up to date.
Does it need an account or a service?
No. The contract is a plain JSON file you can read, diff and commit, and the README says there is no service and no account involved. It runs locally on Playwright against any page a browser can render.