## 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.