tailwind-plugin-lob/README.md

Tailwind CSS plugin for Lob's design system

# tailwind-plugin-lob
Custom Tailwind config for Lob repositories

## Installation

```bash
npm i tailwind-plugin-lob -D
```
## Usage
Add tailwind-plugin-lob to the plugins section of your `tailwind.config.js` file.

```js
module.exports = {
  plugins: [
    require('tailwind-plugin-lob')
  ]
};
```

## Features
Default Tailwind configuration with some replacements for Lob's design system.

The following core plugins have been customized for Lob
- screens
- [colors](#colors)
- fontSize
- fontFamily
- fill
  - a fill class is created for each color in our theme
- boxShadow

The following core plugins have been extended for Lob
- borderWidth: to add a 3px border with `border-3`
- spacing: to add a spacing of 1.125rem with `m-4.5` or `p-4.5`

The following variants have been turned on for a subset of core plugins
- disabled
  - backgroundColor
  - borderColor
  - textColor
- group-hover (see [Tailwind's docs for an explanation of this variant](https://tailwindcss.com/docs/hover-focus-and-other-states#group-hover))
  - translate 

### Colors
The primary color, secondary colors, grays, and whites in the design system are named `${base color}-${numerical shade}`. For example, the palette below would have:
    - `flint-900` as the darkest shade
    - `flint-700`
    - `flint` as the base (middle) color
    - `flint-300`
    - `flint-100` as the lightest shade

This naming convention allows us to preserve the design system's original names, adhere to general Tailwind color conventions, and in addition to providing flexibility if more shades were to be introduced in the future.

![Flint color palette](assets/FlintColorPalette.png)

### Custom plugins
#### Border side colors

By default Tailwind does not allow you to control the color of each side of a border individually. To support CSS triangles and other complex styles, you may need to style each side separately. 

We have a border color that creates a class for each side of a border and each color in our theme. The class name format is `border-${side}-${base color}-${numerical shade}` like `border-r-flint-500`.


### Custom variants
#### Important
When our 'important' variant is enabled for a core plugin, it allows you to prefix a class with `!` to apply `!important` to the style. 

By default this variant has been turned on for a subset of core plugins
- backgroundColor
- borderColor
- textColor
- display

## Recommendations
It is recommended that you configure [PurgeCSS](https://purgecss.com/) in your application to optimize for production. And make sure that you are writing [purgeable markup](https://tailwindcss.com/docs/optimizing-for-production#writing-purgeable-html). 

## License
This project is released under the MIT license, which can be found in LICENSE.txt.