Color Generation

The generate API provides color generation, harmonies, palettes, and color manipulation. All functions are available via api.generate.

Shades, Tints & Scales

`shades(rgb: RGB, count: number): RGB[]`

Generate darker shades by mixing with black.

const base = { r: 255, g: 0, b: 0 };
const shades = api.generate.shades(base, 5);
console.log(shades);
// [
//   { r: 204, g: 0, b: 0 },  // 20% darker
//   { r: 153, g: 0, b: 0 },  // 40% darker
//   { r: 102, g: 0, b: 0 },  // 60% darker
//   { r: 51, g: 0, b: 0 },   // 80% darker
//   { r: 0, g: 0, b: 0 }     // 100% darker (black)
// ]

`tints(rgb: RGB, count: number): RGB[]`

Generate lighter tints by mixing with white.

const base = { r: 255, g: 0, b: 0 };
const tints = api.generate.tints(base, 5);
console.log(tints);
// [
//   { r: 255, g: 51, b: 51 },   // 20% lighter
//   { r: 255, g: 102, b: 102 }, // 40% lighter
//   { r: 255, g: 153, b: 153 }, // 60% lighter
//   { r: 255, g: 204, b: 204 }, // 80% lighter
//   { r: 255, g: 255, b: 255 }  // 100% lighter (white)
// ]

`tones(rgb: RGB, count: number): RGB[]`

Generate tones by mixing with gray (desaturation).

const base = { r: 255, g: 0, b: 0 };
const tones = api.generate.tones(base, 5);
// Returns progressively desaturated versions

`scale(rgb: RGB, shadesCount: number, tintsCount: number): RGB[]`

Generate complete color scale with shades, base, and tints.

const base = { r: 99, g: 102, b: 241 };
const scale = api.generate.scale(base, 4, 4);
console.log(scale.length); // 9 colors (4 shades + base + 4 tints)
 
// Common use: 10-step scale for design systems
const tenStepScale = api.generate.scale(base, 4, 5);

`perceptualShades(rgb: RGB, count: number): RGB[]`

Generate perceptually uniform shades (using OKLAB).

const base = { r: 255, g: 0, b: 0 };
const shades = api.generate.perceptualShades(base, 5);
// More evenly spaced perceptually than regular shades

Better for design systems where visual uniformity matters.

`perceptualTints(rgb: RGB, count: number): RGB[]`

Generate perceptually uniform tints (using OKLAB).

const tints = api.generate.perceptualTints(base, 5);

Color Harmonies

`harmony(rgb: RGB, type: HarmonyType): RGB[]`

Generic harmony generator.

const base = { r: 255, g: 0, b: 0 };
const colors = api.generate.harmony(base, 'triadic');

Available Types:

'complementary'
'analogous'
'triadic'
'tetradic'
'splitComplementary'
'square'
'monochromatic'

`complementary(rgb: RGB): RGB[]`

Generate complementary colors (opposite on color wheel).

const base = { r: 255, g: 0, b: 0 }; // Red
const colors = api.generate.complementary(base);
console.log(colors);
// [
//   { r: 255, g: 0, b: 0 },   // Original (red)
//   { r: 0, g: 255, b: 255 }  // Complement (cyan)
// ]

Returns: 2 colors (180° apart)

`analogous(rgb: RGB): RGB[]`

Generate analogous colors (adjacent on color wheel).

const base = { r: 255, g: 0, b: 0 }; // Red
const colors = api.generate.analogous(base);
console.log(colors);
// [
//   { r: 255, g: 128, b: 0 },  // -30° (orange)
//   { r: 255, g: 0, b: 0 },    // Original (red)
//   { r: 255, g: 0, b: 128 }   // +30° (magenta)
// ]

Returns: 3 colors (base ±30°)

`triadic(rgb: RGB): RGB[]`

Generate triadic colors (evenly spaced on wheel).

const base = { r: 255, g: 0, b: 0 }; // Red
const colors = api.generate.triadic(base);
// [red, green, blue] - 120° apart

Returns: 3 colors (120° apart)

