I've been frustrated with dark mode implementations for years. Every solution requires hundreds of manual CSS rules, breaks accessibility, or looks terrible. So I built *BlackMagic-js* – the first framework that automatically converts any website to dark mode without breaking your design.
## 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.