make-random-color/README.md

A simple and flexible npm package for generating random color codes in various formats.

# make-random-color

`make-random-color` is a versatile and lightweight npm package that provides a collection of functions for generating random colors in various formats and styles. Whether you need a single random color, a gradient of colors, a color family, or colors with ensured contrast, `make-random-color` has you covered.

## Installation

You can install `make-random-color` using npm:

```bash
npm install make-random-color
```

## Usage

First, require the `make-random-color` package in your JavaScript file:

```javascript
const {
  generateRandomColor,
  generateRandomGradientColors,
  generateRandomColorFamily,
  ensureColorContrast,
  generateRandomPastelColor,
  generateRandomDarkColor,
  generateRandomLightColor,
} = require('make-random-color');
```

### Generating a Random Color

To generate a single random color, use the `generateRandomColor` function:

```javascript
const randomColor = generateRandomColor();
console.log(randomColor); // Output: '#a1b2c3'
```

You can customize the generated color by providing options:

```javascript
const options = {
  format: 'rgb',
  min: 100,
  max: 200,
  alpha: true,
  seed: 42,
};
const randomColor = generateRandomColor(options);
console.log(randomColor); // Output: 'rgba(150,175,120,0.75)'
```

### Generating Random Gradient Colors

To generate an array of random colors for a gradient, use the `generateRandomGradientColors` function:

```javascript
const gradientColors = generateRandomGradientColors({ count: 3 });
console.log(gradientColors); // Output: ['#a1b2c3', '#d4e5f6', '#7890ab']
```

### Generating a Random Color Family

To generate a family of colors based on a random base color, use the `generateRandomColorFamily` function:

```javascript
const colorFamily = generateRandomColorFamily({ count: 5, format: 'hsl' });
console.log(colorFamily);
// Output: ['hsl(120,50%,60%)', 'hsl(140,30%,50%)', 'hsl(100,70%,80%)', 'hsl(110,40%,70%)', 'hsl(130,60%,40%)']
```

### Ensuring Color Contrast

To ensure sufficient contrast between two colors, use the `ensureColorContrast` function:

```javascript
const [backgroundColor, textColor] = ensureColorContrast({ color1: '#000000', color2: '#ffffff', contrastRatio: 4.5 });
console.log(backgroundColor); // Output: '#000000'
console.log(textColor); // Output: '#ffffff'
```

### Generating Random Pastel, Dark, and Light Colors

To generate random colors with specific styles, use the `generateRandomPastelColor`, `generateRandomDarkColor`, and `generateRandomLightColor` functions:

```javascript
const pastelColor = generateRandomPastelColor();
console.log(pastelColor); // Output: '#f2d3e5'

const darkColor = generateRandomDarkColor({ format: 'rgb' });
console.log(darkColor); // Output: 'rgb(50,20,80)'

const lightColor = generateRandomLightColor({ format: 'hsl', alpha: true });
console.log(lightColor); // Output: 'hsla(200,80%,80%,0.85)'
```

## API

### `generateRandomColor(options)`

Generates a random color based on the provided options.

- `options` (optional): An object containing the following properties:
  - `format` (string, default: 'hex'): The format of the generated color. Can be 'hex', 'rgb', or 'hsl'.
  - `min` (number, default: 0): The minimum value for RGB color components.
  - `max` (number, default: 255): The maximum value for RGB color components.
  - `alpha` (boolean, default: false): Whether to include an alpha channel in the generated color.
  - `seed` (number, default: null): A seed value for reproducible random color generation.

Returns a string representing the generated random color.

### `generateRandomGradientColors(options)`

Generates an array of random colors for a gradient based on the provided options.

- `options` (optional): An object containing the following properties:
  - `format` (string, default: 'hex'): The format of the generated colors. Can be 'hex', 'rgb', or 'hsl'.
  - `count` (number, default: 2): The number of colors to generate for the gradient.
  - `min` (number, default: 0): The minimum value for RGB color components.
  - `max` (number, default: 255): The maximum value for RGB color components.
  - `alpha` (boolean, default: false): Whether to include an alpha channel in the generated colors.
  - `seed` (number, default: null): A seed value for reproducible random color generation.

Returns an array of strings representing the generated random gradient colors.

### `generateRandomColorFamily(options)`

Generates a family of colors based on a random base color and the provided options.

- `options` (optional): An object containing the following properties:
  - `format` (string, default: 'hex'): The format of the generated colors. Can be 'hex', 'rgb', or 'hsl'.
  - `count` (number, default: 5): The number of colors to generate for the color family.
  - `min` (number, default: 0): The minimum value for RGB color components.
  - `max` (number, default: 255): The maximum value for RGB color components.
  - `alpha` (boolean, default: false): Whether to include an alpha channel in the generated colors.
  - `seed` (number, default: null): A seed value for reproducible random color generation.
  - `hueRange` (number, default: 30): The range of hue variation for the color family.
  - `saturationRange` (number, default: 20): The range of saturation variation for the color family.
  - `lightnessRange` (number, default: 20): The range of lightness variation for the color family.

Returns an array of strings representing the generated color family.

### `ensureColorContrast(options)`

Ensures sufficient contrast between two colors based on the provided options.

- `options` (optional): An object containing the following properties:
  - `color1` (string): The first color in hexadecimal format.
  - `color2` (string): The second color in hexadecimal format.
  - `format` (string, default: 'hex'): The format of the returned colors. Can be 'hex' or 'rgb'.
  - `contrastRatio` (number, default: 4.5): The minimum contrast ratio to ensure between the colors.

Returns an array of two strings representing the colors with ensured contrast.

### `generateRandomPastelColor(options)`

Generates a random pastel color based on the provided options.

- `options` (optional): An object containing the following properties:
  - `format` (string, default: 'hex'): The format of the generated color. Can be 'hex', 'rgb', or 'hsl'.
  - `alpha` (boolean, default: false): Whether to include an alpha channel in the generated color.
  - `seed` (number, default: null): A seed value for reproducible random color generation.

Returns a string representing the generated random pastel color.

### `generateRandomDarkColor(options)`

Generates a random dark color based on the provided options.

- `options` (optional): An object containing the following properties:
  - `format` (string, default: 'hex'): The format of the generated color. Can be 'hex', 'rgb', or 'hsl'.
  - `alpha` (boolean, default: false): Whether to include an alpha channel in the generated color.
  - `seed` (number, default: null): A seed value for reproducible random color generation.

Returns a string representing the generated random dark color.

### `generateRandomLightColor(options)`

Generates a random light color based on the provided options.

- `options` (optional): An object containing the following properties:
  - `format` (string, default: 'hex'): The format of the generated color. Can be 'hex', 'rgb', or 'hsl'.
  - `alpha` (boolean, default: false): Whether to include an alpha channel in the generated color.
  - `seed` (number, default: null): A seed value for reproducible random color generation.

Returns a string representing the generated random light color.

## License

This package is open-source and available under the [MIT License](https://opensource.org/licenses/MIT).