`tetradic(rgb: RGB): RGB[]`

Generate tetradic/rectangular colors.

const colors = api.generate.tetradic(base);

Returns: 4 colors forming rectangle on color wheel

`splitComplementary(rgb: RGB): RGB[]`

Generate split-complementary colors.

const base = { r: 255, g: 0, b: 0 }; // Red
const colors = api.generate.splitComplementary(base);
// [red, cyan-green, cyan-blue]

Returns: 3 colors (base + two colors adjacent to complement)

`square(rgb: RGB): RGB[]`

Generate square harmony colors.

const colors = api.generate.square(base);

Returns: 4 colors (90° apart)

`monochromatic(rgb: RGB): RGB[]`

Generate monochromatic variations (same hue, different lightness).

const base = { r: 255, g: 0, b: 0 };
const colors = api.generate.monochromatic(base);
// Returns 5-7 variations of red with different lightness

Variations

`hueVariations(rgb: RGB, count: number, step: number): RGB[]`

Generate colors by shifting hue.

const base = { r: 255, g: 0, b: 0 };
const variations = api.generate.hueVariations(base, 5, 30);
// Shifts hue by 30° for each step
// [0°, 30°, 60°, 90°, 120°]

`saturationVariations(rgb: RGB, count: number): RGB[]`

Generate variations with different saturation.

const variations = api.generate.saturationVariations(base, 5);
// From fully desaturated to fully saturated

`lightnessVariations(rgb: RGB, count: number): RGB[]`

Generate variations with different lightness.

const variations = api.generate.lightnessVariations(base, 5);
// From dark to light

`subtleVariations(rgb: RGB, count: number): RGB[]`

Generate subtle variations (small hue/saturation/lightness changes).

const base = { r: 99, g: 102, b: 241 };
const variations = api.generate.subtleVariations(base, 5);
// Barely noticeable differences - great for UI backgrounds

`dramaticVariations(rgb: RGB, count: number): RGB[]`

Generate dramatic variations (large changes).

const variations = api.generate.dramaticVariations(base, 5);
// Highly contrasting colors

Color Adjustments

`adjustHue(rgb: RGB, degrees: number): RGB`

Shift hue by specified degrees.

const red = { r: 255, g: 0, b: 0 };
const orange = api.generate.adjustHue(red, 30);
console.log(orange); // Hue shifted +30°
 
const purple = api.generate.adjustHue(red, -30);
// Negative values shift counter-clockwise

`adjustSaturation(rgb: RGB, amount: number): RGB`

Adjust saturation by amount (-100 to +100).

const color = { r: 255, g: 100, b: 100 };
const moreSaturated = api.generate.adjustSaturation(color, 20);
const lessSaturated = api.generate.adjustSaturation(color, -20);

`adjustLightness(rgb: RGB, amount: number): RGB`

Adjust lightness by amount (-100 to +100).

const lighter = api.generate.adjustLightness(color, 20);
const darker = api.generate.adjustLightness(color, -20);

`saturate(rgb: RGB, amount: number): RGB`

Increase saturation (convenience wrapper).

const saturated = api.generate.saturate(color, 30);
// Same as adjustSaturation(color, 30)

`desaturate(rgb: RGB, amount: number): RGB`

Decrease saturation (convenience wrapper).

const desaturated = api.generate.desaturate(color, 30);
// Same as adjustSaturation(color, -30)

`lighten(rgb: RGB, amount: number): RGB`

Make color lighter.

const original = { r: 100, g: 100, b: 100 };
const lighter = api.generate.lighten(original, 20);
console.log(lighter); // Lighter gray

`darken(rgb: RGB, amount: number): RGB`

Make color darker.

const darker = api.generate.darken(original, 20);

`invert(rgb: RGB): RGB`

Invert color (complement in RGB space).

const red = { r: 255, g: 0, b: 0 };
const cyan = api.generate.invert(red);
console.log(cyan); // { r: 0, g: 255, b: 255 }

Formula: 255 - component

`grayscale(rgb: RGB): RGB`

Convert to grayscale.

