Getting Started

Project Overview

Ultimate Dark Mode is an open-source Chrome extension (Manifest V3) that applies dark mode to all websites. It is AI-built and community-driven, with GitHub agents that triage issues, generate site-specific overrides from screenshots, and iterate on user feedback.

Key Principles

• MV3 only — uses Manifest V3 APIs (service workers, not background pages)
• No production dependencies — the extension ships zero npm dependencies; dev tooling only
• Performance matters — content scripts run on every page; they must be fast and small
• Preserve images — never invert or alter images, videos, canvases, or SVGs with photographic content
• Site overrides are CSS-only — override files in src/content/overrides/ are pure CSS, keyed by domain
• NEVER use filter: invert() — no blind color inversion; always use explicit color remapping (see ADR-001)

Architecture at a Glance

The extension uses a three-layer engine. Sites with a dedicated CSS override skip Layers 2 and 3 entirely.

Layer	What it does	Always applied?
Layer 1	Native dark mode forcing (color-scheme: dark)	Yes
Layer 2	Generic CSS with oklch-based dark palette	Only if no override exists
Layer 3	JS MutationObserver for inline styles	Only if no override exists

See the Architecture page for the full breakdown.

How Site Overrides Work

When a site has a dedicated override file (e.g., src/content/overrides/harvestapp.com.css), the extension:

1. Applies Layer 1 (native dark mode — always safe)
2. Skips Layer 2 (generic CSS) entirely
3. Skips Layer 3 (JS mutation observer) entirely
4. Injects the site-specific CSS instead

Override files are matched by base domain. For example, rocketlab.harvestapp.com matches harvestapp.com.css.

All override CSS is wrapped in @layer darkmode.overrides { ... } and scoped with html[data-darkmode].

Code Style

• Vanilla JS (no framework, no TypeScript for now)
• ES modules where supported by Chrome extension APIs
• 2-space indentation, no semicolons (standardjs style)

Commands

Run tests

pnpm test

This runs unit tests via vitest and validates all override CSS files.

Validate overrides only

pnpm validate

Run extension integration tests

# Headless
pnpm test:extension

# Test a specific URL
pnpm test:extension -- https://example.com

# Headed (visible browser)
pnpm test:headed

File Conventions

• Site override CSS: src/content/overrides/{domain}.css (e.g., harvestapp.com.css)
• Subdomain matching: sub.example.com matches example.com.css
• Icons: 16, 48, 128px PNGs in icons/
• Tests: tests/ directory, run via vitest