Module: ColorContrastCalc::Checker

Defined in:
lib/color_contrast_calc/checker.rb

Overview

Utility to check properties of given colors.

This module provides functions that check the relative luminance and contrast ratio of colors. A color is given as RGB value (represented as a tuple of integers) or a hex color code such “#ffff00”.

Defined Under Namespace

Modules: Level, Luminance

Class Method Summary collapse

Class Method Details

.contrast_ratio(color1, color2) ⇒ Float

Calculate the contrast ratio of given colors.

The definition of contrast ratio is given at https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef

Parameters:

  • color1 (String, Array<Integer>) —

    RGB color given as a string or an array of integers. Yellow, for example, can be given as “#ffff00” or [255, 255, 0].

  • color2 (String, Array<Integer>) —

    RGB color given as a string or an array of integers. Yellow, for example, can be given as “#ffff00” or [255, 255, 0].

Returns:

  • (Float) —

    Contrast ratio



77
78
79
80
81
82
 
# File 'lib/color_contrast_calc/checker.rb', line 77

def self.contrast_ratio(color1, color2)
  # https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef

  luminance_to_contrast_ratio(relative_luminance(color1),
                              relative_luminance(color2))
end

.level_to_ratio(level) ⇒ Float

Return a contrast ratio required to meet a given WCAG 2.0 level.

N.B. The size of text is not taken into consideration.

Parameters:

  • level (String) —

    “A”, “AA” or “AAA”

Returns:

  • (Float) —

    Contrast ratio



129
130
131
132
 
# File 'lib/color_contrast_calc/checker.rb', line 129

def self.level_to_ratio(level)
  return level if level.is_a?(Numeric) && level >= 1.0 && level <= 21.0
  LEVEL_TO_RATIO[level]
end

.light_color?(color) ⇒ Boolean

Check if the contrast ratio of a given color against black is higher than against white.

Parameters:

  • color (String, Array<Integer>) —

    RGB color given as a string or an array of integers. Yellow, for example, can be given as “#ffff00” or [255, 255, 0].

Returns:

  • (Boolean) —

    true if the contrast ratio against white is qual to or less than the ratio against black



144
145
146
147
148
149
 
# File 'lib/color_contrast_calc/checker.rb', line 144

def self.light_color?(color)
  l = relative_luminance(color)
  ratio_with_white = luminance_to_contrast_ratio(Luminance::WHITE, l)
  ratio_with_black = luminance_to_contrast_ratio(Luminance::BLACK, l)
  ratio_with_white <= ratio_with_black
end

.luminance_to_contrast_ratio(luminance1, luminance2) ⇒ Float

Calculate contrast ratio from a pair of relative luminance.

Parameters:

  • luminance1 (Float) —

    Relative luminance

  • luminance2 (Float) —

    Relative luminance

Returns:

  • (Float) —

    Contrast ratio



91
92
93
94
 
# File 'lib/color_contrast_calc/checker.rb', line 91

def self.luminance_to_contrast_ratio(luminance1, luminance2)
  l1, l2 = *([luminance1, luminance2].sort {|c1, c2| c2 <=> c1 })
  (l1 + 0.05) / (l2 + 0.05)
end

.ratio_to_level(ratio) ⇒ String

Rate a given contrast ratio according to the WCAG 2.0 criteria.

The success criteria are given at

N.B. The size of text is not taken into consideration.

Parameters:

  • ratio (Float) —

    Contrast Ratio

Returns:

  • (String) —

    If one of criteria is satisfied, “A”, “AA” or “AAA”, otherwise “-”



115
116
117
118
119
120
 
# File 'lib/color_contrast_calc/checker.rb', line 115

def self.ratio_to_level(ratio)
  return Level::AAA if ratio >= 7
  return Level::AA if ratio >= 4.5
  return Level::A if ratio >= 3
  '-'
end

.relative_luminance(rgb = [255, 255, 255]) ⇒ Float

Calculate the relative luminance of a RGB color.

The definition of relative luminance is given at https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef

Parameters:

  • rgb (String, Array<Integer>) (defaults to: [255, 255, 255]) —

    RGB color given as a string or an array of integers. Yellow, for example, can be given as “#ffff00” or [255, 255, 0].

Returns:

  • (Float) —

    Relative luminance of the passed color.



56
57
58
59
60
61
62
 
# File 'lib/color_contrast_calc/checker.rb', line 56

def self.relative_luminance(rgb = [255, 255, 255])
  # https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef

  rgb = Utils.hex_to_rgb(rgb) if rgb.is_a? String
  r, g, b = rgb.map {|c| tristimulus_value(c) }
  r * 0.2126 + g * 0.7152 + b * 0.0722
end