Colors

Colors is a library for handling colors in the Fandom environment. This library serves two purposes:
# it provides a list of the most important colors on the current page, so you can easily adapt your addon's appearance to the host wiki's color scheme, and
# it provides a bunch of functions for manipulating colors, so you can build your own color scheme on top of the host wiki's color scheme.
Note: This library is meant to be used by JavaScript developers. If you're not writing a script, this library won't be of any use to you. You may want to check out the help page about colors to find out more information about colors.
== Colors ==
== Applying the colors ==
The easiest way to use the above colors is to write regular CSS but use pseudo-colors instead of regular ones:
a { color: $link; }
Add all of these rules to a string and then pass it to dev.colors.css(). dev.colors.css() will replace all pseudo-values and append the stylesheet to the document head:
Example 1:
dev.colors.css('a { color: $link; }');
You can use an optional second parameter to add pseudo-values of your own. Note that you need to prefix the name of your own values with a $ sign:
Example 2:
dev.colors.css('a { color: $link; background: $myBackGround; }', {
 myBackGround: 'black'
});
== Brightness and Darkness ==
A key part of designing for the various color schemes across Fandom is to determine whether the scheme is bright or dark. dev.colors offers a method for that, but more importantly: It will add two classes to the body tag:
# .menu-dark or .menu-bright – depending on whether the background of menu and buttons is dark or bright
# .page-dark or .page-bright – depending on whether the background of the article area is dark or bright
== Manipulating Colors ==
To manipulate color you first need to create a color object. dev.colors provides three Factories:
Once you have a color object you can manipulate it:
== Negating colors ==
dev.colors has two functions for negating colors: complement() and invert(). While both are mathematically simple their effect on colors is a bit difficult to visualize:
* invert() negates hue, saturation and lightness of a color because it acts on the RGB color space: rgb_{inverted} = rgb(max_r - r, max_g - g, max_b - b)
* complement() negates only the hue. Saturation and lightness remain unchanged: hsl_{complemented} = hsl(max_h - h, s, l). The most obvious consequence is that complement() only affects colors. White, black and any gray tone in between remain (seemingly) unchanged.
A few examples:
 		invert	compl.	 		invert	compl.	 		invert	compl.
red 		 	 	white 		 	 	orchid		 	
lime 		 	 	black 		 	 	pink 		 	
blue 		 	 	gray 		 	 	indigo		 	
cyan 		 	 	lightgray		 	 	khaki 		 	
yellow 		 	 	darkgray 		 	 	brown 		 	
magenta		 	 	beige 		 	 	 		 	
peru 		 	 	springgr.		 	 	 		 	
== Converting Color Objects to Strings ==
When you've mixed and matched the colors you like, you will want to convert them back into strings so you can use them in CSS:
== Edge Conditions ==
The HSL color space allows for changes that have no visual effect:
* If the saturation of a color is 0, a change of hue no longer has a visual effect. The color will remain a graytone
* If the lightness of a color is 0, neither a change of hue nor a change of saturation will have a visual effect. The color will remain black.
This library does not filter and discard values that have no effect.
The following methods make use of the HSL color space:
* Color.rotate
* Color.hue
* Color.saturate
* Color.saturation
* Color.lighten
* Color.lightness
* Color.complement
== Reference ==
=== Methods of dev.colors ===
; dev.colors.parse(color)
: Parses a color string into a Color object.
:; Parameters
:# color: string
:; Returns
:: New Color object
:; Throws
:: Error if string cannot be parsed or values are out of bounds
:; Examples
:: 
var red = dev.colors.parse('#FF0000'),
 green = dev.colors.parse('#0F0'),
 blue = dev.colors.parse('rgb(0, 0, 255)'),
 white = dev.colors.parse('white'),
 page = dev.colors.parse(dev.colors.fandom.page);
