How it works

Nightfall follows a three-step pipeline: Scan → Analyze → Generate.

1. Launch Playwright — visits each route in a headless browser
2. Auto-Detect Direction — determines light or dark mode by analyzing background lightness in OKLCH
3. DOM Walk — traverses every visible element, collecting background-color, color, border-color, box-shadow, and more
4. Build Color Graph — creates a relationship map of what sits on what
5. Classify Roles — assigns semantic roles (background.page, text.primary, brand.primary, etc.)
6. Transform — applies OKLCH-space transformations based on direction
7. Export — writes the theme in your chosen format

The color graph maps relationships between colors in your UI:

Page Background (#ffffff)
  └── Card Surface (#f8f9fa)
        ├── Card Border (#e5e7eb)
        ├── Heading Text (#111827)    → 18.1:1 contrast
        ├── Body Text (#374151)       → 11.2:1 contrast
        ├── Muted Text (#9ca3af)      →  4.6:1 contrast
        └── Accent Button (#2563eb)   →  4.8:1 contrast
              └── Button Text (#ffffff)

Each node knows its parent (what it sits on) and the contrast ratio between them. This graph is preserved during transformation.

All transformations happen in OKLCH — a perceptually uniform color space where equal numerical changes produce equal visual changes. This means a dark theme generated by Nightfall looks natural, not mathematically inverted.

• L — Lightness (0 = black, 1 = white)
• C — Chroma (saturation intensity)
• H — Hue (0-360 degrees)

Nightfall auto-detects your theme direction by:

1. Sampling the page background color
2. Computing weighted average lightness of all background surfaces
3. If average L > 0.6 → light mode → generates dark
4. If average L < 0.4 → dark mode → generates light
5. If ambiguous (0.4–0.6) → falls back to --direction flag