saltcat-color-palette

A dynamic color palette generation library that constructs palettes based on designated colors with hue offsets.

Features

• Dynamic Palette Construction: Pass in designated colors and automatically determine their place in the palette
• Hue-Based Positioning: Colors are mapped to appropriate positions (e.g., blue-500, green-600) based on hue and lightness
• Full Scale Generation: Generate complete color scales (50-900) for each designated color
• Hue Offsets: Create extended palettes with analogous colors using hue offsets
• Color Grading: Apply professional color grading controls
• LUT Support: Load and apply color lookup tables for advanced color transformations

Installation

npm install saltcat-color-palette

CLI Usage

Generate color palettes from the command line with automatic contrast analysis:

# Basic palette with contrast linting
npx saltcat-palette "#3b82f6,#10b981,#ef4444"

# Extended palette with hue offsets
npx saltcat-palette --extended "#3b82f6"

# Use color harmony algorithms
npx saltcat-palette --algorithm complementary "#3b82f6"
npx saltcat-palette --algorithm triadic "#3b82f6"
npx saltcat-palette --algorithm tetradic "#3b82f6"

# Skip contrast analysis
npx saltcat-palette --no-lint "#3b82f6"

The CLI will output a complete color palette with terminal color swatches for each shade and automatically run contrast analysis to ensure accessibility compliance.

Usage

Basic Palette Generation

import { ColorPalette } from 'saltcat-color-palette';

const palette = new ColorPalette();

// Add designated colors
palette.addDesignatedColor('primary', '#3b82f6');    // Blue brand color
palette.addDesignatedColor('secondary', '#10b981');  // Teal accent color

// Generate the palette
const colorPalette = palette.generatePalette();

console.log(colorPalette['blue-500']);   // '#3b82f6' (original color)
console.log(colorPalette['blue-400']);   // Lighter shade
console.log(colorPalette['blue-600']);   // Darker shade
console.log(colorPalette['teal-600']);   // '#10b981' mapped to teal-600

Extended Palette with Hue Offsets

const extendedPalette = palette.generateExtendedPalette();
// Includes analogous colors with ±30° hue offsets

Color Grading

import { configureGrading } from 'saltcat-color-palette';

// Apply grading adjustments
configureGrading({
  grading: {
    red: { lift: 0.1, gamma: 1, gain: 1 },
    luminance: { lift: 0, gamma: 1.1, gain: 1 }
  }
});

LUT Support

import { setLUT, loadLUTFromFile } from 'saltcat-color-palette';

// Set a custom LUT function
setLUT((color) => {
  // Apply custom transformation
  return color;
});

// Or load from file
loadLUTFromFile('./my-lut.json');

Color Linting

import { linters } from 'saltcat-color-palette';

const palette = new ColorPalette();
palette.addDesignatedColor('brand', '#3b82f6');
const colorPalette = palette.generatePalette();

// Check contrast between adjacent shades
const results = linters.lintContrast(colorPalette, {
  minContrastRatio: 1.2,  // Minimum contrast ratio
  failOnIssues: false     // Don't throw on issues
});

if (!results.passed) {
  console.log('Contrast issues found:', results.issues.length);
  results.issues.forEach(issue => {
    console.log(`${issue.colorName}-${issue.shade1} vs ${issue.colorName}-${issue.shade2}: ${issue.ratio}`);
  });
}

API

ColorPalette

Constructor

new ColorPalette(options?: {
  minBrightness?: number;  // 0-1, default 0
  maxBrightness?: number;  // 0-1, default 1
})

Methods

• addDesignatedColor(name: string, color: string): Add a designated color
• generatePalette(): object: Generate basic palette
• generateExtendedPalette(): object: Generate palette with hue offsets

Grading Functions

• configureGrading(config: object): Configure color grading parameters
• applyGrading(color: Color): Apply grading to a color

LUT Functions

• setLUT(lutFunction: Function): Set LUT transformation function
• applyLUT(color: Color): Apply LUT to a color
• loadLUTFromFile(filePath: string): Load LUT from JSON file

Linters

• linters.lintContrast(palette, options?): Check contrast ratios between adjacent shades
• linters.calculateContrastRatio(color1, color2): Calculate WCAG contrast ratio between two colors
• linters.groupColorsByName(palette): Group palette colors by base color name
• linters.checkShadeContrast(colorGroup, minRatio?): Check contrast within a color group

Palette Building Algorithms

• paletteBuilders.buildAnalogousPalette(palette, angle?, count?): Add adjacent colors on the color wheel
• paletteBuilders.buildComplementaryPalette(palette): Add opposite colors (180° apart)
• paletteBuilders.buildTriadicPalette(palette): Add two colors equally spaced at 120°
• paletteBuilders.buildTetradicPalette(palette): Add three colors in two complementary pairs
• paletteBuilders.buildHexadicPalette(palette): Add five colors equally spaced at 60°
• paletteBuilders.buildWavePalette(palette, steps?, hueRange?): Create a smooth gradient wave of colors
• paletteBuilders.buildGoldenRatioPalette(palette, count?): Add colors using golden ratio spacing

Color Harmony Algorithms

The library includes several color harmony algorithms to automatically generate related color palettes:

• Analogous: Colors adjacent on the color wheel (e.g., blue, blue-green, green)
• Complementary: Colors opposite each other (e.g., blue and orange)
• Triadic: Three colors equally spaced (e.g., blue, red, yellow)
• Tetradic: Four colors in two complementary pairs (90° spacing)
• Hexadic: Six colors equally spaced around the wheel (60° spacing)
• Wave: Smooth gradient of colors across a hue range
• Golden Ratio: Colors spaced using the golden ratio (φ ≈ 1.618) for aesthetically pleasing relationships

Color Positioning Logic

Colors are automatically positioned in the palette based on:

1. Hue: Mapped to the closest Tailwind color name (blue, green, teal, etc.)
2. Lightness: Determines the shade (50-900)
   • Very light colors → 50-100
   • Medium colors → 400-600
   • Dark colors → 700-900

Dependencies

• colorjs.io: Advanced color manipulation
• chroma-js: Color utilities

License

MIT