Update reference docs.

Remove testing doc

templates/pages/reference.md

@@ -17,7 +17,7 @@ Example:
 
 Output:
 
-    'a%3D1'
+    a%3D1
 #Math functions
 ###round
 Applies rounding.
@@ -86,7 +86,7 @@ Output:
 #Color functions
 ##Color definition
 ###rgb
-Creates an opaque color object from red, green and blue (RGB) values. Literal color values in standard HTML/CSS formats may also be used to define colors, for example '#ff0000'.
+Creates an opaque color object from decimal red, green and blue (RGB) values. Literal color values in standard HTML/CSS formats may also be used to define colors, for example `#ff0000`.
 
 Parameters:
 
@@ -98,12 +98,13 @@ Returns: `color`
 
 Example:
 
-    rgb(0.5, 0.5, 0.5)
+    rgb(90, 129, 32)
 
 Output:
 
+    #5a8120
 ###rgba
-Creates a transparent color object from red, green, blue and alpha (RGBA) values.
+Creates a transparent color object from decimal red, green, blue and alpha (RGBA) values.
 
 Parameters:
 
@@ -116,10 +117,11 @@ Returns: `color`
 
 Example:
 
-    rgb(0.5, 0.5, 0.5, 0.5)
+    rgba(90, 129, 32, 0.5)
 
 Output:
 
+    rgba(90, 129, 32, 0.5)
 ###hsl
 Creates an opaque color object from hue, saturation and lightness (HSL) values.
 
@@ -137,6 +139,7 @@ Example:
 
 Output:
 
+    #80ff00
 ###hsla
 Creates a transparent color object from hue, saturation, lightness and alpha (HSLA) values.
 
@@ -155,8 +158,9 @@ Example:
 
 Output:
 
+    rgba(128, 255, 0, 0.5)
 ###hsv
-Creates an opaque color object from hue, saturation and value (HSV) values.
+Creates an opaque color object from hue, saturation and value (HSV) values. Note that this is not the same as `hsl`.
 
 Parameters:
 
@@ -168,12 +172,12 @@ Returns: `color`
 
 Example:
 
-    hsl(90, 100%, 50%)
+    hsv(90, 100%, 50%)
 
 Output:
 
 ###hsva
-Creates a transparent color object from hue, saturation, value and alpha (HSVA) values.
+Creates a transparent color object from hue, saturation, value and alpha (HSVA) values. Note that this is not the same as `hsla`.
 
 Parameters:
 
@@ -186,7 +190,7 @@ Returns: `color`
 
 Example:
 
-    hsla(90, 100%, 50%, 0.5)
+    hsva(90, 100%, 50%, 0.5)
 
 Output:
 
@@ -202,7 +206,7 @@ Returns: `integer` 0-360
 
 Example:
 
-    hue(hsla(90, 100%, 50%))
+    hue(hsl(90, 100%, 50%))
 
 Output:
 
@@ -218,7 +222,7 @@ Returns: `percentage` 0-100
 
 Example:
 
-    saturation(hsla(90, 100%, 50%))
+    saturation(hsl(90, 100%, 50%))
 
 Output:
 
@@ -234,7 +238,7 @@ Returns: `percentage` 0-100
 
 Example:
 
-    lightness(hsla(90, 100%, 50%))
+    lightness(hsl(90, 100%, 50%))
 
 Output:
 
@@ -304,7 +308,7 @@ Output:
 
     0.5
 ###luma
