Class 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:

  • lighten(java.lang.String, double)
  • darken(java.lang.String, double)
  • saturate(java.lang.String, double)
  • desaturate(java.lang.String, double)
  • complement(java.lang.String)

• 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:

  • lighten(java.lang.String, double)
  • darken(java.lang.String, double)
  • saturate(java.lang.String, double)
  • desaturate(java.lang.String, double)
  • complement(java.lang.String)

• 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

• 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:

  • dim(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • dim(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • adjust(java.lang.String, java.util.Map)

• 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:

  • adjust(java.lang.String, java.util.Map)

• 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:

  • adjust(java.lang.String, java.util.Map)

• 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:

  • adjust(java.lang.String, java.util.Map)

• 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:

  • lighten(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • lighten(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • saturate(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • saturate(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • brighten(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • brighten(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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}.

  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}.

  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}.

  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:

  • getColor(java.lang.String)
  • getString(java.lang.String, com.smartgwt.client.types.ColorFormat)

• 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, and "transparent".

  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, and "transparent".

  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, and "transparent".

  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, and "transparent".

  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, and "transparent".

  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, and "transparent".

  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:

  • darken(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • darken(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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

• 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:

  • desaturate(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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:

  • desaturate(java.lang.String, double)
  • adjust(java.lang.String, java.util.Map)

• 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

• shades

  public static String[] shades(String color, int steps)

  Generates a lightness ramp from a single base color, producing an array of colors that range from near-white to near-black (or a custom range) while preserving the base color's hue and chroma. This is the core skin-generation operation: one brand color in, a full tint/shade palette out.

  All interpolation is done in the oklch color space, so each step is perceptually equidistant - no uneven jumps or hue drift.

  The range parameter controls the lightness endpoints as a two-element array [startL, endL] where L is 0 (black) to 1 (white). The default is [0.95, 0.20] (near-white to dark). To generate only tints (lighter shades), use e.g. [0.97, 0.60]; for only darks, [0.50, 0.10].

  Examples of common operations:

  Parameters:

  color - base color - any valid CSS color string or structured object from getColor()

  steps - number of colors to produce (minimum 2)

  Returns:

  CSS color strings in the requested format, or null if the input is not a valid color

• shades

  public static String[] shades(String color, int steps, double[] range)

  See shades()

• shades

  public static String[] shades(String color, int steps, double[] range, ColorFormat outputFormat)

  Generates a lightness ramp from a single base color, producing an array of colors that range from near-white to near-black (or a custom range) while preserving the base color's hue and chroma. This is the core skin-generation operation: one brand color in, a full tint/shade palette out.

  All interpolation is done in the oklch color space, so each step is perceptually equidistant - no uneven jumps or hue drift.

  The range parameter controls the lightness endpoints as a two-element array [startL, endL] where L is 0 (black) to 1 (white). The default is [0.95, 0.20] (near-white to dark). To generate only tints (lighter shades), use e.g. [0.97, 0.60]; for only darks, [0.50, 0.10].

  Examples of common operations:

  Parameters:

  color - base color - any valid CSS color string or structured object from getColor()

  steps - number of colors to produce (minimum 2)

  range - two-element array [startL, endL] defining the lightness range; defaults to [0.95, 0.20]

  outputFormat - format for the returned strings; defaults to the detected format of the input color (hex for named colors)

  Returns:

  CSS color strings in the requested format, or null if the input is not a valid color

• 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:

  • adjust(java.lang.String, java.util.Map)
  • complement(java.lang.String)

• 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:

  • adjust(java.lang.String, java.util.Map)
  • complement(java.lang.String)

• 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