Check your layout

Catching overlaps, overflow and layout shift while you work and in your tests.

buttery checks layout in three places: LayoutGuard while you work, buttery check on the running app, and expectButtery in your tests. Use them together, so a layout problem shows up the moment you make it and can't come back once it's fixed.

While you work

In a Vite development build, ButteryProvider turns on LayoutGuard. It outlines in red anything that breaks a layout rule, such as an overlap, an overflow or a space off the scale, and logs each problem to the console as [buttery:LayoutGuard] with how to fix it.

Production builds never include it, and layoutGuard={false} on ButteryProvider leaves it out in development too.

On the running app

npx buttery check / /settings

buttery check runs the checks expectButtery runs on each page you name, at 390 and 1280 wide, light and dark, starting the app's dev server when it isn't running. --full checks every width, both densities and WebKit too. Command line has its options.

In your tests

expectButtery runs the same checks and more in Playwright, at every width, theme and density you give it. Start with quickMatrix in every test, and run fullMatrix before a release. Testing has its options and every check it runs.

Reading a report

A failed check prints each problem with its rule, the element as a selector, what it measured and a fix:

buttery found 1 layout problem:

✗ orders at 390x844, light, comfortable, chromium
  overflow      html: the page scrolls sideways by 51px
                Fix: Something is wider than the viewport; fix the overflow violations above, or let the widest element shrink.

buttery check --json prints the problems it finds as JSON, for a script or a coding agent to work through, as pnpm test:layout --reporter=json does in buttery's own repository.