Package org.opencms.util

Class CmsColorContrastCalculator

java.lang.Object
org.opencms.util.CmsColorContrastCalculator
public final class CmsColorContrastCalculator extends Object
Calculator for color contrast ratios according to WCAG 2.2 guidelines.

This class provides functionality to:

  • Calculate contrast ratios between colors
  • Check if color combinations meet WCAG AA accessibility standards
  • Suggest compliant foreground colors for given background colors
  • Adjust non-compliant colors to meet contrast requirements
Also provides utility methods for CSS colors to:
  • Check if a given String represents a valid CSS color, supporting "#fff", "#ffffff", "#ffffffaa" and CSS color names like "white" or "aliceblue" as input.
  • Converting a valid CSS color String to hex. e.g. "white" to "#ffffff" or "transparent" to "ffffff00".
  • Converting a valid CSS color String to an int[] array consisting of the RGB(A) values.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    INVALID_FOREGROUND
    Color returned for invalid inputs in foreground methods.

  • Constructor Summary

    Constructors
    Constructor
    Description
    CmsColorContrastCalculator()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    checkForeground(String bgColor, String fgColor)
    Checks if the provided foreground color has sufficient contrast with the background.
    String
    checkForegroundList(String bgColor, List<String> fgColorList)
    Checks if any of the foreground colors in the provided list has sufficient contrast with the background.
    double
    getContrast(String bgColor, String fgColor)
    Calculates the contrast ratio between two colors according to WCAG 2.2 guidelines.
    String
    getForeground(String bgColor)
    Treats the given color as background and returns either black or white as foreground color, choosing whichever provides better contrast according to WCAG guidelines.
    boolean
    hasSufficientContrast(String bgColor, String fgColor)
    Checks if the contrast ratio between two colors meets the WCAG AA standard minimum requirement of 4.5:1 for normal text.
    boolean
    isValid(String color)
    Checks if the provided String represents a CSS color.
    String
    normalize(String color)
    Normalizes a CSS color by converting it to a 6 (or 8 for RGBA) digit hex representation.
    String
    suggestForeground(String bgColor, String fgColor)
    Suggests a WCAG compliant foreground color based on the given background color.
    String
    toHex(String color)
    Converts a CSS color to a 'normalized' hex representation.
    String
    toRgb(String color)
    Converts a CSS color to its corresponding RGB representation as a comma separated String.
    int[]
    toRgbArray(String color)
    Converts a CSS color to its corresponding RGB values.
    int[]
    toRgbArray(String color, boolean supportNames, boolean supportAlpha)
    Converts a CSS color to its corresponding RGB values.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

  • Method Details

    • checkForeground

      public String checkForeground(String bgColor, String fgColor)
      Checks if the provided foreground color has sufficient contrast with the background.

      Returns the provided fgColor if compliant, otherwise black ("#000000") or white ("#ffffff") depending on contrast, or red ("#ff0000") if any parameter is invalid.

      Parameters:
      bgColor - background color
      fgColor - potential foreground color
      Returns:
      the provided fgColor if compliant, otherwise black ("#000000") or white ("#ffffff") depending on contrast, or red ("#ff0000") if any parameter is invalid

    • checkForegroundList

      public String checkForegroundList(String bgColor, List<String> fgColorList)
      Checks if any of the foreground colors in the provided list has sufficient contrast with the background. If so, returns the first compliant color from the list. If not, returns either black ("#000000") or white ("#ffffff"), whichever provides better contrast.

      Parameters:
      bgColor - background color
      fgColorList - list of potential foreground colors
      Returns:
      the first compliant color from the list, otherwise black ("#000000") or white ("#ffffff") depending on contrast, or red ("#ff0000") if any parameter is invalid

    • getContrast

      public double getContrast(String bgColor, String fgColor)
      Calculates the contrast ratio between two colors according to WCAG 2.2 guidelines.

      The contrast ratio formula is (L1 + 0.05) / (L2 + 0.05), where L1 is the lighter relative luminance and L2 is the darker.

      Returns the contrast ratio between 1:1 and 21:1, or 0 if either parameter is invalid.

      Parameters:
      bgColor - background color
      fgColor - foreground color
      Returns:
      the contrast ratio between 1:1 and 21:1, or 0 if either parameter is invalid
      See Also:

    • getForeground

      public String getForeground(String bgColor)
      Treats the given color as background and returns either black or white as foreground color, choosing whichever provides better contrast according to WCAG guidelines.

      Returns black ("#000000") or white ("#ffffff") depending on contrast, or red ("#ff0000") if the parameter is invalid.

      Parameters:
      bgColor - background color
      Returns:
      black ("#000000") or white ("#ffffff") depending on contrast, or red ("#ff0000") if the parameter is invalid

    • hasSufficientContrast

      public boolean hasSufficientContrast(String bgColor, String fgColor)
      Checks if the contrast ratio between two colors meets the WCAG AA standard minimum requirement of 4.5:1 for normal text.

      Returns false if either parameter is invalid.

      Parameters:
      bgColor - background color
      fgColor - foreground color
      Returns:
      true if contrast ratio is at least 4.5:1
      See Also:

    • isValid

      public boolean isValid(String color)
      Checks if the provided String represents a CSS color.

      Accepts hex colors in the format "#rrggbb", "#rgb" or "#rrggbbaa". Additionally, this method supports named CSS colors, e.g. "white", "blue", "transparent" etc. The input will be trimmed, so it can contain leading or trailing white spaces.

      Parameters:
      color - the color to validate
      Returns:
      true if the input is a valid CSS color
      See Also:

    • normalize

      public String normalize(String color)
      Normalizes a CSS color by converting it to a 6 (or 8 for RGBA) digit hex representation.

      Accepts a hex colors in the format "#rrggbb", "#rgb" or "#rrggbbaa". Additionally, this method supports named CSS colors, e.g. "white", "blue", "transparent" etc. If the input includes an alpha channel, it will also be included in the returned String. The input will be trimmed, so it can contain leading or trailing white spaces.

      If the input is not a valid CSS color, the method returns red ("#ff0000"). So it is assured that the output of this methods is always a valid CSS color.

      Parameters:
      color - the color name or hex color code (e.g. "white", "#ffffff" or "#fff")
      Returns:
      to colors hex representation, or red ("#ff0000") if the input is invalid
      See Also:

    • suggestForeground

      public String suggestForeground(String bgColor, String fgColor)
      Suggests a WCAG compliant foreground color based on the given background color.

      If the provided foreground color doesn't meet the minimum contrast ratio of 4.5:1, it will be adjusted to be either darker or lighter until it does.

      Returns red("#ff0000") if either parameter is invalid.

      Parameters:
      bgColor - background color
      fgColor - potential foreground color
      Returns:
      either the original color if compliant, or a suggested compliant alternative

    • toHex

      public String toHex(String color)
      Converts a CSS color to a 'normalized' hex representation.

      Accepts a hex colors in the format "#rrggbb", "#rgb" or "#rrggbbaa". Additionally, this method supports named CSS colors, e.g. "white", "blue", "transparent" etc. If the input includes an alpha channel, it will also be included in the returned String. The input will be trimmed, so it can contain leading or trailing white spaces.

      If the input is not a valid CSS color, the method returns null.

      Parameters:
      color - the color name or hex color code (e.g. "white", "#ffffff" or "#fff")
      Returns:
      to colors hex representation, or null if the input is invalid
      See Also:

    • toRgbArray

      public int[] toRgbArray(String color)
      Converts a CSS color to its corresponding RGB values.

      Accepts a hex colors in the format "#rrggbb", "#rgb" or "#rrggbbaa". Additionally, this method supports named CSS colors, e.g. "white", "blue", "transparent" etc. If the input includes an alpha channel, it will also be included in the returned array. The input will be trimmed, so it can contain leading or trailing white spaces.

      If the input is not a valid CSS color, the method returns null.

      Parameters:
      color - the color name or hex color code (e.g. "white", "#ffffff" or "#fff")
      Returns:
      an array of integers representing the RGB(A) values, or null if the input is not a valid CSS color
      See Also:

    • toRgbArray

      public int[] toRgbArray(String color, boolean supportNames, boolean supportAlpha)
      Converts a CSS color to its corresponding RGB values.

      If the input is not a valid CSS color, the method returns null.

      Parameters:
      color - the color name or hex color code (e.g. "white", "#ffffff", or "#fff")
      supportNames - if true, support named CSS colors in the input
      supportAlpha - if true, support alpha channel in RGB(A) hex codes in the input
      Returns:
      an array of integers representing the RGB(A) values, or null if the input is invalid
      See Also:

    • toRgb

      public String toRgb(String color)
      Converts a CSS color to its corresponding RGB representation as a comma separated String.

      For example, the color "red" will be converted to "255, 0, 0".

      Parameters:
      color - the color name or hex color code (e.g. "white", "#ffffff" or "#fff")
      Returns:
      the RGB representation as a comma separated String, or null if the input is invalid
      See Also: