Migration to Tailwind CSSRecommended
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.
.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.
Then update your CSS import:
/* Before (legacy) */
@import "@nordhealth/css";
/* After (Tailwind) */
@import "@nordhealth/css/tailwind";--fix.
Required changes
Reset class
The reset class must be updated to use the Tailwind prefix syntax:
<!-- 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
pnpm add -D @nordhealth/eslint-pluginConfiguration
The migration rules are included in the recommended config but off by default. Enable them during migration:
// 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:
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:
pnpm eslint --fix "src/**/*.{ts,tsx,vue,html}"--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.