color_contrast_calc 0.1.0

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'color_contrast_calc'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/color_contrast_calc.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'color_contrast_calc/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'color_contrast_calc'
+  spec.version       = ColorContrastCalc::VERSION
+  spec.authors       = ['HASHIMOTO, Naoki']
+  spec.email         = ['hashimoto.naoki@gmail.com']
+
+  spec.summary       = 'Utility that helps you choose colors with sufficient contrast, WCAG 2.0 in mind'
+  # spec.description   = %q(TODO: Write a longer description or delete this line.)
+  spec.homepage      = 'https://github.com/nico-hn/color_contrast_calc_rb/'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) {|f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.49.1'
+  spec.add_development_dependency 'yard', '~> 0.9.9'
+end

data/examples/color_instance.rb

@@ -0,0 +1,12 @@
+require 'color_contrast_calc'
+
+require 'color_contrast_calc'
+
+# Create an instance of Color from a hex code
+# (You can pass 'red' or [255, 0, 0] instead of '#ff0000')
+red = ColorContrastCalc.color_from('#ff0000')
+puts red.class
+puts red.name
+puts red.hex
+puts red.rgb.to_s
+puts red.hsl.to_s

data/examples/color_lists.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+
+require 'color_contrast_calc'
+
+# Named colors
+named_colors = ColorContrastCalc.named_colors
+
+puts("The number of named colors: #{named_colors.size}")
+puts("The first of named colors: #{named_colors[0].name}")
+puts("The last of named colors: #{named_colors[-1].name}")
+
+# Web safe colors
+web_safe_colors = ColorContrastCalc.web_safe_colors
+
+puts("The number of web safe colors: #{web_safe_colors.size}")
+puts("The first of web safe colors: #{web_safe_colors[0].name}")
+puts("The last of web safe colors: #{web_safe_colors[-1].name}")
+
+# HSL colors
+hsl_colors = ColorContrastCalc.hsl_colors
+
+puts("The number of HSL colors: #{hsl_colors.size}")
+puts("The first of HSL colors: #{hsl_colors[0].name}")
+puts("The 60th of HSL colors: #{hsl_colors[60].name}")
+puts("The 120th of HSL colors: #{hsl_colors[120].name}")
+puts("The last of HSL colors: #{hsl_colors[-1].name}")

data/examples/grayscale.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+require 'color_contrast_calc'
+
+yellow = ColorContrastCalc.color_from('yellow')
+orange = ColorContrastCalc.color_from('orange')
+
+report = 'The grayscale of %s is %s.'
+puts(format(report, yellow.hex, yellow.new_grayscale_color))
+puts(format(report, orange.hex, orange.new_grayscale_color))

data/examples/sort_colors.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+require 'color_contrast_calc'
+
+color_names = ['red', 'yellow', 'lime', 'cyan', 'fuchsia', 'blue']
+colors = color_names.map {|c| ColorContrastCalc.color_from(c) }
+
+# sort by hSL order.  An uppercase for a component of color means
+# that component should be sorted in descending order.
+
+hsl_ordered = ColorContrastCalc::Sorter.sort(colors, 'hSL')
+puts("Colors sorted in the order of hSL: #{hsl_ordered.map(&:name)}")
+
+# sort by RGB order.
+
+rgb_ordered = ColorContrastCalc::Sorter.sort(colors, 'RGB')
+puts("Colors sorted in the order of RGB: #{rgb_ordered.map(&:name)}")
+
+# You can also change the precedence of components.
+
+grb_ordered = ColorContrastCalc::Sorter.sort(colors, 'GRB')
+puts("Colors sorted in the order of GRB: #{grb_ordered.map(&:name)}")
+
+# And you can directly sort hex color codes.
+
+## Hex color codes that correspond to the color_names given above.
+hex_codes = ['#ff0000', '#ff0', '#00ff00', '#0ff', '#f0f', '#0000FF']
+
+hsl_ordered = ColorContrastCalc::Sorter.sort(hex_codes, 'hSL')
+puts("Colors sorted in the order of hSL: #{hsl_ordered}")

data/examples/yellow_black_contrast.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'color_contrast_calc'
+
+yellow = ColorContrastCalc.color_from('yellow')
+black = ColorContrastCalc.color_from('black')
+
+contrast_ratio = yellow.contrast_ratio_against(black)
+
+report = 'The contrast ratio between %s and %s is %2.4f'
+puts(format(report, yellow.name, black.name, contrast_ratio))
+puts(format(report, yellow.hex, black.hex, contrast_ratio))

data/examples/yellow_orange_contrast.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+require 'color_contrast_calc'
+
+yellow = ColorContrastCalc.color_from('yellow')
+orange = ColorContrastCalc.color_from('orange')
+
+report = 'The contrast ratio between %s and %s is %2.4f'
+
+# Find brightness adjusted colors.
+
+a_orange = yellow.find_brightness_threshold(orange, 'A')
+a_contrast_ratio = yellow.contrast_ratio_against(a_orange)
+
+aa_orange = yellow.find_brightness_threshold(orange, 'AA')
+aa_contrast_ratio = yellow.contrast_ratio_against(aa_orange)
+
+puts('# Brightness adjusted colors')
+puts(format(report, yellow.hex, a_orange.hex, a_contrast_ratio))
+puts(format(report, yellow.hex, aa_orange.hex, aa_contrast_ratio))
+
+# Find lightness adjusted colors.
+
+a_orange = yellow.find_lightness_threshold(orange, 'A')
+a_contrast_ratio = yellow.contrast_ratio_against(a_orange)
+
+aa_orange = yellow.find_lightness_threshold(orange, 'AA')
+aa_contrast_ratio = yellow.contrast_ratio_against(aa_orange)
+
+puts('# Lightness adjusted colors')
+puts(format(report, yellow.hex, a_orange.hex, a_contrast_ratio))
+puts(format(report, yellow.hex, aa_orange.hex, aa_contrast_ratio))

data/exe/color_contrast_calc

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'color_contrast_calc'

data/lib/color_contrast_calc.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'color_contrast_calc/version'
+require 'color_contrast_calc/utils'
+require 'color_contrast_calc/converter'
+require 'color_contrast_calc/checker'
+require 'color_contrast_calc/threshold_finder'
+require 'color_contrast_calc/color'
+require 'color_contrast_calc/sorter'
+
+module ColorContrastCalc
+  ##
+  # Error raised if creating a Color instance with invalid value.
+
+  class InvalidColorRepresentationError < StandardError; end
+
+  ##
+  # Return an instance of Color.
+  #
+  # As +color_value+, you can pass a predefined color name, or an
+  # RGB value represented as an array of integers or a hex code such
+  # as [255, 255, 0] or "#ffff00". +name+ is assigned to the returned
+  # instance if it does not have a name already assigned.
+  # @param color_value [String, Array<Integer>] Name of a predefined
+  #   color or RGB value
+  # @param name [String] Unless the instance has predefined name, the
+  #   name passed to the method is set to self.name
+  # @return [Color] Instance of Color
+
+  def self.color_from(color_value, name = nil)
+    error_message = 'A color should be given as an array or string.'
+
+    if !color_value.is_a?(String) && !color_value.is_a?(Array)
+      raise InvalidColorRepresentationError, error_message
+    end
+
+    return color_from_rgb(color_value, name) if color_value.is_a?(Array)
+    color_from_str(color_value, name)
+  end
+
+  ##
+  # Return an array of named colors.
+  #
+  # You can find the color names at
+  # https://www.w3.org/TR/SVG/types.html#ColorKeywords
+  # @param frozen [true|false] Set to false if you want an unfrozen array.
+  # @return [Array<Color>] Named colors
+
+  def self.named_colors(frozen: true)
+    named_colors = Color::List::NAMED_COLORS
+    frozen ? named_colors : named_colors.dup
+  end
+
+  ##
+  # Return an array of web safe colors.
+  #
+  # @param frozen [true|false] Set to false if you want an unfrozen array.
+  # @return [Array<Color>] Web safe colors
+
+  def self.web_safe_colors(frozen: true)
+    colors = Color::List::WEB_SAFE_COLORS
+    frozen ? colors : colors.dup
+  end
+
+  ##
+  # Return a list of colors which share the same saturation and lightness.
+  #
+  # By default, so-called pure colors are returned.
+  # @param s 100 [Float] Ratio of saturation in percentage
+  # @param l 50 [Float] Ratio of lightness in percentage
+  # @param h_interval 1 [Integer] Interval of hues in degrees.
+  #   By default, the method returns 360 hues beginning from red.
+  # @return [Array<Color>] Array of colors which share the same
+  #   saturation and lightness
+
+  def self.hsl_colors(s: 100, l: 50, h_interval: 1)
+    Color::List.hsl_colors(s: s, l: l, h_interval: h_interval)
+  end
+
+  def self.color_from_rgb(color_value, name = nil)
+    error_message = 'An RGB value should be given in form of [r, g, b].'
+
+    unless Utils.valid_rgb?(color_value)
+      raise InvalidColorRepresentationError, error_message
+    end
+
+    hex_code = Utils.rgb_to_hex(color_value)
+    Color::List::HEX_TO_COLOR[hex_code] || Color.new(color_value, name)
+  end
+
+  private_class_method :color_from_rgb
+
+  def self.color_from_str(color_value, name = nil)
+    error_message = 'A hex code is in form of "#xxxxxx" where 0 <= x <= f.'
+
+    named_color = Color::List::NAME_TO_COLOR[color_value]
+    return named_color if named_color
+
+    unless Utils.valid_hex?(color_value)
+      raise InvalidColorRepresentationError, error_message
+    end
+
+    hex_code = Utils.normalize_hex(color_value)
+    Color::List::HEX_TO_COLOR[hex_code] || Color.new(hex_code, name)
+  end
+
+  private_class_method :color_from_str
+end

data/lib/color_contrast_calc/checker.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'color_contrast_calc/utils'
+
+module ColorContrastCalc
+  ##
+  # 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".
+
+  module Checker
+    ##
+    # Collection of constants that correspond to the three levels of success
+    # criteria defined in WCAG 2.0. You will find more information at
+    # https://www.w3.org/TR/UNDERSTANDING-WCAG20/conformance.html#uc-conf-req1-head
+
+    module Level
+      # The minimum level of Conformance
+      A = 'A'
+      # Organizations in the public sector generally adopt this level.
+      AA = 'AA'
+      # This level seems to be hard to satisfy.
+      AAA = 'AAA'
+    end
+
+    LEVEL_TO_RATIO = {
+      Level::AAA => 7,
+      Level::AA => 4.5,
+      Level::A => 3,
+      3 => 7,
+      2 => 4.5,
+      1 => 3
+    }.freeze
+
+    private_constant :LEVEL_TO_RATIO
+
+    ##
+    # 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}
+    # @param rgb [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].
+    # @return [Float] Relative luminance of the passed color.
+
+    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
+
+    ##
+    # 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}
+    # @param 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].
+    # @param 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].
+    # @return [Float] Contrast ratio
+
+    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
+
+    ##
+    # Calculate contrast ratio from a pair of relative luminance.
+    #
+    # @param luminance1 [Float] Relative luminance
+    # @param luminance2 [Float] Relative luminance
+    # @return [Float] Contrast ratio
+
+    def self.luminance_to_contrast_ratio(luminance1, luminance2)
+      l1, l2 = *([luminance1, luminance2].sort {|c1, c2| c2 <=> c1 })
+      (l1 + 0.05) / (l2 + 0.05)
+    end
+
+    def self.tristimulus_value(primary_color, base = 255)
+      s = primary_color.to_f / base
+      s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055)**2.4
+    end
+
+    private_class_method :tristimulus_value
+
+    ##
+    # Rate a given contrast ratio according to the WCAG 2.0 criteria.
+    #
+    # The success criteria are given at
+    # * {https://www.w3.org/TR/WCAG20/#visual-audio-contrast}
+    # * {https://www.w3.org/TR/WCAG20-TECHS/G183.html}
+    #
+    # N.B. The size of text is not taken into consideration.
+    # @param ratio [Float] Contrast Ratio
+    # @return [String] If one of criteria is satisfied, "A", "AA" or "AAA",
+    #   otherwise "-"
+
+    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
+
+    ##
+    # Return a contrast ratio required to meet a given WCAG 2.0 level.
+    #
+    # N.B. The size of text is not taken into consideration.
+    # @param level [String] "A", "AA" or "AAA"
+    # @return [Float] Contrast ratio
+
+    def self.level_to_ratio(level)
+      LEVEL_TO_RATIO[level]
+    end
+  end
+end

