🌙 BlackMagic Framework

A powerful JavaScript framework for implementing intelligent dark mode with automatic color adjustment and WCAG-compliant contrast optimization.

See the demo! and read the docs

✨ Features

• 🎨 Smart Color Adjustment - Automatically adjusts colors while maintaining readability
• ♿ WCAG Compliant - Ensures 4.5:1 contrast ratio for accessibility
• 💾 Dual Storage - Uses both cookies and localStorage for maximum compatibility
• 🎭 Theme Class Support - Works with CSS-based themes or dynamic color conversion
• ⚙️ Highly Configurable - Multiple options for customization
• ⚡ Zero Dependencies - Pure JavaScript, no external libraries
• 🌐 Cross-Browser - Works on all modern browsers

🚀 Quick Start

CDN (Recommended)

<script src="https://cdn.jsdelivr.net/npm/blackmagic-js@latest/dist/blackmagic.min.js"></script>

NPM

npm install blackmagic-js

Basic Usage

// Initialize BlackMagic
const blackMagic = new BlackMagic({
    cookieName: 'my-theme',
    backgroundColor: '#1a1a1a',
    factor: 0.4
});

// Add toggle functionality
document.getElementById('toggleBtn').addEventListener('click', () => {
    blackMagic.toggle();
});

📖 Documentation

Configuration Options

Option	Type	Default	Description
cookieName	string	'darkmode'	Cookie name for storing theme preference
backgroundColor	string	'#000'	Dark mode background color
localStorageKey	string	'darkmode'	localStorage key for theme storage
themeClass	string	undefined	CSS class to toggle instead of dynamic colors
cookieDuration	number	365	Cookie expiration time in days
autoSwitch	boolean	true	Automatically apply saved theme on page load
factor	number	0.4	Intensity of color adjustments (0.1-0.8)

Methods

toggle()

Switches between light and dark themes.

getCurrentTheme()

Returns the current theme ('light' or 'dark').

applyTheme(theme)

Applies a specific theme.

• theme (string): Either 'light' or 'dark'

getStoredTheme()

Returns the stored theme preference from cookies or localStorage.

Advanced Configuration

CSS Class Mode

const blackMagic = new BlackMagic({
    themeClass: 'dark-theme',
    autoSwitch: true
});

Custom Color Adjustment

const blackMagic = new BlackMagic({
    backgroundColor: '#2d2d2d',
    factor: 0.6, // More dramatic color changes
    cookieDuration: 30 // Remember for 30 days
});

🧪 Examples & Testing

This repository includes comprehensive examples demonstrating various use cases:

• Basic Example - Simple implementation
• Comprehensive Test - Full feature testing with complex UI
• Theme Class Mode - Using CSS classes instead of dynamic colors
• Factor Testing - High/low intensity color adjustments
• Settings Tests - Auto-switch, custom backgrounds, cookie duration
• Debug Tools - Persistence testing and troubleshooting

Running Examples

# Clone the repository
git clone https://github.com/LucAngevare/BlackMagic-js.git
cd BlackMagic-js

# Start local server
npm run dev

# Open examples
open http://localhost:8000/examples/

Or just look at the already running examples at blackmagic.lucangevare.nl.

🏗️ Project Structure

BlackMagic-js/
├── src/
│   └── blackmagic.js          # Source code
├── dist/
│   ├── blackmagic.js          # UMD build
│   └── blackmagic.esm.js      # ES Module
├── examples/
│   ├── basic/                 # Basic usage examples
│   ├── comprehensive/         # Full feature tests
│   ├── theme-class/          # CSS class mode
│   ├── factors/              # Color adjustment tests
│   ├── settings/             # Configuration tests
│   └── debug/                # Debug tools
├── package.json
└── README.md

🎯 How It Works

Intelligent Color Adjustment

BlackMagic uses advanced algorithms to:

1. Analyze Text Colors - Detects current text colors in the DOM
2. Calculate Backgrounds - Walks up the DOM tree to find actual background colors
3. Ensure Contrast - Calculates contrast ratios using WCAG standards
4. Optimize Colors - Adjusts colors to maintain 4.5:1 contrast ratio
5. Preserve Semantics - Keeps important UI colors (buttons, alerts) unchanged

Storage Strategy

The framework uses a dual storage approach:

1. Cookies (Primary) - Works across all environments
2. localStorage (Fallback) - Provides additional reliability

Accessibility

All color adjustments ensure WCAG AA compliance:

• Minimum 4.5:1 contrast ratio
• Proper luminance calculations
• Gamma correction applied
• Fallback to pure black/white when needed

🌍 Browser Support

• ✅ Chrome 60+
• ✅ Firefox 60+
• ✅ Safari 12+
• ✅ Edge 79+
• ✅ Opera 47+

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• WCAG guidelines for accessibility standards
• Modern CSS color theory and contrast calculations
• Community feedback and testing

📞 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

---

⭐ If you find BlackMagic useful, please consider giving it a star! ⭐