BlackMagic-js

BlackMagic Framework

BlackMagic is a robust JavaScript framework designed for seamless integration of intelligent dark mode features into web applications. This framework not only facilitates automatic color adjustments but also ensures compliance with accessibility standards through its built-in WCAG contrast optimization.

Key Features

• Smart Color Adjustment: Automatically modify colors while preserving readability to enhance user experience in dark mode.
• WCAG Compliance: Achieve a minimum contrast ratio of 4.5:1, ensuring accessibility for all users.
• Dual Storage Solution: Utilizes both cookies and localStorage for maintaining theme preferences across browser sessions.
• Theme Class Support: Compatible with existing CSS themes or allows for dynamic color conversions.
• Highly Configurable: Offers multiple customization options to align with developers' needs.
• Zero Dependencies: A pure JavaScript solution that can function independently without external libraries.
• Cross-Browser Compatibility: Ensures consistent performance across all modern browsers.

Quick Start

To get started with BlackMagic, incorporate it into your project via CDN or NPM:

CDN (Recommended)

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

NPM

npm install blackmagic-js

Basic Usage Example

Initialize BlackMagic with customizable options:

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

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

Configuration Options

Users can tailor their implementation using these configuration options:

Available Methods

• toggle(): Switches between light and dark themes.
• getCurrentTheme(): Returns the current theme ('light' or 'dark').
• applyTheme(theme): Applies a specified theme, either 'light' or 'dark'.
• getStoredTheme(): Retrieves the stored theme preference from cookies or localStorage.

Advanced Configurations

Utilize advanced features for custom implementations:

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

Customize background and color adjustment intensities as needed:

const blackMagic = new BlackMagic({
    backgroundColor: '#2d2d2d',
    factor: 0.6,
    cookieDuration: 30
});

Accessibility Compliance

Every color adjustment prioritizes WCAG AA adherence, ensuring:

• A minimum contrast ratio of 4.5:1,
• Accurate luminance calculations,
• Optional gamma correction,
• Reliable fallbacks to pure black or white when necessary.

Browser Support

BlackMagic guarantees functionality across:

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

Contribution

Contribution to the BlackMagic project is welcomed. Interested parties can fork the repository, create a feature branch, make necessary changes, and submit a pull request for consideration.

Support and Documentation

Comprehensive documentation and support options are available, alongside community discussions and issue reporting on the project's GitHub page.
Explore various examples provided to enhance understanding of functionality and use cases.