Upgrade Angular UI Libraries During Version Migrations: Material + PrimeNG Without UX Regression (Angular 20+)

Where upgrades go sideways

At a broadcast media network scheduling and Charter ads analytics, a single padding change could break line-of-business workflows. The fix wasn’t hero devs clicking around; it was codified tokens, visual tests, and feature flags that let us phase the upgrade by role and route.

• Density shifts change table ergonomics.

• Typography defaults alter chart labels and LCP.

• Overlay stacks (dialogs/tooltips) fight for z-index.

• Legacy Material → MDC breaks spacing tokens.

• PrimeNG variable names/themes shift across majors.

The real regression vectors

Your visual language lives in tokens and spacing expectations, not in the libraries themselves. If you don’t freeze these first, every upgrade becomes a visual reset.

• Default density/typography changes ripple through lists, tables, and buttons.

• Color tokens/semantic roles (info/warn/surface) don’t map 1:1.

• Icon set or spacing reworks shift layouts by a few pixels—death by a thousand cuts.

• Accessibility defaults change (focus rings, contrast, motion).

AngularUX tokens (SCSS + CSS variables)

Lock the palette, typography scale, and density ramps as the source of truth and map them to Material/PrimeNG.

SCSS token definition

// tokens.scss (AngularUX palette + ramps)
$ux-color-primary: #4f46e5; // indigo-600
$ux-color-accent:  #06b6d4; // cyan-500
$ux-color-warn:    #ef4444; // red-500
$ux-surface-0: #0b1020;
$ux-surface-1: #121736;
$ux-text-1: #ffffff;
$ux-text-2: #c1c6d4;

$ux-font-family: 'Inter', system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif;
$ux-type-scale: (
  xs: 12px,
  sm: 14px,
  md: 16px,
  lg: 18px,
  xl: 20px,
  h3: 22px,
  h2: 24px,
  h1: 28px
);

$ux-density: (
  compact: 4px,
  cozy: 8px,
  comfortable: 12px
);

:root {
  --ux-primary: #{$ux-color-primary};
  --ux-accent:  #{$ux-color-accent};
  --ux-warn:    #{$ux-color-warn};
  --ux-surface-0: #{$ux-surface-0};
  --ux-surface-1: #{$ux-surface-1};
  --ux-text-1: #{$ux-text-1};
  --ux-text-2: #{$ux-text-2};
  --ux-font: #{$ux-font-family};
  --ux-space-1: map-get($ux-density, compact);
  --ux-space-2: map-get($ux-density, cozy);
  --ux-space-3: map-get($ux-density, comfortable);
}

Map tokens to Material + PrimeNG

// material-theme.scss
@use '@angular/material' as mat;

$primary-palette: mat.define-palette(mat.$indigo-palette, 600);
$accent-palette:  mat.define-palette(mat.$cyan-palette, 500);
$warn-palette:    mat.define-palette(mat.$red-palette);

$typography: mat.define-typography-config(
  $font-family: var(--ux-font),
  $headline-5: mat.define-typography-level(map-get($ux-type-scale, h2), 32px, 500)
);

$theme: mat.define-light-theme((
  color: (
    primary: $primary-palette,
    accent:  $accent-palette,
    warn:    $warn-palette,
  ),
  typography: $typography,
));

@include mat.all-component-themes($theme);

// prime-theme.scss (override CSS variables for Lara/Aura themes)
:root {
  --primary-500: var(--ux-primary);
  --text-color: var(--ux-text-1);
  --text-color-secondary: var(--ux-text-2);
  --surface-ground: var(--ux-surface-0);
  --surface-card: var(--ux-surface-1);
  --font-family: var(--ux-font);
  --inline-spacing: var(--ux-space-2);
  --content-padding: var(--ux-space-2);
  --border-radius: 8px;
}

Nx-powered inventory

# quick scan for Material legacy tags and PrimeNG attributes
grep -R "mat-legacy-\|p-\w\+=" -n apps/ libs/ > ui-usage.txt

# Nx Affected to scope the upgrade
npx nx affected:graph --base=main --head=HEAD

• nx graph to spot libraries by scope

• AST/grep to list component tags + inputs

• coverage to see what’s untested

Codemod Material legacy components

// tools/migrations/material-legacy-fix.ts (ts-morph)
import { Project, SyntaxKind } from 'ts-morph';

const project = new Project({ tsConfigFilePath: 'tsconfig.base.json' });

project.getSourceFiles('**/*.ts').forEach(sf => {
  sf.getImportDeclarations().forEach(imp => {
    const m = imp.getModuleSpecifierValue();
    if (m.includes('legacy')) {
      imp.setModuleSpecifier(m.replace('legacy-', ''));
    }
  });
});

project.getSourceFiles('**/*.html').forEach(sf => {
  sf.replaceWithText(
    sf.getFullText()
      .replaceAll('mat-legacy-table', 'mat-table')
      .replaceAll('mat-legacy-button', 'button mat-button')
  );
});

project.saveSync();

PrimeNG property rename example

When PrimeNG shifts input names between majors, codemod repetitive templates instead of hand edits.

// tools/migrations/primeng-prop-rename.ts
import { Project } from 'ts-morph';
const p = new Project({ tsConfigFilePath: 'tsconfig.base.json' });

p.getSourceFiles('**/*.html').forEach(sf => {
  let t = sf.getFullText();
  t = t.replaceAll('[showClear]=', '[showClearIcon]='); // example
  t = t.replaceAll('pInputText', 'p-inputtext');        // directive rename example
  sf.replaceWithText(t);
});

p.saveSync();

Cypress component snapshots

// cypress/component/table.cy.ts
import { mount } from 'cypress/angular';
import { MyTableComponent } from './my-table.component';

describe('Data Table', () => {
  it('renders stable density + typography', () => {
    mount(MyTableComponent, { inputs: { dense: true } });
    cy.get('[data-cy=table]').should('be.visible');
    cy.matchImageSnapshot('table-dense');
  });
});

Lighthouse budgets in CI (Nx)

// budgets.json
{
  "resourceSizes": [
    { "resourceType": "script", "budget": 350 },
    { "resourceType": "third-party", "budget": 120 }
  ],
  "timings": [
    { "metric": "first-contentful-paint", "budget": 2000 },
    { "metric": "largest-contentful-paint", "budget": 2500 },
    { "metric": "cumulative-layout-shift", "budget": 0.1 }
  ]
}

# .github/workflows/ci.yml (excerpt)
- name: Lighthouse Budget
  run: npx lighthouse http://localhost:4200 --budgetsPath=budgets.json --chrome-flags="--headless"

Progressive rollout by role/route

// feature-flags.store.ts
import { signalStore, withState, withMethods } from '@ngrx/signals';
import { inject } from '@angular/core';
import { RemoteConfig } from '@angular/fire/remote-config';

export interface FlagsState { useNewTable: boolean; }

export const FeatureFlagsStore = signalStore(
  { providedIn: 'root' },
  withState<FlagsState>({ useNewTable: false }),
  withMethods((store) => ({
    async init() {
      const rc = inject(RemoteConfig);
      await rc.fetchAndActivate();
      store.setState({
        useNewTable: rc.getBoolean('ui_new_table'),
      });
    }
  }))
);

// table-host.component.ts
@Component({
  selector: 'app-table-host',
  template: `
    <ng-container *ngIf="flags.useNewTable(); else legacy">
      <app-primeng-table [rows]="rows" />
    </ng-container>
    <ng-template #legacy>
      <app-material-table [rows]="rows" />
    </ng-template>
  `
})
export class TableHostComponent {
  flags = inject(FeatureFlagsStore);
}

• Turn on new components for internal roles first.

• Expose kill switches for overlays/dialogs.

• Watch error and UX metrics before expanding.

Focus rings and motion

/* Strong, consistent focus across libs */
:root { --focus: 2px dashed var(--ux-accent); --focus-offset: 2px; }
:focus-visible { outline: var(--focus); outline-offset: var(--focus-offset); }

/* Respect prefers-reduced-motion */
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.001ms !important; animation-iteration-count: 1 !important; transition-duration: 0.001ms !important; }
}

Density controls

/* One class to densify both Material + PrimeNG zones */
.compact .p-component, .compact .mat-mdc-form-field, .compact .mat-mdc-button {
  --inline-spacing: 4px; --content-padding: 4px; font-size: 0.875rem;
}

Overlay stacks

/* Align z-index layers so tooltips/dialogs don’t fight */
:root {
  --z-tooltip: 1000; --z-dropdown: 1100; --z-dialog: 1200; --z-toast: 1300;
}
.p-tooltip { z-index: var(--z-tooltip); }
.p-dialog  { z-index: var(--z-dialog); }
.cdk-overlay-container { z-index: var(--z-dropdown); }

Theme your charts once

// highcharts-theme.ts
import Highcharts from 'highcharts';
export function applyUxTheme() {
  Highcharts.setOptions({
    colors: ['#4f46e5', '#06b6d4', '#ef4444', '#22c55e'],
    chart: { backgroundColor: 'transparent', style: { fontFamily: 'var(--ux-font)' } },
    title: { style: { color: 'var(--ux-text-1)', fontSize: '16px' } },
    xAxis: { gridLineColor: 'rgba(255,255,255,0.06)', labels: { style: { color: 'var(--ux-text-2)' } } },
    yAxis: { gridLineColor: 'rgba(255,255,255,0.06)', labels: { style: { color: 'var(--ux-text-2)' } } }
  });
}

Data virtualization

at a major airline’s airport kiosk simulations, we throttled DOM churn with virtualization and debounced Signals on real-time feeds. The upgrade kept render counts flat while improving perceived latency.

• Avoid DOM bloat when tables jump versions.

• Use cdkVirtualFor or PrimeNG VirtualScroller for >10k rows.

• Batch WebSocket updates with Signals debounce to reduce reflows.

Charter ads analytics (PrimeNG)

We staged PrimeNG component swaps behind flags, used Cypress snapshots on 20+ critical dashboards, and held CLS under 0.05.

• PrimeNG major upgrade with VirtualScroller and overlay tweaks.

• Density tokens stabilized tables for ops roles.

a broadcast media network VPS scheduling (Material)

We ran codemods, replaced legacy imports, and validated with Storybook/Chromatic. No support tickets post-cutover.

• Material legacy → MDC migration.

• Custom tokens ensured typography parity across role-based views.

United kiosk (Material + hardware)

We simulated peripherals in Docker, upgraded Material, and kept accessible, jitter-free dialogs—critical when devices reconnect mid-transaction.

• Offline-tolerant UI, strong focus states for scanner/card flows.

Signals you need help now

Bring in an Angular consultant when upgrades stall in review because reviewers spot visual drift. A short, focused engagement sets tokens, codemods, and guardrails so your team can execute with confidence.

• AngularJS/early Angular stuck with custom themes.

• UI library majors skipped; density/typography inconsistent.

• Overlay z-index chaos; accessibility regressions persist.

My step-by-step

This is the exact playbook I used on a global entertainment company employee tooling, Charter analytics, and United kiosk upgrades. It’s fast because we keep UX measurable and enforceable.

• Audit usage via Nx + AST.

• Freeze tokens, map to both libraries.

• Write codemods and component adapters.

• Wire feature flags with Signals/SignalStore.

• Add Cypress/Lighthouse gates; roll by role/route.

What to implement this sprint

• Create tokens.scss and map to Material/PrimeNG.

• Add three Cypress image snapshots for your most-used table, dialog, and form.

• Add Lighthouse budgets to CI.

• Codemod one breaking change end-to-end with tests.

• Gate one high-risk component behind Remote Config.