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 — <table.prices> “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 — <input#weekly>
        #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 — <input#email>
        #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 — <p#terms> “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]

Option
-d, --devices <list>	Device ids, names, sizes like 1024x768, or a preset (default: popular)
-s, --screenshots <dir>	Save a PNG of each device
--full-page	Capture the whole page, not only the first screen
--json	Print the full report as JSON
--all	Also list info-level notes
--fail-on <level>	Exit 1 when a finding is at least error (default), warn or info; never always exits 0
--timeout <ms>	Page load timeout (default 30000)
--list-devices [query]	Show presets and the device catalogue

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"] }
  }
}

Tool	What it does
check_responsive	Loads a URL on several devices and returns the problems on each, with selectors and fixes
screenshot	Returns one labelled image per device (viewport or full page)
compare_element	Measures one element on every device: size, visibility, font size, display, flex and grid
audit_accessibility	Runs axe-core on one device and returns WCAG violations with fixes
list_devices	Lists the device catalogue and presets

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