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.

Core conversion

- `isColor(color, [format])` - validate a color string, optionally restricting to a specific format
- `getColor(color)` - convert to a structured object
- `getString(color, format)` - convert to a CSS string

Inspection and alpha

- `getFormat(color)` - detect the format of a color string
- `getAlpha(color)` - extract the alpha (opacity) component
- `setAlpha(color, alpha)` - return a new color with a different alpha
- `isDark(color)` - perceptual light-vs-dark test (oklch-based)
- `contrast(color1, color2)` - approximate perceptual contrast ratio
- `equals(color1, color2)` - same-color comparison across formats
- `flatten(color, [background], [outputFormat])` - composite semi-transparent color to opaque

Manipulation (all operate in oklch for perceptual uniformity)

- `adjust(color, deltas)` - general-purpose multi-axis adjustment
- `lighten()` / `darken()` - lightness
- `saturate()` / `desaturate()` - chroma
- `complement()` - hue rotation by 180 degrees

Palette generation

- `colorScale()` - multi-step gradient between two colors
- `shades()` - lightness ramp from a single color
- `mix()` - blend two colors at a given ratio
- `mostReadable()` - pick the highest-contrast candidate

Color harmony

- `triad()` / `tetrad()` - 3 or 4 evenly-spaced hues
- `splitComplement()` - flanking the complement
- `analogous()` - nearby hues