data/lib/color_contrast_calc/color.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+require 'color_contrast_calc/utils'
+require 'color_contrast_calc/checker'
+require 'color_contrast_calc/threshold_finder'
+require 'json'
+
+module ColorContrastCalc
+  ##
+  # Represent specific colors.
+  #
+  # This class also provides lists of predefined colors represented as
+  # instances of Color class.
+
+  class Color
+    # @private
+    RGB_LIMITS = [0, 255].freeze
+
+    ##
+    # @!attribute [r] rgb
+    #   @return [Array<Integer>] RGB value of the color
+    # @!attribute [r] hex
+    #   @return [String] Hex color code of the color
+    # @!attribute [r] name
+    #   @return [String] Name of the color
+    # @!attribute [r] relative_luminance
+    #   @return [Float] Relative luminance of the color
+
+    attr_reader :rgb, :hex, :name, :relative_luminance
+
+    ##
+    # Return an instance of Color for a predefined color name.
+    #
+    # Color names are defined at
+    # * {https://www.w3.org/TR/SVG/types.html#ColorKeywords}
+    # @param name [String] Name of color
+    # @return [Color] Instance of Color
+
+    def self.from_name(name)
+      List::NAME_TO_COLOR[name.downcase]
+    end
+
+    ##
+    # Return an instance of Color for a hex color code.
+    #
+    # @param hex [String] Hex color code such as "#ffff00"
+    # @return [Color] Instance of Color
+
+    def self.from_hex(hex)
+      normalized_hex = Utils.normalize_hex(hex)
+      List::HEX_TO_COLOR[normalized_hex] || Color.new(normalized_hex)
+    end
+
+    ##
+    # Create an instance of Color from an HSL value.
+    #
+    # @param hsl [Float] HSL value represented as an array of numbers
+    # @param name [String] You can name the color to be created
+    # @return [Color] Instance of Color
+
+    def self.new_from_hsl(hsl, name = nil)
+      new(Utils.hsl_to_rgb(hsl), name)
+    end
+
+    ##
+    # Create a new instance of Color.
+    #
+    # @param rgb [Array<Integer>, String] RGB value represented as an array
+    #   of integers or hex color code such as [255, 255, 0] or "#ffff00".
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color code is
+    #   assigned instead.
+    # @return [Color] New instance of Color
+
+    def initialize(rgb, name = nil)
+      @rgb = rgb.is_a?(String) ? Utils.hex_to_rgb(rgb) : rgb
+      @hex = Utils.rgb_to_hex(@rgb)
+      @name = name || @hex
+      @relative_luminance = Checker.relative_luminance(@rgb)
+    end
+
+    ##
+    # Return HSL value of the color.
+    #
+    # The value is calculated from the RGB value, so if you create
+    # the instance by Color.new_from_hsl method, the value used to
+    # create the color does not necessarily correspond to the value
+    # of this property.
+    #
+    # @return [Array<Float>] HSL value represented as an array of numbers
+
+    def hsl
+      @hsl ||= Utils.rgb_to_hsl(@rgb)
+    end
+
+    ##
+    # Return a new instance of Color with adjusted contrast.
+    #
+    # @param ratio [Float] Adjustment ratio in percentage
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color
+    #   code is assigned instead.
+    # @return [Color] New color with adjusted contrast
+
+    def new_contrast_color(ratio, name = nil)
+      generate_new_color(Converter::Contrast, ratio, name)
+    end
+
+    ##
+    # Return a new instance of Color with adjusted brightness.
+    #
+    # @param ratio [Float] Adjustment ratio in percentage
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color
+    #   code is assigned instead.
+    # @return [Color] New color with adjusted brightness
+
+    def new_brightness_color(ratio, name = nil)
+      generate_new_color(Converter::Brightness, ratio, name)
+    end
+
+    ##
+    # Return an inverted color as an instance of Color.
+    #
+    # @param ratio [Float] Proportion of the conversion in percentage
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color
+    #   code is assigned instead.
+    # @return [Color] New inverted color
+
+    def new_invert_color(ratio = 100, name = nil)
+      generate_new_color(Converter::Invert, ratio, name)
+    end
+
+    ##
+    # Return a hue rotation applied color as an instance of Color.
+    #
+    # @param degree [Float] Degrees of rotation (0 to 360)
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color
+    #   code is assigned instead.
+    # @return [Color] New hue rotation applied color
+
+    def new_hue_rotate_color(degree, name = nil)
+      generate_new_color(Converter::HueRotate, degree, name)
+    end
+
+    ##
+    # Return a saturated color as an instance of Color.
+    #
+    # @param ratio [Float] Proprtion of the conversion in percentage
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color
+    #   code is assigned instead.
+    # @return [Color] New saturated color
+
+    def new_saturate_color(ratio, name = nil)
+      generate_new_color(Converter::Saturate, ratio, name)
+    end
+
+    ##
+    # Return a grayscale of the original color.
+    #
+    # @param ratio [Float] Conversion ratio in percentage
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color
+    #   code is assigned instead.
+    # @return [Color] New grayscale color
+
+    def new_grayscale_color(ratio = 100, name = nil)
+      generate_new_color(Converter::Grayscale, ratio, name)
+    end
+
+    ##
+    # Try to find a color who has a satisfying contrast ratio.
+    #
+    # The returned color is gained by modifying the brightness of
+    # another color. Even when a color that satisfies the specified
+    # level is not found, it returns a new color anyway.
+    # @param other_color [Color, Array<Integer>, String] Color before
+    #   the adjustment of brightness
+    # @param level [String] "A", "AA" or "AAA"
+    # @return [Color] New color whose brightness is adjusted from that
+    #   of +other_color+
+
+    def find_brightness_threshold(other_color, level = Checker::Level::AA)
+      other_color = Color.new(other_color) unless other_color.is_a? Color
+      ThresholdFinder::Brightness.find(self, other_color, level)
+    end
+
+    ##
+    # Try to find a color who has a satisfying contrast ratio.
+    #
+    # The returned color is gained by modifying the lightness of
+    # another color.  Even when a color that satisfies the specified
+    # level is not found, it returns a new color anyway.
+    # @param other_color [Color, Array<Integer>, String] Color before
+    #   the adjustment of lightness
+    # @param level [String] "A", "AA" or "AAA"
+    # @return [Color] New color whose brightness is adjusted from that
+    #   of +other_color+
+
+    def find_lightness_threshold(other_color, level = Checker::Level::AA)
+      other_color = Color.new(other_color) unless other_color.is_a? Color
+      ThresholdFinder::Lightness.find(self, other_color, level)
+    end
+
+    ##
+    # Calculate the contrast ratio against another color.
+    #
+    # @param other_color [Color, Array<Integer>, String] Another instance
+    #   of Color, RGB value or hex color code
+    # @return [Float] Contrast ratio
+
+    def contrast_ratio_against(other_color)
+      unless other_color.is_a? Color
+        return Checker.contrast_ratio(rgb, other_color)
+      end
+
+      Checker.luminance_to_contrast_ratio(relative_luminance,
+                                          other_color.relative_luminance)
+    end
+
+    ##
+    # Return the level of contrast ratio defined by WCAG 2.0.
+    #
+    # @param other_color [Color, Array<Integer>, String] Another instance
+    #   of Color, RGB value or hex color code
+    # @return [String] "A", "AA" or "AAA" if the contrast ratio meets the
+    #   criteria of WCAG 2.0, otherwise "-"
+
+    def contrast_level(other_color)
+      Checker.ratio_to_level(contrast_ratio_against(other_color))
+    end
+
+    ##
+    # Return a string representation of the color.
+    #
+    # @param base [Ingeger, nil] 16, 10 or nil. when +base+ = 16,
+    #   a hex color code such as "#ffff00" is returned, and when
+    #   +base+ = 10, a code in RGB notation such as "rgb(255, 255, 0)"
+    # @return [String] String representation of the color
+
+    def to_s(base = 16)
+      case base
+      when 16
+        hex
+      when 10
+        @rgb_code ||= format('rgb(%d,%d,%d)', *rgb)
+      else
+        name
+      end
+    end
+
+    ##
+    # Check if the contrast ratio with another color meets a
+    # WCAG 2.0 criterion.
+    #
+    # @param other_color [Color, Array<Integer>, String] Another instance
+    #   of Color, RGB value or hex color code
+    # @param level [String] "A", "AA" or "AAA"
+    # @return [Boolean] true if the contrast ratio meets the specified level
+
+    def sufficient_contrast?(other_color, level = Checker::Level::AA)
+      ratio = Checker.level_to_ratio(level)
+      contrast_ratio_against(other_color) >= ratio
+    end
+
+    ##
+    # Check it two colors have the same RGB value.
+    #
+    # @param other_color [Color, Array<Integer>, String] Another instance
+    #   of Color, RGB value or hex color code
+    # @return [Boolean] true if other_color has the same RGB value
+
+    def same_color?(other_color)
+      case other_color
+      when Color
+        hex == other_color.hex
+      when Array
+        hex == Utils.rgb_to_hex(other_color)
+      when String
+        hex == Utils.normalize_hex(other_color)
+      end
+    end
+
+    ##
+    # Check if the color reachs already the max contrast.
+    #
+    # The max contrast in this context means that of colors modified
+    # by the operation defined at
+    # * {https://www.w3.org/TR/filter-effects/#funcdef-contrast}
+    # @return [Boolean] true if self.new_contrast_color(r) where r is
+    #   greater than 100 returns the same color as self.
+
+    def max_contrast?
+      rgb.all? {|c| RGB_LIMITS.include? c }
+    end
+
+    ##
+    # Check if the color reachs already the min contrast.
+    #
+    # The min contrast in this context means that of colors modified
+    # by the operation defined at
+    # * {https://www.w3.org/TR/filter-effects/#funcdef-contrast}
+    # @return [Boolean] true if self is the same color as "#808080"
+
+    def min_contrast?
+      rgb == GRAY.rgb
+    end
+
+    ##
+    # Check if the color has higher luminance than another color.
+    #
+    # @param other_color [Color] Another color
+    # @return [Boolean] true if the relative luminance of self is higher
+    #   than that of other_color
+
+    def higher_luminance_than?(other_color)
+      relative_luminance > other_color.relative_luminance
+    end
+
+    ##
+    # Check if two colors has the same relative luminance.
+    #
+    # @param other_color [Color] Another color
+    # @return [Boolean] true if the relative luminance of self
+    #   and other_color are same.
+
+    def same_luminance_as?(other_color)
+      relative_luminance == other_color.relative_luminance
+    end
+
+    ##
+    # Check if the contrast ratio against black is higher than against white.
+    #
+    # @return [Boolean] true if the contrast ratio against white is qual to
+    #   or less than the ratio against black
+
+    def light_color?
+      contrast_ratio_against(WHITE.rgb) <= contrast_ratio_against(BLACK.rgb)
+    end
+
+    def generate_new_color(calc, ratio, name = nil)
+      new_rgb = calc.calc_rgb(rgb, ratio)
+      self.class.new(new_rgb, name)
+    end
+
+    private :generate_new_color
+
+    ##
+    # Provide predefined lists of Color instances.
+
+    module List
+      # named colors: https://www.w3.org/TR/SVG/types.html#ColorKeywords
+      keywords_file = "#{__dir__}/data/color_keywords.json"
+      keywords = JSON.parse(File.read(keywords_file))
+
+      ##
+      # Predefined list of named colors.
+      #
+      # You can find the color names at
+      # https://www.w3.org/TR/SVG/types.html#ColorKeywords
+      # @return [Array<Color>] Named colors
+
+      NAMED_COLORS = keywords.map {|name, hex| Color.new(hex, name) }.freeze
+
+      # @private
+      NAME_TO_COLOR = NAMED_COLORS.map {|color| [color.name, color] }.to_h
+
+      # @private
+      HEX_TO_COLOR = NAMED_COLORS.map {|color| [color.hex, color] }.to_h
+
+      def self.generate_web_safe_colors
+        0.step(15, 3).to_a.repeated_permutation(3).sort.map do |rgb|
+          hex_code = Utils.rgb_to_hex(rgb.map {|c| c * 17 })
+          HEX_TO_COLOR[hex_code] || Color.new(hex_code)
+        end
+      end
+
+      private_class_method :generate_web_safe_colors
+
+      ##
+      # Predefined list of web safe colors.
+      #
+      # @return [Array<Color>] Web safe colors
+
+      WEB_SAFE_COLORS = generate_web_safe_colors.freeze
+
+      ##
+      # Return a list of colors which share the same saturation and
+      # lightness.
+      #
+      # By default, so-called pure colors are returned.
+      # @param s 100 [Float] Ratio of saturation in percentage
+      # @param l 50 [Float] Ratio of lightness in percentage
+      # @param h_interval 1 [Integer] Interval of hues in degrees.
+      #   By default, the method returns 360 hues beginning from red.
+      # @return [Array<Color>] Array of colors which share the same
+      #   saturation and lightness
+
+      def self.hsl_colors(s: 100, l: 50, h_interval: 1)
+        0.step(360, h_interval).map {|h| Color.new_from_hsl([h, s, l]) }.freeze
+      end
+    end
+
+    WHITE, GRAY, BLACK = %w[white gray black].map {|n| List::NAME_TO_COLOR[n] }
+  end
+end