Function Signature

js

generateShadeScale(baseHex: string, options?: {
  steps?: number,
  direction?: "darker" | "lighter" | "both",
  includeBase?: boolean,
  minL?: number,
  maxL?: number,
  easing?: (t: number) => number
}): string[]

Parameters

baseHex (string): The base HEX color string (e.g., #ff6600).
options.steps (number, optional): Number of colors in the scale. Defaults to 10.
options.direction ("darker" | "lighter" | "both", optional): Direction of scale. Defaults to "darker".
options.includeBase (boolean, optional): Whether to include the base color. Defaults to true.
options.minL (number, optional): Minimum lightness in Lab (0–100). Defaults to 8.
options.maxL (number, optional): Maximum lightness in Lab (0–100). Defaults to 98.
options.easing (function, optional): Easing function mapping t ∈ [0,1] to control distribution.

Return Value

An array of HEX color strings representing the shade scale. The sequence depends on the selected direction and whether the base color is included.

js

generateShadeScale("#ff6600", { steps: 5, direction: "darker" });
// ["#ff6600", "#d24000", "#a71300", "#7f0000", "#5b0000"]

generateShadeScale("#ff6600", { steps: 7, direction: "both", includeBase: true });
// ["#5b0000", "#8c0000", "#c43300", "#ff6600", "#ff872e", "#ffa84f", "#ffca6f"]

generateShadeScale("#ff6600", { steps: 4, direction: "both", includeBase: true });
// ["#5b0000", "#ff6600", "#ff973e", "#ffca6f"]

Examples

js

// Dark-only scale
console.log(generateShadeScale("#ff6600", { steps: 3 }));
// ["#ff6600", "#a71300", "#5b0000"]

// Light-only scale
console.log(generateShadeScale("#ff6600", { steps: 4, direction: "lighter" }));
// ["#ff6600", "#ff973e", "#ffb65a", "#ffca6f"]

// Both directions, including base
console.log(generateShadeScale("#ff6600", { steps: 5, direction: "both" }));
// ["#5b0000", "#a71300", "#ff6600", "#ff973e", "#ffca6f"]

Implementation Details

Normalizes the base HEX with normalizeHex.
Converts to Lab via hexToRgb → rgbToLab.
Interpolates lightness (L) values toward minL or maxL based on direction.
Uses optional easing(t) to adjust distribution spacing.
Converts back to HEX using labToRgb → rgbToHex.
Includes both darker and lighter branches if direction = "both".

Usage Notes

Scales are perceptually even due to Lab interpolation, unlike simple RGB scaling.
Darker and lighter branches are symmetrically distributed when using both.
The easing option allows for non-linear shade distributions (e.g., exponential, logarithmic).
Clamps values to valid RGB (0–255) to ensure proper output.