- ## 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 String[]`
  `analogous(Map color)`
  Returns a set of analogous colors - hues near the original, evenly spaced within a segment of the color wheel.
  `static String[]`
  `analogous(Map color, int results)`
  See `analogous()`
  `static String[]`
  `analogous(Map color, int results, int slices)`
  See `analogous()`
  `static String[]`
  `analogous(Map 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[]`
  `colorScale(String color1, String color2, int steps)`
  Generates an array of evenly-spaced colors between two endpoints.
  `static String[]`
  `colorScale(String color1, String color2, int steps, ColorFormat format)`
  Generates an array of evenly-spaced colors between two endpoints.
  `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 String`
  `complement(Map color)`
  Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees).
  `static String`
  `complement(Map color, ColorFormat outputFormat)`
  Returns the complementary color - the hue on the opposite side of the color wheel (rotated by 180 degrees).
  `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 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 that looks the same as the given semi-transparent color composited over a background.
  `static String`
  `flatten(Color color, String background)`
  See `flatten()`
  `static String`
  `flatten(Color color, String background, ColorFormat outputFormat)`
  Returns an opaque color that looks the same as the given semi-transparent color composited over a background.
  `static String`
  `flatten(String color)`
  Returns an opaque color that looks the same as the given semi-transparent color composited over a background.
  `static String`
  `flatten(String color, String background)`
  See `flatten()`
  `static String`
  `flatten(String color, String background, ColorFormat outputFormat)`
  Returns an opaque color that looks the same as the given semi-transparent color composited over a background.
  `static String`
  `flatten(Map color)`
  Returns an opaque color that looks the same as the given semi-transparent color composited over a background.
  `static String`
  `flatten(Map color, String background)`
  See `flatten()`
  `static String`
  `flatten(Map color, String background, ColorFormat outputFormat)`
  Returns an opaque color that looks the same as the given semi-transparent color composited over a background.
  `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 Double`
  `getAlpha(Map 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(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`
  `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 Boolean`
  `isDark(Map 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(String color1, String color2)`
  Blends two colors in the oklch color space, producing a single result color.
  `static String`
  `mix(String color1, String color2, Double ratio)`
  See `mix()`
  `static String`
  `mix(String color1, String color2, Double ratio, ColorFormat outputFormat)`
  Blends two colors in the oklch color space, producing a single result color.
  `static String`
  `mostReadable(String background, String[] candidates)`
  Returns the color from `candidates` that has the highest contrast against `background`.
  `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 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[]`
  `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.
  `static String[]`
  `shades(String color, int steps, double[] range)`
  See `shades()`
  `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.
  `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[]`
  `splitComplement(Map 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(Map 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[]`
  `tetrad(Map color)`
  Returns four colors with hues spaced 90 degrees apart (square scheme).
  `static String[]`
  `tetrad(Map 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).
  `static String[]`
  `triad(Map color)`
  Returns the three triadic colors (hues spaced 120 degrees apart).
  `static String[]`
  `triad(Map 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:
      - `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(Map 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(Map 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(Map 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

  - ### analogous

    public static String[] analogous(Map 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

  - ### colorScale

    public static String[] colorScale(String color1, String color2, int steps)
    Generates an array of evenly-spaced colors between two endpoints. Interpolation is always performed in the oklch color space, which produces perceptually uniform steps — equal numeric changes yield visually equal differences. The optional `format` parameter controls only the output format of the returned strings.

    Useful for data-visualization ramps, theme generation, and palette tooling.

    Parameters:
      `color1` - start color (any valid CSS color string or structured object)
      `color2` - end color
      `steps` - number of colors to produce (minimum 2)
    Returns:
      CSS color strings in the requested format

  - ### colorScale

    public static String[] colorScale(String color1, String color2, int steps, ColorFormat format)
    Generates an array of evenly-spaced colors between two endpoints. Interpolation is always performed in the oklch color space, which produces perceptually uniform steps — equal numeric changes yield visually equal differences. The optional `format` parameter controls only the output format of the returned strings.

    Useful for data-visualization ramps, theme generation, and palette tooling.

    Parameters:
      `color1` - start color (any valid CSS color string or structured object)
      `color2` - end color
      `steps` - number of colors to produce (minimum 2)
      `format` - output format for the returned color strings; defaults to the detected format of `color1` (hex for named colors)
    Returns:
      CSS color strings in the requested format

  - ### 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(Map 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)`

  - ### complement

    public static String complement(Map 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)`

  - ### contrast

    public static Double contrast(String color1, String color2)
    Returns the approximate perceptual contrast ratio between two colors, based on oklch lightness. The result is a positive number where 1.0 means no contrast and higher values indicate greater contrast. A ratio of at least 4.5 is recommended for normal text readability (WCAG AA), and 7.0 for enhanced readability (WCAG AAA).

    This method uses a simplified lightness-based approximation rather than the full WCAG relative-luminance formula, but oklch lightness correlates well with perceived contrast. Returns null if either color is invalid.

    Parameters:
      `color1` - first color
      `color2` - second color
    Returns:
      approximate contrast ratio (>= 1.0), or null

  - ### 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)`

  - ### 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. For example, `"red"`, `"#ff0000"`, and `"rgb(255, 0, 0)"` are all equal.
    Parameters:
      `color1` - first color
      `color2` - second color
    Returns:
      true if the colors are identical, false otherwise, null if either invalid

  - ### flatten

    public static String flatten(String color)
    Returns an opaque color that looks the same as the given semi-transparent color composited over a background. Solves the layering problem where translucent background colors look different depending on what is behind them - a button on a white panel looks different from the same button on a colored window header, and different again if either is disabled. Flattening removes the dependency on parent backgrounds entirely.

    If the input color is already fully opaque (alpha = 1), it is returned unchanged. The optional `background` defaults to white; if it is itself semi-transparent, it is first flattened against white before compositing.

    Parameters:
      `color` - a semi-transparent color to flatten to opaque
    Returns:
      opaque CSS color string, or null if the input is not a valid color

  - ### flatten

    public static String flatten(Color color)
    Returns an opaque color that looks the same as the given semi-transparent color composited over a background. Solves the layering problem where translucent background colors look different depending on what is behind them - a button on a white panel looks different from the same button on a colored window header, and different again if either is disabled. Flattening removes the dependency on parent backgrounds entirely.

    If the input color is already fully opaque (alpha = 1), it is returned unchanged. The optional `background` defaults to white; if it is itself semi-transparent, it is first flattened against white before compositing.

    Parameters:
      `color` - a semi-transparent color to flatten to opaque
    Returns:
      opaque CSS color string, or null if the input is not a valid color

  - ### flatten

    public static String flatten(Map color)
    Returns an opaque color that looks the same as the given semi-transparent color composited over a background. Solves the layering problem where translucent background colors look different depending on what is behind them - a button on a white panel looks different from the same button on a colored window header, and different again if either is disabled. Flattening removes the dependency on parent backgrounds entirely.

    If the input color is already fully opaque (alpha = 1), it is returned unchanged. The optional `background` defaults to white; if it is itself semi-transparent, it is first flattened against white before compositing.

    Parameters:
      `color` - a semi-transparent color to flatten to opaque
    Returns:
      opaque CSS color string, or null if the input is not a valid color

  - ### flatten

    public static String flatten(String color, String background)
    See `flatten()`

  - ### flatten

    public static String flatten(Color color, String background)
    See `flatten()`

  - ### flatten

    public static String flatten(Map color, String background)
    See `flatten()`

  - ### flatten

    public static String flatten(String color, String background, ColorFormat outputFormat)
    Returns an opaque color that looks the same as the given semi-transparent color composited over a background. Solves the layering problem where translucent background colors look different depending on what is behind them - a button on a white panel looks different from the same button on a colored window header, and different again if either is disabled. Flattening removes the dependency on parent backgrounds entirely.

    If the input color is already fully opaque (alpha = 1), it is returned unchanged. The optional `background` defaults to white; if it is itself semi-transparent, it is first flattened against white before compositing.

    Parameters:
      `color` - a semi-transparent color to flatten to opaque
      `background` - background to composite against; defaults to "#ffffff"
      `outputFormat` - output format; defaults to the detected format of the input color (hex for named colors)
    Returns:
      opaque CSS color string, or null if the input is not a valid color

  - ### flatten

    public static String flatten(Color color, String background, ColorFormat outputFormat)
    Returns an opaque color that looks the same as the given semi-transparent color composited over a background. Solves the layering problem where translucent background colors look different depending on what is behind them - a button on a white panel looks different from the same button on a colored window header, and different again if either is disabled. Flattening removes the dependency on parent backgrounds entirely.

    If the input color is already fully opaque (alpha = 1), it is returned unchanged. The optional `background` defaults to white; if it is itself semi-transparent, it is first flattened against white before compositing.

    Parameters:
      `color` - a semi-transparent color to flatten to opaque
      `background` - background to composite against; defaults to "#ffffff"
      `outputFormat` - output format; defaults to the detected format of the input color (hex for named colors)
    Returns:
      opaque CSS color string, or null if the input is not a valid color

  - ### flatten

    public static String flatten(Map color, String background, ColorFormat outputFormat)
    Returns an opaque color that looks the same as the given semi-transparent color composited over a background. Solves the layering problem where translucent background colors look different depending on what is behind them - a button on a white panel looks different from the same button on a colored window header, and different again if either is disabled. Flattening removes the dependency on parent backgrounds entirely.

    If the input color is already fully opaque (alpha = 1), it is returned unchanged. The optional `background` defaults to white; if it is itself semi-transparent, it is first flattened against white before compositing.

    Parameters:
      `color` - a semi-transparent color to flatten to opaque
      `background` - background to composite against; defaults to "#ffffff"
      `outputFormat` - output format; defaults to the detected format of the input color (hex for named colors)
    Returns:
      opaque CSS color string, or null if the input is not a valid color

  - ### 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

  - ### getAlpha

    public static Double getAlpha(Map 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(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

  - ### 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

  - ### isDark

    public static Boolean isDark(Map 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)`

  - ### mix

    public static String mix(String color1, String color2)
    Blends two colors in the oklch color space, producing a single result color. Oklch mixing avoids the muddy midpoints of RGB blending and the hue drift of HSL blending.

    The `ratio` controls the blend: 0 returns `color1`, 1 returns `color2`, and 0.5 (the default) returns an equal mix. Intermediate values weight toward the corresponding color.

    Common uses include tinting a neutral toward a brand color (e.g. `mix(gray, brand, 0.15)`) and generating overlay effects.

    Examples of common operations:

    Parameters:
      `color1` - first color - any valid CSS color string or structured object
      `color2` - second color
    Returns:
      CSS color string in the requested format, or null if either input is not a valid color

  - ### mix

    public static String mix(String color1, String color2, Double ratio)
    See `mix()`

  - ### mix

    public static String mix(String color1, String color2, Double ratio, ColorFormat outputFormat)
    Blends two colors in the oklch color space, producing a single result color. Oklch mixing avoids the muddy midpoints of RGB blending and the hue drift of HSL blending.

    The `ratio` controls the blend: 0 returns `color1`, 1 returns `color2`, and 0.5 (the default) returns an equal mix. Intermediate values weight toward the corresponding color.

    Common uses include tinting a neutral toward a brand color (e.g. `mix(gray, brand, 0.15)`) and generating overlay effects.

    Examples of common operations:

    Parameters:
      `color1` - first color - any valid CSS color string or structured object
      `color2` - second color
      `ratio` - blend ratio from 0.0 (all color1) to 1.0 (all color2); defaults to 0.5
      `outputFormat` - format for the returned string; defaults to the detected format of `color1` (hex for named colors)
    Returns:
      CSS color string in the requested format, or null if either input is not a valid color

  - ### 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(Map 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

  - ### splitComplement

    public static String[] splitComplement(Map 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(Map 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

  - ### tetrad

    public static String[] tetrad(Map 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(Map 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

  - ### triad

    public static String[] triad(Map 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