const color = { r: 255, g: 100, b: 50 };
const gray = api.generate.grayscale(color);
console.log(gray); // { r: 135, g: 135, b: 135 }

Uses perceptual weighting for accurate grayscale.

`mix(color1: RGB, color2: RGB, weight: number): RGB`

Mix two colors (weight 0-1).

const red = { r: 255, g: 0, b: 0 };
const blue = { r: 0, g: 0, b: 255 };
const purple = api.generate.mix(red, blue, 0.5);
console.log(purple); // { r: 127, g: 0, b: 127 }
 
// More red
const reddishPurple = api.generate.mix(red, blue, 0.7);
 
// More blue
const bluishPurple = api.generate.mix(red, blue, 0.3);

Weight: 0 = all color2, 1 = all color1

Color Blindness Simulation

`simulateColorBlindness(rgb: RGB, type: ColorBlindnessType): RGB`

Simulate how color appears with color vision deficiency.

const red = { r: 255, g: 0, b: 0 };
 
// Protanopia (red-blind)
const protanopia = api.generate.simulateColorBlindness(red, 'protanopia');
console.log(protanopia); // Appears brownish
 
// Deuteranopia (green-blind)
const deuteranopia = api.generate.simulateColorBlindness(red, 'deuteranopia');
 
// Tritanopia (blue-blind)
const tritanopia = api.generate.simulateColorBlindness(red, 'tritanopia');

Available Types:

'protanopia' - Red-blind (~1% males)
'deuteranopia' - Green-blind (~1% males)
'tritanopia' - Blue-blind (rare)
'protanomaly' - Red-weak (~1% males)
'deuteranomaly' - Green-weak (~5% males)
'tritanomaly' - Blue-weak (rare)
'achromatopsia' - Complete color blindness (very rare)
'achromatomaly' - Partial color blindness (very rare)

`simulateAllColorBlindness(rgb: RGB): ColorBlindnessSimulation`

Simulate all types at once.

const red = { r: 255, g: 0, b: 0 };
const simulations = api.generate.simulateAllColorBlindness(red);
console.log(simulations);
// {
//   protanopia: { r: ..., g: ..., b: ... },
//   deuteranopia: { r: ..., g: ..., b: ... },
//   tritanopia: { r: ..., g: ..., b: ... },
//   protanomaly: { r: ..., g: ..., b: ... },
//   deuteranomaly: { r: ..., g: ..., b: ... },
//   tritanomaly: { r: ..., g: ..., b: ... },
//   achromatopsia: { r: ..., g: ..., b: ... },
//   achromatomaly: { r: ..., g: ..., b: ... }
// }

Color Matching

`findClosestColor(rgb: RGB): ColorMatch`

Find closest named color from 300+ database.

const color = { r: 250, g: 10, b: 10 };
const match = api.generate.findClosestColor(color);
console.log(match);
// {
//   color: {
//     name: "Red",
//     hex: "#FF0000",
//     category: "Red",
//     rgb: { r: 255, g: 0, b: 0 }
//   },
//   distance: 10.5
// }

Uses Delta-E 2000 for perceptually accurate matching.

`findClosestColors(rgb: RGB, count: number): ColorMatch[]`

Find N closest named colors.

const color = { r: 100, g: 150, b: 200 };
const matches = api.generate.findClosestColors(color, 5);
console.log(matches);
// [
//   { color: { name: "Steel Blue", ... }, distance: 8.2 },
//   { color: { name: "Cornflower Blue", ... }, distance: 12.5 },
//   ...
// ]

`getColorCategories(): string[]`

Get all color categories.

const categories = api.generate.getColorCategories();
console.log(categories);
// ["Red", "Orange", "Yellow", "Green", "Blue", 
//  "Purple", "Pink", "Brown", "Gray", "White", "Black"]

`findColorsByCategory(category: string): NamedColor[]`

Get all colors in a category.

const reds = api.generate.findColorsByCategory("Red");
console.log(reds);
// [
//   { name: "Red", hex: "#FF0000", category: "Red", rgb: {...} },
//   { name: "Crimson", hex: "#DC143C", category: "Red", rgb: {...} },
//   { name: "Fire Brick", hex: "#B22222", category: "Red", rgb: {...} },
//   ...
// ]

