import { MDXLayoutNext } from '@/components';

export const meta = {
  templateTitle: 'Button Plugin',
  description: 'Button Plugin | Fluid Design',
  date: '2023-02-01',
  author: 'Oliver Pan',
  tags: [
    'fluid ui',
    'react',
    'framer motion',
    'headless ui',
    'tailwindcss',
    'button plugin',
  ],
};

export default (props) => <MDXLayoutNext meta={meta} {...props} />;

# Button Plugin

A plugin that provides powerful button components for Tailwindcss. Supports all the variants, states and a11y.

## Installation

Install the plugin from npm:

```js
npm install @fluid-design/fluid-ui
```

Then add the plugin to your tailwind.config.js file:

```js tailwind.config.js
// tailwind.config.js
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@fluid-design/fluid-ui/dist/plugin/core'),
    require('@fluid-design/fluid-ui/dist/plugin/button'),
    // ...
  ],
};
```

## Usage

View the [Button](/docs/button) component for more details.

```jsx

<button className="btn-primary">Primary</button>
<button className="btn-rose">Secondary</button>
<button className="btn-light-amber-100">Tertiary</button>
<button className="btn-bold-[#FFFF00]">Light</button>
<button className="btn-outline-[cyan]">Outline</button>
<button className="btn-clear-[rgb(119,187,235)]">Clear</button>

```

By default, the plugin provides the following colors:

| Color   | Class                               |
| ------- | ----------------------------------- |
| red     | `*-red` \| `*-red-<50-900>`         |
| orange  | `*-orange` \| `*-orange-<50-900>`   |
| amber   | `*-amber` \| `*-amber-<50-900>`     |
| yellow  | `*-yellow` \| `*-yellow-<50-900>`   |
| lime    | `*-lime` \| `*-lime-<50-900>`       |
| green   | `*-green` \| `*-green-<50-900>`     |
| emerald | `*-emerald` \| `*-emerald-<50-900>` |
| teal    | `*-teal` \| `*-teal-<50-900>`       |
| cyan    | `*-cyan` \| `*-cyan-<50-900>`       |
| sky     | `*-sky` \| `*-sky-<50-900>`         |
| blue    | `*-blue` \| `*-blue-<50-900>`       |
| indigo  | `*-indigo` \| `*-indigo-<50-900>`   |
| violet  | `*-violet` \| `*-violet-<50-900>`   |
| purple  | `*-purple` \| `*-purple-<50-900>`   |
| fuchsia | `*-fuchsia` \| `*-fuchsia-<50-900>` |
| pink    | `*-pink` \| `*-pink-<50-900>`       |
| rose    | `*-rose` \| `*-rose-<50-900>`       |
| gray    | `*-gray` \| `*-gray-<50-900>`       |
| slate   | `*-slate` \| `*-slate-<50-900>`     |
| zinc    | `*-zinc` \| `*-zinc-<50-900>`       |
| neutral | `*-neutral` \| `*-neutral-<50-900>` |
| stone   | `*-stone` \| `*-stone-<50-900>`     |

## Features

### Variants

The plugin supports default tailwindcss colors out of the box. See the <ExternalLink href="https://tailwindcss.com/docs/customizing-colors">Tailwindcss Colors</ExternalLink> for more details.
You can also specify the step of the color by adding a number after the color name. For example, `*-red-100` or `*-red-900`.
It also supports abitrary values for colors. For example, you can use hex values, rgb values, hsl values, etc.

### Mutating colors

If a valid color is provided, the plugin will automatically generate hover,
focus, active and disabled states for the button. It also generates
appropriate a11y colors for the button for each state. Since these colors are generated on fly, you don't need to worry
about shipping massive CSS files. If the color is not valid, such as `var(--color)`, the plugin will use `filter`
CSS property to generate the hover, focus, active and disabled states. The plugin
uses minimized version of the <ExternalLink href="https://www.npmjs.com/package/tinycolor2">tinycolor2</ExternalLink> library to generate the colors.

### Dark mode

With the V2.0.0 update, the plugin does not provide dark mode variants by default,
this is to prevent if users want to use speicific colors for dark mode.
If you want to use dark mode variants, you can use the `dark` prefix. For example, `dark:btn-primary`.

### Focus ring

For each different button type, the plugin generates a focus ring that is
visible when the button is focused. The focus ring is generated using
tailwindcss's `box-shadow` utility. That means you can customize the focus ring
by providing `ring` variants to the button.

### Accessibility

The plugin will try to generate the a11y colors based on the color provided.
In short, the text color will be > 4.5:1 contrast ratio with the background color.
And in high contrast mode, the text color will be > 7:1 contrast ratio with the background color.

Read more about accessible color contrast <ExternalLink href='https://www.w3.org/TR/WCAG20-TECHS/G18.html'>here</ExternalLink>.

## Reference

Here is a complete table of the provided `btn-*` classes for reference:

| Type    | Class           |
| ------- | --------------- |
| default | `btn-*`         |
| light   | `btn-light-*`   |
| bold    | `btn-bold-*`    |
| outline | `btn-outline-*` |
| clear   | `btn-clear-*`   |