Nightfall CSS

Basic Usage

npx nightfall-css scan --url http://localhost:3000

This launches Playwright, visits the root route, and extracts all computed styles including background colors, text colors, border colors, box shadows, and CSS variables.

Multi-Route Scanning

Pass multiple routes to scan your entire application. Nightfall deduplicates colors across routes and merges results into a single color graph:

npx nightfall-css scan --url http://localhost:3000 --routes / /about /pricing /dashboard

# Scan routes from a file (one route per line)
npx nightfall-css scan --url http://localhost:3000 --routes-file routes.txt

What Gets Extracted

For every visible DOM element, Nightfall collects:

Computed styles — background-color, color, border-color, box-shadow, outline-color
CSS custom properties — All --var declarations on :root and scoped elements
Tailwind classes — Detected utility classes like bg-slate-100, text-gray-900
Element relationships — Parent-child nesting to build the color graph
Contrast ratios — WCAG contrast between every foreground/background pair

Options

npx nightfall-css scan --url URL [options]

Options:
  --url <url>            Target URL (required)
  --routes <paths...>    Routes to visit (default: /)
  --routes-file <file>   Load routes from a file
  --direction <dir>      Force direction: light-to-dark | dark-to-light | both
  --wait <ms>            Wait time after page load (default: 1000)
  --viewport <WxH>       Viewport size (default: 1280x720)
  --auth <cookie>        Authentication cookie to inject
  --ignore <selectors>   CSS selectors to skip
  --output <path>        Save scan data to file (default: .nightfall/scan.json)
  --verbose              Show detailed scan progress

Authentication

For pages behind authentication, pass a session cookie:

npx nightfall-css scan \
  --url http://localhost:3000 \
  --routes /dashboard /settings \
  --auth "session=abc123; Path=/; HttpOnly"

Scan Output

The scan produces a JSON file at .nightfall/scan.json containing the full color graph. You can inspect it to see what Nightfall found:

.nightfall/scan.json

{
  "version": "0.1.0",
  "scannedAt": "2026-04-08T12:00:00Z",
  "direction": "light-to-dark",
  "routes": ["/", "/about"],
  "colors": {
    "backgrounds": [
      { "value": "oklch(0.99 0.002 240)", "role": "page", "area": 921600 },
      { "value": "oklch(1.00 0.000 0)", "role": "surface", "area": 345600 }
    ],
    "text": [
      { "value": "oklch(0.15 0.01 240)", "role": "heading", "contrastOn": "page" },
      { "value": "oklch(0.30 0.01 240)", "role": "body", "contrastOn": "surface" }
    ],
    "borders": [...],
    "shadows": [...],
    "brand": [...]
  },
  "variables": {
    "--bg-primary": "#fafafa",
    "--text-primary": "#111827"
  }
}

Ignoring Elements

Skip elements that should not be theme-transformed (e.g., images, videos, third-party widgets):

npx nightfall-css scan \
  --url http://localhost:3000 \
  --ignore "img, video, iframe, [data-nightfall-ignore]"