Migrate from v3 to v4

Use this guide to upgrade @qualcomm-ui/angular from 3.x to 4.0.0. This release adopts the QDS v2 measurement scales and deprecates several component props, values, and types.

Migration

Update dependencies

Use npm-check-updates:

npx npm-check-updates@latest --filter '@qualcomm-ui/*' --deep -u

This command updates all package.json entries for @qualcomm-ui/* dependencies to the latest release. Run your package manager's install command after to update the dependencies.

Apply codemods

Continue reading below to automatically migrate your codebase.

Migrate measurement tokens

@qualcomm-ui/qds-core v2 and @qualcomm-ui/tailwind-plugin v2 rename the spacing, sizing, and border radius tokens. This is the breaking change in this release.

QUI's component CSS already uses the new tokens. Components render at the same sizes. Only application code that references these tokens directly must be migrated:

  • CSS variables: --spacing-*, --sizing-*, and --border-radius-*.
  • Tailwind spacing utilities, such as p-qds-40.
  • Tailwind theme variables: --spacing-qds-*.

Some token names exist in both scales with different pixel values. Legacy --spacing-100 is 16px. The new --spacing-100 is 4px.

Token codemod

Before running this command, check your codebase for references to the legacy tokens. Chances are you never used these directly. Do not run it on projects that started on @qualcomm-ui/qds-core v2.

Run from your project root:

npx @qualcomm-ui/codemod@latest migrate qds-v2-tokens
  • Use --dry-run to preview changes without writing files.
  • The migration cancels without writing files if any scanned file contains v2-only tokens. --force skips this check. Review mixed legacy and v2 references before using it.
  • Detected v1 dependencies on @qualcomm-ui/qds-core and @qualcomm-ui/tailwind-plugin are updated to v2.
  • The codemod adds a qui.completedMigrations record and a note field to package.json. Commit the qui field. Do not edit or remove it. Removing the record can cause tokens to be renamed again.

Update runtime-built names, such as `--spacing-${step}`, and bare names without the -- prefix manually. These are not rewritten.

Refer to the codemod README for migration details.

Manual token migration

Replace each legacy token with the new token that preserves its pixel value:

.panel {
  padding: var(--spacing-40); 
  padding: var(--spacing-100); 
  width: var(--sizing-70); 
  width: var(--sizing-400); 
  border-radius: var(--border-radius-md); 
  border-radius: var(--border-radius-100); 
}

Update Tailwind spacing utilities:

<div class="p-qds-40">Content</div>
<div class="p-qds-100">Content</div>

rounded-* utilities and --radius-* variables from @qualcomm-ui/tailwind-plugin keep their existing names and pixel values. The plugin adds rounded-2xl (14px), rounded-3xl (16px), rounded-4xl (20px), and rounded-5xl (24px) in this update.

Migrate deprecated props

This step is optional, but recommended. The deprecated props, values, and types remain supported in v4.

Run the Angular codemod:

npx @qualcomm-ui/codemod@latest migrate angular

The codemod can run before or after upgrading. It updates detected @qualcomm-ui/angular v3 dependencies to v4 in package.json. It is idempotent, so there is no risk of it breaking something if it runs more than once. Run your formatter afterward, the codemod does not reformat files.

migrate angular only updates @qualcomm-ui/angular. Update @qualcomm-ui/qds-core with qds-v2-tokens or manually.

Props and values

The emphasis prop has changed for these components:

ComponentsDeprecatedReplacement
Slider, SegmentedControl, Breadcrumbs, Progress, ProgressRingprimarybrand
Tagoutline-brandbrand-outline
Tagoutline-neutralneutral-outline
Tagkiwilime

Types

The codemod renames these types in imports, re-exports, and their references:

PackageDeprecatedReplacement
@qualcomm-ui/qds-core/sliderQdsSliderVariantQdsSliderEmphasis
@qualcomm-ui/qds-core/segmented-controlQdsSegmentedControlVariantQdsSegmentedControlEmphasis

Manual updates

The codemod handles external .html templates and inline template strings. It rewrites static attributes, [variant] bindings, and interpolations on QUI selectors.

Review these cases manually:

  • Non-literal expressions such as [variant]="value" have the prop renamed, but the value source still requires review.
  • Elements with both variant and emphasis are reported without changes. Remove variant.
  • Inline templates with ${} substitutions or escape sequences, and templates that fail to parse, are reported without changes.
  • Prop objects built elsewhere, direct qds-core API usage, and CSS are not rewritten.

Review custom CSS

The prop codemod does not update CSS selectors. If you customized CSS manually for our components, check your CSS files for the following:

ComponentsPrevious default attributeNew default attribute
Slider, SegmentedControldata-variant="primary"data-emphasis="brand"
Breadcrumbs, Progress, ProgressRingdata-emphasis="primary"data-emphasis="brand"
Tagdata-emphasis="outline-brand"data-emphasis="brand-outline"

Slider and SegmentedControl render data-emphasis instead of data-variant, including when the deprecated variant prop is used. Update selectors for both primary and neutral variants on these components.

Updated by Ryan Bower