socialdept/color-scales

What is Color Scales?

Color Scales is a Laravel package that generates beautiful, Tailwind-compatible color palettes from any input color. Using perceptually uniform color spaces (OKLCH & HSLuv), it creates 11-shade palettes (50-950) that match the quality of professional color tools like tints.dev and uicolors.app.

Think of it as your personal color palette designer that understands color science.

Why use Color Scales?

• Matches tints.dev - Generates palettes identical to the popular tints.dev tool
• Perceptually uniform - Uses OKLCH and HSLuv for visually consistent results
• Automatic shade detection - Intelligently determines where your input color fits (50-950)
• Dual modes - Choose between perceived (HSLuv) or linear (HSL) distribution
• Multiple formats - Export as HEX, RGB, HSL, OKLCH, or Tailwind config
• RGB gamut clamping - Automatically adjusts out-of-gamut colors

Quick Example

use SocialDept\ColorScales\Generator\ColorScaleGenerator;

$generator = new ColorScaleGenerator();

// Generate a palette from any color
$palette = $generator->generate('#d8b965');

// Get colors as hex values
$colors = $palette->toHex();
// [
//   '50' => '#f6f4e9',
//   '100' => '#ede9d3',
//   '200' => '#dbd3a7',
//   '300' => '#d8b965', // Input color (auto-detected as shade 300)
//   '400' => '#c9a94d',
//   ...
// ]

// Or export as Tailwind CSS config
$config = $palette->toTailwindConfig('gold');
// 'gold': {
//   50: '#f6f4e9',
//   100: '#ede9d3',
//   ...
// }

Installation

composer require socialdept/color-scales

Basic Usage

Generating Palettes

Color Scales accepts multiple input formats:

use SocialDept\ColorScales\Generator\ColorScaleGenerator;

$generator = new ColorScaleGenerator();

// From hex
$palette = $generator->generate('#511ef3');

// From RGB
$palette = $generator->generate('rgb(81, 30, 243)');

// From HSL
$palette = $generator->generate('hsl(254, 88%, 54%)');

// From OKLCH
$palette = $generator->generate('oklch(0.48 0.29 275)');

Choosing a Mode

Select between perceived (default, matches tints.dev) or linear mode:

// Perceived mode (HSLuv) - perceptually uniform, best for design
$palette = $generator->generate('#d8b965', ['mode' => 'perceived']);

// Or use the convenience method
$palette = $generator->generatePerceived('#d8b965');

// Linear mode (HSL) - mathematically simple
$palette = $generator->generate('#d8b965', ['mode' => 'linear']);

// Or use the convenience method
$palette = $generator->generateLinear('#d8b965');

Perceived mode uses relative luminance for shade detection and HSLuv for color generation, matching tints.dev's output exactly. Linear mode uses HSL lightness for both, producing a simpler mathematical distribution.

Advanced Options

Customize palette generation with additional parameters:

$palette = $generator->generate('#511ef3', [
    'mode' => 'perceived',    // 'perceived' or 'linear'
    'h' => 0,                 // Hue shift amount
    's' => 0,                 // Saturation shift amount
    'lMin' => 0,              // Minimum lightness (darkest shade)
    'lMax' => 100,            // Maximum lightness (lightest shade)
    'valueStop' => 500,       // Force input color to specific shade (auto-detected by default)
]);

Export Formats

Export your palette in multiple formats:

$palette = $generator->generate('#511ef3');

// Hex strings
$hex = $palette->toHex();
// ['50' => '#f2f1ff', '100' => '#e7e6ff', ...]

// RGB strings
$rgb = $palette->toRgb();
// ['50' => 'rgb(242, 241, 255)', ...]

// HSL strings
$hsl = $palette->toHsl();
// ['50' => 'hsl(245, 100%, 97%)', ...]

// OKLCH strings
$oklch = $palette->toOklch();
// ['50' => 'oklch(0.975 0.02 275)', ...]

// Tailwind CSS v4 config format (@theme) - OKLCH (default)
$config = $palette->toTailwindV4Config('primary', 'oklch');
// @theme {
//   --color-primary-50: oklch(0.975 0.02 275);
//   --color-primary-100: oklch(0.95 0.04 275);
//   ...
// }

// Tailwind CSS v4 config format - HEX
$config = $palette->toTailwindV4Config('primary', 'hex');
// @theme {
//   --color-primary-50: #f2f1ff;
//   --color-primary-100: #e7e6ff;
//   ...
// }

