-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
6 additions
and
156 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,161 +1,11 @@ | ||
| # colori | ||
| JavaScript module to convert (between CSS-supported formats) and manipulate colors // also available in PHP | ||
| JavaScript module to convert (between CSS-supported formats) and manipulate colors. | ||
|
|
||
| # Documentation (js) | ||
| Also available in PHP if that's what you use to generate colors server-side. | ||
|
|
||
| **colori.js** is a JavaScript module to convert a color into its different CSS-supported formats (RGB, HSL, HWB), and to manipulate colors with some useful functions (blend two colors, calculate their contrast, etc.). | ||
| My main goal with **colori** is to make it easy to use for everyone. You just download the .js or .php file and import it in your code as shown below. | ||
|
|
||
| (Note: _**colori**_ means _**colors**_ in Italian. The singular is _**colore**_.) | ||
| ### Documentation | ||
|
|
||
| ### How to use colori.js | ||
|
|
||
| You need to download the file colori.js (avaiable on GitHub), then just import it into your JavaScript code like this: | ||
|
|
||
| import Colore from 'colori.js'; | ||
|
|
||
| You can replace `Colore` by any other name you want to give to the class. Remember this any time you read `Colore` on this page. | ||
|
|
||
| ### Create a color | ||
|
|
||
| To be able to use colori.js's functions, you need to create a `Colore`-type object: | ||
|
|
||
| const rosso = new Colore('red'); | ||
|
|
||
| rosso == { | ||
| "r": 1, | ||
| "g": 0, | ||
| "b": 0, | ||
| "a": 1, | ||
| "h": 0, | ||
| "s": 1, | ||
| "l": 0.5, | ||
| "w": 0, | ||
| "bk": 0, | ||
| "name": "red" | ||
| } | ||
|
|
||
| The parameter in `new Colore(parameter)` must be a string in a supported format [according to the CSS specification about color formats](https://drafts.csswg.org/css-color/#colorunits). | ||
|
|
||
| The `Colore`-type object thus created stores 10 properties from its color. Each numerical value of these properties is clamped to the [0, 1] interval. | ||
|
|
||
| * The `r`, `g` and `b` properties are the red, blue and green values of the color, when it's expressed in RGB format. These values are usually given by a number between 0 and 255 or a percentage. | ||
| * The `h` property is the hue of the color, when it's expressed in HSL or HWB format. This value is an angle, usually given in degrees (from 0 to 360), gradians (from 0 to 400), radians (from 0 to 2π) or turns (from 0 to 1). | ||
| * The `s` and `l` properties are the saturation and luminosity values of the color, when it's expressed in HSL format. These values are usually given as percentages. | ||
| * The `w` and `bk` properties are the whiteness and blackness values of the color, when it's expressed in HWB format. These values are usually given as percentages. | ||
| * The `a` property is the opacity of the color. This value is usually given in the [0, 1] interval or as a percentage. | ||
| * The `name` property is the name of the color, if it's among the [named colors in the CSS spec](https://drafts.csswg.org/css-color/#named-colors). Otherwise, `name == null`. | ||
|
|
||
| ### Express a color in different formats | ||
|
|
||
| You can get the string containing the expression of the color in the desired format by using the `hex`, `rgb` and `hsl` properties: | ||
|
|
||
| rosso.hex == '#ff0000' | ||
| rosso.rgb == 'rgb(255, 0, 0)' | ||
| rosso.hsl == 'hsl(0, 100%, 50%)' | ||
| rosso.hwb == 'hwb(0 0% 0%)' | ||
|
|
||
| Transparent colors (`a < 1`) are supported too: | ||
|
|
||
| const colore = new Colore('rgb(147 28 45 / .3)'); | ||
|
|
||
| colore.hex == '#931c2d4d' | ||
| colore.rgb == 'rgb(147, 28, 45, 0.3)' | ||
| colore.hsl == 'hsl(351, 68%, 34%, 0.3)' | ||
| colore.hwb == 'hwb(351 11% 42% / 0.3)' | ||
|
|
||
| The `hex`, `rgb`, `hsl` and `hwb` properties don't display opacity when it's equal to 1\. If you want to display it anyway, you can use the `hexa`, `rgba`, `hsla` and `hwba` properties: | ||
|
|
||
| rosso.hex == '#ff0000' | ||
| rosso.hexa == '#ff0000ff' | ||
|
|
||
| rosso.rgb == 'rgb(255, 0, 0)' | ||
| rosso.rgba == 'rgba(255, 0, 0, 1)' | ||
|
|
||
| rosso.hsl == 'hsl(0, 100%, 50%)' | ||
| rosso.hsla == 'hsla(0, 100%, 50%, 1)' | ||
|
|
||
| rosso.hwb == 'hwb(0 0% 0%)' | ||
| rosso.hwba == 'hwb(0 0% 0% / 1)' | ||
|
|
||
| ### Blend two couleurs | ||
|
|
||
| The static method `blend` from class `Colore` blends two colors: pass it one opaque `Colore`-type object (`a == 1`) and one transparent `Colore`-type object (order doesn't matter), and `blend` will give you the color obtained by overlaying the transparent color over the opaque one: | ||
|
|
||
| const trasparente = new Colore('rgba(255, 255, 255, .5)'); | ||
| const opaco = new Colore('rgb(0, 0, 0)'); | ||
| const fusione = Colore.blend(trasparente, opaco); | ||
|
|
||
| fusione.rgb == 'rgb(128, 128, 128)' | ||
|
|
||
| ### Calculate the contrast between two colors | ||
|
|
||
| To calculate the contrast between two colors, for example to check if it passes the [WCAG 2.0 guidelines](https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast), you can use static method `contrast` : | ||
|
|
||
| const bianco = new Colore('white'); | ||
| const nero = new Colore('black'); | ||
|
|
||
| Colore.contrast(nero, bianco) == 21 | ||
|
|
||
| The `contrastedText` method tells you if black or white text would have better contast on a colored background: | ||
|
|
||
| const sfondo = new Colore('darkred'); | ||
|
|
||
| sfondo.contrastedText() == 'white' | ||
|
|
||
| The `luminance` method gives the relative luminance of the color, [as defined by W3C](https://www.w3.org/TR/WCAG20-TECHS/G18.html#G18-procedure) and used in the calculation of contrast: | ||
|
|
||
| sfondo.luminance() == 0.05488967453113127 | ||
|
|
||
| ### Modify a color | ||
|
|
||
| #### `change` | ||
|
|
||
| The `change` method can modify any property from a color, and then gives you a new `Colore`-type object whose properties have all been recalculated taking the change into account. For example, to reduce luminosity `l` by 10%: | ||
|
|
||
| const nuovoColore = rosso.change('l', '-10%'); | ||
|
|
||
| rosso.hsl == 'hsl(0, 100%, 50%)' | ||
| nuovoColore.hsl == 'hsl(0, 100%, 40%)' | ||
|
|
||
| To replace the chosen value instead of adding it (for example, to set luminosity to 35% instead of increasing it by 35%), you can add `{replace: true} as the third parameter: | ||
|
|
||
| const nuovoColore = rosso.change('l', '35%', {replace: true}); | ||
|
|
||
| rosso.hsl == 'hsl(0, 100%, 50%)' | ||
| nuovoColore.hsl == 'hsl(0, 100%, 35%)' | ||
|
|
||
|
|
||
| #### `darken`, `lighten`, `desaturate`, `saturate` | ||
|
|
||
| Multiple functions are available to simplify the use of `change`. For example, to lower luminosity, you can use `darken`: | ||
|
|
||
| const nuovoColore = rosso.darken('10%'); | ||
|
|
||
| rosso.hsl == 'hsl(0, 100%, 50%)' | ||
| nuovoColore.hsl == 'hsl(0, 100%, 40%)' | ||
|
|
||
| If you want to lower luminosity by 10% of its current value instead, you can add the option `{scale: true}`: | ||
|
|
||
| const nuovoColore = rosso.darken('10%', {scale: true}); | ||
|
|
||
| rosso.hsl == 'hsl(0, 100%, 50%)' | ||
| nuovoColore.hsl == 'hsl(0, 100%, 45%)' | ||
|
|
||
| Here is a list of other functions that work exactly like `darken`: | ||
|
|
||
| * `darken`, to decrease luminosity | ||
| * `lighten`, to increase luminosity | ||
| * `desaturate`, to decrease saturation | ||
| * `saturate`, to increase saturation | ||
|
|
||
| ### Complementary and inverse colors | ||
|
|
||
| The `complement` method computes the complementary color of a color, and the `negative` method computes the inverse color of a color: | ||
|
|
||
| const rosa = new Colore('pink'); | ||
| const complementare = rosa.complement(); | ||
| const negativo = rosa.negative(); | ||
|
|
||
| rosa.rgb == 'rgb(255, 192, 203)' | ||
| complementare.rgb == 'rgb(194, 255, 245)' | ||
| negativo.rgb == 'rgb(0, 63, 52)' | ||
| * [JavaScript documentation](https://github.com/Remiscan/colori/wiki/Documentation-(JavaScript)) | ||
| * [PHP documentation](https://github.com/Remiscan/colori/wiki/Documentation-(PHP)) |