npm package: @primer/tailwind-config
Description: <p align="center">   <img alt="Primer logo" width="300px" src="https://user-images.githubusercontent.com/4608155/127241386-f11da52d-00d9-4366-b01c-6f4c1ebcf7f2.png"> </p>
Latest version: 0.2.0

<p align="center">
  <img alt="Primer logo" width="300px" src="https://user-images.githubusercontent.com/4608155/127241386-f11da52d-00d9-4366-b01c-6f4c1ebcf7f2.png">
</p>

<h1 align="center">@primer/tailwind-config</h1>

<p align="center">A Tailwind CSS configuration for projects working with Primer</p>

<p align="center">
  <a aria-label="npm package" href="https://www.npmjs.com/package/@primer/tailwind-config">
    <img alt="npm package"
    src="https://img.shields.io/npm/v/@primer/tailwind-config.svg">
  </a>
  <a aria-label="contributors graph" href="https://github.com/primer/tailwind-config/graphs/contributors">
    <img alt="contributors graph" src="https://img.shields.io/github/contributors/primer/tailwind-config.svg">
  </a>
  <a aria-label="last commit" href="https://github.com/primer/tailwind-config/commits/main">
    <img alt="last commit" src=
  "https://img.shields.io/github/last-commit/primer/tailwind-config.svg">
  </a>
  <a aria-label="license" href="https://github.com/primer/tailwind-config/blob/main/LICENSE">
    <img alt="license" src="https://img.shields.io/github/license/primer/tailwind-config.svg" alt="">
  </a>
</p>

## Features

