From 00d2be23061d5c9be57ec5e54dddbe8c812e995a Mon Sep 17 00:00:00 2001 From: Cory Rylan Date: Thu, 30 Apr 2026 16:30:39 -0500 Subject: [PATCH 1/2] chore(docs): improve migration docs and layouts Signed-off-by: Cory Rylan --- projects/site/eleventy.config.js | 8 +- projects/site/src/_11ty/shortcodes/index.js | 24 ++ projects/site/src/docs/about/migration.md | 218 +++++++++--------- projects/site/src/docs/about/support.md | 2 +- .../site/src/docs/changelog/index.11ty.js | 2 +- projects/site/src/docs/patterns/index.md | 2 +- 6 files changed, 145 insertions(+), 111 deletions(-) diff --git a/projects/site/eleventy.config.js b/projects/site/eleventy.config.js index 9c6517d87..d0f2282cf 100644 --- a/projects/site/eleventy.config.js +++ b/projects/site/eleventy.config.js @@ -21,7 +21,12 @@ import { elementLoaderTransform } from './src/_11ty/transforms/element-loader.js import { anchorGeneratorTransform } from './src/_11ty/transforms/anchor-generator.js'; import { htmlMinifyTransform } from './src/_11ty/transforms/html-minify.js'; import { envReplaceTransform } from './src/_11ty/transforms/env-replace.js'; -import { installShortcode, doDontShortcode, splitShortcode } from './src/_11ty/shortcodes/index.js'; +import { + installShortcode, + doDontShortcode, + beforeAfterShortcode, + splitShortcode +} from './src/_11ty/shortcodes/index.js'; import { exampleShortcode, exampleTagsShortcode } from './src/_11ty/shortcodes/example.js'; import { exampleDocShortcode } from './src/_11ty/shortcodes/example-doc.js'; import { exampleGroupShortcode } from './src/_11ty/shortcodes/example-group.js'; @@ -198,6 +203,7 @@ export default function (eleventyConfig) { eleventyConfig.addShortcode('artifactory-usage', renderArtifactoryUsageShortcode); eleventyConfig.addPairedShortcode('dodont', doDontShortcode); eleventyConfig.addPairedShortcode('split', splitShortcode); + eleventyConfig.addPairedShortcode('before-after', beforeAfterShortcode); // Register custom transforms for content processing eleventyConfig.addTransform('env-replace', envReplaceTransform); diff --git a/projects/site/src/_11ty/shortcodes/index.js b/projects/site/src/_11ty/shortcodes/index.js index 190838647..95d4c4c89 100644 --- a/projects/site/src/_11ty/shortcodes/index.js +++ b/projects/site/src/_11ty/shortcodes/index.js @@ -66,6 +66,30 @@ export async function doDontShortcode(content) { `; } +export async function beforeAfterShortcode(content) { + return /* html */ ` +
+ +
+ Before + After +
+
+ ${content} +
+
`; +} + export async function splitShortcode(content) { return /* html */ `
diff --git a/projects/site/src/docs/about/migration.md b/projects/site/src/docs/about/migration.md index 38696dfd2..439a0067c 100644 --- a/projects/site/src/docs/about/migration.md +++ b/projects/site/src/docs/about/migration.md @@ -6,6 +6,12 @@ } --- + + # {{ title }} This guide covers migrating from the internal `@nve/*` packages to the new open source `@nvidia-elements/*` packages. @@ -14,8 +20,6 @@ This guide covers migrating from the internal `@nve/*` packages to the new open 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. -## Package Name Changes - | Internal Package | New Package | | -------------------- | --------------------------- | | `@nve/elements` | `@nvidia-elements/core` | @@ -30,8 +34,6 @@ The Elements Design System is now hosted and developed in a public GitHub reposi | `@nve-labs/media` | `@nvidia-elements/media` | | `@nve-labs/lint` | `@nvidia-elements/lint` | -Note: `@nve/elements` is now `@nvidia-elements/core`, not `@nvidia-elements/elements`. - ## Migration Steps ### 1. Update Registry Configuration @@ -71,84 +73,89 @@ Replace import paths throughout your source code: + import '@nvidia-elements/themes/dist/index.css'; ``` -### 4. Install Updated Packages +## Deprecations & Removals -```shell -# pnpm -pnpm install +The following are the active deprecations. Each next major release removes the prior deprecations. Read more about the versioning and deprecation cycle policy. -# npm -npm install -``` +### Logo removed -### 5. Verify +The `nve-logo` component no longer includes the NVIDIA SVG logo; consumers must provide their own SVG as child content in the default slot. -Run your project's build and tests to confirm everything resolves correctly: +{% before-after %} -```shell -pnpm run build -pnpm run test +```html + ``` -## API Changes - -`@nvidia-elements/core` no longer includes the following internal-only or deprecated pre-1.0 Maglev APIs, and the public packages omit them: +```html + + NVIDIA + +``` -| API | Change | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `@nvidia-elements/core/app-header` | (pre-maglev) replaced by `@nvidia-elements/core/page-header` | -| `@nvidia-elements/core/css/*` | (pre-maglev) replaced by `@nvidia-elements/styles` | -| `@nvidia-elements/core/index.css` | (pre-maglev) replaced by `@nvidia-elements/styles` | -| `@nvidia-elements/core/logo` | The logo component no longer includes the NVIDIA SVG logo; consumers must provide their own SVG as child content in the default slot | +{% endbefore-after %} -All prior Maglev based conventions and prefixes are now removed. +### Popover Behavior Triggers deprecated -## What Stays the Same +Before native HTML popovers, popovers required `behaviorTrigger` or `behavior-trigger` for stateful popovers. The native [HTML popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) replaces this approach. -- **Component tag prefix**: All components continue to use the `nve-` prefix (``, ``, etc.) -- **CSS custom properties**: Theme tokens and component CSS custom properties keep the same names (`--nve-*`) -- **Component APIs**: Properties, attributes, events, slots, and CSS parts remain the same -- **Theme files**: Same theme names and token structure +{% before-after %} -## Deprecations +```html + +tooltip +``` -The following are the active deprecations. Each next major release removes the prior deprecations. Read more about the versioning and deprecation cycle policy. +```html +hello there +tooltip +``` -### @nvidia-elements 0.x +{% endbefore-after %} -TBD +### Layout Full deprecated -### @nve/testing deprecated +The `grow` property now uses `full` instead to avoid confusion with flexbox grow behavior. -The custom test utilities are now deprecated. +{% before-after %} -### @nve/elements +```html +
+``` -#### Scoped Tags deprecated +```html +
+``` -Avoid `@nve/elements/scoped`. Instead, consuming applications define their own tag name and leverage the `@lit-labs/scoped-registry-mixin` package directly. +{% endbefore-after %} -#### Popover Behavior Triggers deprecated +### Typography "eyebrow" deprecated -Before native HTML popovers, popovers required `behaviorTrigger` or `behavior-trigger` for stateful popovers. The native [HTML popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) replaces this approach. +The typography `eyebrow` utility no longer exists, to align with the standardized semantic names and size options available. -Before: +{% before-after %} ```html - -tooltip +
``` -After: - ```html -hello there -tooltip +
``` -### @maglev/elements +{% endbefore-after %} + +### @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 -#### Scope deprecated +{% before-after %} ```css /* before */ @@ -156,8 +163,6 @@ Before native HTML popovers, popovers required `behaviorTrigger` or `behavior-tr @import '@maglev/elements/inter.css'; ``` -After: - ```css @import '@nvidia-elements/themes/fonts/inter.css'; @import '@nvidia-elements/themes/index.css'; @@ -171,9 +176,13 @@ Before native HTML popovers, popovers required `behaviorTrigger` or `behavior-tr @import '@nvidia-elements/styles/view-transitions.css'; ``` +{% endbefore-after %} + +### Maglev - CSS Prefix removed + Update any CSS Custom property usage -Before: +{% before-after %} ```css .selector { @@ -181,51 +190,79 @@ Update any CSS Custom property usage } ``` -After: - ```css .selector { color: var(--nve-ref-color-brand-green-200); } ``` +{% endbefore-after %} + +### Maglev - Attribute Prefix removed + Update style utility attributes -Before: +{% before-after %} -````html +```html

``` -After: - ```html

-```` +``` + +{% endbefore-after %} + +### Maglev - HTML Prefix removed Update HTML elements -Before: +{% before-after %} ```html ... ``` -After: - ```html ... ``` -#### Alert Banner deprecated +{% endbefore-after %} + +### Maglev - App Header removed + +`nve-page-header` replaces the early Maglev scoped package `mlv-app-header`. + +{% before-after %} + +```html + + ... + +``` + +```html + + NV +

Infrastructure

+ Link 1 + Link 2 + EL + +``` + +{% endbefore-after %} + +### Maglev - Alert Banner removed The alert banner component no longer exists. Use `nve-alert-group` with the `prominence="emphasis"` option. -Before: +{% before-after %} ```html @@ -235,8 +272,6 @@ The alert banner component no longer exists. Use `nve-alert-group` with the `pro ``` -After: - ```html @@ -245,48 +280,17 @@ The alert banner component no longer exists. Use `nve-alert-group` with the `pro ``` -#### JSON Viewer deprecated - -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. - -#### Layout Full deprecated - -The `grow` property now uses `full` instead to avoid confusion with flexbox grow behavior. +{% endbefore-after %} -Before: +### Maglev - JSON Viewer removed -```html -
-``` - -After: - -```html -
-``` - -#### Typography "eyebrow" deprecated - -The typography `eyebrow` utility no longer exists, to align with the standardized semantic names and size options available. - -Before: - -```html -
-``` - -After: - -```html -
-``` +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. -#### Icon Names deprecated +### Maglev - Icon Names removed The following icons now use new names: - | before | after | | ------------------ | ------------------------- | @@ -324,11 +328,11 @@ The following icons now use new names: -### Icon Button Name Directions deprecated +### Maglev - Icon Button Name Directions removed With the deprecation of directional icons the icon button now requires a explicit direction. -Before: +{% before-after %} ```html @@ -345,8 +349,6 @@ With the deprecation of directional icons the icon button now requires a explici ``` -After: - ```html @@ -360,3 +362,5 @@ With the deprecation of directional icons the icon button now requires a explici ``` + +{% endbefore-after %} diff --git a/projects/site/src/docs/about/support.md b/projects/site/src/docs/about/support.md index 6d8aba57f..051618f80 100644 --- a/projects/site/src/docs/about/support.md +++ b/projects/site/src/docs/about/support.md @@ -23,7 +23,7 @@ Elements [supports a wide variety](https://custom-elements-everywhere.com) of JavaScript frameworks and libraries as well as vanilla JS. Read more at the [installation](./docs/about/installation/) page. -
+
{% svg-logo 'typescript' '18' %} TypeScript diff --git a/projects/site/src/docs/changelog/index.11ty.js b/projects/site/src/docs/changelog/index.11ty.js index e5b4085df..5d92b010a 100644 --- a/projects/site/src/docs/changelog/index.11ty.js +++ b/projects/site/src/docs/changelog/index.11ty.js @@ -19,7 +19,7 @@ export function render() { # Changelog -
+
${changelogs .map( changelog => /* html */ ` diff --git a/projects/site/src/docs/patterns/index.md b/projects/site/src/docs/patterns/index.md index aecee0a70..57a4d7740 100644 --- a/projects/site/src/docs/patterns/index.md +++ b/projects/site/src/docs/patterns/index.md @@ -20,7 +20,7 @@ Patterns are an essential component of creating a cohesive and consistent user experience. Patterns are pre-defined combinations of existing components that teams reuse across different parts of the platform to streamline development and ensure consistency in the UI. By grouping components into patterns, teams can create a more organized and maintainable UI, as well as provide a unified look and feel for all users. -
+
From 1727575fa8cbe9231cc872ac65cd94c9445fcefd Mon Sep 17 00:00:00 2001 From: Cory Rylan Date: Thu, 30 Apr 2026 16:34:18 -0500 Subject: [PATCH 2/2] fix(cli): improved migration context Signed-off-by: Cory Rylan --- .../internals/tools/src/context/migration.md | 466 +++++++++++++----- 1 file changed, 336 insertions(+), 130 deletions(-) diff --git a/projects/internals/tools/src/context/migration.md b/projects/internals/tools/src/context/migration.md index cc20d2bc0..8269e74b9 100644 --- a/projects/internals/tools/src/context/migration.md +++ b/projects/internals/tools/src/context/migration.md @@ -2,96 +2,274 @@ Instructions for migrating a project from deprecated Elements APIs to the latest versions. This workflow uses the `@nvidia-elements/lint` ESLint package for static analysis and MCP tools for project health. -## Step 1: Project Health Check +## Core Rules + +- The public npm registry hosts the public packages under the `@nvidia-elements` scope. +- Internal NVIDIA teams should keep using Artifactory. Artifactory proxies the public npm registry. +- Component APIs, `nve-*` tag names, and the theming system remain the same unless a rule below says to change them. +- The new packages reset version numbers to `0.x`. Use the latest available public package versions instead of copying old internal versions. +- The `0.x` public packages contain the same non-deprecated components as the latest internal releases. Deprecated or removed APIs need explicit migration. +- Prefer lint-driven changes. Install `@nvidia-elements/lint`, run ESLint, build a work list from the findings, and fix one category at a time. + +## Recommended Agent Workflow + +1. Check project health. + - Use `project_validate` for setup, configuration, and dependency issues. + - Use `packages_list` to compare installed Elements packages with latest published versions. +2. Update packages. + - Use `project_setup` when available to set up or update Elements packages. + - Otherwise update `package.json` manually using the package map below. +3. Configure migration linting. + - Install `@nvidia-elements/lint` as a dev dependency. + - Add the recommended Elements ESLint config. + - Run ESLint and convert findings into a migration task list. +4. Apply migration rules. + - Start with package names and import paths. + - Then fix removed APIs. + - Then fix deprecated APIs. + - Use `api_list` and `api_get` before inventing replacements for component APIs. +5. Verify. + - Re-run ESLint until it reports no deprecation violations. + - Use `api_template_validate` on migrated HTML templates. + - Run `project_validate` again after package and source changes. + +## Tool Reference + +- `project_validate`: Check setup, configuration, dependencies, and project health. +- `project_setup`: Set up or update a project to use latest Elements packages. +- `packages_list`: List current and latest package versions. +- `packages_changelogs_get`: Read migration-relevant package changelogs. +- `api_template_validate`: Check HTML templates against current Elements APIs. +- `api_list`: List available Elements APIs. +- `api_get`: Get documentation for a specific component API. + +## ESLint Setup + +Install: -Assess the current state of the project before making changes. +```bash +npm install -D @nvidia-elements/lint +``` -### Tools to use +or: -- `project_validate`: check project setup, configuration issues, and outdated dependencies -- `packages_list`: check current vs latest versions of all Elements packages +```bash +pnpm add -D @nvidia-elements/lint +``` -## Step 2: Update Packages +Configure `eslint.config.js`: -Update to the latest versions of all Elements packages. +```javascript +import { elementsRecommended } from '@nvidia-elements/lint/eslint'; -### Tools to use +export default [...elementsRecommended]; +``` -- `project_setup`: setup or update a project to use Elements, including updating packages to the latest versions +Run: -### Package Scope Migration +```bash +npx eslint . +``` -If the project uses the legacy `@maglev/elements` package, replace it with the new scoped packages: +or: +```bash +pnpm eslint . ``` -@maglev/elements → @nvidia-elements/core + @nvidia-elements/themes + @nvidia-elements/styles + +## Package Scope Migration + +Replace internal package names with public package names. + +| Before | After | +| -------------------- | --------------------------- | +| `@nve/elements` | `@nvidia-elements/core` | +| `@nve/styles` | `@nvidia-elements/styles` | +| `@nve/themes` | `@nvidia-elements/themes` | +| `@nve/monaco` | `@nvidia-elements/monaco` | +| `@nve-labs/forms` | `@nvidia-elements/forms` | +| `@nve-labs/cli` | `@nvidia-elements/cli` | +| `@nve-labs/code` | `@nvidia-elements/code` | +| `@nve-labs/create` | `@nvidia-elements/create` | +| `@nve-labs/markdown` | `@nvidia-elements/markdown` | +| `@nve-labs/media` | `@nvidia-elements/media` | +| `@nve-labs/lint` | `@nvidia-elements/lint` | + +If the project uses the older `@maglev/elements` package, split it into the public packages that match the APIs the project uses: + +```text +@maglev/elements -> @nvidia-elements/core + @nvidia-elements/themes + @nvidia-elements/styles ``` -## Step 3: Install & Run Lint for Deprecation Detection +## Dependency Examples -Install and configure the `@nvidia-elements/lint` ESLint package to detect all deprecated API usage. +Before: -### Install +```json +{ + "dependencies": { + "@nve/elements": "^1.67.0", + "@nve/themes": "^1.12.0", + "@nve/styles": "^1.14.0" + } +} +``` -```bash -npm install -D @nvidia-elements/lint # or pnpm add -D @nvidia-elements/lint +After: + +```json +{ + "dependencies": { + "@nvidia-elements/core": "0.x", + "@nvidia-elements/themes": "0.x", + "@nvidia-elements/styles": "0.x" + } +} ``` -### Configure ESLint +## Source Import Migration -Create or update `eslint.config.js`: +Replace package scopes in import paths. Keep component paths the same unless another rule below says otherwise. + +Before: ```javascript -import { elementsRecommended } from '@nvidia-elements/lint/eslint'; -export default [...elementsRecommended]; +import { Button } from '@nve/elements/button'; +import '@nve/elements/button/define.js'; +import '@nve/themes/dist/index.css'; ``` -### Run ESLint +After: -```bash -npx eslint . # or pnpm eslint . +```javascript +import { Button } from '@nvidia-elements/core/button'; +import '@nvidia-elements/core/button/define.js'; +import '@nvidia-elements/themes/dist/index.css'; ``` -Parse the lint output to create a migration work list of all deprecated API usage. +## Removed APIs -## Step 4: Deprecation Reference & Fixes +### Logo Content -Apply fixes based on the following before→after mappings for each deprecation category. +`nve-logo` no longer includes the NVIDIA SVG logo. Consumers must provide their own SVG or image in the default slot. -### CSS Imports +Before: + +```html + +``` + +After: + +```html + + NVIDIA + +``` + +### `@nve/testing` + +The custom `@nve/testing` utilities are not supported in the public scope. Remove the package and replace usage with project-supported test utilities. + +### Scoped Tags + +Do not use `@nve/elements/scoped`. Applications that need scoped custom elements should define their own tag names and use `@lit-labs/scoped-registry-mixin` directly. + +## Deprecated APIs + +### Popover Behavior Triggers + +Remove `behaviorTrigger` or `behavior-trigger` from stateful popovers. Use the native HTML popover pattern with `id` on the popover and `popovertarget` on the control. + +Before: + +```html + +tooltip +``` + +After: + +```html +hello there +tooltip +``` + +### Layout `grow` + +Use `full` instead of `grow` in `nve-layout`. + +Before: + +```html +
+``` + +After: + +```html +
+``` + +### Typography `eyebrow` + +Use `label sm` instead of `eyebrow` in `nve-text`. + +Before: + +```html +
+``` + +After: + +```html +
+``` + +## Maglev CSS Migration + +Replace Maglev CSS entrypoints with public theme and style entrypoints. + +Before: ```css -/* before */ @import '@maglev/elements/index.css'; -/* or */ @import '@nvidia-elements/core/index.css'; +@import '@maglev/elements/inter.css'; +``` -/* after */ +After: + +```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'; ``` -| Before | After | -| ------------------------------------------------- | ---------------------------------------------------------------------------------- | -| `@maglev/elements/index.css` | Split into `@nvidia-elements/themes/*` + `@nvidia-elements/styles/*` imports above | -| `@maglev/elements/css/module.layout.css` | `@nvidia-elements/styles/layout.css` | -| `@maglev/elements/css/module.typography.css` | `@nvidia-elements/styles/typography.css` | -| `@nvidia-elements/core/index.css` | Split into `@nvidia-elements/themes/*` + `@nvidia-elements/styles/*` imports above | -| `@nvidia-elements/core/css/module.layout.css` | `@nvidia-elements/styles/layout.css` | -| `@nvidia-elements/core/css/module.typography.css` | `@nvidia-elements/styles/typography.css` | - -### CSS Variables - -Replace all `--mlv-*` CSS custom properties with `--nve-*`: +Replace Maglev CSS custom property prefixes: ```css -/* before */ color: var(--mlv-ref-color-brand-green-200); -/* after */ color: var(--nve-ref-color-brand-green-200); +/* before */ +.selector { + color: var(--mlv-ref-color-brand-green-200); +} + +/* after */ +.selector { + color: var(--nve-ref-color-brand-green-200); +} ``` -### Global Attributes +## Maglev HTML Migration + +Replace Maglev utility attributes with `nve-*` attributes. | Before | After | | ------------ | ------------ | @@ -99,109 +277,137 @@ Replace all `--mlv-*` CSS custom properties with `--nve-*`: | `mlv-layout` | `nve-layout` | | `mlv-text` | `nve-text` | -### HTML Tags +Replace `mlv-*` element tag prefixes with `nve-*` where the corresponding `nve-*` element exists. Check uncertain tags with `api_list` and `api_get`. -Replace all `mlv-*` tag prefixes with `nve-*`, verify the tag is valid by using the `api_list` and `api_get` tools: +Before: ```html - ... - ... -``` - -**Deprecated nve-\* tags:** - -| Before | After | -| ------------------ | --------------------------------------------------------------------- | -| `nve-alert-banner` | `nve-alert-group` with `prominence="emphasis"` and `container="full"` | -| `nve-app-header` | Deprecated (no direct replacement) | - -### Icon Names - -| Before | After | -| -------------------- | -------------------------------------- | -| `chevron-right` | `chevron` (add `direction="right"`) | -| `chevron-down` | `chevron` (add `direction="down"`) | -| `chevron-left` | `chevron` (add `direction="left"`) | -| `additional-actions` | `more-actions` | -| `analytics` | `pie-chart` | -| `annotation` | `transparent-box` | -| `app-switcher` | `switch-apps` | -| `assist` | `chat-bubble` | -| `checkmark` | `check` | -| `date` | `calendar` | -| `docs` | `book` | -| `expand-full-screen` | `maximize` | -| `expand-panel` | `arrow-stop` (add `direction="right"`) | -| `collapse-panel` | `arrow-stop` (add `direction="left"`) | -| `failed` | `x-circle` | -| `favorite-filled` | `star` | -| `favorite-outline` | `star-stroke` | -| `information` | `information-circle-stroke` | -| `maintenance` | `wrench` | -| `navigate-to` | `arrow` (add `direction="right"`) | -| `open-external-link` | `arrow-angle` | -| `location` | `map-pin` | -| `pinned-1` | `pin` | -| `project` | `folder` | -| `settings` | `gear` | -| `user` | `person` | -| `video-pause` | `pause` | -| `video-play` | `play` | -| `video-stop` | `stop` | -| `visible` | `eye` | -| `warning` | `exclamation-triangle` | - -### Popover Attributes - -Replace the deprecated `trigger` and `behavior-trigger` attributes on `nve-dialog`, `nve-tooltip`, `nve-toast`, `nve-drawer`, `nve-dropdown`, and `nve-notification` with the native HTML Popover API: +... +``` -```html - - -tooltip +After: - -hello there -tooltip +```html +... ``` -### Deprecated Slots +## Maglev Component Replacements -| Component | Deprecated Slots | -| ---------------------- | ------------------------------------ | -| `nve-accordion-header` | `title`, `subtitle`, `actions` | -| `nve-card-header` | `title`, `subtitle`, `header-action` | +### App Header -Use the `api_get` tool to look up the current slot API for these components. +Replace the early Maglev `mlv-app-header` element with `nve-page-header`. -### Typography +Before: ```html -
-
+ + ... + ``` -### Layout +After: ```html -
-
+ + NV +

