npx hoverlab

There is nothing to install. npx fetches the current version each time, which is what you want for a tool you run a handful of times per project.

npx hoverlab help

If you reach for it often enough to mind the fetch, npm i -g hoverlab works too.

# a single block
npx hoverlab add pricing-tiers

# several at once
npx hoverlab add pricing-tiers faq-accordion footer-mega

# a page — writes the page and every block it imports
npx hoverlab add checkout-page

# an effect, tweaked on the way in
npx hoverlab add btn-gradient --hue 40 --speed 1.5

Where files land. Effects go into a hoverlab/ folder inside your components or styles directory. Blocks and pages keep their own paths — components/pricing-tiers.tsx, app/checkout/page.tsx — rooted at your project, or at src/ if you use one. That is not a preference: page sources import their blocks by those paths, so moving them breaks the imports. --dir overrides it if you know what you are doing.

Hoverlab installs source you own, which is the point — and the reason a fix to a block could never reach you once it was in your repo. add now records what it wrote in a hoverlab.lock.json beside your package.json, and outdated compares that against the catalog.

# what has moved on since you installed it
npx hoverlab outdated

# what actually changed in one of them
npx hoverlab diff pricing-tiers

# machine-readable, for CI
npx hoverlab outdated --json

Neither command writes. There is deliberately no --fix. The file is yours and you have probably edited it; a command that overwrote local changes on the strength of a hash comparison would be the most destructive thing this CLI could do. diff shows you what changed and the merge is your call.

A template is a whole project — routes, pages, blocks and config. init writes it into a new directory.

# see what is available
npx hoverlab init

# scaffold one
npx hoverlab init storefront ./shop

cd shop && npm install && npm run dev

Search covers all four tiers at once and ranks them together, which matters when a word like “pricing” names a block, a page and thirty effects.

npx hoverlab search checkout
npx hoverlab search "pulsing teal button" --level effect
npx hoverlab search pricing --level block --featured
npx hoverlab show pricing-tiers --deep

review reads your source. audit-url loads the running site in a real browser and reports what only exists once a page is rendered: the contrast ratio of text against the background actually underneath it, spacing and colour that drift from the site's own scale, and what breaks when the page is laid out right-to-left. Each finding names the closest tool, primitive or command in the catalog.

npx hoverlab audit-url https://staging.example.com

# also load it with dir=rtl and report what breaks
npx hoverlab audit-url http://localhost:3000 --dir rtl

# a phone-sized viewport, dark scheme, and more pages on the same origin
npx hoverlab audit-url https://example.com --viewport mobile --dark --pages /pricing,/docs

# machine-readable, or a pull-request comment body
npx hoverlab audit-url https://example.com --json
npx hoverlab audit-url https://example.com --format markdown

Tokens are inferred, not assumed. Nothing here compares your site to Hoverlab's design. It reads the computed values your page painted, works out the scale they follow (a 4px spacing grid, a handful of radii and type sizes) and reports the values that break it: a 13px padding on a 4px grid, a 7px radius among 8px ones, a near-duplicate grey. Only rare values close to a dominant one are reported, and every finding carries its counts so you can overrule it.

It needs Playwright. The CLI itself has no dependencies, so the browser driver is not installed with it. Add it to the project you run the command from:

npm i -D playwright && npx playwright install chromium

Without it the command prints that line and exits with code 2. If Playwright's Chromium is missing but Chrome or Edge is installed, that is used instead. axe-core is optional: when it can be found its contrast results are merged in, and the built-in measurement works without it.

It reports what it measured and says what it did not: text over images and gradients, hover and focus states, pages behind a login, and real Arabic or Hebrew copy are outside what one rendering can show.

The CLI doubles as an MCP server so your editor's agent can search and install from the catalog directly. See the MCP docs.