Migration Guide

This guide covers migrating from the internal @nve/* packages to the new open source @nvidia-elements/* packages.

Agent Skill

Install the Elements skill, which includes the migration reference, or invoke the MCP migration prompt.

nve skills.install

In an MCP client, invoke /migrate to load the same migration guidance.

Overview

The Elements Design System is now hosted and developed in a public GitHub repository. Packages are now published to the public npm registry under the @nvidia-elements scope. The component APIs, tag names, and theming system remain the same. The primary changes are package names, import paths, and registry configuration.

Stability and Versioning

Teams have run Elements in production since 2022, and NVIDIA already released it internally as 1.x. The move to open source changes the package scope to @nvidia-elements/*, but it does not reset the maturity of the system.

NVIDIA published the initial public open source packages as 0.x while the project completed its public release migration. Treat these 0.x versions as transitional open source preview releases, not proof that Elements itself is experimental or newly developed.

Elements moved from public 0.x prerelease versions to 2.0.0 for the stable open source release. This means there is no public 1.0.0 release under the @nvidia-elements/* scope. The missing public 1.0.0 is intentional: 1.x represents the prior internal production generation, and 2.0.0 represents the next stable generation under the public @nvidia-elements/* scope.

Migration Steps

1. Update Registry Configuration

The @nvidia-elements packages are on the public npm registry and require no special registry configuration. Internal teams should continue to use Artifactory regardless of which package scope. Artifactory proxies the public npm registry automatically.

2. Update Dependencies

In your package.json, replace the old scope names with the new ones:

"dependencies": {
-   "@nve/elements": "^1.67.0",
-   "@nve/themes": "^1.12.0",
-   "@nve/styles": "^1.14.0"
+   "@nvidia-elements/core": "^0.0.3",
+   "@nvidia-elements/themes": "^0.0.4",
+   "@nvidia-elements/styles": "^0.0.3"
  }

3. Update Source Imports

Replace import paths throughout your source code:

- import '@nve/elements/button/define.js';
- import { Button } from '@nve/elements/button';
+ import '@nvidia-elements/core/button/define.js';
+ import { Button } from '@nvidia-elements/core/button';

- import '@nve/themes/dist/index.css';
+ import '@nvidia-elements/themes/dist/index.css';

Deprecations & Removals

The following are the active deprecations. Each next major release removes the prior deprecations. Read more about the versioning and deprecation cycle policy.

Logo removed

The nve-logo component no longer includes the NVIDIA SVG logo; consumers must provide their own SVG as child content in the default slot.

<nve-logo aria-label="NVIDIA"></nve-logo>

<nve-logo>
  <img src="./logo.svg" alt="NVIDIA" />
</nve-logo>

Popover Behavior Triggers deprecated

Before native HTML popovers, popovers required behaviorTrigger or behavior-trigger for stateful popovers. The native HTML popover API replaces this approach.

<nve-tooltip trigger="tooltip-btn" behavior-trigger position="top" hidden>hello there</nve-tooltip>
<nve-button id="tooltip-btn">tooltip</nve-button>

<nve-tooltip id="my-tooltip" position="top">hello there</nve-tooltip>
<nve-button popovertarget="my-tooltip">tooltip</nve-button>

Combobox No Tags removed

Elements removed the notags attribute. Use tag-layout="hidden" instead so all tag layout modes use the same attribute.

<nve-combobox notags></nve-combobox>

<nve-combobox tag-layout="hidden"></nve-combobox>

Layout Full removed

The grow property now uses full instead to avoid confusion with flexbox grow behavior.

<div nve-layout="grow"></div>

<div nve-layout="full"></div>

Typography "eyebrow" removed

The typography eyebrow utility no longer exists, to align with the standardized semantic names and size options available.

<div nve-text="eyebrow"></div>

<div nve-text="label sm"></div>

@nve/testing removed

The custom test utilities are no longer supported in the public scope.

Scoped Tags removed

Avoid @nve/elements/scoped. Instead, consuming applications define their own tag name and leverage the @lit-labs/scoped-registry-mixin package directly.

Maglev - CSS Entrypoints removed

/* before */
@import '@maglev/elements/index.css';
@import '@maglev/elements/inter.css';

@import '@nvidia-elements/themes/fonts/inter.css';
@import '@nvidia-elements/themes/index.css';
@import '@nvidia-elements/themes/high-contrast.css';
@import '@nvidia-elements/themes/reduced-motion.css';
@import '@nvidia-elements/themes/compact.css';
@import '@nvidia-elements/themes/dark.css';
@import '@nvidia-elements/themes/debug.css';
@import '@nvidia-elements/styles/typography.css';
@import '@nvidia-elements/styles/layout.css';
@import '@nvidia-elements/styles/view-transitions.css';

Maglev - CSS Prefix removed

Update any CSS Custom property usage

.selector {
  color: var(--mlv-ref-color-brand-green-200);
}

.selector {
  color: var(--nve-ref-color-brand-green-200);
}

Maglev - Attribute Prefix removed

Update style utility attributes

<html mlv-theme="...">
<div mlv-layout="...">
<p mlv-text="...">

<html nve-theme="...">
<div nve-layout="...">
<p nve-text="...">

Maglev - HTML Prefix removed

Update HTML elements

<mlv-button>...</mlv-button>

<nve-button>...</nve-button>

Maglev - App Header removed

nve-page-header replaces the early Maglev scoped package mlv-app-header.

<mlv-app-header>
  ...
</mlv-app-header>

<nve-page-header>
  <nve-logo slot="prefix" size="sm">NV</nve-logo>
  <h2 slot="prefix" nve-text="heading sm">Infrastructure</h2>
  <nve-button selected container="flat"><a href="#">Link 1</a></nve-button>
  <nve-button container="flat"><a href="#">Link 2</a></nve-button>
  <nve-icon-button slot="suffix" interaction="emphasis" size="sm">EL</nve-icon-button>
</nve-page-header>

Maglev - Alert Banner removed

The alert banner component no longer exists. Use nve-alert-group with the prominence="emphasis" option.

<nve-alert-banner>
  <nve-alert closable>
    <span slot="prefix">Standard</span> banner message
  </nve-alert>
</nve-alert-banner>

<nve-alert-group prominence="emphasis" container="full">
  <nve-alert closable>
    <span slot="prefix">Standard</span> banner message
  </nve-alert>
</nve-alert-group>

Maglev - JSON Viewer removed

The JSON viewer element is an internal API. You can access this API via the public exports but should avoid using it. Use nve-codeblock or nve-monaco-input for JSON content rendering.

Maglev - Icon Names removed

The following icons now use new names:

Maglev - Icon Button Name Directions removed

With the deprecation of directional icons the icon button now requires a explicit direction.

<nve-icon name="chevron-left"></nve-icon>
<nve-icon name="beginning"></nve-icon>
<nve-icon name="beginning-left"></nve-icon>
<nve-icon name="collapse-panel"></nve-icon>
<nve-icon name="navigate-back"></nve-icon>
<nve-icon name="chevron-right"></nve-icon>
<nve-icon name="end"></nve-icon>
<nve-icon name="expand-panel"></nve-icon>
<nve-icon name="navigate-to"></nve-icon>
<nve-icon name="carousel-horizontal"></nve-icon>
<nve-icon name="chevron-down"></nve-icon>
<nve-icon name="thumbs-down"></nve-icon>

<nve-icon name="chevron" direction="left"></nve-icon>
<nve-icon name="beginning" direction="left"></nve-icon>
<nve-icon name="arrow-stop" direction="left"></nve-icon>
<nve-icon name="navigate-back" direction="left"></nve-icon>
<nve-icon name="chevron" direction="right"></nve-icon>
<nve-icon name="end" direction="right"></nve-icon>
<nve-icon name="arrow-stop" direction="right"></nve-icon>
<nve-icon name="arrow" direction="right"></nve-icon>
<nve-icon name="carousel-horizontal" direction="right"></nve-icon>
<nve-icon name="chevron" direction="down"></nve-icon>
<nve-icon name="thumb" direction="down"></nve-icon>