- Ready-to-use Tailwind config preset for Primer
- Automatically syncs with [@primer/primitives](https://github.com/primer/primitives) design tokens
- Maps Primer colors, spacing, radii, typography, and other tokens to Tailwind utilities
- Consistent theming and responsive design primitives
- Designed for easy integration with React ([@primer/react](https://github.com/primer/react)), vanilla projects, or other frameworks

## Getting started

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

```bash
npm install -S @primer/tailwind-config @primer/primitives
```

This command will install two packages in your project:

- `@primer/tailwind-config`: used to setup tailwind with Primer's design system
- `@primer/primitives`: used to include the design tokens from Primer

To learn more about how to use `@primer/tailwind-config`, visit our documentation site at:
[primer.style](https://primer.style).

## Usage

In your project's `index.css` file:

```css
/* 1. Import @primer/primitives */
@import '@primer/primitives/dist/css/primitives.css';
@import '@primer/primitives/dist/css/functional/themes/light.css';
@import '@primer/primitives/dist/css/functional/themes/dark.css';

/* 2. Import Tailwind CSS */
@import 'tailwindcss';

/* 3. Import this package */
@import '@primer/tailwind-config';
```

### Without Preflight

By default, `@import 'tailwindcss'` includes [Preflight](https://tailwindcss.com/docs/preflight), an opinionated CSS reset. If your project already has its own reset styles (e.g., Primer's reset), you can import Tailwind's parts individually to skip Preflight:

```css
/* 1. Import @primer/primitives */
@import '@primer/primitives/dist/css/primitives.css';
@import '@primer/primitives/dist/css/functional/themes/light.css';
@import '@primer/primitives/dist/css/functional/themes/dark.css';

/* 2. Import Tailwind CSS without Preflight */
@layer theme, base, components, utilities;
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

/* 3. Import this package */
@import '@primer/tailwind-config';
```

### Granular Imports

You can also import individual modules if you only need specific parts:

```css
@import '@primer/tailwind-config/color';
@import '@primer/tailwind-config/typography';
@import '@primer/tailwind-config/size';
@import '@primer/tailwind-config/radius';
@import '@primer/tailwind-config/border';
@import '@primer/tailwind-config/shadow';
@import '@primer/tailwind-config/easing';
```

In addition, you will need to add the following attributes to your `html` element:

```html
<html data-light-theme="light" data-dark-theme="dark" data-color-mode="auto">
  <!-- ... -->
</html>
```

## 📖 Documentation

The main use case of `@primer/tailwind-config` is to customize primer components or quickly build components during prototyping or experimentational builds. Once a feature is shipped and meant to stay, components should be build using CSS modules and [`primer/primitives`](https://primer.style/product/primitives/) as CSS variables.

Most of [Tailwinds utilility classes](https://tailwindcss.com/docs/aspect-ratio) have been preserved, however the following changes have been made to make sure to align with Primer.

### Border

**Border width** - Primer border width utilities:

- `border` (1px)
- `border-thin` (1px)
- `border-thick` (2px)
- `border-thicker` (4px)

**Focus outline** - Apply focus outline with:

- `outline-focus`
- `focus:outline-focus`
- `focus-within:outline-focus`

**Border colors** - See Color section below for semantic border utilities like `border-default`, `border-accent-emphasis`, etc.

### Color

Primer color tokens are available as Tailwind utilities through three categories:

**Display colors** - Base color scales (0-9) for all 18 Primer display colors:

- `bg-display-{color}-{shade}`, `text-display-{color}-{shade}`, `border-display-{color}-{shade}`
- Available colors: auburn, blue, brown, coral, cyan, gray, green, indigo, lemon, lime, olive, orange, pine, pink, plum, purple, red, teal, yellow

**Functional colors** - Semantic tokens that adapt to themes:

- Background: `bg-{semantic}` (e.g., `bg-default`, `bg-muted`, `bg-accent-emphasis`)
- Foreground: `text-{semantic}` (e.g., `text-default`, `text-muted`, `text-danger`)
- Border: `border-{semantic}` (e.g., `border-default`, `border-accent-emphasis`)
- Semantic variants: default, muted, emphasis, accent, success, danger, attention, severe, done, sponsors, open, closed, draft, neutral, upsell

**Label colors** - Interactive label states for all 18 colors:

- `bg-label-{color}`, `text-label-{color}`, `border-label-{color}`
- States: `hover` and `active` are applied automatically to text and bg colors.

All colors reference `@primer/primitives` tokens and automatically adapt to the active theme.

### Easing

Primer easing curves for smooth animations are available as classes:

- `ease-linear`
- `ease-in`
- `ease-out`
- `ease-in-out`

Use with Tailwind's transition utilities: `transition-all ease-out duration-200`

### Radius

Border radius utilities following Primer's scale:

- `rounded-sm` (3px)
- `rounded-md` (6px)
- `rounded-default` (6px)
- `rounded-lg` (12px)
- `rounded-full`

### Shadow

Primer shadow tokens for depth and elevation:

**Resting shadows** - Subtle depth for static elements:

- `shadow-resting-xs`
- `shadow-resting-sm`
- `shadow-resting-md`

**Floating shadows** - Prominent elevation for overlays and menus:

- `shadow-floating-sm`
- `shadow-floating-md`
- `shadow-floating-lg`
- `shadow-floating-xl`

**Inset shadow** - Inner shadows:

- `inset-shadow`

### Size

**Spacing** - Base spacing unit is `--spacing` (4px), used with Tailwind's spacing scale (e.g., `p-4`, `m-8`, `gap-2`)

**Breakpoints** - Responsive design breakpoints:

- `xs` (20rem)
- `sm` (34rem)
- `md` (48rem)
- `lg` (63.25rem)
- `xl` (80rem)
- `2xl` (87.5rem)

Use with Tailwind's responsive prefixes: `md:flex`, `lg:grid-cols-3`

### Typography

**Font families** - Primer typeface stacks:

- `font-sans`
- `font-display`
- `font-mono`

**Font sizes**
Semantic text scales:

- `text-caption`
- `text-body-{small|medium|large}`
- `text-subtitle`
- `text-title-{small|medium|large}`
- `text-display`

T-shirt sizes:

- `text-xs`
- `text-sm`
- `text-md`
- `text-lg`
- `text-xl`
- `text-2xl`

**Font weights**:

- `font-light`
- `font-normal`
- `font-medium`
- `font-semibold`

## 🙌 Contributing

We love collaborating with folks inside and outside of GitHub and welcome contributions! If you're interested, check out our [contributing docs](./CONTRIBUTING.md) for more info on how to get started.

## Resources

- [Primer Design System](https://primer.style/)
- [Primer Primitives](https://github.com/primer/primitives)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs/configuration)
- [@primer/react](https://github.com/primer/react)

## 📝 License

Licensed under the [MIT License](/LICENSE).