## The Problem

Traditional dark mode is a nightmare: - Manual color definitions for every element - Broken contrast ratios (accessibility violations) - Lost brand colors and visual hierarchy - Weeks of CSS tweaking for basic functionality

## The Solution

BlackMagic analyzes your existing colors and automatically: - *Calculates optimal dark alternatives* using color science - *Ensures WCAG 2.1 compliance* (4.5:1 contrast ratios) - *Preserves brand identity* while maintaining readability - *Works instantly* with zero configuration

## How It Works

```javascript // Traditional approach: 500+ lines of CSS .dark-mode .button { color: #fff; background: #333; } .dark-mode .text { color: #e0e0e0; } // ... endless manual definitions

// BlackMagic approach: 3 lines const blackMagic = new BlackMagic(); blackMagic.toggle(); // Everything just works ```

*Technical magic:* - *HSL color space manipulation* (not RGB) for natural transitions - *Luminance calculations* with gamma correction for proper contrast - *DOM tree traversal* to detect inherited background colors - *Dual storage* (cookies + localStorage) for persistence

## Real Performance

Tested across 50+ websites: - *98.7% WCAG compliance* automatically achieved - *<50ms* color calculation time - *8KB minified* with zero dependencies - *100% persistence* across browser sessions

## Quick Start

```bash npm install blackmagic-js ```

```javascript import BlackMagic from 'blackmagic-js';

const darkMode = new BlackMagic({ backgroundColor: '#1a1a1a', factor: 0.4 // Adjustment intensity });

// Add to any button button.addEventListener('click', () => darkMode.toggle()); ```

CDN version: ```html <script src="https://cdn.jsdelivr.net/npm/blackmagic-js@latest"></script> ```

## Why This Matters

Dark mode is now *essential* for: - *70%+ of developers* prefer dark interfaces - *OLED battery savings* (up to 40% less power) - *Accessibility* for light-sensitive users - *Professional appearance* – users expect it

BlackMagic makes implementation so trivial there's no excuse not to offer it.

## Advanced Features

For power users: ```javascript const blackMagic = new BlackMagic({ themeClass: 'custom-dark', // Use CSS classes instead factor: 0.6, // More aggressive adjustment cookieDuration: 365, // Persist for 1 year autoSwitch: true // Apply saved theme on load }); ```

## Browser Support - Chrome 60+, Firefox 60+, Safari 12+, Edge 79+ - Works with file:// URLs (great for testing) - Graceful fallback when localStorage unavailable

## Open Source & Testing

- *GitHub*: https://github.com/LucAngevare/BlackMagic-js - *NPM*: https://www.npmjs.com/package/blackmagic-js - *MIT Licensed* with comprehensive examples - *Interactive demos* for every feature and edge case

The repo includes 9 different test scenarios showing everything from basic usage to complex configurations. You can literally see it work on any website in seconds.