PHP Contrast Tools

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 [email protected] instead of using the issue tracker.

Credits

• Omigosh Dev
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

PHP Package Boilerplate

This package was generated using the PHP Package Boilerplate.