README

Provides various utilities for working with color contrast.

The primary purpose is to facilitate easy generation of accessible (minimum 3.0 contrast ratio) hex color pairs. A variation of these tools restricts the generated colors to TailwindCSS's default palette.

I've created a demo page to show how color pairs can be generated by this package.

Installation

You can install the package via composer:

composer require breadthe/php-contrast

Usage

Import the class.

use Breadthe\PhpContrast\HexColor; // factory

use Breadthe\PhpContrast\HexColorPair; // hex pair utilities

use Breadthe\PhpContrast\TailwindColor; // Tailwind color pair utilities

Check the contrast ratio between 2 colors

$hexColorPair = HexColorPair::make(HexColor::make('000000'), HexColor::make('ffffff'));
$hexColorPair->ratio; // 21
$hexColorPair->fg; // '#000000'
$hexColorPair->bg; // '#ffffff'

Get a random color pair (with the resulting ratio), with minimum 3:1 contrast ratio

$hexColorPair = HexColorPair::random();
$hexColorPair->ratio; // 3.8
$hexColorPair->fg->hex; // '#36097e'
$hexColorPair->fg->name; // null
$hexColorPair->bg->hex; // '#ed4847'
$hexColorPair->bg->name; // null

Get a random color pair (with the resulting ratio), with minimum specified contrast ratio (but no less than 3:1)

⚠️ Warning For performance reasons, the minimum requested contrast ratio is capped at 4.5, although the generated pairs can go up to the theoretical maximum 21:1 ratio.

⚠️ Caution When chaining with minContrast(), make sure to use getRandom() instead of random().

$hexColorPair = HexColorPair::minContrast(4.5)->getRandom();
$hexColorPair->ratio; // 7.6
$hexColorPair->fg->hex; // '#0c402f'
$hexColorPair->fg->name; // null
$hexColorPair->bg->hex; // '#badd73'
$hexColorPair->bg->name; // null

Get a random accessible sibling for the given color, with minimum specified contrast ratio (but no less than 3:1)

// Minimum 3:1 contrast ratio
HexColorPair::sibling('000000')->hex; // '#ffffff'

// Minimum specified contrast ratio (no less than 3:1)
HexColorPair::minContrast(4.5)->getSibling('000000')->hex; // '#ffffff'

Generate a random TailwindCSS color

$twColor = TailwindColor::random();
$twColor->hex; // '#e2e8f0'
$twColor->name; // 'gray-300'

Generate a pair of random accessible TailwindCSS colors

$twColorpair = TailwindColor::randomPair();
$twColorpair->ratio; // 3.3
$twColorpair->fg->hex; // '#63b3ed'
$twColorpair->fg->name; // 'blue-400'
$twColorpair->bg->hex; // '#4a5568'
$twColorpair->bg->name; // 'green-700'

Generate a pair of random accessible TailwindCSS colors, with minimum specified contrast ratio (but no less than 3:1)

⚠️ Warning For performance reasons, the minimum requested contrast ratio is capped at 4.5, although the generated pairs can go up to the theoretical maximum 21:1 ratio.

⚠️ Caution When chaining with minContrast(), make sure to use getRandomPair() instead of randomPair().

$twColorpair = TailwindColor::minContrast(4.5)->getRandomPair();
$twColorpair->ratio; // 7.0
$twColorpair->fg->hex; // '#faf5ff'
$twColorpair->fg->name; // 'purple-100'
$twColorpair->bg->hex; // '#9b2c2c'
$twColorpair->bg->name; // 'red-800'

Merge the default Tailwind colors with a custom palette

You may extend the default Tailwind colors with your own custom palette. Here's an example of how to import a custom palette from a JSON file.

{
    "background": "#FFFFFF",
    "headline": "#1f1235",
    "sub-headline": "#1b1425",
    "button": "#ff6e6c",
    "button-text": "#1f1235"
}

$customPalette = json_decode(file_get_contents('custom-palette.json'), true);

$colors = TailwindColor::merge($customPalette)->getColors();

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email omigoshdev@protonmail.com instead of using the issue tracker.

breadthe / php-contrast

Maintainers

Details