# Migration to Tailwind CSS
>
*This guide will help you migrate from the legacy CSS framework to the new Tailwind CSS integration.*
## Why migrate?
The new Tailwind CSS integration offers several advantages:
- **Smaller bundle sizes** through automatic purging of unused styles
- **Better developer experience** with IDE support, linting and autocompletion
- **Industry standard** utilities and patterns
- **Modern tooling** with Tailwind CSS v4
---
## Compatibility
The legacy CSS framework and Tailwind CSS can be used together. You can migrate incrementally, adopting Tailwind utilities in new code while keeping existing legacy classes.
> [!WARNING]
> **
> Required change:
> **
> You must replace
> `
> .n-reset
> `
> with
> `
> .n:reset
> `
> to ensure Tailwind utilities can override styles correctly.
---
## Installation
First, ensure you have [Tailwind CSS v4 installed](https://tailwindcss.com/docs/installation){target="_blank"} in your project.
> [!NOTE]
> **
> Side-by-side support:
> **
> Use both Tailwind and the legacy CSS framework simultaneously. You can migrate incrementally while both systems coexist in your codebase.
Then update your CSS import:
```css
/* Before (legacy) */
@import "@nordhealth/css";
/* After (Tailwind) */
@import "@nordhealth/css/tailwind";
```
> [!NOTE]
> **
> Automate your migration!
> **
> Use our
> [
> ESLint plugin
> ](#automated-migration-with-eslint)
> to automatically convert legacy classes to Tailwind equivalents with
> `
> --fix
> `
> .
---
## Required changes
### Reset class
The reset class **must** be updated to use the Tailwind prefix syntax:
```html
```
This is required because the colon syntax ensures proper CSS specificity, allowing Tailwind utilities to override the reset styles.
---
## Optional changes
The following classes can be migrated gradually. Legacy classes will continue to work alongside Tailwind utilities.
### Component classes
| Legacy CSS | Tailwind CSS |
| ------------ | ------------------------- |
| `.n-reset` | `.n:reset` **(required)** |
| `.n-typeset` | `.n:typeset` |
| `.n-dl` | `.n:dl` |
| `.n-label` | `.n:label` |
| `.n-hint` | `.n:hint` |
| `.n-error` | `.n:error` |
| `.n-input` | `.n:input` |
### Utility classes
For new code, prefer Tailwind utilities over legacy classes:
| Legacy CSS | Tailwind CSS |
| ---------------------- | ---------------------- |
| `.n-padding-m` | `.n:p-m` |
| `.n-margin-m` | `.n:m-m` |
| `.n-color-text` | `.n:text-default` |
| `.n-color-text-weak` | `.n:text-weak` |
| `.n-color-accent` | `.n:text-accent` |
| `.n-bg-surface` | `.n:bg-surface` |
| `.n-bg-status-success` | `.n:bg-status-success` |
| `.n-border-color` | `.n:border-default` |
| `.n-font-size-l` | `.n:text-l` |
---
## Automated migration with ESLint
The `@nordhealth/eslint-plugin` provides an auto-fixable rule to help migrate legacy classes to Tailwind equivalents.
### Installation
```bash
pnpm add -D @nordhealth/eslint-plugin
```
### Configuration
The migration rules are included in the recommended config but **off by default**. Enable them during migration:
```javascript
// eslint.config.mjs
import nordPlugin from '@nordhealth/eslint-plugin'
export default [
nordPlugin.configs.recommended,
{
rules: {
// Enable migration rules - disable after migration is complete
'@nordhealth/no-legacy-classes': 'warn'
}
}
]
```
### Incremental migration
To migrate gradually, enable only specific categories:
```javascript
rules: {
// Start with spacing and colors, add more categories over time
"@nordhealth/no-legacy-classes": ["warn", {
categories: ["spacing", "colors"]
}]
}
```
Available categories:
| Category | Classes migrated |
| ------------ | --------------------------------------------------------------- |
| `spacing` | Margin, padding, gap (`n-margin-*`, `n-padding-*`, `n-gap-*`) |
| `borders` | Border styles, colors, radius (`n-border-*`) |
| `typography` | Font sizes, weights, line heights (`n-font-*`, `n-typescale-*`) |
| `colors` | Text, background, status colors (`n-color-*`) |
| `layout` | Flex, grid, alignment (`n-stack-*`, `n-grid-*`, `n-justify-*`) |
| `components` | Form elements, icons (`n-label`, `n-input`, `n-size-icon-*`) |
| `utilities` | Shadows, z-index, misc (`n-box-shadow-*`, `n-index-*`) |
### Running the fix
Once configured, run ESLint with the `--fix` flag to automatically migrate classes:
```bash
pnpm eslint --fix "src/**/*.{ts,tsx,vue,html}"
```
> [!NOTE]
> The rule will report each deprecated class and automatically replace it with the Tailwind equivalent when you run
> `
> --fix
> `
> .
---
## Getting support
Have questions about migrating to Tailwind CSS? Please head over to the [Support page](/resources/support/) for more guidelines and ways to contact us.