Palette Generation

`semanticPalette(rgb: RGB, mode: ThemeMode): SemanticPalette`

Generate complete UI palette from base color.

const base = { r: 99, g: 102, b: 241 };
const palette = api.generate.semanticPalette(base, 'dark');
console.log(palette);
// {
//   primary: { r: 99, g: 102, b: 241 },
//   secondary: { r: 241, g: 99, b: 194 },
//   accent: { r: 99, g: 241, b: 194 },
//   success: { r: 34, g: 197, b: 94 },
//   warning: { r: 251, g: 191, b: 36 },
//   error: { r: 239, g: 68, b: 68 },
//   info: { r: 59, g: 130, b: 246 },
//   background: { r: 15, g: 15, b: 25 },
//   surface: { r: 25, g: 25, b: 35 },
//   text: { r: 255, g: 255, b: 255 },
//   textMuted: { r: 156, g: 163, b: 175 },
//   border: { r: 55, g: 65, b: 81 },
//   onPrimary: { r: 255, g: 255, b: 255 },
//   onSuccess: { r: 255, g: 255, b: 255 },
//   onWarning: { r: 0, g: 0, b: 0 },
//   onError: { r: 255, g: 255, b: 255 },
//   onInfo: { r: 255, g: 255, b: 255 }
// }

Modes: 'light' or 'dark'

Perfect for generating complete design system palettes.

`primaryScale(rgb: RGB): RGB[]`

Generate 10-step primary color scale.

const base = { r: 99, g: 102, b: 241 };
const scale = api.generate.primaryScale(base);
console.log(scale.length); // 10
// [lightest → darkest]
// Commonly used as: primary-50, primary-100, ..., primary-900

`neutralScale(rgb: RGB): RGB[]`

Generate 10-step neutral/gray scale based on color.

const base = { r: 99, g: 102, b: 241 };
const grays = api.generate.neutralScale(base);
// Grays tinted with base color
// More harmonious than pure grays

`darkModeColor(rgb: RGB): RGB`

Generate dark mode variant of color.

const lightColor = { r: 99, g: 102, b: 241 };
const darkColor = api.generate.darkModeColor(lightColor);
// Adjusted for dark backgrounds

`lightModeColor(rgb: RGB): RGB`

Generate light mode variant of color.

const darkColor = { r: 59, g: 62, b: 191 };
const lightColor = api.generate.lightModeColor(darkColor);
// Adjusted for light backgrounds

Type Definitions

type HarmonyType = 
  | 'complementary'
  | 'analogous'
  | 'triadic'
  | 'tetradic'
  | 'splitComplementary'
  | 'square'
  | 'monochromatic';
 
type ColorBlindnessType =
  | 'protanopia'
  | 'deuteranopia'
  | 'tritanopia'
  | 'protanomaly'
  | 'deuteranomaly'
  | 'tritanomaly'
  | 'achromatopsia'
  | 'achromatomaly';
 
type ThemeMode = 'light' | 'dark';
 
interface NamedColor {
  name: string;
  hex: string;
  category: string;
  rgb: RGB;
}
 
interface ColorMatch {
  color: NamedColor;
  distance: number;
}
 
interface SemanticPalette {
  primary: RGB;
  secondary: RGB;
  accent: RGB;
  success: RGB;
  warning: RGB;
  error: RGB;
  info: RGB;
  background: RGB;
  surface: RGB;
  text: RGB;
  textMuted: RGB;
  border: RGB;
  onPrimary: RGB;
  onSuccess: RGB;
  onWarning: RGB;
  onError: RGB;
  onInfo: RGB;
}
 
interface ColorBlindnessSimulation {
  protanopia: RGB;
  deuteranopia: RGB;
  tritanopia: RGB;
  protanomaly: RGB;
  deuteranomaly: RGB;
  tritanomaly: RGB;
  achromatopsia: RGB;
  achromatomaly: RGB;
}

Color Generation

On this page