Package com.smartgwt.client.util

Class Colors

java.lang.Object
com.smartgwt.client.util.Colors
public class Colors extends Object
Utility class for color format conversion, validation, and manipulation. Accepts any valid CSS color specification (hex, rgb/rgba, hsl/hsla, oklch, named colors, "transparent") and converts between formats. See the Color Overview for a detailed guide to color spaces, formats, manipulation, CSS color relationships, and palettes.

The core entry points are getColor() to parse any color into a Color object (with RGB, HSL, and oklch properties pre-computed), getString() to convert back to a CSS string, and getValues() for raw numeric components in a single color space. adjust() is the general-purpose manipulation method - all convenience methods like lighten(), saturate(), etc. delegate to it.

See the Color Overview for a full guide organized by topic: conversion, inspection, manipulation (including alpha compositing), palettes and harmony, theme generation, and CSS color relationships.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Colors()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    adjust(String color, Map deltas)
    The general-purpose method for deriving a related color from a base color.
    static String
    adjust(String color, Map deltas, ColorFormat outputFormat)
    The general-purpose method for deriving a related color from a base color.
    static String[]
    analogous(Color color)
    Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel.
    static String[]
    analogous(Color color, int results)
    See analogous()
    static String[]
    analogous(Color color, int results, int slices)
    See analogous()
    static String[]
    analogous(Color color, int results, int slices, ColorFormat outputFormat)
    Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel.
    static String[]
    analogous(String color)
    Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel.
    static String[]
    analogous(String color, int results)
    See analogous()
    static String[]
    analogous(String color, int results, int slices)
    See analogous()
    static String[]
    analogous(String color, int results, int slices, ColorFormat outputFormat)
    Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel.
    static Color
    autoContrast(Color background)
    Returns a text color that meets a target contrast ratio against the given background.
    static Color
    autoContrast(Color background, Map options)
    Returns a text color that meets a target contrast ratio against the given background.
    static Color
    autoContrast(String background)
    Returns a text color that meets a target contrast ratio against the given background.
    static Color
    autoContrast(String background, Map options)
    Returns a text color that meets a target contrast ratio against the given background.
    static String
    brighten(String color, double amount)
    Returns a brighter, more vivid version of the given color by boosting both chroma (color intensity) and lightness together.
    static String
    brighten(String color, double amount, ColorFormat outputFormat)
    Returns a brighter, more vivid version of the given color by boosting both chroma (color intensity) and lightness together.
    static String[]
    colorScale(Color color1, Color color2, int steps)
    Generates an array of evenly-spaced colors between two Color endpoints, interpolated in the oklch color space for perceptual uniformity.
    static String[]
    colorScale(Color color1, Color color2, int steps, ColorFormat format)
    Generates an array of evenly-spaced colors between two Color endpoints, interpolated in the oklch color space for perceptual uniformity.
    static String[]
    colorScale(Color color1, Color color2, int steps, ColorFormat format, ColorFormat space)
    Generates an array of evenly-spaced colors between two Color endpoints, interpolated in the specified color space.
    static String[]
    colorScale(String color1, String color2, int steps)
    Generates an array of evenly-spaced colors between two endpoints, interpolated in oklch by default.
    static String[]
    colorScale(String color1, String color2, int steps, ColorFormat format)
    Generates an array of evenly-spaced colors between two endpoints, interpolated in the oklch color space for perceptual uniformity.
    static String[]
    colorScale(String color1, String color2, int steps, ColorFormat format, ColorFormat space)
    Generates an array of evenly-spaced colors between two endpoints, interpolated in the specified color space.
    static String
    complement(Color color)
    Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees).
    static String
    complement(Color color, ColorFormat outputFormat)
    Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees).
    static String
    complement(String color)
    Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees).
    static String
    complement(String color, ColorFormat outputFormat)
    Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees).
    static Double
    contrast(Color color1, Color color2)
    Returns the approximate perceptual contrast ratio between two Color objects, based on oklch lightness.
    static Double
    contrast(String color1, String color2)
    Returns the approximate perceptual contrast ratio between two colors, based on oklch lightness.
    static String
    darken(String color, double amount)
    Returns a darker version of the given color.
    static String
    darken(String color, double amount, ColorFormat outputFormat)
    Returns a darker version of the given color.
    static String
    desaturate(String color, double amount)
    Returns a more muted version of the given color by reducing its chroma (color intensity).
    static String
    desaturate(String color, double amount, ColorFormat outputFormat)
    Returns a more muted version of the given color by reducing its chroma (color intensity).
    static Map
    describeRelationship(String baseColor, String derivedColor)
    Computes the perceptual relationship between two colors in oklch space and returns a structured description.
    static String
    dim(String color, double amount)
    Returns a dimmer, less vivid version of the given color — the inverse of brighten().
    static String
    dim(String color, double amount, ColorFormat outputFormat)
    Returns a dimmer, less vivid version of the given color — the inverse of brighten().
    static Double
    distance(Color color1, Color color2)
    Returns a number indicating how different two Color objects look to the human eye.
    static Double
    distance(String color1, String color2)
    Returns a number indicating how different two colors look to the human eye.
    static Boolean
    equals(Color color1, Color color2)
    Returns true if two Color objects represent the same color (same R, G, B, and alpha).
    static Boolean
    equals(String color1, String color2)
    Returns true if two color values represent the same color (same R, G, B, and alpha), regardless of input format.
    static String
    flatten(Color color)
    Returns an opaque color visually equivalent to the given semi-transparent Color composited over a background (default white).
    static String
    flatten(Color color, Color background)
    Flattens a semi-transparent Color against a background.
    static String
    flatten(Color color, Color background, ColorFormat outputFormat)
    Flattens a semi-transparent Color against a background, returning the result in the specified format.
    static String
    flatten(String color)
    Returns an opaque color visually equivalent to the given semi-transparent color composited over a background (default white).
    static String
    flatten(String color, String background)
    Flattens a semi-transparent color against a background.
    static String
    flatten(String color, String background, ColorFormat outputFormat)
    Flattens a semi-transparent color against a background, returning the result in the specified format.
    static String
    generateCSS(String origin, Map relationship)
    Converts an oklch relationship descriptor (as returned by describeRelationship() or parseRelationship()) into a CSS Relative Color Syntax expression.
    static Double
    getAlpha(Color color)
    Returns the alpha (opacity) component of the given color as a float from 0.0 (fully transparent) to 1.0 (fully opaque).
    static Double
    getAlpha(String color)
    Returns the alpha (opacity) component of the given color as a float from 0.0 (fully transparent) to 1.0 (fully opaque).
    static Color
    getColor(Color color)
    Parses any valid CSS color into a structured Color object with RGB, HSL, and oklch properties pre-computed, plus convenience methods for manipulation.
    static Color
    getColor(String color)
    Parses any valid CSS color into a structured Color object with RGB, HSL, and oklch properties pre-computed, plus convenience methods for manipulation.
    static Color
    getColor(Map color)
    Parses any valid CSS color into a structured Color object with RGB, HSL, and oklch properties pre-computed, plus convenience methods for manipulation.
    static ColorFormat
    getFormat(String color)
    Returns the ColorFormat of the given color string, or null if the value is not a valid color.
    static String
    getString(String color, ColorFormat format)
    Converts any valid CSS color to a string in the specified format.
    static Map
    getValues(String color, ColorFormat format)
    Returns a plain object with color component values in the requested format.
    static boolean
    isColor(Color color)
    Returns true if the given value is a valid CSS color specification.
    static boolean
    isColor(Color color, ColorFormat format)
    Returns true if the given value is a valid CSS color specification.
    static boolean
    isColor(String color)
    Returns true if the given value is a valid CSS color specification.
    static boolean
    isColor(String color, ColorFormat format)
    Returns true if the given value is a valid CSS color specification.
    static boolean
    isColor(Map color)
    Returns true if the given value is a valid CSS color specification.
    static boolean
    isColor(Map color, ColorFormat format)
    Returns true if the given value is a valid CSS color specification.
    static Boolean
    isDark(Color color)
    Returns true if the given color is perceptually dark (i.e.
    static Boolean
    isDark(String color)
    Returns true if the given color is perceptually dark (i.e.
    static String
    lighten(String color, double amount)
    Returns a lighter version of the given color.
    static String
    lighten(String color, double amount, ColorFormat outputFormat)
    Returns a lighter version of the given color.
    static String
    mix(Color color1, Color color2)
    Blends two Color objects in the oklch color space.
    static String
    mix(Color color1, Color color2, Double ratio)
    Blends two Color objects in the oklch color space at the given ratio.
    static String
    mix(Color color1, Color color2, Double ratio, ColorFormat outputFormat)
    Blends two Color objects in the oklch color space at the given ratio, returning the result in the specified format.
    static String
    mix(String color1, String color2)
    Blends two colors in the oklch color space, producing a single result.
    static String
    mix(String color1, String color2, Double ratio)
    Blends two colors in the oklch color space at the given ratio.
    static String
    mix(String color1, String color2, Double ratio, ColorFormat outputFormat)
    Blends two colors in the oklch color space at the given ratio, returning the result in the specified format.
    static String
    mostReadable(String background, String[] candidates)
    Returns the color from candidates that has the highest contrast against background.
    static Color[]
    palette(Color color)
    Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue.
    static Color[]
    palette(Color color, int steps)
    See palette()
    static Color[]
    palette(Color color, int steps, Map options)
    Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue.
    static Color[]
    palette(String color)
    Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue.
    static Color[]
    palette(String color, int steps)
    See palette()
    static Color[]
    palette(String color, int steps, Map options)
    Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue.
    static Map
    parseRelationship(String rcsExpr)
    Extracts structural information from a CSS Relative Color Syntax (RCS) expression - the origin reference, color space, and per-channel modifications - without evaluating it.
    static Color
    resolveCSS(String expr)
    Resolves any CSS color expression to a flat Color by evaluating it through the browser's CSS engine.
    static Color
    resolveCSS(String expr, Element element)
    Resolves any CSS color expression to a flat Color by evaluating it through the browser's CSS engine.
    static String
    saturate(String color, double amount)
    Returns a more vivid version of the given color by increasing its chroma (color intensity).
    static String
    saturate(String color, double amount, ColorFormat outputFormat)
    Returns a more vivid version of the given color by increasing its chroma (color intensity).
    static Map
    scheme(Color color)
    Generates a set of harmonious seed colors from a single primary.
    static Map
    scheme(Color color, String type)
    Generates a set of harmonious seed colors from a single primary.
    static Map
    scheme(String color)
    Generates a set of harmonious seed colors from a single primary.
    static Map
    scheme(String color, String type)
    Generates a set of harmonious seed colors from a single primary.
    static String
    setAlpha(String color, double alpha)
    Returns a new color string with the alpha (opacity) component replaced.
    static String
    setAlpha(String color, double alpha, ColorFormat outputFormat)
    Returns a new color string with the alpha (opacity) component replaced.
    static String
    spin(String color, double degrees)
    Rotates the hue of a color by the given number of degrees (in oklch space).
    static String
    spin(String color, double degrees, ColorFormat outputFormat)
    Rotates the hue of a color by the given number of degrees (in oklch space).
    static String[]
    splitComplement(Color color)
    Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly).
    static String[]
    splitComplement(Color color, ColorFormat outputFormat)
    Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly).
    static String[]
    splitComplement(String color)
    Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly).
    static String[]
    splitComplement(String color, ColorFormat outputFormat)
    Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly).
    static String[]
    tetrad(Color color)
    Returns four colors with hues spaced 90 degrees apart (square scheme).
    static String[]
    tetrad(Color color, ColorFormat outputFormat)
    Returns four colors with hues spaced 90 degrees apart (square scheme).
    static String[]
    tetrad(String color)
    Returns four colors with hues spaced 90 degrees apart (square scheme).
    static String[]
    tetrad(String color, ColorFormat outputFormat)
    Returns four colors with hues spaced 90 degrees apart (square scheme).
    static String[]
    triad(Color color)
    Returns the three triadic colors (hues spaced 120 degrees apart).
    static String[]
    triad(Color color, ColorFormat outputFormat)
    Returns the three triadic colors (hues spaced 120 degrees apart).
    static String[]
    triad(String color)
    Returns the three triadic colors (hues spaced 120 degrees apart).
    static String[]
    triad(String color, ColorFormat outputFormat)
    Returns the three triadic colors (hues spaced 120 degrees apart).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Colors

      public Colors()

  • Method Details

    • adjust

      public static String adjust(String color, Map deltas)
      The general-purpose method for deriving a related color from a base color. Accepts any combination of adjustment keys in the deltas object and returns the result as a CSS color string. Single-axis convenience wrappers - lighten(), darken(), saturate(), desaturate(), and complement() - all delegate to this method.

      Friendly percentage keys (recommended for most uses):

      • lightness (-100 to 100): positive values lighten (toward white), negative darken (toward black). See lighten()/darken.
      • saturation (-100 to 100): positive values intensify color, negative desaturate toward gray. See saturate()/desaturate.
      • hue (degrees): signed rotation around the color wheel. See complement() for the hue wheel reference.
      • alpha: signed delta to opacity (0 = transparent, 1 = opaque).

      Raw oklch keys (for fine-grained control - see the oklch color space):

      • L: signed delta to lightness (0-1). +0.1 is noticeably lighter.
      • C: signed delta to chroma (0 = gray, max ~0.4). -0.05 desaturates subtly.
      • h and alpha work the same as the friendly keys above.
      Friendly and raw keys may be mixed freely; friendly keys are applied first. The output format defaults to the input format, so rgb(...) input returns rgb(...) output, etc.

      Examples:

      Parameters:
      color - base color - any valid CSS color string or structured object from getColor()
      deltas - adjustment keys - any combination of friendly keys (lightness , saturation, hue, alpha) and/or raw oklch keys (L, C, h). See the key lists above.
      Returns:
      CSS color string in the requested format, or null if the input is not a valid color
      See Also:

    • adjust

      public static String adjust(String color, Map deltas, ColorFormat outputFormat)
      The general-purpose method for deriving a related color from a base color. Accepts any combination of adjustment keys in the deltas object and returns the result as a CSS color string. Single-axis convenience wrappers - lighten(), darken(), saturate(), desaturate(), and complement() - all delegate to this method.

      Friendly percentage keys (recommended for most uses):

      • lightness (-100 to 100): positive values lighten (toward white), negative darken (toward black). See lighten()/darken.
      • saturation (-100 to 100): positive values intensify color, negative desaturate toward gray. See saturate()/desaturate.
      • hue (degrees): signed rotation around the color wheel. See complement() for the hue wheel reference.
      • alpha: signed delta to opacity (0 = transparent, 1 = opaque).

      Raw oklch keys (for fine-grained control - see the oklch color space):

      • L: signed delta to lightness (0-1). +0.1 is noticeably lighter.
      • C: signed delta to chroma (0 = gray, max ~0.4). -0.05 desaturates subtly.
      • h and alpha work the same as the friendly keys above.
      Friendly and raw keys may be mixed freely; friendly keys are applied first. The output format defaults to the input format, so rgb(...) input returns rgb(...) output, etc.

      Examples:

      Parameters:
      color - base color - any valid CSS color string or structured object from getColor()
      deltas - adjustment keys - any combination of friendly keys (lightness , saturation, hue, alpha) and/or raw oklch keys (L, C, h). See the key lists above.
      outputFormat - format for the returned string; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string in the requested format, or null if the input is not a valid color
      See Also:

    • analogous

      public static String[] analogous(String color)
      Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults to 6 results spanning 30 degrees.
      Parameters:
      color - base color
      Returns:
      CSS color strings

    • analogous

      public static String[] analogous(Color color)
      Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults to 6 results spanning 30 degrees.
      Parameters:
      color - base color
      Returns:
      CSS color strings

    • analogous

      public static String[] analogous(String color, int results)
      See analogous()

    • analogous

      public static String[] analogous(Color color, int results)
      See analogous()

    • analogous

      public static String[] analogous(String color, int results, int slices)
      See analogous()

    • analogous

      public static String[] analogous(Color color, int results, int slices)
      See analogous()

    • analogous

      public static String[] analogous(String color, int results, int slices, ColorFormat outputFormat)
      Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults to 6 results spanning 30 degrees.
      Parameters:
      color - base color
      results - number of colors to return (default 6)
      slices - how many slices to divide the wheel into (default 30, meaning each step is 12 degrees)
      outputFormat - output format; defaults to input format
      Returns:
      CSS color strings

    • analogous

      public static String[] analogous(Color color, int results, int slices, ColorFormat outputFormat)
      Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel. Defaults to 6 results spanning 30 degrees.
      Parameters:
      color - base color
      results - number of colors to return (default 6)
      slices - how many slices to divide the wheel into (default 30, meaning each step is 12 degrees)
      outputFormat - output format; defaults to input format
      Returns:
      CSS color strings

    • autoContrast

      public static Color autoContrast(String background)
      Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability - given any background color, this method finds a foreground color that passes WCAG accessibility guidelines.

      By default, tries white first (preferred for dark backgrounds) and falls back to black. When tint is true, the result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.

      Parameters:
      background - the background color to find a readable text color for
      Returns:
      a Color meeting the contrast target, or the best available if the target cannot be met
      See Also:

    • autoContrast

      public static Color autoContrast(Color background)
      Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability - given any background color, this method finds a foreground color that passes WCAG accessibility guidelines.

      By default, tries white first (preferred for dark backgrounds) and falls back to black. When tint is true, the result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.

      Parameters:
      background - the background color to find a readable text color for
      Returns:
      a Color meeting the contrast target, or the best available if the target cannot be met
      See Also:

    • autoContrast

      public static Color autoContrast(String background, Map options)
      Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability - given any background color, this method finds a foreground color that passes WCAG accessibility guidelines.

      By default, tries white first (preferred for dark backgrounds) and falls back to black. When tint is true, the result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.

      Parameters:
      background - the background color to find a readable text color for
      options - optional settings:
      • target - minimum contrast ratio (default 4.5 for WCAG AA; use 7.0 for WCAG AAA)
      • prefer - "white" (default) or "black"; which extreme to try first
      • tint - if true, lightly tint the result toward the background's hue (default false)
      Returns:
      a Color meeting the contrast target, or the best available if the target cannot be met
      See Also:

    • autoContrast

      public static Color autoContrast(Color background, Map options)
      Returns a text color that meets a target contrast ratio against the given background. Useful for ensuring readability - given any background color, this method finds a foreground color that passes WCAG accessibility guidelines.

      By default, tries white first (preferred for dark backgrounds) and falls back to black. When tint is true, the result is lightly tinted toward the background's hue for a more polished look, while still meeting the contrast target.

      Parameters:
      background - the background color to find a readable text color for
      options - optional settings:
      • target - minimum contrast ratio (default 4.5 for WCAG AA; use 7.0 for WCAG AAA)
      • prefer - "white" (default) or "black"; which extreme to try first
      • tint - if true, lightly tint the result toward the background's hue (default false)
      Returns:
      a Color meeting the contrast target, or the best available if the target cannot be met
      See Also:

    • brighten

      public static String brighten(String color, double amount)
      Returns a brighter, more vivid version of the given color by boosting both chroma (color intensity) and lightness together. This produces an "intensified" highlight rather than a washed-out tint (as lighten() alone would) or a hue shift without luminance change (as saturate() alone would).

      A typical use is hover highlighting in charts: the highlighted color should look like a more vibrant version of the base color rather than a lighter or pinker variant.

      The amount controls both axes: lightness receives the full amount while chroma receives half, keeping the color recognizable at typical hover percentages (25–40). For independent control use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to brighten, 0-100
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • brighten

      public static String brighten(String color, double amount, ColorFormat outputFormat)
      Returns a brighter, more vivid version of the given color by boosting both chroma (color intensity) and lightness together. This produces an "intensified" highlight rather than a washed-out tint (as lighten() alone would) or a hue shift without luminance change (as saturate() alone would).

      A typical use is hover highlighting in charts: the highlighted color should look like a more vibrant version of the base color rather than a lighter or pinker variant.

      The amount controls both axes: lightness receives the full amount while chroma receives half, keeping the color recognizable at typical hover percentages (25–40). For independent control use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to brighten, 0-100
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • complement

      public static String complement(String color)
      Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent to adjust(color, {h: 180}).

      Complementary pairs produce maximum hue contrast and are commonly used for accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via adjust(): +120/-120 for triadic accents, +90/-90 for square-scheme accents.

      Parameters:
      color - any valid CSS color string or structured color object
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • complement

      public static String complement(Color color)
      Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent to adjust(color, {h: 180}).

      Complementary pairs produce maximum hue contrast and are commonly used for accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via adjust(): +120/-120 for triadic accents, +90/-90 for square-scheme accents.

      Parameters:
      color - any valid CSS color string or structured color object
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • complement

      public static String complement(String color, ColorFormat outputFormat)
      Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent to adjust(color, {h: 180}).

      Complementary pairs produce maximum hue contrast and are commonly used for accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via adjust(): +120/-120 for triadic accents, +90/-90 for square-scheme accents.

      Parameters:
      color - any valid CSS color string or structured color object
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • complement

      public static String complement(Color color, ColorFormat outputFormat)
      Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees). Equivalent to adjust(color, {h: 180}).

      Complementary pairs produce maximum hue contrast and are commonly used for accents, call-to-action elements, or alert states against a primary brand color. The oklch hue wheel: red ~30, yellow ~90, green ~145, cyan ~195, blue ~265, purple ~310. Other useful rotations via adjust(): +120/-120 for triadic accents, +90/-90 for square-scheme accents.

      Parameters:
      color - any valid CSS color string or structured color object
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • darken

      public static String darken(String color, double amount)
      Returns a darker version of the given color. Equivalent to adjust(color, {lightness: -amount}).

      The amount is a percentage (0-100) indicating how far to move toward black: 0 returns the original color, 100 returns black. Intermediate values move proportionally - darken(color, 20) always looks like "20% darker" regardless of the starting lightness.

      For multi-axis adjustments, use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to darken, 0-100
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • darken

      public static String darken(String color, double amount, ColorFormat outputFormat)
      Returns a darker version of the given color. Equivalent to adjust(color, {lightness: -amount}).

      The amount is a percentage (0-100) indicating how far to move toward black: 0 returns the original color, 100 returns black. Intermediate values move proportionally - darken(color, 20) always looks like "20% darker" regardless of the starting lightness.

      For multi-axis adjustments, use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to darken, 0-100
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • desaturate

      public static String desaturate(String color, double amount)
      Returns a more muted version of the given color by reducing its chroma (color intensity). Equivalent to adjust(color, {saturation: -amount}).

      The amount is a percentage (0-100) of chroma to remove: 0 returns the original color, 100 returns a pure gray at the same lightness.

      For multi-axis adjustments, use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to desaturate, 0-100
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • desaturate

      public static String desaturate(String color, double amount, ColorFormat outputFormat)
      Returns a more muted version of the given color by reducing its chroma (color intensity). Equivalent to adjust(color, {saturation: -amount}).

      The amount is a percentage (0-100) of chroma to remove: 0 returns the original color, 100 returns a pure gray at the same lightness.

      For multi-axis adjustments, use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to desaturate, 0-100
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • describeRelationship

      public static Map describeRelationship(String baseColor, String derivedColor)
      Computes the perceptual relationship between two colors in oklch space and returns a structured description. This is the analytical inverse of color manipulation: given a base and a derived color, it tells you what oklch adjustments were applied.

      For example, a skin has an accent color #3B82F6 and a hand-picked hover color #6BA3F8. To find out what the relationship actually is (so it can be expressed as a formula rather than a second hard-coded hex value):

      The returned object contains:

      • type - a simplified classification: "lighten", "darken", "saturate", "desaturate", "spin", "adjust" (multiple significant changes), or "identical"
      • L - oklch lightness delta (positive = lighter, 0-1 scale)
      • C - oklch chroma delta (positive = more saturated)
      • h - oklch hue delta in degrees (shortest-arc rotation, -180 to +180)

      The type classification uses perceptual thresholds: L changes > 0.01, C changes > 0.005, and hue changes > 2 degrees are considered significant. When exactly one dimension changes significantly, the type reflects that dimension. When multiple dimensions change, the type is "adjust".

      Parameters:
      baseColor - the origin/base color
      derivedColor - the derived/transformed color
      Returns:
      relationship descriptor with type, L, C, h properties
      See Also:

    • dim

      public static String dim(String color, double amount)
      Returns a dimmer, less vivid version of the given color — the inverse of brighten(). Reduces both chroma and lightness together, producing a muted, subdued appearance.
      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to dim, 0-100
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • dim

      public static String dim(String color, double amount, ColorFormat outputFormat)
      Returns a dimmer, less vivid version of the given color — the inverse of brighten(). Reduces both chroma and lightness together, producing a muted, subdued appearance.
      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to dim, 0-100
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • generateCSS

      public static String generateCSS(String origin, Map relationship)
      Converts an oklch relationship descriptor (as returned by describeRelationship() or parseRelationship()) into a CSS Relative Color Syntax expression. The generated expression uses oklch as the color space, ensuring perceptually uniform transforms.

      For example, to define a hover color that is always 10% lighter than the theme's accent, regardless of what the accent color actually is:

      The origin parameter is the CSS expression to use as the RCS origin - typically a var() reference like "var(--isc-accent)", but can also be a literal color like "#3B82F6".

      Parameters:
      origin - the CSS origin expression for the RCS - typically a var() reference or a literal color
      relationship - an object with oklch deltas: L (lightness), C (chroma), and/or h (hue). Properties that are zero, null, or omitted produce identity channel passes. Accepts the output of both describeRelationship() and parseRelationship()
      Returns:
      a CSS oklch RCS expression
      See Also:

    • getAlpha

      public static Double getAlpha(String color)
      Returns the alpha (opacity) component of the given color as a float from 0.0 (fully transparent) to 1.0 (fully opaque). Returns null if the color is not valid.

      Accepts any valid CSS color string or structured color object. Fully opaque colors that lack an explicit alpha component return 1.0. The keyword "transparent" returns 0.0.

      Parameters:
      color - any valid CSS color string or structured color object
      Returns:
      alpha component (0.0 - 1.0), or null if invalid

    • getAlpha

      public static Double getAlpha(Color color)
      Returns the alpha (opacity) component of the given color as a float from 0.0 (fully transparent) to 1.0 (fully opaque). Returns null if the color is not valid.

      Accepts any valid CSS color string or structured color object. Fully opaque colors that lack an explicit alpha component return 1.0. The keyword "transparent" returns 0.0.

      Parameters:
      color - any valid CSS color string or structured color object
      Returns:
      alpha component (0.0 - 1.0), or null if invalid

    • getColor

      public static Color getColor(String color)
      Parses any valid CSS color into a structured Color object with RGB, HSL, and oklch properties pre-computed, plus convenience methods for manipulation.

      Accepts any CSS color string (#hex, rgb(), hsl(), oklch(), named colors) or a structured component object in any supported color space: {r, g, b}, {h, s, l}, or {L, C, h}.

      Also accepts CSS Relative Color Syntax (RCS) expressions with literal color origins, such as rgb(from #3B82F6 calc(r - 0.1) g b), hsl(from #47a7e3 h s calc(l + 20)), or oklch(from #3B82F6 calc(l + 0.15) c h). The origin can be any parseable color string - hex, named, or a nested function call. Channel keywords use CSS-native ranges: RGB channels are 0-1 sRGB fractions (not 0-255), HSL s/l are 0-100, oklch L is 0-1. The origin is resolved, the channel adjustments (bare keywords, calc(), max(), min()) are evaluated, and the result is returned as a fully resolved Color.

      Expressions containing var() references or color-mix() are automatically resolved through the browser's CSS engine (via resolveCSS()). This requires DOM access - on the server, such expressions return an invalid Color.

      Always returns a Color object. If the input cannot be parsed, the returned object will have isValid() returning false (properties default to black). If the input is already a Color, a new Color with the same values is returned.

      Parameters:
      color - any valid CSS color string, an existing Color (copied), or a structured object with {r,g,b}, {h,s,l}, or {L,C,h} keys
      Returns:
      a Color object - check isValid() for parse success

    • getColor

      public static Color getColor(Color color)
      Parses any valid CSS color into a structured Color object with RGB, HSL, and oklch properties pre-computed, plus convenience methods for manipulation.

      Accepts any CSS color string (#hex, rgb(), hsl(), oklch(), named colors) or a structured component object in any supported color space: {r, g, b}, {h, s, l}, or {L, C, h}.

      Also accepts CSS Relative Color Syntax (RCS) expressions with literal color origins, such as rgb(from #3B82F6 calc(r - 0.1) g b), hsl(from #47a7e3 h s calc(l + 20)), or oklch(from #3B82F6 calc(l + 0.15) c h). The origin can be any parseable color string - hex, named, or a nested function call. Channel keywords use CSS-native ranges: RGB channels are 0-1 sRGB fractions (not 0-255), HSL s/l are 0-100, oklch L is 0-1. The origin is resolved, the channel adjustments (bare keywords, calc(), max(), min()) are evaluated, and the result is returned as a fully resolved Color.

      Expressions containing var() references or color-mix() are automatically resolved through the browser's CSS engine (via resolveCSS()). This requires DOM access - on the server, such expressions return an invalid Color.

      Always returns a Color object. If the input cannot be parsed, the returned object will have isValid() returning false (properties default to black). If the input is already a Color, a new Color with the same values is returned.

      Parameters:
      color - any valid CSS color string, an existing Color (copied), or a structured object with {r,g,b}, {h,s,l}, or {L,C,h} keys
      Returns:
      a Color object - check isValid() for parse success

    • getColor

      public static Color getColor(Map color)
      Parses any valid CSS color into a structured Color object with RGB, HSL, and oklch properties pre-computed, plus convenience methods for manipulation.

      Accepts any CSS color string (#hex, rgb(), hsl(), oklch(), named colors) or a structured component object in any supported color space: {r, g, b}, {h, s, l}, or {L, C, h}.

      Also accepts CSS Relative Color Syntax (RCS) expressions with literal color origins, such as rgb(from #3B82F6 calc(r - 0.1) g b), hsl(from #47a7e3 h s calc(l + 20)), or oklch(from #3B82F6 calc(l + 0.15) c h). The origin can be any parseable color string - hex, named, or a nested function call. Channel keywords use CSS-native ranges: RGB channels are 0-1 sRGB fractions (not 0-255), HSL s/l are 0-100, oklch L is 0-1. The origin is resolved, the channel adjustments (bare keywords, calc(), max(), min()) are evaluated, and the result is returned as a fully resolved Color.

      Expressions containing var() references or color-mix() are automatically resolved through the browser's CSS engine (via resolveCSS()). This requires DOM access - on the server, such expressions return an invalid Color.

      Always returns a Color object. If the input cannot be parsed, the returned object will have isValid() returning false (properties default to black). If the input is already a Color, a new Color with the same values is returned.

      Parameters:
      color - any valid CSS color string, an existing Color (copied), or a structured object with {r,g,b}, {h,s,l}, or {L,C,h} keys
      Returns:
      a Color object - check isValid() for parse success

    • getFormat

      public static ColorFormat getFormat(String color)
      Returns the ColorFormat of the given color string, or null if the value is not a valid color. For named colors (e.g. "red") and "transparent", the format is reported as "hex" since the canonical representation is hexadecimal.
      Parameters:
      color - a CSS color string
      Returns:
      the detected format, or null if invalid

    • getString

      public static String getString(String color, ColorFormat format)
      Converts any valid CSS color to a string in the specified format. Accepts a CSS color string or a structured color object (as returned by getColor()). Returns null if the input is not a valid color or the format is unrecognized.

      Supported target formats:

      • "hex" - "#RRGGBB" when opaque, "#RRGGBBAA" when semi-transparent
      • "rgb" - "rgb(R, G, B)" when opaque, "rgba(R, G, B, A)" when semi-transparent
      • "hsl" - "hsl(H, S%, L%)" when opaque, "hsla(H, S%, L%, A)" when semi-transparent
      • "oklch" - "oklch(L% C h)" when opaque, "oklch(L% C h / A)" when semi-transparent
      Parameters:
      color - any valid CSS color string, or a structured color object with {r,g,b}, {h,s,l}, or {L,C,h} keys
      format - target format: "hex", "rgb", "hsl", or "oklch"
      Returns:
      CSS color string in the target format, or null

    • getValues

      public static Map getValues(String color, ColorFormat format)
      Returns a plain object with color component values in the requested format. Unlike getColor(), which returns a full Color object with methods and properties in all color spaces, this returns only the numeric components for the requested format - useful when you need raw values for computation without the overhead of a full Color, or when passing components to external APIs.

      Supported formats and their returned keys:

      • "rgb" - {r, g, b, alpha} (0-255 integers, alpha 0-1)
      • "hsl" - {h, s, l, alpha} (h: 0-360 degrees, s/l: 0-100 percent, alpha 0-1)
      • "oklch" - {L, C, h, alpha} (L: 0-1 lightness, C: 0+ chroma, h: 0-360 degrees, alpha 0-1)
      Parameters:
      color - any valid CSS color string or Color
      format - target format: "rgb", "hsl", or "oklch"
      Returns:
      plain object with numeric component keys, or null if invalid
      See Also:

    • isColor

      public static boolean isColor(String color)
      Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and var() or color-mix() expressions (resolved via the browser's CSS engine when a DOM is available; returns false server-side).

      If format is specified, the value must be parseable in that particular format (or be "transparent", which is always valid).

      Parameters:
      color - value to test
      Returns:
      true if the value represents a valid color

    • isColor

      public static boolean isColor(Color color)
      Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and var() or color-mix() expressions (resolved via the browser's CSS engine when a DOM is available; returns false server-side).

      If format is specified, the value must be parseable in that particular format (or be "transparent", which is always valid).

      Parameters:
      color - value to test
      Returns:
      true if the value represents a valid color

    • isColor

      public static boolean isColor(Map color)
      Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and var() or color-mix() expressions (resolved via the browser's CSS engine when a DOM is available; returns false server-side).

      If format is specified, the value must be parseable in that particular format (or be "transparent", which is always valid).

      Parameters:
      color - value to test
      Returns:
      true if the value represents a valid color

    • isColor

      public static boolean isColor(String color, ColorFormat format)
      Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and var() or color-mix() expressions (resolved via the browser's CSS engine when a DOM is available; returns false server-side).

      If format is specified, the value must be parseable in that particular format (or be "transparent", which is always valid).

      Parameters:
      color - value to test
      format - if specified, require this format
      Returns:
      true if the value represents a valid color

    • isColor

      public static boolean isColor(Color color, ColorFormat format)
      Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and var() or color-mix() expressions (resolved via the browser's CSS engine when a DOM is available; returns false server-side).

      If format is specified, the value must be parseable in that particular format (or be "transparent", which is always valid).

      Parameters:
      color - value to test
      format - if specified, require this format
      Returns:
      true if the value represents a valid color

    • isColor

      public static boolean isColor(Map color, ColorFormat format)
      Returns true if the given value is a valid CSS color specification. Accepts any format: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba(), hsl(), hsla(), oklch(), named colors, "transparent", CSS Relative Color Syntax expressions, and var() or color-mix() expressions (resolved via the browser's CSS engine when a DOM is available; returns false server-side).

      If format is specified, the value must be parseable in that particular format (or be "transparent", which is always valid).

      Parameters:
      color - value to test
      format - if specified, require this format
      Returns:
      true if the value represents a valid color

    • isDark

      public static Boolean isDark(String color)
      Returns true if the given color is perceptually dark (i.e. would need light foreground text for readability), false if it is light. Uses oklch lightness, which is perceptually uniform - unlike RGB or HSL brightness, a threshold of 0.6 consistently separates light from dark colors across hues. Use !isDark(color) to test for lightness.

      Returns null if the color is not valid.

      Parameters:
      color - any valid CSS color string or structured color object
      Returns:
      true if perceptually dark, false if light, null if invalid

    • isDark

      public static Boolean isDark(Color color)
      Returns true if the given color is perceptually dark (i.e. would need light foreground text for readability), false if it is light. Uses oklch lightness, which is perceptually uniform - unlike RGB or HSL brightness, a threshold of 0.6 consistently separates light from dark colors across hues. Use !isDark(color) to test for lightness.

      Returns null if the color is not valid.

      Parameters:
      color - any valid CSS color string or structured color object
      Returns:
      true if perceptually dark, false if light, null if invalid

    • lighten

      public static String lighten(String color, double amount)
      Returns a lighter version of the given color. Equivalent to adjust(color, {lightness: amount}).

      The amount is a percentage (0-100) indicating how far to move toward white: 0 returns the original color, 100 returns white. Intermediate values move proportionally - lighten(color, 20) on a dark color produces a bigger absolute lightness change than on an already-light color, but both look like "20% lighter" perceptually.

      For multi-axis adjustments (e.g. lighten and desaturate together), use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to lighten, 0-100
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • lighten

      public static String lighten(String color, double amount, ColorFormat outputFormat)
      Returns a lighter version of the given color. Equivalent to adjust(color, {lightness: amount}).

      The amount is a percentage (0-100) indicating how far to move toward white: 0 returns the original color, 100 returns white. Intermediate values move proportionally - lighten(color, 20) on a dark color produces a bigger absolute lightness change than on an already-light color, but both look like "20% lighter" perceptually.

      For multi-axis adjustments (e.g. lighten and desaturate together), use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to lighten, 0-100
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • mostReadable

      public static String mostReadable(String background, String[] candidates)
      Returns the color from candidates that has the highest contrast against background. Useful for choosing a text color that will be readable on a given background - typically called with ["#ffffff", "#000000"] as candidates.
      Parameters:
      background - the background color to test against
      candidates - list of candidate foreground colors
      Returns:
      the candidate with the highest contrast ratio, or null if inputs invalid

    • palette

      public static Color[] palette(String color)
      Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color theory, lighter variants of a color are called tints (mixed toward white) and darker variants are called shades (mixed toward black); this method produces both in a single ramp. This is the core operation for theme generation: one brand color in, a full light-to-dark palette out.

      At its simplest, palette("#3366CC", 7) produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes) and a subtle hue shift for a professional, non-flat appearance.

      For a plain lightness scale with no chroma or hue variation, pass { chromaCurve: "constant", hueShift: 0 }.

      All returned colors are guaranteed to be within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where in the ramp it falls - it is not forced to a specific stop index.

      Parameters:
      color - the seed color whose hue and chroma define the palette
      Returns:
      array of Color objects ordered from darkest to lightest
      See Also:

    • palette

      public static Color[] palette(Color color)
      Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color theory, lighter variants of a color are called tints (mixed toward white) and darker variants are called shades (mixed toward black); this method produces both in a single ramp. This is the core operation for theme generation: one brand color in, a full light-to-dark palette out.

      At its simplest, palette("#3366CC", 7) produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes) and a subtle hue shift for a professional, non-flat appearance.

      For a plain lightness scale with no chroma or hue variation, pass { chromaCurve: "constant", hueShift: 0 }.

      All returned colors are guaranteed to be within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where in the ramp it falls - it is not forced to a specific stop index.

      Parameters:
      color - the seed color whose hue and chroma define the palette
      Returns:
      array of Color objects ordered from darkest to lightest
      See Also:

    • palette

      public static Color[] palette(String color, int steps)
      See palette()

    • palette

      public static Color[] palette(Color color, int steps)
      See palette()

    • palette

      public static Color[] palette(String color, int steps, Map options)
      Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color theory, lighter variants of a color are called tints (mixed toward white) and darker variants are called shades (mixed toward black); this method produces both in a single ramp. This is the core operation for theme generation: one brand color in, a full light-to-dark palette out.

      At its simplest, palette("#3366CC", 7) produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes) and a subtle hue shift for a professional, non-flat appearance.

      For a plain lightness scale with no chroma or hue variation, pass { chromaCurve: "constant", hueShift: 0 }.

      All returned colors are guaranteed to be within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where in the ramp it falls - it is not forced to a specific stop index.

      Parameters:
      color - the seed color whose hue and chroma define the palette
      steps - number of stops to generate (default 11)
      options - optional settings:
      • lightnessRange - two-element array of oklch L values for the darkest and lightest stops (default [0.15, 0.97])
      • chromaCurve - "natural" (default) tapers chroma toward extremes using a cosine curve; "constant" uses the seed's chroma for all stops; "peaked" pushes maximum chroma to a configurable lightness
      • hueShift - degrees of hue rotation across the full lightness range (default ~4; set to 0 to disable). Positive values shift lighter stops toward warmer hues.
      Returns:
      array of Color objects ordered from darkest to lightest
      See Also:

    • palette

      public static Color[] palette(Color color, int steps, Map options)
      Generates a tonal ramp - an ordered series of colors at different lightness levels sharing the same hue. In color theory, lighter variants of a color are called tints (mixed toward white) and darker variants are called shades (mixed toward black); this method produces both in a single ramp. This is the core operation for theme generation: one brand color in, a full light-to-dark palette out.

      At its simplest, palette("#3366CC", 7) produces 7 stops from dark to light - usable directly as skin backgrounds, hover fills, text colors, and borders. With no options, it uses sensible defaults: a natural chroma curve (vivid in the mid-range, muted at extremes) and a subtle hue shift for a professional, non-flat appearance.

      For a plain lightness scale with no chroma or hue variation, pass { chromaCurve: "constant", hueShift: 0 }.

      All returned colors are guaranteed to be within the sRGB gamut (via automatic chroma reduction at the extremes). The seed color's own lightness determines where in the ramp it falls - it is not forced to a specific stop index.

      Parameters:
      color - the seed color whose hue and chroma define the palette
      steps - number of stops to generate (default 11)
      options - optional settings:
      • lightnessRange - two-element array of oklch L values for the darkest and lightest stops (default [0.15, 0.97])
      • chromaCurve - "natural" (default) tapers chroma toward extremes using a cosine curve; "constant" uses the seed's chroma for all stops; "peaked" pushes maximum chroma to a configurable lightness
      • hueShift - degrees of hue rotation across the full lightness range (default ~4; set to 0 to disable). Positive values shift lighter stops toward warmer hues.
      Returns:
      array of Color objects ordered from darkest to lightest
      See Also:

    • parseRelationship

      public static Map parseRelationship(String rcsExpr)
      Extracts structural information from a CSS Relative Color Syntax (RCS) expression - the origin reference, color space, and per-channel modifications - without evaluating it. This is pure string parsing: no DOM access and no color resolution. It works with any origin, including var() references (which getColor() would resolve via the DOM - parseRelationship preserves the raw reference for structural inspection).

      For example, a skin config stores oklch(from var(--isc-accent) calc(l + 0.15) c h) for a hover color. parseRelationship() extracts the structure so you can see what is being derived from what, without needing to resolve the colors:

      The returned object describes the expression's structure:

      • origin - the raw origin string as it appears in the expression (e.g. "var(--isc-accent)", "#ff0000"). If the origin is a var() reference, the caller must use resolveCSS() to resolve it to an actual color - getColor() cannot resolve var() references.
      • space - the color space: "rgb", "hsl", or "oklch"
      • deltas - an object mapping channel names to their additive delta (only channels that differ from identity). For example, {l: 0.15} means lightness is shifted by +0.15 while other channels pass through unchanged. Channels with complex expressions (multiplication, clamping via max/min) are omitted from deltas but present in rawChannels.
      • rawChannels - an array of three raw channel expression strings in CSS order, useful for complex expressions that cannot be reduced to a simple delta
      • alpha - the alpha value (1.0 if not specified)

      Returns null if the expression is not valid RCS syntax (plain hex, rgb(), named colors, and color-mix() are not RCS and will return null).

      Parameters:
      rcsExpr - a CSS RCS expression, e.g. "oklch(from var(--x) calc(l + 0.15) c h)"
      Returns:
      structured descriptor, or null if not valid RCS
      See Also:

    • resolveCSS

      public static Color resolveCSS(String expr)
      Resolves any CSS color expression to a flat Color by evaluating it through the browser's CSS engine. Handles var() references, color-mix(), and any other CSS color constructs supported by the current browser.

      getColor() automatically delegates to this method for expressions containing var() or color-mix(), so most callers never need to call resolveCSS() directly. The main reason to use it explicitly is when you need to pass an element context for inherited CSS custom properties:

      Internally, a scratch DOM element's color style is set to the expression and getComputedStyle() reads back the browser-resolved value. If an element is provided, the scratch element is temporarily appended as its child, allowing inherited CSS custom properties to resolve correctly.

      Returns an invalid Color (with isValid() false) if the expression is not a valid CSS color in the current browser, or if no DOM is available (e.g. server-side).

      Parameters:
      expr - any CSS color expression - hex, rgb(), hsl(), oklch(), color-mix(), var() references, RCS expressions, or any combination the browser supports
      Returns:
      resolved Color object, or an invalid Color if the expression could not be resolved
      See Also:

    • resolveCSS

      public static Color resolveCSS(String expr, Element element)
      Resolves any CSS color expression to a flat Color by evaluating it through the browser's CSS engine. Handles var() references, color-mix(), and any other CSS color constructs supported by the current browser.

      getColor() automatically delegates to this method for expressions containing var() or color-mix(), so most callers never need to call resolveCSS() directly. The main reason to use it explicitly is when you need to pass an element context for inherited CSS custom properties:

      Internally, a scratch DOM element's color style is set to the expression and getComputedStyle() reads back the browser-resolved value. If an element is provided, the scratch element is temporarily appended as its child, allowing inherited CSS custom properties to resolve correctly.

      Returns an invalid Color (with isValid() false) if the expression is not a valid CSS color in the current browser, or if no DOM is available (e.g. server-side).

      Parameters:
      expr - any CSS color expression - hex, rgb(), hsl(), oklch(), color-mix(), var() references, RCS expressions, or any combination the browser supports
      element - optional DOM element to use as the resolution context; if provided, CSS custom properties inherited by this element will be available for var() resolution
      Returns:
      resolved Color object, or an invalid Color if the expression could not be resolved
      See Also:

    • saturate

      public static String saturate(String color, double amount)
      Returns a more vivid version of the given color by increasing its chroma (color intensity). Equivalent to adjust(color, {saturation: amount}).

      The amount is a percentage (0-100) of additional chroma to add, scaled relative to a practical maximum. A gray color (chroma 0) saturated by 50 produces a clearly visible color; 100 gives full vivid saturation.

      For multi-axis adjustments, use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to saturate, 0-100
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • saturate

      public static String saturate(String color, double amount, ColorFormat outputFormat)
      Returns a more vivid version of the given color by increasing its chroma (color intensity). Equivalent to adjust(color, {saturation: amount}).

      The amount is a percentage (0-100) of additional chroma to add, scaled relative to a practical maximum. A gray color (chroma 0) saturated by 50 produces a clearly visible color; 100 gives full vivid saturation.

      For multi-axis adjustments, use adjust() directly.

      Parameters:
      color - any valid CSS color string or structured color object
      amount - percentage to saturate, 0-100
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • scheme

      public static Map scheme(String color)
      Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods (triad(), tetrad(), etc.) which return raw CSS strings at fixed hue rotations, scheme() returns a structured object with semantic key names and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a requirement for professional UI themes.

      The returned object always contains a primary Color plus one or more supporting keys depending on the scheme type. It also includes auto-generated neutral (very low chroma at the primary's hue) and error (red variant) keys. Each seed can be passed to palette() to generate a full tonal ramp.

      Parameters:
      color - the primary seed color
      Returns:
      a map with primary, secondary, tertiary (where applicable), neutral, and error keys, each a Color object
      See Also:

    • scheme

      public static Map scheme(Color color)
      Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods (triad(), tetrad(), etc.) which return raw CSS strings at fixed hue rotations, scheme() returns a structured object with semantic key names and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a requirement for professional UI themes.

      The returned object always contains a primary Color plus one or more supporting keys depending on the scheme type. It also includes auto-generated neutral (very low chroma at the primary's hue) and error (red variant) keys. Each seed can be passed to palette() to generate a full tonal ramp.

      Parameters:
      color - the primary seed color
      Returns:
      a map with primary, secondary, tertiary (where applicable), neutral, and error keys, each a Color object
      See Also:

    • scheme

      public static Map scheme(String color, String type)
      Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods (triad(), tetrad(), etc.) which return raw CSS strings at fixed hue rotations, scheme() returns a structured object with semantic key names and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a requirement for professional UI themes.

      The returned object always contains a primary Color plus one or more supporting keys depending on the scheme type. It also includes auto-generated neutral (very low chroma at the primary's hue) and error (red variant) keys. Each seed can be passed to palette() to generate a full tonal ramp.

      Parameters:
      color - the primary seed color
      type - scheme type: "complementary", "analogous", "triadic", "split-complementary" (default), "tetradic", or "monochromatic"
      Returns:
      a map with primary, secondary, tertiary (where applicable), neutral, and error keys, each a Color object
      See Also:

    • scheme

      public static Map scheme(Color color, String type)
      Generates a set of harmonious seed colors from a single primary. Unlike the lower-level harmony methods (triad(), tetrad(), etc.) which return raw CSS strings at fixed hue rotations, scheme() returns a structured object with semantic key names and applies chroma/lightness adjustments so that secondary and tertiary colors feel subordinate to the primary - a requirement for professional UI themes.

      The returned object always contains a primary Color plus one or more supporting keys depending on the scheme type. It also includes auto-generated neutral (very low chroma at the primary's hue) and error (red variant) keys. Each seed can be passed to palette() to generate a full tonal ramp.

      Parameters:
      color - the primary seed color
      type - scheme type: "complementary", "analogous", "triadic", "split-complementary" (default), "tetradic", or "monochromatic"
      Returns:
      a map with primary, secondary, tertiary (where applicable), neutral, and error keys, each a Color object
      See Also:

    • setAlpha

      public static String setAlpha(String color, double alpha)
      Returns a new color string with the alpha (opacity) component replaced. The output format matches the input format when possible; for named colors, hex is used.

      Useful for deriving semi-transparent variants of a color without converting it to a different format.

      Parameters:
      color - any valid CSS color string or structured color object
      alpha - new alpha value, 0.0 (transparent) to 1.0 (opaque)
      Returns:
      CSS color string with the new alpha, or null if invalid

    • setAlpha

      public static String setAlpha(String color, double alpha, ColorFormat outputFormat)
      Returns a new color string with the alpha (opacity) component replaced. The output format matches the input format when possible; for named colors, hex is used.

      Useful for deriving semi-transparent variants of a color without converting it to a different format.

      Parameters:
      color - any valid CSS color string or structured color object
      alpha - new alpha value, 0.0 (transparent) to 1.0 (opaque)
      outputFormat - optional output format; defaults to the detected format of the input color
      Returns:
      CSS color string with the new alpha, or null if invalid

    • spin

      public static String spin(String color, double degrees)
      Rotates the hue of a color by the given number of degrees (in oklch space). Positive values rotate clockwise, negative counter-clockwise. This is a convenience wrapper around adjust(color, {hue: degrees}).
      Parameters:
      color - any valid CSS color string or structured color object
      degrees - signed rotation in degrees (e.g. 90, -45, 180)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • spin

      public static String spin(String color, double degrees, ColorFormat outputFormat)
      Rotates the hue of a color by the given number of degrees (in oklch space). Positive values rotate clockwise, negative counter-clockwise. This is a convenience wrapper around adjust(color, {hue: degrees}).
      Parameters:
      color - any valid CSS color string or structured color object
      degrees - signed rotation in degrees (e.g. 90, -45, 180)
      outputFormat - output format; defaults to the detected format of the input color (hex for named colors)
      Returns:
      CSS color string, or null if the input is not a valid color
      See Also:

    • splitComplement

      public static String[] splitComplement(String color)
      Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
      Parameters:
      color - base color
      Returns:
      three CSS color strings

    • splitComplement

      public static String[] splitComplement(Color color)
      Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
      Parameters:
      color - base color
      Returns:
      three CSS color strings

    • splitComplement

      public static String[] splitComplement(String color, ColorFormat outputFormat)
      Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
      Parameters:
      color - base color
      outputFormat - output format; defaults to input format
      Returns:
      three CSS color strings

    • splitComplement

      public static String[] splitComplement(Color color, ColorFormat outputFormat)
      Returns three colors: the original plus two split-complement accents (hue +150 and +210 degrees - flanking the complement rather than hitting it directly). Produces a more nuanced palette than a straight complementary pair.
      Parameters:
      color - base color
      outputFormat - output format; defaults to input format
      Returns:
      three CSS color strings

    • tetrad

      public static String[] tetrad(String color)
      Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then +90, +180, +270 degrees.
      Parameters:
      color - base color
      Returns:
      four CSS color strings

    • tetrad

      public static String[] tetrad(Color color)
      Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then +90, +180, +270 degrees.
      Parameters:
      color - base color
      Returns:
      four CSS color strings

    • tetrad

      public static String[] tetrad(String color, ColorFormat outputFormat)
      Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then +90, +180, +270 degrees.
      Parameters:
      color - base color
      outputFormat - output format; defaults to input format
      Returns:
      four CSS color strings

    • tetrad

      public static String[] tetrad(Color color, ColorFormat outputFormat)
      Returns four colors with hues spaced 90 degrees apart (square scheme). The first element is the original color, then +90, +180, +270 degrees.
      Parameters:
      color - base color
      outputFormat - output format; defaults to input format
      Returns:
      four CSS color strings

    • triad

      public static String[] triad(String color)
      Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is +120 degrees, the third is +240 degrees.
      Parameters:
      color - base color
      Returns:
      three CSS color strings

    • triad

      public static String[] triad(Color color)
      Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is +120 degrees, the third is +240 degrees.
      Parameters:
      color - base color
      Returns:
      three CSS color strings

    • triad

      public static String[] triad(String color, ColorFormat outputFormat)
      Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is +120 degrees, the third is +240 degrees.
      Parameters:
      color - base color
      outputFormat - output format; defaults to input format
      Returns:
      three CSS color strings

    • triad

      public static String[] triad(Color color, ColorFormat outputFormat)
      Returns the three triadic colors (hues spaced 120 degrees apart). The first element is the original color, the second is +120 degrees, the third is +240 degrees.
      Parameters:
      color - base color
      outputFormat - output format; defaults to input format
      Returns:
      three CSS color strings

    • colorScale

      public static String[] colorScale(String color1, String color2, int steps)
      Generates an array of evenly-spaced colors between two endpoints, interpolated in oklch by default. Use the 5-parameter overload to choose a different interpolation space.
      Parameters:
      color1 - start color
      color2 - end color
      steps - number of colors to produce (minimum 2)
      Returns:
      CSS color strings, or null if either input is invalid

    • colorScale

      public static String[] colorScale(String color1, String color2, int steps, ColorFormat format)
      Generates an array of evenly-spaced colors between two endpoints, interpolated in the oklch color space for perceptual uniformity.
      Parameters:
      color1 - start color
      color2 - end color
      steps - number of colors to produce (minimum 2)
      format - output format; defaults to the detected format of color1
      Returns:
      CSS color strings, or null if either input is invalid

    • colorScale

      public static String[] colorScale(Color color1, Color color2, int steps)
      Generates an array of evenly-spaced colors between two Color endpoints, interpolated in the oklch color space for perceptual uniformity.
      Parameters:
      color1 - start color
      color2 - end color
      steps - number of colors to produce (minimum 2)
      Returns:
      CSS color strings, or null if either input is invalid

    • colorScale

      public static String[] colorScale(Color color1, Color color2, int steps, ColorFormat format)
      Generates an array of evenly-spaced colors between two Color endpoints, interpolated in the oklch color space for perceptual uniformity.
      Parameters:
      color1 - start color
      color2 - end color
      steps - number of colors to produce (minimum 2)
      format - output format; defaults to the detected format of color1
      Returns:
      CSS color strings, or null if either input is invalid

    • colorScale

      public static String[] colorScale(String color1, String color2, int steps, ColorFormat format, ColorFormat space)
      Generates an array of evenly-spaced colors between two endpoints, interpolated in the specified color space.
      Parameters:
      color1 - start color
      color2 - end color
      steps - number of colors to produce (minimum 2)
      format - output format; defaults to the detected format of color1
      space - color space for interpolation: oklch (default), hsl, or rgb/hex (both mean linear RGB)
      Returns:
      CSS color strings, or null if either input is invalid

    • colorScale

      public static String[] colorScale(Color color1, Color color2, int steps, ColorFormat format, ColorFormat space)
      Generates an array of evenly-spaced colors between two Color endpoints, interpolated in the specified color space.
      Parameters:
      color1 - start color
      color2 - end color
      steps - number of colors to produce (minimum 2)
      format - output format; defaults to the detected format of color1
      space - color space for interpolation: oklch (default), hsl, or rgb/hex (both mean linear RGB)
      Returns:
      CSS color strings, or null if either input is invalid

    • flatten

      public static String flatten(String color)
      Returns an opaque color visually equivalent to the given semi-transparent color composited over a background (default white). If already fully opaque, returns unchanged.
      Parameters:
      color - a semi-transparent color to flatten
      Returns:
      opaque CSS color string, or null if invalid

    • flatten

      public static String flatten(Color color)
      Returns an opaque color visually equivalent to the given semi-transparent Color composited over a background (default white). If already fully opaque, returns unchanged.
      Parameters:
      color - a semi-transparent color to flatten
      Returns:
      opaque CSS color string, or null if invalid

    • flatten

      public static String flatten(String color, String background)
      Flattens a semi-transparent color against a background.
      Parameters:
      color - a semi-transparent color to flatten
      background - background to composite against
      Returns:
      opaque CSS color string, or null if invalid

    • flatten

      public static String flatten(String color, String background, ColorFormat outputFormat)
      Flattens a semi-transparent color against a background, returning the result in the specified format.
      Parameters:
      color - a semi-transparent color to flatten
      background - background to composite against
      outputFormat - output format; defaults to the detected format of the input color
      Returns:
      opaque CSS color string, or null if invalid

    • flatten

      public static String flatten(Color color, Color background)
      Flattens a semi-transparent Color against a background.
      Parameters:
      color - a semi-transparent color to flatten
      background - background to composite against
      Returns:
      opaque CSS color string, or null if invalid

    • flatten

      public static String flatten(Color color, Color background, ColorFormat outputFormat)
      Flattens a semi-transparent Color against a background, returning the result in the specified format.
      Parameters:
      color - a semi-transparent color to flatten
      background - background to composite against
      outputFormat - output format; defaults to the detected format of the input color
      Returns:
      opaque CSS color string, or null if invalid

    • contrast

      public static Double contrast(String color1, String color2)
      Returns the approximate perceptual contrast ratio between two colors, based on oklch lightness. A ratio of at least 4.5 is recommended for WCAG AA, 7.0 for AAA. Returns null if either color is invalid.
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      contrast ratio (>= 1.0), or null

    • contrast

      public static Double contrast(Color color1, Color color2)
      Returns the approximate perceptual contrast ratio between two Color objects, based on oklch lightness. A ratio of at least 4.5 is recommended for WCAG AA, 7.0 for AAA. Returns null if either color is invalid.
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      contrast ratio (>= 1.0), or null

    • distance

      public static Double distance(String color1, String color2)
      Returns a number indicating how different two colors look to the human eye. 0 means identical; larger values mean more visible difference. Uses oklab (the Cartesian form of oklch) so that equal numeric distances correspond to equal perceived differences. Returns null if either color is invalid.
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      perceptual distance (>= 0), or null

    • distance

      public static Double distance(Color color1, Color color2)
      Returns a number indicating how different two Color objects look to the human eye. 0 means identical; larger values mean more visible difference. Uses oklab so that equal numeric distances correspond to equal perceived differences. Returns null if either color is invalid.
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      perceptual distance (>= 0), or null

    • equals

      public static Boolean equals(String color1, String color2)
      Returns true if two color values represent the same color (same R, G, B, and alpha), regardless of input format.
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      true if identical, false otherwise, null if either invalid

    • equals

      public static Boolean equals(Color color1, Color color2)
      Returns true if two Color objects represent the same color (same R, G, B, and alpha).
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      true if identical, false otherwise, null if either invalid

    • mix

      public static String mix(String color1, String color2)
      Blends two colors in the oklch color space, producing a single result. Equivalent to calling mix(String, String, Double, ColorFormat) with default ratio (0.5) and default format.
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      CSS color string, or null if either input is invalid

    • mix

      public static String mix(String color1, String color2, Double ratio)
      Blends two colors in the oklch color space at the given ratio.
      Parameters:
      color1 - first color
      color2 - second color
      ratio - blend ratio, 0.0 (all color1) to 1.0 (all color2); defaults to 0.5
      Returns:
      CSS color string, or null if either input is invalid

    • mix

      public static String mix(String color1, String color2, Double ratio, ColorFormat outputFormat)
      Blends two colors in the oklch color space at the given ratio, returning the result in the specified format.
      Parameters:
      color1 - first color
      color2 - second color
      ratio - blend ratio, 0.0 (all color1) to 1.0 (all color2); defaults to 0.5
      outputFormat - output format; defaults to the detected format of color1
      Returns:
      CSS color string, or null if either input is invalid

    • mix

      public static String mix(Color color1, Color color2)
      Blends two Color objects in the oklch color space. Equivalent to calling mix(Color, Color, Double, ColorFormat) with default ratio (0.5) and default format.
      Parameters:
      color1 - first color
      color2 - second color
      Returns:
      CSS color string, or null if either input is invalid

    • mix

      public static String mix(Color color1, Color color2, Double ratio)
      Blends two Color objects in the oklch color space at the given ratio.
      Parameters:
      color1 - first color
      color2 - second color
      ratio - blend ratio, 0.0 (all color1) to 1.0 (all color2); defaults to 0.5
      Returns:
      CSS color string, or null if either input is invalid

    • mix

      public static String mix(Color color1, Color color2, Double ratio, ColorFormat outputFormat)
      Blends two Color objects in the oklch color space at the given ratio, returning the result in the specified format.
      Parameters:
      color1 - first color
      color2 - second color
      ratio - blend ratio, 0.0 (all color1) to 1.0 (all color2); defaults to 0.5
      outputFormat - output format; defaults to the detected format of color1
      Returns:
      CSS color string, or null if either input is invalid