https://github.com/jfairbank/chroma
Ruby gem for color manipulation and palette generation
https://github.com/jfairbank/chroma
Last synced: 6 months ago
JSON representation
Ruby gem for color manipulation and palette generation
- Host: GitHub
- URL: https://github.com/jfairbank/chroma
- Owner: jfairbank
- License: isc
- Created: 2015-01-10T21:39:54.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2021-04-12T17:34:11.000Z (over 4 years ago)
- Last Synced: 2025-04-04T00:07:29.056Z (6 months ago)
- Language: Ruby
- Homepage:
- Size: 106 KB
- Stars: 234
- Watchers: 8
- Forks: 29
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Chroma
[](http://badge.fury.io/rb/chroma)
[](https://travis-ci.org/jfairbank/chroma)
Chroma is a color manipulation and palette generation library. It is heavily
inspired by and a very close Ruby port of the
[tinycolor.js](https://bgrins.github.io/TinyColor/)
library. Many thanks to [Brian Grinstead](http://www.briangrinstead.com/blog/)
for his hard work on that library.
Please don't hesitate to examine the code and make issues, feature requests,
or pull requests. Please refer to the [Contributing](#contributing) section
below.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'chroma'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install chroma
## Creating Colors
Colors are created via the `Chroma.paint` method. It expects any one of
many possible color formats as a string, including names, hexadecimal, rgb,
hsl, and hsv. As a convenience, a `String#paint` is also available for more
succinct color creation.
```ruby
# With Chroma.paint
Chroma.paint 'red' # named colors
Chroma.paint '#00ff00' # 6 character hexadecimal
Chroma.paint '#00f' # 3 character hexadecimal
Chroma.paint 'rgb(255, 255, 0)' # rgb
Chroma.paint 'rgba(255, 255, 0, 0.5)' # rgba
Chroma.paint 'hsl(60, 100%, 50%)' # hsl with percentages
Chroma.paint 'hsl(60, 1, 0.5)' # hsl with decimals
Chroma.paint 'hsla(60, 100%, 50%, 0.5)' # hsla
Chroma.paint 'hsv(60, 100%, 50%)' # hsv with percentages
Chroma.paint 'hsv(60, 1, 0.5)' # hsv with decimals
Chroma.paint 'hsva(60, 100%, 50%, 0.75)' # hsva
# With String#paint
'red'.paint
'#00ff00'.paint
'#00f'.paint
'rgb(255, 255, 0)'.paint
'rgba(255, 255, 0, 0.5)'.paint
'hsl(60, 100%, 50%)'.paint
'hsla(60, 100%, 50%, 0.5)'.paint
'hsv(60, 100%, 50%)'.paint
'hsva(60, 100%, 50%. 0.5)'.paint
```
## Motivation
Chroma's major strength is manipulating colors and generating color palettes,
which allows you to easily generate dynamic colors, dynamic themes for a web
application, and more.
## Color Manipulation
#### Lighten
Lighten the color by a given amount. Defaults to 10.
```ruby
'red'.paint.lighten #=> #ff3333
'red'.paint.lighten(20) #=> #ff6666
```
#### Brighten
Brighten the color by a given amount. Defaults to 10.
```ruby
'red'.paint.brighten #=> #ff1a1a
'red'.paint.brighten(20) #=> #ff3333
```
#### Darken
Darken the color by a given amount. Defaults to 10.
```ruby
'red'.paint.darken #=> #cc0000
'red'.paint.darken(20) #=> #990000
```
#### Desaturate
Desaturate the color by a given amount. Defaults to 10.
```ruby
'red'.paint.desaturate #=> #f20d0d
'red'.paint.desaturate(20) #=> #e61919
```
#### Saturate
Saturate the color by a given amount. Defaults to 10.
```ruby
'#123'.paint.saturate #=> #0e2236
'#123'.paint.saturate(20) #=> #0a223a
```
#### Grayscale
Convert the color to grayscale.
```ruby
'green'.paint.grayscale #=> #404040
# greyscale is an alias
'red'.paint.greyscale #=> #808080
```
#### Opacity
Set the opacity of the color to a given amount.
```ruby
'red'.paint.opacity(0.3) #=> #ff0000
'red'.paint.opacity(0.3).to_rgb #=> 'rgba(255, 0, 0, 0.3)'
```
#### Spin
Spin a given amount in degrees around the hue wheel.
```ruby
'red'.paint.spin(30) #=> #ff8000
'red'.paint.spin(60) #=> yellow
'red'.paint.spin(90) #=> #80ff00
```
## Generating Palettes
Chroma's most powerful feature is palette generation. You can use the default
palettes available or even create your own custom palettes.
Palette methods are available via `Color#palette` and by default output an
array of colors. If you want the underlying color strings, you can pass in
the desired format via the `:as` option.
#### Available Formats
* name
* rgb
* hex
* hex6 (alias for hex)
* hex3
* hex8 (includes the alpha value in the highest order byte)
* hsl
* hsv
#### Complement
Generate a complement palette.
```ruby
'red'.paint.palette.complement #=> [red, cyan]
'red'.paint.palette.complement(as: :name) #=> ['red', 'cyan']
'red'.paint.palette.complement(as: :hex) #=> ['#ff0000', '#00ffff']
```
#### Triad
Generate a triad palette.
```ruby
'red'.paint.palette.triad #=> [red, lime, blue]
'red'.paint.palette.triad(as: :name) #=> ['red', 'lime', 'blue']
'red'.paint.palette.triad(as: :hex) #=> ['#ff0000', '#00ff00', '#0000ff']
```
#### Tetrad
Generate a tetrad palette.
```ruby
'red'.paint.palette.tetrad
#=> [red, #80ff00, cyan, #7f00ff]
'red'.paint.palette.tetrad(as: :name)
#=> ['red', '#80ff00', 'cyan', '#7f00ff']
'red'.paint.palette.tetrad(as: :hex)
#=> ['#ff0000', '#80ff00', '#00ffff', '#7f00ff']
```
#### Split Complement
Generate a split complement palette.
```ruby
'red'.paint.palette.split_complement
#=> [red, #ccff00, #0066ff]
'red'.paint.palette.split_complement(as: :name)
#=> ['red', '#ccff00', '#0066ff']
'red'.paint.palette.split_complement(as: :hex)
#=> ['#ff0000', '#ccff00', '#0066ff']
```
#### Analogous
Generate an analogous palette. Pass in a `:size` option to specify the size
of the palette (defaults to 6). Pass in a `:slice_by` option to specify the
angle size to slice into the hue wheel (defaults to 30 degrees).
```ruby
'red'.paint.palette.analogous
#=> [red, #ff0066, #ff0033, red, #ff3300, #ff6600]
'red'.paint.palette.analogous(as: :hex)
#=> ['#f00', '#f06', '#f03', '#f00', '#f30', '#f60']
'red'.paint.palette.analogous(size: 3)
#=> [red, #ff001a, #ff1a00]
'red'.paint.palette.analogous(size: 3, slice_by: 60)
#=> [red, #ff000d, #ff0d00]
```
#### Monochromatic
Generate a monochromatic palette. Pass in a `:size` option to specify the size
of the palette (defaults to 6).
```ruby
'red'.paint.palette.monochromatic
#=> [red, #2a0000, #550000, maroon, #aa0000, #d40000]
'red'.paint.palette.monochromatic(as: :hex)
#=> ['#ff0000', '#2a0000', '#550000', '#800000', '#aa0000', '#d40000']
'red'.paint.palette.monochromatic(size: 3)
#=> [red, #550000, #aa0000]
```
## Defining Custom Palettes
Chroma allows you to define your own custom palettes if the default ones aren't
all you're looking for. You can define a custom palette by calling
`Chroma.define_palette`, passing in a palette name and definition block. The
definition block uses the color manipulation methods (i.e. `lighten`, `spin`,
etc.) as its DSL. Every DSL call defines a new color that will be included
in the palette. Your seed color (i.e. the color from which you call the
palette method) will be included as the first color in your palette too.
```ruby
red = 'red'.paint
red.palette.respond_to? :my_palette #=> false
# Define a palette with 5 colors including the seed color
Chroma.define_palette :my_palette do
spin 60
spin 180
spin(60).brighten(20) # chain calls as well
greyscale
end
red.palette.respond_to? :my_palette #=> true
red.palette.my_palette #=> [#ff0000 #ffff00 #00ffff #ffff33 #808080]
```
## Dynamic Custom Palettes
You can generate custom palettes on the fly too with
`Chroma::Color#custom_palette`.
```ruby
'red'.paint.custom_palette do
spin 60
spin 180
end
#=> [red, yellow, cyan]
```
## Serializing Colors
Colors offer several methods to output to different string color [formats](#available-formats).
| Method | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------- |
| `to_hsv` | output to hsv string, outputs hsva if alpha < 1 |
| `to_hsl` | output to hsl string, outputs hsla if alpha < 1 |
| `to_hex` | output to hex string, optional argument allows 3-character hex output if possible |
| `to_hex8` | output to 8-character hex string with alpha value in the highest order byte |
| `to_rgb` | output to rgb string, outputs rgba if alpha < 1 |
| `to_name` | output to color name string if available, otherwise `''` or `to_hex` output based on optional arg value |
| `to_s` | output to the appropriate string format based on how the color was created, optional arg forces the format |
```ruby
# to_hsv
'red'.paint.to_hsv #=> 'hsv(0, 100%, 100%)'
'rgba(255, 0, 0, 0.5)'.paint.to_hsv #=> 'hsva(0, 100%, 100%, 0.5)'
# to_hsl
'red'.paint.to_hsl #=> 'hsl(0, 100%, 50%)'
'rgba(255, 0, 0, 0.5)'.paint.to_hsl #=> 'hsla(0, 100%, 50%, 0.5)'
# to_hex
'red'.paint.to_hex #=> '#ff0000'
'red'.paint.to_hex(true) #=> '#f00'
'rgba(255, 0, 0, 0.5)'.paint.to_hex #=> '#ff0000'
'red'.paint.to_hex #=> '#ffff0000'
'rgba(255, 0, 0, 0.5)'.paint.to_hex #=> '#80ff0000'
# to_rgb
'red'.paint.to_rgb #=> 'rgb(255, 0, 0)'
'rgba(255, 0, 0, 0.5)'.paint.to_rgb #=> 'rgb(255, 0, 0, 0.5)'
# to_name
'red'.paint.to_name #=> 'red'
'#00f'.paint.to_name #=> 'blue'
'rgba(255, 0, 0, 0.5)'.paint.to_name #=> ''
'#123'.paint.to_name(true) #=> '#112233'
# to_s
'red'.paint.to_s #=> 'red'
'rgb(255, 0, 0)'.paint.to_s #=> 'rgb(255, 0, 0)'
'#f00'.paint.to_s #=> '#f00'
'#80ff0000'.paint.to_s(:rgb) #=> 'rgba(255, 0, 0, 0.5)'
```
## Other Methods
Colors also have a few other helper methods:
| Method | Description |
| ------------ | ------------------------------------------------------ |
| `dark?` | is the color dark? |
| `light?` | is the color light? |
| `alpha` | retrieve the alpha value |
| `brightness` | calculate the brightness as a number between 0 and 255 |
| `complement` | return the complementary color |
```ruby
# dark?
'red'.paint.dark? #=> true
'yellow'.paint.dark? #=> false
# light?
'red'.paint.light? #=> false
'yellow'.paint.light? #=> true
# alpha
'red'.paint.alpha #=> 1.0
'rgba(0, 0, 0, 0.5)'.paint.alpha #=> 0.5
# brightness
'red'.paint.brightness #=> 76.245
'yellow'.paint.brightness #=> 225.93
'white'.paint.brightness #=> 255.0
'black'.paint.brightness #=> 0.0
# complement
'red'.paint.complement #=> cyan
```
## Contributing
Please branch from **dev** for all pull requests.
1. Fork it (https://github.com/jfairbank/chroma/fork)
2. Checkout dev (`git checkout dev`)
3. Create your feature branch (`git checkout -b my-new-feature`)
4. Commit your changes (`git commit -am 'Add some feature'`)
5. Push to the branch (`git push origin my-new-feature`)
6. Create a new pull request against dev