npm package: @plangrid/color
Description: Color codes, classes, and variables
Latest version: 0.29.2

# [
color
](https://www.npmjs.com/package/@plangrid/color)

**Renamed to [`@plangrid/paint`](https://www.npmjs.com/package/@plangrid/paint) : )**

Future versions will appear there.

## Production

```css
@import "node_modules/@plangrid/color/main";
```

- [`main.css`](main.css) is the production bundle
- [`live.css`](live.css) is the same bundle but with live CSS vars
- [`module.css`](module.css) shows the module content for both

## Low-level atomic API

Stateful atomic classes are made via [templates](templates) and provided for all swatches for use like `class="ccc-blue-500"`

- <code>`.ccc-*`</code> base `color`
  - <code>`.fcc-*`</code> focus `color`
  - <code>`.hcc-*`</code> hover `color`
  - <code>`.xcc-*`</code> press `color`
  - <code>`.acc-*`</code> active `color`
  - <code>`.dcc-*`</code> disabled `color`
- <code>`.ggg-*`</code> base `background`
  - <code>`.fgg-*`</code> focus `background`
  - <code>`.hgg-*`</code> hover `background`
  - <code>`.xgg-*`</code> press `background`
  - <code>`.agg-*`</code> active `background`
  - <code>`.dgg-*`</code> disabled `background`
- <code>`.bbb-*`</code> base `border-color`
  - <code>`.fbb-*`</code> focus `border-color`
  - <code>`.hbb-*`</code> hover `border-color`
  - <code>`.xbb-*`</code> press `border-color`
  - <code>`.abb-*`</code> active `border-color`
  - <code>`.dbb-*`</code> disabled `border-color`

An earlier simpler less-capable atomic set exists in [`atomic.css`](atomic.css) but we plan to move away from those and instead to the ones above wrapped in a higher-level API via JavaScript. See [#sheen](#sheen)

## [Tone](tone.css)

- `.tone-validate` is designed for inputs using native [`[aria-invalid]`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute) (Recommended)
- `.tone-validity` is designed for inputs using native [constraint validation](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation)
- `.tone-valid` is designed for forcing valid appearance
- `.tone-invalid` is designed for forcing invalid appearance
- `.tone-primary` is designed for primary actions (Save)
- `.tone-additive` is designed for additive actions (Create)
- `.tone-destructive` is designed for destructive actions (Delete)
- `.tone-pill` combines primary and destructive for deletable pills
- `.tone-secondary` is designed for secondary actions (Cancel)
- `.tone-icon` is designed for buttons represented by icons
- `.tone-link` is designed for links or buttons appearing as links
- `.tone-check` is designed for radios and checkboxes

## [Shadow](shadow.css)

- `.shadow-raised` base static raised shadow
- `.shadow-ring` applies our standard ring on `:focus`
- `.shadow-halo` **experimental** static raised ring

## [Blending](blending.css)

Blending patterns are useful for routing colors in component designs. Blending classes themselves are for demoing the technique and are excluded from the main bundle.

| Classes | `color` | `background` | `border-color` |
|:--------|:--------|:-------------|:---------------|
| `.blend` `.blend-before` `.blend-after` | `inherit` | `transparent` |  `transparent` |
| `.dodge` `.dodge-before` `.dodge-after` | `transparent` | `transparent` |  `inherit` |
| `.burn` `.burn-before` `.burn-after` | `inherit` | `transparent ` | `currentColor` |
| `.coat` `.coat-before` `.coat-after` | `inherit` | `inherit` |  `inherit` |
| `.blot` `.blot-before` `.blot-after` | `inherit` | `currentColor` | `currentColor` |

## JavaScript API

### [`paint`](paint.js)

```js
const paint = require("@plangrid/color")
```

[`paint`](paint.js) includes a superset of [`sheen`](#sheen) [`swatch`](#swatch) [`ink`](#ink). These modules are also each available for direct import.

```js
paint.vivid("blue") // atomic classes for vivid blue paint
paint.glaze("blue") // atomic classes for glaze blue paint
paint.matte("blue") // atomic classes for matte blue paint
paint.swatch("blue-500") // "#0085de"
paint.identify("#0085de") // "blue-500"
paint.nearest("#0085dd") // "blue-500"
paint.ideal("blue-base") // "blue-500"
paint.inks() // ["red", "orange", ...]
/*...*/
```

### [`sheen`](sheen.js)

```js
const sheen = require("@plangrid/color/sheen")
```

```js
sheen.vivid("blue") // atomic classes for vivid blue paint
sheen.glaze("blue") // atomic classes for glaze blue paint
sheen.matte("blue") // atomic classes for matte blue paint
```

### [`ink`](ink.js)

```js
const ink = require("@plangrid/color/ink")
```

`ink` is special paint for annotations

#### `ink.wet(hue)` aka `ink.user(hue)`

```js
ink.wet("orange") // "#f38109"
ink.user("orange") // "#f38109"
```

#### `ink.dry(hue)` aka `ink.master(hue)`

```js
ink.dry("orange") // "#e6400a"
ink.master("orange") // "#e6400a"
```

#### `ink.inks(start=0, end=undefined)`

Slice a copy of all the ink hues in the set

```js
ink.inks() // ["red", "orange", ...]
```

### [`swatch`](swatch.js)

```js
const swatch = require("@plangrid/color/swatch")
```

<code>swatch(<var>name</var>)</code> is a custom JavaScript function for providing `color` by its name in our design system.

```js
swatch("black") // "#1f313d"
swatch("blue-500") // "#0085de"
```

`swatch` also works with identical interface in `postcss` via [`postcss-functions`](https://www.npmjs.com/package/postcss-functions) and `node-sass` via `--functions`

```css
box-shadow: 1em 1em swatch("black");
box-shadow: 1em 1em swatch("shade-50");
```

#### `swatch.identify(value)`

- `value` can be any valid color format
- Returns `id` of exact match or else throws error

```js
swatch.identify("#1f313d") // "black"
swatch.identify("rgba(31, 49, 61, 0.5)") // "dark-50"
```

#### `swatch.ideal(id)`

- Return ideal id for <var>id</var>
- <var>id</var> may be an alias but the return won't be

```js
swatch.ideal("blue-base") // "blue-500"
swatch.ideal("blue-dim") // "blue-700"
```

#### `swatch.ideals()`

- Return array of all ideals

```js
swatch.ideals() // ["blue-100", "blue-200" ,...]
```

#### `swatch.nearest(value)`

- `value` can be any valid color format
- [Returns `id` for nearest non-transparent match](https://github.com/plangrid/color/pull/145)

```js
swatch.nearest("#444") // "steel"
swatch.nearest("rgb(1, 1, 1)") // "black"
swatch.nearest("rgba(1, 1, 1, .1)") // "black"
```

#### `swatch.pluck(key)`

- Pluck key from registry objects
- Return array of plucked values

## Development

```
git clone git@github.com:plangrid/color.git
cd color
npm install
npm test
npm start
open index.html
```

Right now the source of truth for the values is in [swatch.js](swatch.js) and [dev.js](dev.js). Running <b>`npm start`</b> updates the other files.

## Next coat

:art: [`@plangrid/paint`](https://www.npmjs.com/package/@plangrid/paint)