Migrations

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.

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 in your project.

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:

Copy code

/* Before (legacy) */
@import "@nordhealth/css";

/* After (Tailwind) */
@import "@nordhealth/css/tailwind";

Automate your migration! Use our ESLint plugin 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:

Copy code

<!-- Before -->
<html class="n-reset">

<!-- After -->
<html class="n:reset">

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

Copy code

pnpm add -D @nordhealth/eslint-plugin

Configuration

The migration rules are included in the recommended config but off by default. Enable them during migration:

Copy code

// 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:

Copy code

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:

Copy code

pnpm eslint --fix "src/**/*.{ts,tsx,vue,html}"

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 for more guidelines and ways to contact us.

Migrations

Was this page helpful?