Facet

facet-check

Check a web page for responsive design problems on real phone, tablet and desktop viewports. It runs from the command line, in CI, or as an MCP server that AI coding agents (Claude Code, Cursor, Codex, VS Code) can call.

npx @chandra14/facet-check localhost:3000

Or install it once with npm install -g @chandra14/facet-check, then run facet-check localhost:3000.

Output for a test page with a price table that is too wide for phones (shortened):

Facet check http://localhost:3000

6 devices · 14 errors · 14 warnings

✗ iPhone 16 393×852 @3x error Page scrolls sideways by 267px — The document is 660px wide in a 393px viewport. error Extends 267px past the viewport — “SizeWhole beanGroundSubscriptionWholesal” html > body > main > table fix: Constrain it with max-width: 100%, min-width: 0 on a flex child, overflow-wrap: anywhere, or let it scroll inside its own container. error Tap target is 13 × 13px — #weekly fix: Targets must be at least 24 × 24px (WCAG 2.5.8); 44 × 44px is comfortable. warn Field text is 14px, so iOS zooms in on focus — #email fix: Give form controls font-size: 16px or larger. console Carousel failed to initialise at 393px

! Full HD laptop at 125% (most common) 1536×864 @1.25x warn Text is only 10px — “Prices include tax. Orders placed after ”

Each device is a real emulation in headless Chromium, not a resized window. It uses the device's viewport, pixel ratio, touch support, mobile viewport behaviour and user agent. A page with no viewport meta tag lays out at 980px on a phone, as it would on the real device.

It is the command-line and agent side of Facet, an open-source browser for responsive web development. Facet's device catalogue has 290+ profiles, from the iPhone SE to 2026 flagships, foldables, tablets, laptops and 4K monitors.

What it finds

On every device:

• Horizontal scrolling, and the element that causes it (the table, not each of its cells)
• Tap targets smaller than 24 × 24px on touch devices (WCAG 2.5.8)
• Text smaller than 12px, and text that is cut off without an ellipsis
• Form fields under 16px, which make iOS zoom in when focused
• Viewport meta problems: missing, not device-width, or zoom disabled
• Images that are far larger than needed, blurry on high-density screens, or missing dimensions
• Fixed headers and banners that cover too much of a small screen
• Console errors, uncaught exceptions and failed requests, per device. An error that only one device logs is a viewport-specific bug.

Command line

npx @chandra14/facet-check <url> [options]

The URL can be a full URL, a bare host (example.com), a local dev server (localhost:3000, :5173) or a path to an HTML file.

Presets: popular (the six most common real-world sizes), default (phone, tablet, laptop), phones, latest, tablets, desktops, apple, foldables, extremes.

npx @chandra14/facet-check localhost:3000 -d phones --screenshots shots

npx @chandra14/facet-check https://example.com -d iphone-17,"Galaxy S26",ipad,1440x900 --json

In CI

The exit code is 1 when errors are found, so it can gate a pull request:

- run: npx @chandra14/facet-check http://localhost:4173 --fail-on error

MCP server for AI agents

facet-check mcp runs a Model Context Protocol server over stdio. An agent can then check its own CSS changes on many screen sizes and look at the result.

Claude Code

claude mcp add facet -- npx -y @chandra14/facet-check mcp

Cursor, VS Code, Claude Desktop and other clients

{

"mcpServers": { "facet": { "command": "npx", "args": ["-y", "@chandra14/facet-check", "mcp"] } } }

Then ask, for example: *"Check localhost:3000 on phones and fix anything that scrolls sideways."*

Requirements

Node 20 or later and a Chromium-based browser. facet-check uses, in order: the browser at FACET_CHROME, Playwright's Chromium (npx playwright install chromium), Google Chrome, then Microsoft Edge. Most machines already have one of these.

Limits

• Chromium only. An iPhone profile emulates the iPhone's screen, not Safari's WebKit engine. Safari-specific bugs still need Safari.
• It checks the page as it is after load. Content behind a login or a click is out of reach from the command line.

License

MIT