// Tailwind CSS v4 config format - RGB
$config = $palette->toTailwindV4Config('primary', 'rgb');
// @theme {
//   --color-primary-50: rgb(242 241 255);
//   --color-primary-100: rgb(231 230 255);
//   ...
// }

// Tailwind CSS v4 config format - HSL
$config = $palette->toTailwindV4Config('primary', 'hsl');
// @theme {
//   --color-primary-50: hsl(245.0 100.0% 97.3%);
//   --color-primary-100: hsl(245.0 100.0% 95.1%);
//   ...
// }

// Tailwind CSS v3 config format (OKLCH with alpha)
$config = $palette->toTailwindV3Config('primary', 'oklch');
// 'primary': {
//   50: 'oklch(0.975 0.02 275 / <alpha-value>)',
//   100: 'oklch(0.95 0.04 275 / <alpha-value>)',
//   ...
// }

// Tailwind CSS v3 config format (HEX - legacy)
$config = $palette->toTailwindV3Config('primary', 'hex');
// 'primary': {
//   50: '#f2f1ff',
//   100: '#e7e6ff',
//   ...
// }

// Array (alias for toHex)
$array = $palette->toArray();

Accessing Individual Shades

Get specific shades or all Color objects:

$palette = $generator->generate('#511ef3');

// Get a specific shade
$shade500 = $palette->getShade(500);

// Access color properties
$oklch = $shade500->toOklch();
// ['l' => 0.48, 'c' => 0.29, 'h' => 275]

// Get all Color objects
$colors = $palette->getColors();
// [50 => Color, 100 => Color, ..., 950 => Color]

Use Cases

Tailwind CSS Theme

$generator = new ColorScaleGenerator();

$colors = [
    'primary' => $generator->generate('#3b82f6'),
    'success' => $generator->generate('#10b981'),
    'warning' => $generator->generate('#f59e0b'),
    'danger' => $generator->generate('#ef4444'),
];

// Export for Tailwind v4 (CSS @theme)
foreach ($colors as $name => $palette) {
    echo $palette->toTailwindV4Config($name) . "\n\n";
}

// Or export for Tailwind v3 (OKLCH with alpha support)
foreach ($colors as $name => $palette) {
    echo $palette->toTailwindV3Config($name, 'oklch') . "\n\n";
}

Dynamic Theming

// User selects brand color
$brandColor = $request->input('brand_color');

// Generate complete palette
$palette = $generator->generate($brandColor);

// Store in database or cache
cache()->put("brand_palette_{$userId}", $palette->toHex(), now()->addDay());

Design System Generator

// Generate multiple palettes from a base color
$baseColor = '#511ef3';

$palettes = [
    'default' => $generator->generate($baseColor),
    'vibrant' => $generator->generate($baseColor, ['s' => 10]),
    'muted' => $generator->generate($baseColor, ['s' => -10]),
];

// Export as CSS variables
foreach ($palettes['default']->toHex() as $shade => $hex) {
    echo "--color-{$shade}: {$hex};\n";
}

Accessibility Tool

// Generate palette and analyze contrast
$palette = $generator->generate('#2563eb');

$textColor = $palette->getShade(50)->toHex();  // Light text
$bgColor = $palette->getShade(900)->toHex();   // Dark background

// Calculate contrast ratio for accessibility
// (integrate with your contrast checker)

Testing

The package includes comprehensive tests validating palette generation accuracy:

./vendor/bin/phpunit

Tests ensure generated palettes match tints.dev output within acceptable tolerance.

Requirements

• PHP 8.2+
• Laravel 11+ (optional - package works standalone)
• hsluv/hsluv ^2.0 - HSLuv color space conversions

Resources

• tints.dev - Color palette generator inspiration
• OKLCH Color Space - Perceptually uniform colors
• HSLuv - Human-friendly HSL alternative
• Tailwind CSS - Color palette system

Support & Contributing

Found a bug or have a feature request? Open an issue.

Want to contribute? We'd love your help! Check out the contribution guidelines.

Credits

• Miguel Batres - founder & lead maintainer
• Inspired by tints.dev by Simeon Griggs

License

Color Scales is open-source software licensed under the MIT license.

Built for Tailwind Developers • By Social Dept.