seer

Catch CSS layout bugs automatically — no screenshots needed.

Like ESLint, but for rendered CSS. Seer detects horizontal overflow, covered buttons, tiny touch targets, and other structural bugs that slip through code review.

seer check http://localhost:3000

❌ OVERFLOW Horizontal overflow detected (page scrolls 740px beyond viewport)
   └─ Element: div.hero-banner
   └─ Fix: Add overflow-x: hidden or check for elements with fixed widths

❌ CLICKABILITY Interactive element is covered by another element
   └─ Element: button.submit-btn
   └─ Covered by: div.modal-backdrop
   └─ Fix: Check z-index or remove covering element

⚠️  TOUCH-TARGETS Touch target too small: 32x28px (min: 44x44px)
   └─ Element: a.nav-link
   └─ Fix: Add min-width: 44px and min-height: 44px

──────────────────────────────────────────────────
Results: 2 errors, 1 warning, 47 passed
──────────────────────────────────────────────────

The Problem

CSS bugs are invisible in code review. Your PR looks fine, tests pass, but then:

• The page scrolls horizontally on mobile
• A modal backdrop covers your buttons
• Touch targets are too small for actual fingers

These aren't styling issues — they're structural bugs that can be detected programmatically using getBoundingClientRect(), getComputedStyle(), and elementFromPoint().

Installation

Note: First run downloads Chromium (~150MB) and takes ~30-60 seconds. Subsequent runs are instant.

npm install seer-css playwright

Quick Start

# Check any URL
npx seer check https://example.com

# Check your dev server
npx seer check http://localhost:3000

# Check multiple viewports (mobile + desktop)
npx seer check --viewport 375x667,1920x1080 http://localhost:3000

# Auto-detect framework and start dev server
npx seer dev

Checks

| Check | Severity | What it catches | |-------|----------|-----------------| | overflow | error | Horizontal scrollbars from content wider than viewport | | clickability | error | Buttons/links covered by other elements (z-index bugs) | | touch-targets | warning | Elements smaller than 44×44px (WCAG 2.5.5) | | visibility | warning | Interactive elements that are invisible or off-screen | | text-overflow | warning | Text clipped without proper ellipsis handling |

Framework Support

Seer auto-detects your framework and handles hydration:

# Auto-detect and start dev server
npx seer dev --routes /,/about,/contact

# Specify framework manually
npx seer dev --framework nextjs --routes /,/api/health

Supported: Next.js, SvelteKit, Vite, Remix, Astro, Nuxt, Create React App

Playwright Integration

import { test, expect } from '@playwright/test';
import { checkPage } from 'seer-css';

test('homepage has no CSS issues', async ({ page }) => {
  await page.goto('/');
  const results = await checkPage(page);
  expect(results.summary.errors).toBe(0);
});

Library Usage

import { chromium } from 'playwright';
import { checkPage } from 'seer-css';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('http://localhost:3000');

const results = await checkPage(page);
console.log(results.summary);
// { passed: 47, errors: 1, warnings: 2 }

await browser.close();

MCP Server (for AI Agents)

Seer includes an MCP server for integration with Claude Code and other AI tools:

{
  "mcpServers": {
    "seer": {
      "command": "npx",
      "args": ["seer-mcp"]
    }
  }
}

Available tools:

• check_page — Check a URL for CSS issues
• check_html — Check raw HTML content
• check_file — Check a local HTML file
• screenshot — Take a screenshot (returns image for visual debugging)

Configuration

// seer.config.js
export default {
  checks: {
    overflow: { horizontal: true },
    touchTargets: { minWidth: 44, minHeight: 44 },
    clickability: { checkCorners: true },
    textOverflow: { allowEllipsis: true },
  },
  ignore: ['.tooltip', '[data-seer-ignore]'],
};

Ignoring Elements

<!-- Skip specific elements -->
<input type="checkbox" data-seer-ignore>

CI Integration

# .github/workflows/css-health.yml
name: CSS Health Check
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build
      - run: npm start & npx wait-on http://localhost:3000
      - run: npx seer check --fail-on warning http://localhost:3000

Tip: Chromium downloads automatically on first run. For faster CI, cache ~/.cache/ms-playwright or pre-install with npx playwright install chromium.

CLI Reference

seer check <urls...>
  -v, --viewport <size>      Viewport size (e.g., 375x667,1920x1080)
  -f, --format <format>      Output: text, json, junit
  -o, --only <checks>        Run specific checks only
  -i, --ignore <selectors>   Ignore matching elements
  -c, --config <path>        Config file path
  --fail-on <severity>       Exit code 1 on: error, warning
  --headed                   Show browser window
  --wait-for-hydration       Wait for SPA hydration

seer dev
  -r, --routes <routes>      Routes to check (default: /)
  -p, --port <port>          Dev server port
  --framework <name>         Framework override
  --no-start-server          Use existing dev server

How It Works

Seer doesn't compare screenshots. Instead, it queries the DOM:

// Overflow detection
document.documentElement.scrollWidth > document.documentElement.clientWidth

// Covered element detection
document.elementFromPoint(x, y) !== expectedElement

// Touch target detection
element.getBoundingClientRect().width < 44

These checks are deterministic, fast, and don't require human review.

Why Not Visual Regression?

Visual regression (screenshot comparison) catches everything but requires human review for every change. Seer catches structural bugs that are objectively wrong:

| Visual Regression | Seer | |-------------------|------| | Catches color changes | Catches layout bugs | | Requires baseline images | No baselines needed | | Needs human review | Fully automated | | Slow (image comparison) | Fast (DOM queries) |

Use both! Visual regression for design fidelity, Seer for structural correctness.

License

MIT