philiprehberger-color_convert
v0.6.0390,702 downloadsMIT
Color format conversion with parsing, manipulation, harmony generation, color blindness simulation, and CSS named colors
$
gem install philiprehberger-color_convertREADME
philiprehberger-color_convert
Color format conversion with parsing, manipulation, harmony generation, color blindness simulation, and CSS named colors
Requirements
- Ruby >= 3.1
Installation
Add to your Gemfile:
gem "philiprehberger-color_convert"
Or install directly:
gem install philiprehberger-color_convert
Usage
require "philiprehberger/color_convert"
color = Philiprehberger::ColorConvert.parse("#ff6347")
color.to_hex # => "#ff6347"
color.to_rgb # => { r: 255, g: 99, b: 71 }
color.to_hsl # => { h: 9.1, s: 100.0, l: 63.9 }
color.to_hsv # => { h: 9.1, s: 72.2, v: 100.0 }
color.to_cmyk # => { c: 0.0, m: 61.2, y: 72.2, k: 0.0 }
color.to_lab # => { l: 62.2, a: 57.86, b: 46.42 }
Parsing Formats
Philiprehberger::ColorConvert.parse("#ff0000") # hex
Philiprehberger::ColorConvert.parse("f00") # short hex
Philiprehberger::ColorConvert.parse("rgb(255, 0, 0)") # RGB
Philiprehberger::ColorConvert.parse("hsl(0, 100%, 50%)") # HSL
Philiprehberger::ColorConvert.parse("hsv(0, 100%, 100%)") # HSV
Philiprehberger::ColorConvert.parse("cmyk(0, 100, 100, 0)") # CMYK
Philiprehberger::ColorConvert.parse("tomato") # CSS named color
Color Manipulation
color = Philiprehberger::ColorConvert.parse("steelblue")
color.lighten(20) # lighter by 20%
color.darken(10) # darker by 10%
color.saturate(15) # more saturated by 15%
color.desaturate(15) # less saturated by 15%
color.complement # complementary color (180 degrees)
color.invert # inverted (negative) color, preserves alpha
Color Blending
red = Philiprehberger::ColorConvert.parse("red")
blue = Philiprehberger::ColorConvert.parse("blue")
red.blend(blue) # => equal mix (purple)
red.blend(blue, weight: 0.25) # => 75% red, 25% blue
Color Harmonies
color = Philiprehberger::ColorConvert.parse("#ff6347")
color.analogous # => [Color, Color, Color] (-30, 0, +30 degrees)
color.triadic # => [Color, Color, Color] (0, 120, 240 degrees)
color.tetradic # => [Color, Color, Color, Color] (0, 90, 180, 270 degrees)
color.split_complementary # => [Color, Color, Color] (0, 150, 210 degrees)
Color Blindness Simulation
color = Philiprehberger::ColorConvert.parse("#ff6347")
color.simulate_color_blindness(:protanopia) # red-blind
color.simulate_color_blindness(:deuteranopia) # green-blind
color.simulate_color_blindness(:tritanopia) # blue-blind
Palette Generation
red = Philiprehberger::ColorConvert.parse("red")
blue = Philiprehberger::ColorConvert.parse("blue")
red.gradient(blue, steps: 5) # => [Color, ...] gradient from red to blue
red.monochromatic(steps: 5) # => [Color, ...] dark to light shades of red
Color Temperature
color = Philiprehberger::ColorConvert.parse("#ff6347")
color.temperature # => :warm
color.warm? # => true
color.cool? # => false
blue = Philiprehberger::ColorConvert.parse("blue")
blue.temperature # => :cool
blue.cool? # => true
Alpha Channel
# Parse colors with alpha
color = Philiprehberger::ColorConvert.parse('rgba(255, 0, 0, 0.5)')
color.opacity # => 0.5
color.alpha # => 0.5
color.opaque? # => false
color.transparent? # => true
color.to_rgba # => { r: 255, g: 0, b: 0, a: 0.5 }
color.to_s # => "rgba(255, 0, 0, 0.5)"
# Parse HSLA
Philiprehberger::ColorConvert.parse('hsla(0, 100%, 50%, 0.8)')
# Parse 8-digit hex (last two digits are alpha)
Philiprehberger::ColorConvert.parse('#ff000080') # alpha ~ 0.502
# Create with alpha
color = Philiprehberger::ColorConvert::Color.new(255, 0, 0, alpha: 0.5)
# Adjust opacity
semi = color.with_opacity(0.3)
opaque = color.with_opacity(1.0)
Contrast Ratio
white = Philiprehberger::ColorConvert.parse("white")
black = Philiprehberger::ColorConvert.parse("black")
white.contrast_ratio(black) # => 21.0 (WCAG contrast ratio)
Accessibility (WCAG)
require "philiprehberger/color_convert"
text = Philiprehberger::ColorConvert.parse('#222')
text.wcag_aa?(bg: '#fff') # => true
text.wcag_aaa?(bg: '#fff') # => true
Short Hex
Philiprehberger::ColorConvert.parse('#ff0000').to_short_hex # => "#f00"
CSS Named Colors
colors = Philiprehberger::ColorConvert.named_colors
colors["tomato"] # => "#ff6347"
colors["cornflowerblue"] # => "#6495ed"
colors.size # => 148
Named Color Check
Validate that an input string is a recognized CSS named color before passing it to parse:
Philiprehberger::ColorConvert.named?("red") # => true
Philiprehberger::ColorConvert.named?("Red") # => true (case-insensitive)
Philiprehberger::ColorConvert.named?(" red ") # => true (whitespace-tolerant)
Philiprehberger::ColorConvert.named?("cornflowerblue") # => true
Philiprehberger::ColorConvert.named?("#ff0000") # => false (hex is not a name)
Philiprehberger::ColorConvert.named?("fakecolor") # => false
Philiprehberger::ColorConvert.named?(nil) # => false
API
ColorConvert
| Method | Description |
|---|---|
.parse(str) | Parse a color string (hex, RGB, HSL, HSV, CMYK, or CSS name) |
.named_colors | Return all 148 CSS named colors as name => hex hash |
.named?(input) | Check whether a string is a recognized CSS named color (case-insensitive) |
Color
| Method | Description |
|---|---|
#to_hex | Convert to hex string (e.g., "#ff0000") |
#to_rgb | Convert to RGB hash ({ r:, g:, b: }) |
#to_rgba | Convert to RGBA hash ({ r:, g:, b:, a: }) |
#to_hsl | Convert to HSL hash ({ h:, s:, l: }) |
#to_hsv | Convert to HSV hash ({ h:, s:, v: }) |
#to_cmyk | Convert to CMYK hash ({ c:, m:, y:, k: }) |
#to_lab | Convert to CIELAB hash ({ l:, a:, b: }) |
#to_xyz | Convert to CIE XYZ hash ({ x:, y:, z: }) |
#lighten(n) | Lighten by n percent |
#darken(n) | Darken by n percent |
#saturate(n) | Increase saturation by n percent |
#desaturate(n) | Decrease saturation by n percent |
#complement | Return the complementary color |
#invert | Return inverted (negative) color; preserves alpha |
#blend(other, weight:) | Blend with another color (weight 0.0-1.0) |
#analogous | Generate analogous color harmony (3 colors) |
#triadic | Generate triadic color harmony (3 colors) |
#tetradic | Generate tetradic color harmony (4 colors) |
#split_complementary | Generate split-complementary harmony (3 colors) |
#simulate_color_blindness(type) | Simulate protanopia, deuteranopia, or tritanopia |
#gradient(other, steps:) | Generate gradient palette between two colors |
#monochromatic(steps:) | Generate monochromatic palette (dark to light) |
#temperature | Classify as :warm, :cool, or :neutral by hue |
#warm? | True if color temperature is warm |
#cool? | True if color temperature is cool |
#contrast_ratio(other) | WCAG contrast ratio (1.0 to 21.0) |
#wcag_aa?(bg:, large: false) | True when contrast meets WCAG AA |
#wcag_aaa?(bg:, large: false) | True when contrast meets WCAG AAA |
#to_short_hex | 3-digit hex when channels collapse, full hex otherwise |
#opacity | Return alpha value (0.0-1.0) |
#alpha | Alias for #opacity (attr_reader) |
#with_opacity(val) | Return new Color with given alpha (0.0-1.0) |
#opaque? | True if alpha is 1.0 |
#transparent? | True if alpha is less than 1.0 |
.from_hsl(h, s, l) | Create Color from HSL values |
.from_cmyk(c, m, y, k) | Create Color from CMYK values |
.from_lab(l, a, b) | Create Color from CIELAB values |
.from_xyz(x, y, z) | Create Color from CIE XYZ values |
Development
bundle install
bundle exec rspec
bundle exec rubocop
Support
If you find this project useful: