Migration to 3.0.0 Web ComponentsNew

This guide will help you understand how to transition an existing project from using an older version of Nord Web Components to using the latest 3.0.0 version.

What’s changing? #

This release brings major changes and improvements to Nord Design System to better support the needs of feature teams and various products using Nord. The main difference is the introduction of a new Layout and Top Bar component which now allow functionality such as search and contextual menus to be placed at the top of the interface instead of the Navigation menu.

We’ve also improved the underlying color system to make it more extensible and better cover the use cases of our different products. This release utilizes the new color system and brings many new styles and variants to components such as Badge and Banner.

While the color system updates introduce some breaking changes, we’ve covered those further down on this page. Most other changes have been kept backwards compatible, and we still support the old style layout as well. Not all of our products need the additional top bar or more advanced utilities, so you can keep using the current layout that your users are already familiar with.

Comparison of changes in the release

Breaking changes #

Below you can find an overview of the breaking changes in this major release. You can view more details about each specific change further down this page, or by clicking one of the “more details” links.

@nordhealth/components #

@nordhealth/tokens #

@nordhealth/css #

@nordhealth/themes #

Updating package.json and dependencies #

The first step towards migrating to the latest Nord packages is to update package.json with the necessary dependencies. You should:

Here’s an example package.json:

{
  "dependencies": {
    "@nordhealth/css": "^3.0.0",
    "@nordhealth/themes": "^8.0.0",
    "@nordhealth/components": "^3.0.0",
  }
}

New internal color scales #

Each internal color scale in Nord now has 12 steps. Each step was designed with a specific use case in mind. It is worth noting that the table below is a simplified overview of the most common use cases we have internally in the system. Most of the colors listed below aren’t surfaced directly in our Design Tokens API, as we want to keep the usage of color tied to specific color roles to keep this simple for the consumers of the system.


StepUse case
1Surface: App background
2Surface: Subtle background
3Component: UI element background
4Component: Hovered UI element background
5Component: Active / Selected UI element background
6Border: Subtle borders and separators
7Border: UI element border and focus rings
8Border: Hovered UI element border
9Fill: Solid backgrounds
10Fill: Hovered solid backgrounds
11Text: Low-contrast text
12Text: High-contrast text

Light theme

Improvements to theming #

For applications that utilize the new Top Bar component, Nord now provides slightly more control over the visual appearance. In addition to the existing var(--n-color-accent), we now also provide a new secondary supporting color named var(--n-color-accent-secondary). This token can be used to customize the background color of the top bar and navigation header:

Nord theme

To get started using this feature, add the following styles and replace {color} with custom hex values that provide at least 4.5:1 contrast ratio against white text:

<style>
  :root {
    /* CUSTOM ACCENT COLORS */
    --n-color-accent: {color};
    --n-color-accent-secondary: {color};
  }
</style>

You can view a live example in our Layout component docs. To get more control over the theming and text colors, please see themes documentation.

Good to know: By default, the var(--n-color-accent-secondary) aliases var(--n-color-accent) to provide good defaults for those who want to keep the theming simple.

View documentation

Changes to design tokens #

We’ve improved the underlying color system to make it more extensible and better cover the use cases of our different products. If you were previously using any of the following design tokens directly:

You now might need to replace them with:

New color tokens in CSS Framework #

We’ve introduced the following new color tokens into Design Tokens and CSS Framework:

Changes to CSS Framework #

.n-stack and .n-gap now have a gap of var(--n-space-m) by default instead of none, to mirror the Stack component’s default behaviour.

Stack utilities

View documentation

Changes to Badge component #

This release changes the way our Badge component works and may require you to communicate to your users about the changes and what is expected:

NeutralDangerWarningSuccessInfoHighlight

Changes to Banner component #

Nord’s Banner component has an improved visual style which uses the newly introduced design tokens and status colors. This is a non-breaking change and requires no changes from your side. New style looks like this:

We’ve updated your plan, make sure you know how these changes affect it. Learn more.We’re experiencing an incident. Please see our status page for more details.Payment details missing. To stay on your current plan, add payment details.Your order has been shipped and will arrive on May 27th. Track order.

Changes to Navigation component #

We’ve updated Navigation component’s styles and theming functionality to match new designs and added a new “auto-collapsing” behavior: When a Nav Item is marked as active, its ancestors are opened, and any others are closed.

Nord navigation

Additionally, this release includes:

Changes to Layout component #

There are multiple changes to the Layout component:

Nord theme

Changes to Avatar component #

Nord’s Avatar component has an improved visual style, which uses a slightly cooler gray instead of the previous warm gray. This release also adds a new custom property --n-avatar-box-shadow to the Avatar component that allows developers to control the box-shadow around the avatar.

Changes to Button and Input components #

We’ve adjusted the small size of Nord’s Button component, Input component and Select component to better match with the latest visual changes and the new Top Bar component. The new height for these components is 28px:

DefaultPrimaryDangerFilterPlainDisabled

Additionally, this release includes:

Changes to background colors #

Nord’s Layout component has an improved visual style, which uses gray instead of white as the background color for the main content area. This change was introduced to provide better visual separation between blocks of content. This change also prepares the design system parts for new upcoming components such as the Top Bar:

Nord layout theming example

Changes to Error states #

Nord’s error states have an improved visual style which use much more prominent and vibrant error colors:

Badge as dropdown toggle #

We’ve added a new example which demonstrates how to use a badge inside a dropdown toggle to allow the user to change the status of an object:

DischargedWaiting for consultationConsultationArrivedUpcomingCancelled

New icons #

This release introduces 13 new icons called interface-warning-small, file-invoice, file-patient-records, file-treatment-plan, generic-company, generic-farm, generic-hospital, medical-drip, medical-neutered, medical-spayed, medical-surgery, navigation-finances, navigation-reports-2:

New Top Bar component #

This release introduces a new Top Bar component. Please note this is still in draft stage, and we will be soon introducing more features such as search, notifications and tasks functionality to fully utilize this component.

Nord top bar component

New notification color #

We’ve changed the notification indicator color from yellow to red:

Nord notification

Update themes #

We’ve reworked and updated each Nord theme with new colors:

Nord Themes

New Vue types and editor integration #

Nord's components work out of the box with Vue, but they don't provide any TypeScript support or editor integration. To improve the developer experience, we now offer the @nordhealth/vue package. This package only contains types and no code.

To integrate these into your project, install @nordhealth/components as you normally would, along with @nordhealth/vue. Then add the following to your tsconfig.json in a TypeScript project, or jsconfig.json in a JavaScript project:

{
  "compilerOptions": {
    "types": ["@nordhealth/vue"]
  }
}

Now you will get full type checking and auto-completion in your Vue templates.

Note: to use components you should still import from the @nordhealth/components package.

Changes to Command Menu #

We’ve moved the placeholder prop to a localization string instead. This change was done to simplify translation for this component, as the rest of translations are set through localization strings. There is a new example added which shows how you can integrate the Nord translations with a localization framework by writing a wrapper around it.

View localization docs

Updated dependencies #

We’ve updated all Nord Design System package dependencies to the latest versions, including the following:

Getting support #

Have a question about migration to 3.0.0? Please head over to the Support page for more guidelines and ways to contact us.

Was this page helpful?

YesNoSend feedback

We use this feedback to improve our documentation.

 
Edit page