Class ColorContrast

java.lang.Object
com.iizix.prop.ColorContrast
public final class ColorContrast extends Object
The WCAG 2.x contrast arithmetic, shared by the server, the Designer and the tests: the relative luminance of a color, the contrast ratio of a foreground on a background, and the quick fix that moves a foreground until a pair passes (THEME-DESIGN.md section 4.3, order CC-THEME-TE1-MODEL).

A color is an ARGB int, the form of GColor.getColor(). A translucent foreground is composited over its background first, as the browser paints it; a translucent background is composited over white, the page a theme is designed against when nothing else is known. The sRGB transfer uses the threshold 0.04045 of IEC 61966-2-1; WCAG 2.x prints 0.03928, a difference that changes no 8-bit channel value.

The ratios are WCAG's: AA_TEXT 4.5:1 for text, AA_NON_TEXT 3:1 for the marks a user must see (borders, focus outlines, a control's base color), AAA_TEXT 7:1 for the enhanced level the Contrast family promises.

Author:
Christopher Mindus

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    ColorContrast.Shortfall
    A contrast pair below its ratio.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    AA_NON_TEXT
    The WCAG AA ratio for the marks of user interface components and graphics: 3:1.
    static final double
    AA_TEXT
    The WCAG AA ratio for text: 4.5:1.
    static final double
    AAA_TEXT
    The WCAG AAA ratio for text: 7:1.

  • Method Summary

    Modifier and Type
    Method
    Description
    static OptionalInt
    adjust(int fg, int bg, double target)
    Moves a foreground's lightness in OKLab, away from the background, until the pair reaches a ratio: the nearest passing color of the same hue.
    static int
    composite(int fg, int bg)
    Composites a color over a background as the browser paints it, in sRGB; a translucent background is composited over white first.
    static String
    format(double ratio)
    Formats a ratio as a designer reads it: one decimal, rounded DOWN so that a pair shown as 4.5:1 really passes 4.5:1.
    static double
    luminance(int argb)
    Gets the relative luminance of a color; the alpha is ignored.
    static boolean
    passes(int fg, int bg, double threshold)
    Checks if a pair passes a threshold.
    static double
    ratio(int fg, int bg)
    Gets the contrast ratio of a foreground on a background.
    static List<ColorContrast.Shortfall>
    shortfalls(Map<String,Integer> colors)
    Checks the pairs of ColorRoles.CONTRAST_PAIRS against their own ratios.
    static List<ColorContrast.Shortfall>
    shortfalls(Map<String,Integer> colors, double textRatio, double nonTextRatio)
    Checks the pairs of ColorRoles.CONTRAST_PAIRS against given ratios: the text pairs against one, the marks against the other - AAA_TEXT and AA_NON_TEXT for the Contrast family's promise.

    Methods inherited from class Object

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

  • Field Details

    • AA_TEXT

      public static final double AA_TEXT
      The WCAG AA ratio for text: 4.5:1.
      See Also:

    • AA_NON_TEXT

      public static final double AA_NON_TEXT
      The WCAG AA ratio for the marks of user interface components and graphics: 3:1.
      See Also:

    • AAA_TEXT

      public static final double AAA_TEXT
      The WCAG AAA ratio for text: 7:1.
      See Also:

  • Method Details

    • luminance

      public static double luminance(int argb)
      Gets the relative luminance of a color; the alpha is ignored.
      Parameters:
      argb - The color.
      Returns:
      The luminance, 0 for black to 1 for white.

    • composite

      public static int composite(int fg, int bg)
      Composites a color over a background as the browser paints it, in sRGB; a translucent background is composited over white first.
      Parameters:
      fg - The foreground.
      bg - The background.
      Returns:
      The opaque color seen.

    • ratio

      public static double ratio(int fg, int bg)
      Gets the contrast ratio of a foreground on a background.
      Parameters:
      fg - The foreground, composited over the background when translucent.
      bg - The background, composited over white when translucent.
      Returns:
      The ratio, 1 for two equal colors to 21 for black on white; symmetric for opaque colors.

    • passes

      public static boolean passes(int fg, int bg, double threshold)
      Checks if a pair passes a threshold.
      Parameters:
      fg - The foreground.
      bg - The background.
      threshold - The ratio needed.
      Returns:
      true when ratio(int,int) reaches the threshold.

    • format

      public static String format(double ratio)
      Formats a ratio as a designer reads it: one decimal, rounded DOWN so that a pair shown as 4.5:1 really passes 4.5:1.
      Parameters:
      ratio - The ratio.
      Returns:
      E.g. 4.4:1.

    • shortfalls

      public static List<ColorContrast.Shortfall> shortfalls(Map<String,Integer> colors)
      Checks the pairs of ColorRoles.CONTRAST_PAIRS against their own ratios.
      Parameters:
      colors - The ARGB colors of one member, by role name; a pair with a role absent is skipped.
      Returns:
      The pairs below their ratio, in the order of the table, possibly empty.

    • shortfalls

      public static List<ColorContrast.Shortfall> shortfalls(Map<String,Integer> colors, double textRatio, double nonTextRatio)
      Checks the pairs of ColorRoles.CONTRAST_PAIRS against given ratios: the text pairs against one, the marks against the other - AAA_TEXT and AA_NON_TEXT for the Contrast family's promise.
      Parameters:
      colors - The ARGB colors of one member, by role name; a pair with a role absent is skipped.
      textRatio - The ratio a text pair needs.
      nonTextRatio - The ratio a mark needs.
      Returns:
      The pairs below their ratio, in the order of the table, possibly empty.

    • adjust

      public static OptionalInt adjust(int fg, int bg, double target)
      Moves a foreground's lightness in OKLab, away from the background, until the pair reaches a ratio: the nearest passing color of the same hue. The chroma is kept where the sRGB gamut allows it and reduced where it does not, the alpha is kept.
      Parameters:
      fg - The foreground.
      bg - The background.
      target - The ratio to reach, e.g. AA_TEXT.
      Returns:
      The foreground itself when it already passes, the nearest passing color otherwise, empty when no lightness of that hue reaches the ratio on this background.