; dev.colors.fromRgb(red, green, blue)
: Creates a Color object from numeric RGB values.
:; Parameters
:# red: Number between 0 and 255
:# green: Number between 0 and 255
:# blue: Number between 0 and 255
:; Returns
:: New Color object
:; Throws
:: Error if parameters aren't numbers or out of bounds
:; Examples
:: 
var red = dev.colors.fromRgb(255, 0, 0);
; dev.colors.fromHsl(hue, saturation, lightness)
: Creates a Color object from HSL values.
:; Parameters
:# hue: Number between 0 and 1
:# saturation: Number between 0 and 1
:# lightness: Number between 0 and 1
:; Returns
:: New Color object
:; Throws
:: Error if parameters aren't numbers or out of bounds
:; Examples
:: 
var red = dev.colors.fromHsl(0, 1, 1);
; dev.colors.css(styles)
: Adds CSS-string to the document head after replacing pseudo-values.
:; Parameters
:# styles: string that can be parsed into CSS
; dev.colors.css(styles, custom)
: Adds CSS-string to the document head after replacing pseudo-values.
:; Parameters
:# styles: string that can be parsed into CSS
:# custom: object with pseudo-values as keys and real values as values
=== Methods of Color Objects ===
; Color.rotate(degree)
: Rotates a color's hue by a degree.
:; Parameters
:# degree: Number between -360 and 360
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var magenta = dev.colors.parse('lime').rotate(180);
var blue = blue.rotate(360).rotate(-360); // no change!
; Color.saturate(percentage)
: Saturates (positive values) or desaturates (negative values) a color.
:; Parameters
:# percentage: Number between -100 and 100
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var paleBlue = dev.colors.parse('blue').saturate(-10);
; Color.lighten(percentage)
: Lightens (positive values) or darkens (negative values) a color.
:; Parameters
:# percentage: Number between -100 and 100
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var darkBlue = dev.colors.parse('blue').lighten(-10);
; Color.mix(otherColor)
: Mixes two colors together (like the equivalent SASS function) in equal proportion (50-50).
:; Parameters
:# otherColor: Color object or string that can be parsed into Color object
:; Returns
:: New Color object
:; Throws
:: Error if the first argument is not a Color object or cannot be parsed
:; Examples
:: 
var orange = yellow.mix('red');
; Color.mix(otherColor, percentage)
: Mixes a second color with the object's current color. The given weight value biases the proportion/dominance of the current color. Values below 50 bias against the current color, values above 50 are in favor of it.
:; Parameters
:# otherColor: Color object or string that can be parsed into Color object
:# percentage: Number between 0 and 100
:; Returns
:: New Color object
:; Throws
:: Error if the first argument is not a Color object or cannot be parsed
:; Examples
:: 
var sunYellow = yellow.mix('red', 80);
; Color.invert()
: Inverts a color (see section about negating colors above).
:; Returns
:: New Color object
; Color.complement()
: Complements a color (see section about negating colors above).
:; Returns
:: New Color object
; Color.isBright()
: Checks whether a color is bright or dark (luminance).
:; Returns
:: boolean
:; Examples
:: 
console.log(dev.colors.parse('lightgray').isBright()); // true
console.log(dev.colors.parse('darkgray').isBright()); // false
; Color.isColor()
: Checks whether this color is not a graytone. i.e. saturation and lightness are both greater than zero.
:; Returns
:: boolean
:; Examples
:: 
console.log(dev.colors.parse('white').isColor()); // false
console.log(dev.colors.parse('orange').isColor()); // true
; Color.red()
: Gets the amount of red spectrum mixed into the color.
:; Returns
:: Number between 0 and 255
:; Examples
:: 
alert(dev.colors.parse('red').red()); // 255
; Color.red(value)
: Sets the amount of red spectrum mixed into the color.
:; Parameters
:# value: Number between 0 and 255
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var white = cyan.red(255);
; Color.green()
: Gets the amount of green spectrum mixed into the color.
:; Returns
:: Number between 0 and 255
:; Examples
:: 
alert(dev.colors.parse('red').green()); // 0
; Color.green(value)
: Sets the amount of green spectrum mixed into the color.
:; Parameters
:# value: Number between 0 and 255
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var white = magenta.green(255);
; Color.blue()
: Gets the amount of blue spectrum mixed into the color.
:; Returns
:: Number between 0 and 255
:; Examples
:: 
alert(dev.colors.parse('red').blue()); // 0
; Color.blue(value)
: Sets the amount of blue spectrum mixed into the color.
:; Parameters
:# value: Number between 0 and 255
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var white = yellow.blue(255);
; Color.hue()
: Gets the hue of a color.
:; Returns
:: Number between 0 and 1
:; Examples
:: 
alert(dev.colors.parse('white').hue()); // 0
; Color.hue(value)
: Sets the hue of a color.
:; Parameters
:# value: Number between 0 and 1
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var red = cyan.hue(0);
; Color.saturation()
: Gets the saturation of a color.
:; Returns
:: Number between 0 and 1
:; Examples
:: 
alert(dev.colors.parse('white').saturation()); // 0
; Color.saturation(value)
: Sets the saturation of a color.
:; Parameters
:# value: Number between 0 and 1
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var white = red.saturation(0);
; Color.lightness()
: Gets the lightness (brightness) of a color.
:; Returns
:: Number between 0 and 1
:; Examples
:: 
alert(dev.colors.parse('white').lightness()); // 1
; Color.lightness(value)
: Sets the saturation of a color.
:; Parameters
:# value: Number between 0 and 1
:; Returns
:: New Color object
:; Throws
:: Error if the argument is not a number or out of bounds
:; Examples
:: 
var black = red.lightness(0);
; Color.rgb()
: Converts the Color object to a string in RGB format.
:; Returns
:: string
:; Examples
:: 
alert('Blue is: ' + dev.colors.parse('blue').rgb()); // Blue is: rgb(0, 0, 255)
; Color.hsl()
: Converts the Color object to a string in HSL format.
:; Returns
:: string
:; Examples
:: 
alert('Blue is: ' + dev.colors.parse('blue').hsl());
// Blue is: hsl(240, 100%, 50%)
; Color.hex()
: Converts the Color object to a string in hex format. This method is more or less redundant since it doubles as the Color object's toString() method. Whenever you let JavaScript handle the converting you will implicitly call Color.hex.
:; Returns
:: string
:; Examples
:: 
alert('Blue is: ' + dev.colors.parse('blue').hex()); // Blue is: #0000FF
; Color.toString()
: toString() is a standard JavaScript function. This is an alias for Color.hex which will automatically convert your color object instances into hex form when concatenated.
:; Returns
:: string
:; Examples
:: 
alert('Blue is: ' + dev.colors.parse('blue')); // Blue is: #0000ff