npm package: @siteone/system-toolset
Description: Useful functions and mixins to supercharge work with @siteone/system-* libraries
Author: Viktor Bezdek
Latest version: 1.0.0

# @siteone/system-toolset

[![package version](https://img.shields.io/npm/v/@siteone/system-toolset.svg?style=flat-square)](https://npmjs.org/package/@siteone/system-toolset)
[![package downloads](https://img.shields.io/npm/dm/@siteone/system-toolset.svg?style=flat-square)](https://npmjs.org/package/@siteone/system-toolset)
[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
[![package license](https://img.shields.io/npm/l/@siteone/system-toolset.svg?style=flat-square)](https://npmjs.org/package/@siteone/system-toolset)
[![make a pull request](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)

> Useful functions and mixins to supercharge work with @siteone/system-\* libraries

## Table of Contents

-   [Install](#install)
-   [Usage](#usage)
-   [Contribute](#contribute)
-   [License](#License)

## Install

This project uses [node](https://nodejs.org) and [npm](https://www.npmjs.com). 

```sh
$ npm install @siteone/system-toolset
$ # OR
$ yarn add @siteone/system-toolset
```

## Usage

Use within theme or application itself. Should be used as stand-alone imports via destructuring. Like this:

```js

import { topShadow, bottomShadow } from '@siteone/system-toolset'

```

Don't be afraid of bundle size increase as library is tree-shakable if bundled properly.

## API

### function `adjustHue`

Changes the hue of the color. Hue is a number between 0 to 360. The first
argument for adjustHue is the amount of degrees the color is rotated along
the color wheel.

#### Parameters

-   `degree` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: adjustHue(180, '#448'),
  background: adjustHue('180', 'rgba(101,100,205,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${adjustHue(180, '#448')};
  background: ${adjustHue('180', 'rgba(101,100,205,0.7)')};
`

// CSS in JS Output
element {
  background: "#888844";
  background: "rgba(136,136,68,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `complement`

Returns the complement of the provided color. This is identical to adjustHue(180, **_color_**).

#### Parameters

-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: complement('#448'),
  background: complement('rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${complement('#448')};
  background: ${complement('rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#884";
  background: "rgba(153,153,153,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `darken`

Returns a string value for the darkened color.

#### Parameters

-   `amount` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: darken(0.2, '#FFCD64'),
  background: darken('0.2', 'rgba(255,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${darken(0.2, '#FFCD64')};
  background: ${darken('0.2', 'rgba(255,205,100,0.7)')};
`

// CSS in JS Output

element {
  background: "#ffbd31";
  background: "rgba(255,189,49,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `desaturate`

Decreases the intensity of a color. Its range is between 0 to 1. The first
argument of the desaturate function is the amount by how much the color
intensity should be decreased.

#### Parameters

-   `amount` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: desaturate(0.2, '#CCCD64'),
  background: desaturate('0.2', 'rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${desaturate(0.2, '#CCCD64')};
  background: ${desaturate('0.2', 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#b8b979";
  background: "rgba(184,185,121,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `getLuminance`

Returns a number (float) representing the luminance of a color.

#### Parameters

-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: getLuminance('#CCCD64') >= getLuminance('#0000ff') ? '#CCCD64' : '#0000ff',
  background: getLuminance('rgba(58, 133, 255, 1)') >= getLuminance('rgba(255, 57, 149, 1)') ?
                            'rgba(58, 133, 255, 1)' :
                            'rgba(255, 57, 149, 1)',
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${getLuminance('#CCCD64') >= getLuminance('#0000ff') ? '#CCCD64' : '#0000ff'};
  background: ${getLuminance('rgba(58, 133, 255, 1)') >= getLuminance('rgba(255, 57, 149, 1)') ?
                            'rgba(58, 133, 255, 1)' :
                            'rgba(255, 57, 149, 1)'};

// CSS in JS Output

div {
  background: "#CCCD64";
  background: "rgba(58, 133, 255, 1)";
}
```

Returns **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 

---

### function `grayscale`

Converts the color to a grayscale, by reducing its saturation to 0.

#### Parameters

-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: grayscale('#CCCD64'),
  background: grayscale('rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${grayscale('#CCCD64')};
  background: ${grayscale('rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#999";
  background: "rgba(153,153,153,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `hsl`

Returns a string value for the color. The returned result is the smallest possible hex notation.

#### Parameters

-   `value` **([HslColor](#hslcolor) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `saturation` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 
-   `lightness` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: hsl(359, 0.75, 0.4),
  background: hsl({ hue: 360, saturation: 0.75, lightness: 0.4 }),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${hsl(359, 0.75, 0.4)};
  background: ${hsl({ hue: 360, saturation: 0.75, lightness: 0.4 })};
`

// CSS in JS Output

element {
  background: "#b3191c";
  background: "#b3191c";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `hsla`

Returns a string value for the color. The returned result is the smallest possible rgba or hex notation.

#### Parameters

-   `value` **([HslaColor](#hslacolor) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `saturation` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 
-   `lightness` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 
-   `alpha` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: hsla(359, 0.75, 0.4, 0.7),
  background: hsla({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0,7 }),
  background: hsla(359, 0.75, 0.4, 1),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${hsla(359, 0.75, 0.4, 0.7)};
  background: ${hsla({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0,7 })};
  background: ${hsla(359, 0.75, 0.4, 1)};
`

// CSS in JS Output

element {
  background: "rgba(179,25,28,0.7)";
  background: "rgba(179,25,28,0.7)";
  background: "#b3191c";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `hslToColorString`

Converts a HslColor or HslaColor object to a color string.
This util is useful in case you only know on runtime which color object is
used. Otherwise we recommend to rely on `hsl` or `hsla`.

#### Parameters

-   `color` **([HslColor](#hslcolor) \| [HslaColor](#hslacolor) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: hslToColorString({ hue: 240, saturation: 1, lightness: 0.5 }),
  background: hslToColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 }),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${hslToColorString({ hue: 240, saturation: 1, lightness: 0.5 })};
  background: ${hslToColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 })};
`

// CSS in JS Output
element {
  background: "#00f";
  background: "rgba(179,25,25,0.72)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `invert`

Inverts the red, green and blue values of a color.

#### Parameters

-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: invert('#CCCD64'),
  background: invert('rgba(101,100,205,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${invert('#CCCD64')};
  background: ${invert('rgba(101,100,205,0.7)')};
`

// CSS in JS Output

element {
  background: "#33329b";
  background: "rgba(154,155,50,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `lighten`

Returns a string value for the lightened color.

#### Parameters

-   `amount` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: lighten(0.2, '#CCCD64'),
  background: lighten('0.2', 'rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${lighten(0.2, '#FFCD64')};
  background: ${lighten('0.2', 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output

element {
  background: "#e5e6b1";
  background: "rgba(229,230,177,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `mix`

Mixes the two provided colors together by calculating the average of each of the RGB components weighted to the
first color by the provided weight.

#### Parameters

-   `weight` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `otherColor` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: mix(0.5, '#f00', '#00f')
  background: mix(0.25, '#f00', '#00f')
  background: mix('0.5', 'rgba(255, 0, 0, 0.5)', '#00f')
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${mix(0.5, '#f00', '#00f')};
  background: ${mix(0.25, '#f00', '#00f')};
  background: ${mix('0.5', 'rgba(255, 0, 0, 0.5)', '#00f')};
`

// CSS in JS Output

element {
  background: "#7f007f";
  background: "#3f00bf";
  background: "rgba(63, 0, 191, 0.75)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `opacify`

Increases the opacity of a color. Its range for the amount is between 0 to 1.

#### Parameters

-   `amount` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: opacify(0.1, 'rgba(255, 255, 255, 0.9)');
  background: opacify(0.2, 'hsla(0, 0%, 100%, 0.5)'),
  background: opacify('0.5', 'rgba(255, 0, 0, 0.2)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${opacify(0.1, 'rgba(255, 255, 255, 0.9)')};
  background: ${opacify(0.2, 'hsla(0, 0%, 100%, 0.5)')},
  background: ${opacify('0.5', 'rgba(255, 0, 0, 0.2)')},
`

// CSS in JS Output

element {
  background: "#fff";
  background: "rgba(255,255,255,0.7)";
  background: "rgba(255,0,0,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `parseToHsl`

Returns an HslColor or HslaColor object. This utility function is only useful
if want to extract a color component. With the color util `toColorString` you
can convert a HslColor or HslaColor object back to a string.

#### Parameters

-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Assigns `{ hue: 0, saturation: 1, lightness: 0.5 }` to color1
const color1 = parseToHsl('rgb(255, 0, 0)');
// Assigns `{ hue: 128, saturation: 1, lightness: 0.5, alpha: 0.75 }` to color2
const color2 = parseToHsl('hsla(128, 100%, 50%, 0.75)');
```

Returns **([HslColor](#hslcolor) \| [HslaColor](#hslacolor))** 

---

### function `parseToRgb`

Returns an RgbColor or RgbaColor object. This utility function is only useful
if want to extract a color component. With the color util `toColorString` you
can convert a RgbColor or RgbaColor object back to a string.

#### Parameters

-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Assigns `{ red: 255, green: 0, blue: 0 }` to color1
const color1 = parseToRgb('rgb(255, 0, 0)');
// Assigns `{ red: 92, green: 102, blue: 112, alpha: 0.75 }` to color2
const color2 = parseToRgb('hsla(210, 10%, 40%, 0.75)');
```

Returns **([RgbColor](#rgbcolor) \| [RgbaColor](#rgbacolor))** 

---

### function `readableColor`

Returns black or white (or optional light and dark return colors) for best contrast depending on the luminosity of
the given color. Follows [W3C specs for readability](https://www.w3.org/TR/WCAG20-TECHS/G18.html).

#### Parameters

-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `lightReturnColor` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'#000'`)
-   `darkReturnColor` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'#fff'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  color: readableColor('#000'),
  color: readableColor('black', '#001', '#ff8'),
  color: readableColor('white', '#001', '#ff8'),
}

// syled (CSS in JS) usage
const div = styled.div`
  color: ${readableColor('#000')};
  color: ${readableColor('black', '#001', '#ff8')};
  color: ${readableColor('white', '#001', '#ff8')};
`

// CSS in JS Output

element {
  color: "#fff";
  color: "#ff8";
  color: "#001";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `rgb`

Returns a string value for the color. The returned result is the smallest possible hex notation.

#### Parameters

-   `value` **([RgbColor](#rgbcolor) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `green` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 
-   `blue` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: rgb(255, 205, 100),
  background: rgb({ red: 255, green: 205, blue: 100 }),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${rgb(255, 205, 100)};
  background: ${rgb({ red: 255, green: 205, blue: 100 })};
`

// CSS in JS Output

element {
  background: "#ffcd64";
  background: "#ffcd64";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `rgba`

Returns a string value for the color. The returned result is the smallest possible rgba or hex notation.

Can also be used to fade a color by passing a hex value or named CSS color along with an alpha value.

#### Parameters

-   `firstValue` **([RgbaColor](#rgbacolor) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `secondValue` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 
-   `thirdValue` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 
-   `fourthValue` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: rgba(255, 205, 100, 0.7),
  background: rgba({ red: 255, green: 205, blue: 100, alpha: 0.7 }),
  background: rgba(255, 205, 100, 1),
  background: rgba('#ffffff', 0.4),
  background: rgba('black', 0.7),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${rgba(255, 205, 100, 0.7)};
  background: ${rgba({ red: 255, green: 205, blue: 100, alpha: 0.7 })};
  background: ${rgba(255, 205, 100, 1)};
  background: ${rgba('#ffffff', 0.4)};
  background: ${rgba('black', 0.7)};
`

// CSS in JS Output

element {
  background: "rgba(255,205,100,0.7)";
  background: "rgba(255,205,100,0.7)";
  background: "#ffcd64";
  background: "rgba(255,255,255,0.4)";
  background: "rgba(0,0,0,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `rgbToColorString`

Converts a RgbColor or RgbaColor object to a color string.
This util is useful in case you only know on runtime which color object is
used. Otherwise we recommend to rely on `rgb` or `rgba`.

#### Parameters

-   `color` **([RgbColor](#rgbcolor) \| [RgbaColor](#rgbacolor))** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: rgbToColorString({ red: 255, green: 205, blue: 100 }),
  background: rgbToColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 }),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${rgbToColorString({ red: 255, green: 205, blue: 100 })};
  background: ${rgbToColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 })};
`

// CSS in JS Output
element {
  background: "#ffcd64";
  background: "rgba(255,205,100,0.72)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `saturate`

Increases the intensity of a color. Its range is between 0 to 1. The first
argument of the saturate function is the amount by how much the color
intensity should be increased.

#### Parameters

-   `amount` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: saturate(0.2, '#CCCD64'),
  background: saturate('0.2', 'rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${saturate(0.2, '#FFCD64')};
  background: ${saturate('0.2', 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output

element {
  background: "#e0e250";
  background: "rgba(224,226,80,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `setHue`

Sets the hue of a color to the provided value. The hue range can be
from 0 and 359.

#### Parameters

-   `hue` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: setHue(42, '#CCCD64'),
  background: setHue('244', 'rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${setHue(42, '#CCCD64')};
  background: ${setHue('244', 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#cdae64";
  background: "rgba(107,100,205,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `setLightness`

Sets the lightness of a color to the provided value. The lightness range can be
from 0 and 1.

#### Parameters

-   `lightness` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: setLightness(0.2, '#CCCD64'),
  background: setLightness('0.75', 'rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${setLightness(0.2, '#CCCD64')};
  background: ${setLightness('0.75', 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#4d4d19";
  background: "rgba(223,224,159,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `setSaturation`

Sets the saturation of a color to the provided value. The saturation range can be
from 0 and 1.

#### Parameters

-   `saturation` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: setSaturation(0.2, '#CCCD64'),
  background: setSaturation('0.75', 'rgba(204,205,100,0.7)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${setSaturation(0.2, '#CCCD64')};
  background: ${setSaturation('0.75', 'rgba(204,205,100,0.7)')};
`

// CSS in JS Output
element {
  background: "#adad84";
  background: "rgba(228,229,76,0.7)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `shade`

Shades a color by mixing it with black. `shade` can produce
hue shifts, where as `darken` manipulates the luminance channel and therefore
doesn't produce hue shifts.

#### Parameters

-   `percentage` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: shade(0.25, '#00f')
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${shade(0.25, '#00f')};
`

// CSS in JS Output

element {
  background: "#00003f";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `tint`

Tints a color by mixing it with white. `tint` can produce
hue shifts, where as `lighten` manipulates the luminance channel and therefore
doesn't produce hue shifts.

#### Parameters

-   `percentage` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: tint(0.25, '#00f')
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${tint(0.25, '#00f')};
`

// CSS in JS Output

element {
  background: "#bfbfff";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `toColorString`

Converts a RgbColor, RgbaColor, HslColor or HslaColor object to a color string.
This util is useful in case you only know on runtime which color object is
used. Otherwise we recommend to rely on `rgb`, `rgba`, `hsl` or `hsla`.

#### Parameters

-   `color` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: toColorString({ red: 255, green: 205, blue: 100 }),
  background: toColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 }),
  background: toColorString({ hue: 240, saturation: 1, lightness: 0.5 }),
  background: toColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 }),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${toColorString({ red: 255, green: 205, blue: 100 })};
  background: ${toColorString({ red: 255, green: 205, blue: 100, alpha: 0.72 })};
  background: ${toColorString({ hue: 240, saturation: 1, lightness: 0.5 })};
  background: ${toColorString({ hue: 360, saturation: 0.75, lightness: 0.4, alpha: 0.72 })};
`

// CSS in JS Output
element {
  background: "#ffcd64";
  background: "rgba(255,205,100,0.72)";
  background: "#00f";
  background: "rgba(179,25,25,0.72)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `transparentize`

Decreases the opacity of a color. Its range for the amount is between 0 to 1.

#### Parameters

-   `amount` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** 
-   `color` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  background: transparentize(0.1, '#fff');
  background: transparentize(0.2, 'hsl(0, 0%, 100%)'),
  background: transparentize('0.5', 'rgba(255, 0, 0, 0.8)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  background: ${transparentize(0.1, '#fff')};
  background: ${transparentize(0.2, 'hsl(0, 0%, 100%)')},
  background: ${transparentize('0.5', 'rgba(255, 0, 0, 0.8)')},
`

// CSS in JS Output

element {
  background: "rgba(255,255,255,0.9)";
  background: "rgba(255,255,255,0.8)";
  background: "rgba(255,0,0,0.3)";
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `directionalProperty`

Enables shorthand for direction-based properties. It accepts a property (hyphenated or camelCased) and up to four
values that map to top, right, bottom, and left, respectively. You can optionally pass an empty string to get only
the directional values as properties. You can also optionally pass a null argument for a directional value to ignore
it.

#### Parameters

-   `property` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)? | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...directionalProperty('padding', '12px', '24px', '36px', '48px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${directionalProperty('padding', '12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'paddingTop': '12px',
  'paddingRight': '24px',
  'paddingBottom': '36px',
  'paddingLeft': '48px'
}
```

Returns **[Styles](#styles)** 

---

### function `em`

Convert pixel value to ems. The default base value is 16px, but can be changed by passing a
second argument to the function.

Type: function (value: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)), base: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))): [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

#### Parameters

-   `pxval` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `base` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))**  (optional, default `'16px'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  'height': em('16px')
}

// syled (CSS in JS) usage
const div = styled.div`
  height: ${em('16px')}
`

// CSS in JS Output

element {
  'height': '1em'
}
```

---

### function `getValueAndUnit`

Returns a given CSS value and its unit as elements of an array.

#### Parameters

-   `value` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  '--dimension': getValueAndUnit('100px')[0],
  '--unit': getValueAndUnit('100px')[1],
}

// syled (CSS in JS) usage
const div = styled.div`
  --dimension: ${getValueAndUnit('100px')[0]};
  --unit: ${getValueAndUnit('100px')[1]};
`

// CSS in JS Output

element {
  '--dimension': 100,
  '--unit': 'px',
}
```

Returns **\[([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)), ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | void)]** 

**Meta**

-   **deprecated**: getValueAndUnit has been marked for deprecation in polished 3.0 and will be fully deprecated in 4.0.
      It's functionality has been been moved to stripUnit as an optional return.


---

### function `modularScale`

Establish consistent measurements and spacial relationships throughout your projects by incrementing an em or rem
value up or down a defined scale. We provide a list of commonly used scales as pre-defined variables.

#### Parameters

-   `steps` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 
-   `base` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**  (optional, default `'1em'`)
-   `ratio` **[ModularScaleRatio](#modularscaleratio)**  (optional, default `1.333`)

#### Examples

```javascript
// Styles as object usage
const styles = {
   // Increment two steps up the default scale
  'fontSize': modularScale(2)
}

// syled (CSS in JS) usage
const div = styled.div`
   // Increment two steps up the default scale
  fontSize: ${modularScale(2)}
`

// CSS in JS Output

element {
  'fontSize': '1.77689em'
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `rem`

Convert pixel value to rems. The default base value is 16px, but can be changed by passing a
second argument to the function.

Type: function (value: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)), base: ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))): [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

#### Parameters

-   `pxval` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `base` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))**  (optional, default `'16px'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  'height': rem('16px')
}

// syled (CSS in JS) usage
const div = styled.div`
  height: ${rem('16px')}
`

// CSS in JS Output

element {
  'height': '1rem'
}
```

---

### function `stripUnit`

Returns a given CSS value minus its unit (or the original value if an invalid string is passed). Optionally returns
an array containing the stripped value and the original unit of measure.

#### Parameters

-   `value` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `unitReturn` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  '--dimension': stripUnit('100px'),
  '--unit': stripUnit('100px')[1],
}

// syled (CSS in JS) usage
const div = styled.div`
  --dimension: ${stripUnit('100px')};
  --unit: ${stripUnit('100px')[1]};
`

// CSS in JS Output

element {
  '--dimension': 100,
  '--unit': 'px',
}
```

Returns **any** 

---

### function `math`

Helper for doing math with CSS Units. Accepts a formula as a string. All values in the formula must have the same
unit (or be unitless). Supports complex formulas utliziing addition, subtraction, multiplication, division, square
root, powers, factorial, min, max, as well as parentheses for order of operation.

In cases where you need to do calculations with mixed units where one unit is a [relative length unit](https://developer.mozilla.org/en-US/docs/Web/CSS/length#Relative_length_units), you will want to use [CSS Calc](https://developer.mozilla.org/en-US/docs/Web/CSS/calc).

_warning_ While we've done everything possible to ensure math safely evalutes formulas expressed as strings, you
should always use extreme caution when passing `math` user provided values.

#### Parameters

-   `formula` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `additionalSymbols` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  fontSize: math('12rem + 8rem'),
  fontSize: math('(12px + 2px) * 3'),
  fontSize: math('3px^2 + sqrt(4)'),
}

// syled (CSS in JS) usage
const div = styled.div`
  fontSize: ${math('12rem + 8rem')};
  fontSize: ${math('(12px + 2px) * 3')};
  fontSize: ${math('3px^2 + sqrt(4)')};
`

// CSS as JS Output

div: {
  fontSize: '20rem',
  fontSize: '42px',
  fontSize: '11px',
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `between`

Returns a CSS calc formula for linear interpolation of a property between two values. Accepts optional minScreen
(defaults to '320px') and maxScreen (defaults to '1200px').

#### Parameters

-   `fromSize` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `toSize` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `minScreen` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'320px'`)
-   `maxScreen` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'1200px'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  fontSize: between('20px', '100px', '400px', '1000px'),
  fontSize: between('20px', '100px')
}

// syled (CSS in JS) usage
const div = styled.div`
  fontSize: ${between('20px', '100px', '400px', '1000px')};
  fontSize: ${between('20px', '100px')}
`

// CSS as JS Output

h1: {
  'fontSize': 'calc(-33.33333333333334px + 13.333333333333334vw)',
  'fontSize': 'calc(-9.090909090909093px + 9.090909090909092vw)'
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `clearFix`

CSS to contain a float (credit to CSSMojo).

#### Parameters

-   `parent` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'&'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
   ...clearFix(),
}

// syled (CSS in JS) usage
const div = styled.div`
  ${clearFix()}
`

// CSS as JS Output

'&::after': {
  'clear': 'both',
  'content': '""',
  'display': 'table'
}
```

Returns **[Styles](#styles)** 

---

### function `cover`

CSS to fully cover an area. Can optionally be passed an offset to act as a "padding".

#### Parameters

-   `offset` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**  (optional, default `0`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...cover()
}

// syled (CSS in JS) usage
const div = styled.div`
  ${cover()}
`

// CSS as JS Output

div: {
  'position': 'absolute',
  'top': '0',
  'right: '0',
  'bottom': '0',
  'left: '0'
}
```

Returns **[Styles](#styles)** 

---

### function `ellipsis`

CSS to represent truncated text with an ellipsis.

#### Parameters

-   `width` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))**  (optional, default `'100%'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...ellipsis('250px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${ellipsis('250px')}
`

// CSS as JS Output

div: {
  'display': 'inline-block',
  'maxWidth': '250px',
  'overflow': 'hidden',
  'textOverflow': 'ellipsis',
  'whiteSpace': 'nowrap',
  'wordWrap': 'normal'
}
```

Returns **[Styles](#styles)** 

---

### function `fluidRange`

Returns a set of media queries that resizes a property (or set of properties) between a provided fromSize and
toSize. Accepts optional minScreen (defaults to '320px') and maxScreen (defaults to '1200px') to constrain the
interpolation.

#### Parameters

-   `cssProp` **([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[FluidRangeConfiguration](#fluidrangeconfiguration)> | [FluidRangeConfiguration](#fluidrangeconfiguration))** 
-   `minScreen` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'320px'`)
-   `maxScreen` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'1200px'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...fluidRange(
   {
       prop: 'padding',
       fromSize: '20px',
       toSize: '100px',
     },
     '400px',
     '1000px',
   )
}

// syled (CSS in JS) usage
const div = styled.div`
  ${fluidRange(
     {
       prop: 'padding',
       fromSize: '20px',
       toSize: '100px',
     },
     '400px',
     '1000px',
   )}
`

// CSS as JS Output

div: {
  "@media (min-width: 1000px)": Object {
    "padding": "100px",
  },
  "@media (min-width: 400px)": Object {
    "padding": "calc(-33.33333333333334px + 13.333333333333334vw)",
  },
  "padding": "20px",
}
```

Returns **[Styles](#styles)** 

---

### function `fontFace`

CSS for a @font-face declaration.

#### Parameters

-   `$0` **any** 
    -   `$0.fontFamily`  
    -   `$0.fontFilePath`  
    -   `$0.fontStretch`  
    -   `$0.fontStyle`  
    -   `$0.fontVariant`  
    -   `$0.fontWeight`  
    -   `$0.fileFormats`   (optional, default `['eot','woff2','woff','ttf','svg']`)
    -   `$0.formatHint`   (optional, default `false`)
    -   `$0.localFonts`  
    -   `$0.unicodeRange`  
    -   `$0.fontDisplay`  
    -   `$0.fontVariationSettings`  
    -   `$0.fontFeatureSettings`  

#### Examples

```javascript
// Styles as object basic usage
const styles = {
   ...fontFace({
     'fontFamily': 'Sans-Pro',
     'fontFilePath': 'path/to/file'
   })
}

// styled-components basic usage
const GlobalStyle = createGlobalStyle`${
  fontFace({
    'fontFamily': 'Sans-Pro',
    'fontFilePath': 'path/to/file'
  }
)}`

// CSS as JS Output

'@font-face': {
  'fontFamily': 'Sans-Pro',
  'src': 'url("path/to/file.eot"), url("path/to/file.woff2"), url("path/to/file.woff"), url("path/to/file.ttf"),
  url("path/to/file.svg")',
}
```

Returns **[Styles](#styles)** 

---

### function `hideText`

CSS to hide text to show a background image in a SEO-friendly way.

#### Examples

```javascript
// Styles as object usage
const styles = {
  'backgroundImage': 'url(logo.png)',
  ...hideText(),
}

// syled (CSS in JS) usage
const div = styled.div`
  backgroundImage: url(logo.png);
  ${hideText()};
`

// CSS as JS Output

'div': {
  'backgroundImage': 'url(logo.png)',
  'textIndent': '101%',
  'overflow': 'hidden',
  'whiteSpace': 'nowrap',
}
```

Returns **[Styles](#styles)** 

---

### function `hideVisually`

CSS to hide content visually but remain accessible to screen readers.
from [HTML5
Boilerplate](https://github.com/h5bp/html5-boilerplate/blob/9a176f57af1cfe8ec70300da4621fb9b07e5fa31/src/css/main.css#L121)

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...hideVisually(),
}

// syled (CSS in JS) usage
const div = styled.div`
  ${hideVisually()};
`

// CSS as JS Output

'div': {
  'border': '0',
  'clip': 'rect(0 0 0 0)',
  'clipPath': 'inset(50%)',
  'height': '1px',
  'margin': '-1px',
  'overflow': 'hidden',
  'padding': '0',
  'position': 'absolute',
  'whiteSpace': 'nowrap',
  'width': '1px',
}
```

Returns **[Styles](#styles)** 

---

### function `hiDPI`

Generates a media query to target HiDPI devices.

#### Parameters

-   `ratio` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**  (optional, default `1.3`)

#### Examples

```javascript
// Styles as object usage
const styles = {
 [hiDPI(1.5)]: {
   width: 200px;
 }
}

// syled (CSS in JS) usage
const div = styled.div`
  ${hiDPI(1.5)} {
    width: 200px;
  }
`

// CSS as JS Output

'@media only screen and (-webkit-min-device-pixel-ratio: 1.5),
 only screen and (min--moz-device-pixel-ratio: 1.5),
 only screen and (-o-min-device-pixel-ratio: 1.5/1),
 only screen and (min-resolution: 144dpi),
 only screen and (min-resolution: 1.5dppx)': {
  'width': '200px',
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `linearGradient`

CSS for declaring a linear gradient, including a fallback background-color. The fallback is either the first
color-stop or an explicitly passed fallback color.

#### Parameters

-   `$0` **any** 
    -   `$0.colorStops`  
    -   `$0.fallback`  
    -   `$0.toDirection`   (optional, default `''`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...linearGradient({
colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
toDirection: 'to top right',
fallback: '#FFF',
})
}

// syled (CSS in JS) usage
const div = styled.div`
  ${linearGradient({
colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
toDirection: 'to top right',
fallback: '#FFF',
})}
`

// CSS as JS Output

div: {
  'backgroundColor': '#FFF',
  'backgroundImage': 'linear-gradient(to top right, #00FFFF 0%, rgba(0, 0, 255, 0) 50%, #0000FF 95%)',
}
```

Returns **[Styles](#styles)** 

---

### function `normalize`

CSS to normalize abnormalities across browsers (normalize.css v8.0.0 | MIT License |
github.com/necolas/normalize.css)

#### Examples

```javascript
// Styles as object usage
const styles = {
   ...normalize(),
}

// syled (CSS in JS) usage
const GlobalStyle = createGlobalStyle`${normalize()}`

// CSS as JS Output

html {
  lineHeight: 1.15,
  textSizeAdjust: 100%,
} ...
```

Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Styles](#styles)>** 

---

### function `radialGradient`

CSS for declaring a radial gradient, including a fallback background-color. The fallback is either the first
color-stop or an explicitly passed fallback color.

#### Parameters

-   `$0` **any** 
    -   `$0.colorStops`  
    -   `$0.extent`   (optional, default `''`)
    -   `$0.fallback`  
    -   `$0.position`   (optional, default `''`)
    -   `$0.shape`   (optional, default `''`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...radialGradient({
    colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
    extent: 'farthest-corner at 45px 45px',
    position: 'center',
    shape: 'ellipse',
  })
}

// syled (CSS in JS) usage
const div = styled.div`
  ${radialGradient({
    colorStops: ['#00FFFF 0%', 'rgba(0, 0, 255, 0) 50%', '#0000FF 95%'],
    extent: 'farthest-corner at 45px 45px',
    position: 'center',
    shape: 'ellipse',
  })}
`

// CSS as JS Output

div: {
  'backgroundColor': '#00FFFF',
  'backgroundImage': 'radial-gradient(center ellipse farthest-corner at 45px 45px, #00FFFF 0%, rgba(0, 0, 255, 0)
  50%, #0000FF 95%)',
}
```

Returns **[Styles](#styles)** 

---

### function `retinaImage`

A helper to generate a retina background image and non-retina
background image. The retina background image will output to a HiDPI media query. The mixin uses
a \_2x.png filename suffix by default.

#### Parameters

-   `filename` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `backgroundSize` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `extension` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'png'`)
-   `retinaFilename` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `retinaSuffix` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'_2x'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
 ...retinaImage('my-img')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${retinaImage('my-img')}
`

// CSS as JS Output
div {
  backgroundImage: 'url(my-img.png)',
  '@media only screen and (-webkit-min-device-pixel-ratio: 1.3),
   only screen and (min--moz-device-pixel-ratio: 1.3),
   only screen and (-o-min-device-pixel-ratio: 1.3/1),
   only screen and (min-resolution: 144dpi),
   only screen and (min-resolution: 1.5dppx)': {
    backgroundImage: 'url(my-img_2x.png)',
  }
}
```

Returns **[Styles](#styles)** 

---

### function `timingFunctions`

String to represent common easing functions as demonstrated here: (github.com/jaukia/easie).

#### Parameters

-   `timingFunction` **[TimingFunction](#timingfunction)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  'transitionTimingFunction': timingFunctions('easeInQuad')
}

// syled (CSS in JS) usage
 const div = styled.div`
  transitionTimingFunction: ${timingFunctions('easeInQuad')};
`

// CSS as JS Output

'div': {
  'transitionTimingFunction': 'cubic-bezier(0.550,  0.085, 0.680, 0.530)',
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `triangle`

CSS to represent triangle with any pointing direction with an optional background color.

#### Parameters

-   `$0` **any** 
    -   `$0.pointingDirection`  
    -   `$0.height`  
    -   `$0.width`  
    -   `$0.foregroundColor`  
    -   `$0.backgroundColor`   (optional, default `'transparent'`)

#### Examples

```javascript
// Styles as object usage

const styles = {
  ...triangle({ pointingDirection: 'right', width: '100px', height: '100px', foregroundColor: 'red' })
}


// syled (CSS in JS) usage
const div = styled.div`
  ${triangle({ pointingDirection: 'right', width: '100px', height: '100px', foregroundColor: 'red' })}


// CSS as JS Output

div: {
 'borderColor': 'transparent transparent transparent red',
 'borderStyle': 'solid',
 'borderWidth': '50px 0 50px 100px',
 'height': '0',
 'width': '0',
}
```

Returns **[Styles](#styles)** 

---

### function `wordWrap`

Provides an easy way to change the `wordWrap` property.

#### Parameters

-   `wrap` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**  (optional, default `'break-word'`)

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...wordWrap('break-word')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${wordWrap('break-word')}
`

// CSS as JS Output

const styles = {
  overflowWrap: 'break-word',
  wordWrap: 'break-word',
  wordBreak: 'break-all',
}
```

Returns **[Styles](#styles)** 

---

### function `animation`

Shorthand for easily setting the animation property. Allows either multiple arrays with animations
or a single animation spread over the arguments.

#### Parameters

-   `args` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))> | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...animation(['rotate', '1s', 'ease-in-out'], ['colorchange', '2s'])
}

// syled (CSS in JS) usage
const div = styled.div`
  ${animation(['rotate', '1s', 'ease-in-out'], ['colorchange', '2s'])}
`

// CSS as JS Output

div {
  'animation': 'rotate 1s ease-in-out, colorchange 2s'
}
```

```javascript
// Styles as object usage
const styles = {
  ...animation('rotate', '1s', 'ease-in-out')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${animation('rotate', '1s', 'ease-in-out')}
`

// CSS as JS Output

div {
  'animation': 'rotate 1s ease-in-out'
}
```

Returns **[Styles](#styles)** 

---

### function `backgroundImages`

Shorthand that accepts any number of backgroundImage values as parameters for creating a single background statement.

#### Parameters

-   `properties` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...backgroundImages('url("/image/background.jpg")', 'linear-gradient(red, green)')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${backgroundImages('url("/image/background.jpg")', 'linear-gradient(red, green)')}
`

// CSS as JS Output

div {
  'backgroundImage': 'url("/image/background.jpg"), linear-gradient(red, green)'
}
```

Returns **[Styles](#styles)** 

---

### function `backgrounds`

Shorthand that accepts any number of background values as parameters for creating a single background statement.

#### Parameters

-   `properties` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...backgrounds('url("/image/background.jpg")', 'linear-gradient(red, green)', 'center no-repeat')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${backgrounds('url("/image/background.jpg")', 'linear-gradient(red, green)', 'center no-repeat')}
`

// CSS as JS Output

div {
  'background': 'url("/image/background.jpg"), linear-gradient(red, green), center no-repeat'
}
```

Returns **[Styles](#styles)** 

---

### function `border`

Shorthand for the border property that splits out individual properties for use with tools like Fela and Styletron.
A side keyword can optionally be passed to target only one side's border properties.

#### Parameters

-   `sideKeyword` **([SideKeyword](#sidekeyword) \| [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 
-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...border('1px', 'solid', 'red')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${border('1px', 'solid', 'red')}
`

// CSS as JS Output

div {
  'borderColor': 'red',
  'borderStyle': 'solid',
  'borderWidth': `1px`,
}

// Styles as object usage
const styles = {
  ...border('top', '1px', 'solid', 'red')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${border('top', '1px', 'solid', 'red')}
`

// CSS as JS Output

div {
  'borderTopColor': 'red',
  'borderTopStyle': 'solid',
  'borderTopWidth': `1px`,
}
```

Returns **[Styles](#styles)** 

---

### function `borderColor`

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective
directions.

#### Parameters

-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...borderColor('red', 'green', 'blue', 'yellow')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${borderColor('red', 'green', 'blue', 'yellow')}
`

// CSS as JS Output

div {
  'borderTopColor': 'red',
  'borderRightColor': 'green',
  'borderBottomColor': 'blue',
  'borderLeftColor': 'yellow'
}
```

Returns **[Styles](#styles)** 

---

### function `borderRadius`

Shorthand that accepts a value for side and a value for radius and applies the radius value to both corners of the
side.

#### Parameters

-   `side` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `radius` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...borderRadius('top', '5px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${borderRadius('top', '5px')}
`

// CSS as JS Output

div {
  'borderTopRightRadius': '5px',
  'borderTopLeftRadius': '5px',
}
```

Returns **[Styles](#styles)** 

---

### function `borderStyle`

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective
directions.

#### Parameters

-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...borderStyle('solid', 'dashed', 'dotted', 'double')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${borderStyle('solid', 'dashed', 'dotted', 'double')}
`

// CSS as JS Output

div {
  'borderTopStyle': 'solid',
  'borderRightStyle': 'dashed',
  'borderBottomStyle': 'dotted',
  'borderLeftStyle': 'double'
}
```

Returns **[Styles](#styles)** 

---

### function `borderWidth`

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective
directions.

#### Parameters

-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)? | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...borderWidth('12px', '24px', '36px', '48px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${borderWidth('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'borderTopWidth': '12px',
  'borderRightWidth': '24px',
  'borderBottomWidth': '36px',
  'borderLeftWidth': '48px'
}
```

Returns **[Styles](#styles)** 

---

### function `buttons`

Populates selectors that target all buttons. You can pass optional states to append to the selectors.

#### Parameters

-   `states` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[InteractionState](#interactionstate)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  [buttons('active')]: {
    'border': 'none'
  }
}

// syled (CSS in JS) usage
const div = styled.div`
  > ${buttons('active')} {
    border: none;
  }
`

// CSS in JS Output

 'button:active,
 'input[type="button"]:active,
 'input[type=\"reset\"]:active,
 'input[type=\"submit\"]:active: {
  'border': 'none'
}
```

Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** 

---

### function `margin`

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective
directions.

#### Parameters

-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)? | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...margin('12px', '24px', '36px', '48px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${margin('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'marginTop': '12px',
  'marginRight': '24px',
  'marginBottom': '36px',
  'marginLeft': '48px'
}
```

Returns **[Styles](#styles)** 

---

### function `padding`

Shorthand that accepts up to four values, including null to skip a value, and maps them to their respective
directions.

#### Parameters

-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)? | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...padding('12px', '24px', '36px', '48px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${padding('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'paddingTop': '12px',
  'paddingRight': '24px',
  'paddingBottom': '36px',
  'paddingLeft': '48px'
}
```

Returns **[Styles](#styles)** 

---

### function `position`

Shorthand accepts up to five values, including null to skip a value, and maps them to their respective directions.
The first value can optionally be a position keyword.

#### Parameters

-   `positionKeyword` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | null)** 
-   `values` **...[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)? | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?)>** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  ...position('12px', '24px', '36px', '48px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${position('12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'top': '12px',
  'right': '24px',
  'bottom': '36px',
  'left': '48px'
}

// Styles as object usage
const styles = {
  ...position('absolute', '12px', '24px', '36px', '48px')
}

// syled (CSS in JS) usage
const div = styled.div`
  ${position('absolute', '12px', '24px', '36px', '48px')}
`

// CSS as JS Output

div {
  'position': 'absolute',
  'top': '12px',
  'right': '24px',
  'bottom': '36px',
  'left': '48px'
}
```

Returns **[Styles](#styles)** 

### CSSHelpers

---

### function `topShadow`

Computes a material design style top shadow effect to mimic depth.

#### Parameters

-   `depth` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  boxShadow: `${topShadow(0)}, ${topShadow(1)}`
}

// syled (CSS in JS) usage
const div = styled.div`
  box-shadow: ${topShadow(0)}, ${topShadow(1)};
`

// CSS as JS Output

div {
  'box-shadow': '0 2px 0 rgba(18, 23, 28, 0.012), 0 4px 3px rgba(18, 23, 28, 0.016)'
}
```

---

### function `bottomShadow`

Computes a material design style bottom shadow effect to mimic depth.

#### Parameters

-   `depth` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** 

#### Examples

```javascript
// Styles as object usage
const styles = {
  boxShadow: `${bottomShadow(0)}, ${bottomShadow(1)}`
}

// syled (CSS in JS) usage
const div = styled.div`
  box-shadow: ${bottomShadow(0)}, ${bottomShadow(1)};
`

// CSS as JS Output

div {
  'box-shadow': '0 0.5px 0.5px rgba(18, 23, 28, 0.017), 0 1.5px 1px rgba(18, 23, 28, 0.024)'
}
```

---

### function `size`

Shorthand to set the height