-Calculates the [luma](http://en.wikipedia.org/wiki/Luma_(video)) (perceptual brightness) of a color object. Uses SMPTE C / Rec. 709 coefficients, as recommended in [WCAG 2.0](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef).
+Calculates the [luma](http://en.wikipedia.org/wiki/Luma_(video)) (perceptual brightness) of a color object. Uses SMPTE C / Rec. 709 coefficients, as recommended in [WCAG 2.0](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef). This calculation is also used in the contrast function.
 
 Parameters:
 
@@ -314,15 +318,15 @@ Returns: `percentage` 0-100%
 
 Example:
 
-    luma(rgb(10, 20, 30))
+    luma(rgb(100, 200, 30))
 
 Output:
 
-    90%
+    65%
 ##Color operations
-Color operations generally take parameters in the same units as the values they are changing, and percentage are handles as absolutes, so increasing a 10% value by 10% results in 20%, not 11%, and values are clamped to their allowed ranges, they do not wrap around. Where return values are shown, we've used formats that make it clear what each function has done, rather than their RGB(A) hex equivalents that you will actually be working with.
+Color operations generally take parameters in the same units as the values they are changing, and percentage are handled as absolutes, so increasing a 10% value by 10% results in 20%, not 11%, and values are clamped to their allowed ranges; they do not wrap around. Where return values are shown, we've also shown formats that make it clear what each function has done, in addition to the hex versions that you will usually be be working with.
 ###saturate
-Increase the saturation of a color.
+Increase the saturation of a color by an absolute amount.
 
 Parameters:
 
@@ -337,9 +341,9 @@ Example:
 
 Output:
 
-    hsl(90, 100%, 50%)
+    #80ff00 (hsl(90, 100%, 50%))
 ###desaturate
-Decrease the saturation of a color.
+Decrease the saturation of a color by an absolute amount.
 
 Parameters:
 
@@ -354,9 +358,9 @@ Example:
 
 Output:
 
-    hsl(90, 80%, 50%)
+    #80e51a (hsl(90, 80%, 50%))
 ###lighten
-Increase the lightness of a color.
+Increase the lightness of a color by an absolute amount.
 
 Parameters:
 
@@ -371,9 +375,9 @@ Example:
 
 Output:
 
-    hsl(90, 90%, 60%)
+    #99f53d (hsl(90, 90%, 60%))
 ###darken
-Decrease the lightness of a color.
+Decrease the lightness of a color by an absolute amount.
 
 Parameters:
 
@@ -388,9 +392,9 @@ Example:
 
 Output:
 
-    hsl(90, 90%, 40%)
+    #66c20a (hsl(90, 90%, 40%))
 ###fadein
-Decrease the transparency of a color, making it more opaque. Has no effect on opaque colours.
+Decrease the transparency (or increase the opacity) of a color, making it more opaque. Has no effect on opaque colours. To fade in the other direction use `fadeout`.
 
 Parameters:
 
@@ -405,9 +409,9 @@ Example:
 
 Output:
 
-    hsla(90, 90%, 50%, 0.4)
+    rgba(128, 242, 13, 0.6) (hsla(90, 90%, 50%, 0.6))
 ###fadeout
-Increase the transparency of a color, making it less opaque.
+Increase the transparency (or decrease the opacity) of a color, making it less opaque. To fade in the other direction use `fadein`.
 
 Parameters:
 
@@ -422,9 +426,9 @@ Example:
 
 Output:
 
-    hsla(90, 90%, 50%, 0.6)
+    rgba(128, 242, 13, 0.4) (hsla(90, 90%, 50%, 0.6))
 ###fade
-Set the transparency of a color explicitly.
+Set the absolute transparency of a color. Can be applied to colors whether they already have an opacity value or not.
 
 Parameters:
 
@@ -435,13 +439,13 @@ Returns: `color`
 
 Example:
 
-    fadeout(hsl(90, 90%, 50%), 10%)
+    fade(hsl(90, 90%, 50%), 10%)
 
 Output:
 
-    hsla(90, 90%, 50%, 0.1)
+    rgba(128, 242, 13, 0.1) (hsla(90, 90%, 50%, 0.1))
 ###spin
-Rotate the hue angle of a color in either direction. Note that colours are often passed through an RGB conversion, which doesn't retain hue value for greys (because hue has no meaning when there is no saturation), so make sure you apply functions in a way that preserves hue, for example don't do this:
+Rotate the hue angle of a color in either direction. While the angle range is 0-360, it applies a mod 360 operation, so you can pass in much larger (or negative) values and they will wrap around e.g. angles of 360 and 720 will produce the same result. Note that colours are passed through an RGB conversion, which doesn't retain hue value for greys (because hue has no meaning when there is no saturation), so make sure you apply functions in a way that preserves hue, for example don't do this:
 
     @c: saturate(spin('#aaaaaa', 10), 10%);
 
@@ -463,11 +467,30 @@ Example:
 
 Output:
 
-    hsl(30, 90%, 50%)
-    hsl(350, 90%, 50%)
+    #f27f0d (hsl(30, 90%, 50%))
+    #f20d33 (hsl(350, 90%, 50%))
 ###mix
+Mix two colors together in variable proportion. Opacity is included in the calculations.
+
+Parameters:
+
+* `color1`: A color object.
+* `color1`: A color object.
+* `weight`: Optional, a percentage balance point between the two colors, defaults to 50.
+
+Returns: `color`
+
+Example:
+
+    mix(#ff0000, #0000ff, 50)
+    mix(rgba(100,0,0,1.0), rgba(0,100,0,0.5), 50)
+
+Output:
+
+    #800080
+    rgba(75, 25, 0, 0.75);
 ###greyscale
-Remove all saturation from a color; the same as calling `desaturate(@color, 100%)`. Because the saturation is not affected by hue, the resulting color mapping may be somewhat dull or muddy; `luma` may provide a better result as it extracts perceptual rather than linear brightness, for example `greyscale('#0000ff')` will return the same value as `greyscale('#00ff00')`, when they appear quite different in brightness to the human eye.
+Remove all saturation from a color; the same as calling `desaturate(@color, 100%)`. Because the saturation is not affected by hue, the resulting color mapping may be somewhat dull or muddy; `luma` may provide a better result as it extracts perceptual rather than linear brightness, for example `greyscale('#0000ff')` will return the same value as `greyscale('#00ff00')`, though they appear quite different in brightness to the human eye.
 
 Parameters:
 
@@ -481,9 +504,9 @@ Example:
 
 Output:
 
-    hsl(90, 0%, 50%)
+    #808080 (hsl(90, 0%, 50%))
 ###contrast
-Choose which of two colors provides the greatest contrast with another. This is useful for ensuring that a color is readable against a background, which is also useful for accessibility compliance. This function works the same way as the [contrast function in Compass for SASS](http://compass-style.org/reference/compass/utilities/color/contrast/). In accordance with WCAG 2.0, colors are compared using their luma value, not their lightness.
+Choose which of two colors provides the greatest contrast with another. This is useful for ensuring that a color is readable against a background, which is also useful for accessibility compliance. This function works the same way as the [contrast function in Compass for SASS](http://compass-style.org/reference/compass/utilities/color/contrast/). In accordance with [WCAG 2.0](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef), colors are compared using their luma value, not their lightness.
 
 Parameters:
 
@@ -496,20 +519,21 @@ Returns: `color`
 
 Example:
 
-    contrast('#aaaaaa')
-    contrast('#222222', '#101010')
-    contrast('#222222', '#101010', '#dddddd')
-    contrast(hsl(90, 100%, 50%), , , 40%)
-    contrast(hsl(90, 100%, 50%), , , 60%)
+    contrast(#aaaaaa)
+    contrast(#222222, #101010)
+    contrast(#222222, #101010, #dddddd)
+    contrast(hsl(90, 100%, 50%),#000000,#ffffff,40%);
+    contrast(hsl(90, 100%, 50%),#000000,#ffffff,60%);
 
 Output:
 
-    'black'
-    'white'
-    '#dddddd'
-    'black'
-    'white'
+    #000000 (black)
+    #ffffff (white)
+    #dddddd
+    #000000 (black)
+    #ffffff (white)
 ##Color blending
+These operations are the same as the blend modes found in image editors like Photoshop, so you can use them to make your CSS colors match your images.
 ###multiply
 ###screen
 ###overlay