npm package: @stead/colors
Description: Colors for digital and software products
Latest version: 0.1.1

# @stead/colors

> Colors for digital and software products using the Stead Design System

## Getting started

To install `@stead/colors` in your project, you will need to run the following
command using [npm](https://www.npmjs.com/):

```bash
npm install -S @stead/colors
```

If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
instead:

```bash
yarn add @stead/colors
```

## Usage

You can use the `@stead/colors` module in your JavaScript, in addition to your
Sass.

### Sass

In Sass, you can import the files individual by doing:

```scss
@import '@stead/colors/scss/colors';
```

This file automatically includes the `stead-colors` mixin which initializes
all the color variables for the Stead Design Language.

These color variables follow the naming convention: `$stead-<swatch>-<grade>`.
For example:

```scss
$stead-blue-50;
$stead-cool-gray-10;
$stead-black-100;
$stead-white-0;
```

You can also use the shorthand form of these colors by dropping the `stead-`
namespace:

```scss
$blue-50;
$cool-gray-10;
$black-100;
$white-0;
```

_Note: the shorthand variables require that you do not have any other
conflicting variables in your setup. Namespaced variables are always preferred
for this reason, unless you are confident that no collisions will occur._

If you would like you choose when these variables are defined, then you can call
the `stead-colors` mixin directly by importing the following file:

```scss
@import '@stead/colors/scss/mixins';

// ...
@include stead-colors();
```

Alongside the color variables detailed above, we also provide a map of colors so
that you can programmatically use these values. This map is called
`$stead-colors` and each key is the name of a swatch. The value of these
swatches is also a map, but each key is now the grade. In code, this looks like
the following:

<!-- prettier-ignore-start -->

```scss
$stead-colors: (
  'blue': (
    10: #edf4ff,
    // ...
  )
);
```

<!-- prettier-ignore-end -->

You can include this variable by including `@stead/colors/scss/colors` or
calling the `stead-colors()` mixin directly.

```scss
@import '@stead/colors/scss/mixins';

@include ibm--colors();
```

### JavaScript

For JavaScript, you can import and use this module by doing the following in
your code:

```js
// ESM
import { black, blue, warmGray } from '@stead/colors';

// CommonJS
const { black, blue, warmGray } = require('@stead/colors');
```

Each color swatch is exported as a variable, and each color name is also
exported as an object that can be called by specifying grade, for example:

```js
black;
blue[50]; // Using the `blue` object.
warmGray100; // Using the `warmGray100` variable.
```

## 📖 API Documentation

If you're looking for `@stead/colors` API documentation, check out:

- [Sass](./docs/sass.md)

## 🙌 Contributing

We're always looking for contributors to help us fix bugs, build new features,
or help us improve the project documentation. If you're interested, definitely
check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀

## 📝 License

Licensed under the [Apache 2.0 License](/LICENSE).