Infrastructure

+ Link 1 + Link 2 + EL + ``` -## Step 5: Verification +### Alert Banner -After applying all fixes: +Replace `nve-alert-banner` with `nve-alert-group` using `prominence="emphasis"` and `container="full"`. -1. Re-run ESLint to confirm zero deprecation violations -2. Use the `api_template_validate` tool on any HTML templates to check for correct API usage -3. Use the `project_validate` tool to confirm a healthy project state +Before: -## Available MCP Tools +```html + + + Standard banner message + + +``` + +After: + +```html + + + Standard banner message + + +``` -- `project_validate`: check project setup and find issues -- `project_setup`: setup or update to latest Elements package versions -- `packages_list`: check latest published versions -- `packages_changelogs_get`: get changelogs for migration-relevant changes -- `api_template_validate`: check HTML templates for correct API usage -- `api_list`: list all available Elements APIs -- `api_get`: get documentation for a specific component +### JSON Viewer + +The JSON viewer is an internal API. Avoid using it even if public exports expose it. Use `nve-codeblock` or `nve-monaco-input` for JSON content rendering. + +## Icon Migration + +Rename old icon names to current icon names. + +| Before | After | +| -------------------- | --------------------------- | +| `chevron-right` | `chevron` | +| `chevron-down` | `chevron` | +| `chevron-left` | `chevron` | +| `additional-actions` | `more-actions` | +| `analytics` | `pie-chart` | +| `annotation` | `transparent-box` | +| `app-switcher` | `switch-apps` | +| `assist` | `chat-bubble` | +| `checkmark` | `check` | +| `date` | `calendar` | +| `docs` | `book` | +| `expand-full-screen` | `maximize` | +| `expand-panel` | `arrow-stop` | +| `collapse-panel` | `arrow-stop` | +| `failed` | `x-circle` | +| `favorite-filled` | `star` | +| `favorite-outline` | `star-stroke` | +| `information` | `information-circle-stroke` | +| `maintenance` | `wrench` | +| `navigate-to` | `arrow` | +| `open-external-link` | `arrow-angle` | +| `location` | `map-pin` | +| `pinned-1` | `pin` | +| `project` | `folder` | +| `settings` | `gear` | +| `user` | `person` | +| `video-pause` | `pause` | +| `video-play` | `play` | +| `video-stop` | `stop` | +| `visible` | `eye` | +| `warning` | `exclamation-triangle` | + +For directional icons, add an explicit `direction` attribute. + +| Before | After | +| -------------------------------------------------- | -------------------------------------------------------------------- | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | + +## Final Verification Checklist + +- `package.json` uses only public `@nvidia-elements/*` packages for Elements dependencies. +- Source imports use public package scopes. +- CSS imports use public theme and style entrypoints. +- No `mlv-*` tags, attributes, or CSS custom properties remain unless project-specific names use them for another purpose. +- Removed components and APIs have replacements or no longer appear. +- Migrate deprecated `nve-layout`, `nve-text`, popover trigger, logo, and icon patterns. +- ESLint reports no Elements deprecation violations. +- `api_template_validate` passes for migrated templates. +- `project_validate` reports a healthy project state.