Update to Element v51¶

Element v51 requires Angular v22. It introduces the system tokens of the Siemens Design Language. Most Element components keep their appearance. Typography is the main visual change. Legacy utilities and Sass variables are deprecated, but they still work. Only text-primary and btn-ghost changed meaning.

The migration-v51 schematic applies most of the breaking changes. This guide covers the remaining steps.

Before you start¶

1. Update to the latest Element v49 release. If you are updating from v48 or older, follow the v49 update guide first.
2. Update to Angular v22, following the Angular update guide. Keep it separate from the Element update, so both changes stay easy to review. This is also a good moment to modernize your application setup by running Angular migrations and to review your eslint setup. Use Siemens Lint and avoid disabling rules to catch deprecated Angular constructs.
3. Clean up deprecated Element APIs. Use @typescript-eslint/no-deprecated to find them. Some of them are migrated for you, see Changes applied by the schematic. Not every deprecated API is removed in v51, but the ones that are will turn into compile errors after the update. Handling them now keeps that list short.
4. Commit or stash your changes, because the update rewrites templates, styles, and TypeScript across your project.

Update Element¶

ng update bumps all @siemens/* Element packages together, but it does not install their peer dependencies. Take care of those yourself:

@angular/aria, @siemens/map-styles and gridstack v13 are new requirements in v51. For the other three, v51 raises the minimum version. The lower version listed in each row still works, so move to the newer major only when it suits you.

If you use Formly, @siemens/element-ng/formly is now based on ngx-formly v7.1. To stay on v6, keep @ngx-formly/* at v6 and import SiFormlyModule from @siemens/element-ng/formly-legacy. To move to v7.1, use the standalone SiFormlyComponent from @siemens/element-ng/formly. See dynamic forms.

Then run the update:

npm i @simpl/brand@4.0.1 # Only for Siemens applications
ng update @siemens/element-ng@51

This command runs the migration-v51 schematic, and from 51.0.1 also migration-v51-0-1.

If you already updated to Element v51.0.0, install @simpl/brand@4.0.1 and run ng update again so migration-v51-0-1 rewrites the color token names. Typography tokens stay as they are. Utility classes such as .background-0 are unchanged.

If you import generated brand dist files, update those paths: si-dark.* and si-light.* become si-sys-color.dark.* and si-sys-color.light.*, si-typography.* becomes si-sys-typography.default.*, and si-sys-classes.* becomes si-sys-color-classes.*.

If the schematic cannot infer a pixel size for si-split, or if scale and unit conflict, it logs the files where you need to set size and unit.

If you still use the legacy tabs, migrate them with:

ng g @siemens/element-ng:migrate-tabs-legacy

If a tab usage is too complex to migrate automatically, the schematic logs the file so you can update it by hand.

Class names the schematic does not rewrite¶

The schematic rewrites class names only in the static class attribute of your templates. It does not rewrite class names in stylesheets, [ngClass], [class], [class.*] bindings, or strings you build in TypeScript. CSS custom properties and Sass variables in your stylesheets are already rewritten.

Rename the remaining class names yourself, using the same mappings the schematic applied to your templates. Most mappings are one-to-one. Two pairs swapped meaning, so apply those in this order:

1. text-primary → text-accent, then text-body → text-primary
2. btn-ghost → btn-tertiary-ghost, then btn-primary-ghost → btn-ghost

Limit the search to the places listed above, because a project-wide find and replace would also rename templates the schematic already migrated.

Fix remaining API changes¶

Fix these remaining API changes from the compile errors, and check the file uploader and gauge chart by hand because they do not fail the build:

Migrate $element tokens¶

Element v51 still ships the $element-* design-system tokens, but they are deprecated and will be removed in an upcoming major version. The Siemens Design Language tokens ($si-sys-color-*) replace them and should be used from now on. There is not always a 1:1 mapping, because the token structure changed. The mapping files below include rules so the migration can be automated as much as possible.

If your application uses $element-* tokens, we recommend migrating them now. The schematic does not rewrite these usages. Feed the mapping files to an AI assistant together with your stylesheets:

• color-migration-map.json
• typography-migration-map.json

Example prompt:

Need to migrate SCSS variables: replace $element-* with the new
design system tokens. Look at color-migration-map.json and
typography-migration-map.json for the mapping between 'old' and
'new'. Note that the JSON uses '.' while the SCSS variables use
'-'. Note that there are rules described in the mapping as well
as the old->new mapping isn't 1:1.

Review the result in the running application. Consult UX designers where a mapping depends on context. Visual regression tests help catch mistakes in this migration.

Review the UI¶

The changes below are visual, so check them in the running application:

Typography: Headings are now semibold, and font sizes follow a new 1.2 step scale. For page titles, use the page header with h2.si-layout-title.

Icons: si-application-header and si-navbar-vertical now use the default 20px icons. Overrides of the .element-* icon font classes no longer apply to Element components. Provide custom icons through the icons property of your theme.

Buttons: btn-ghost is now the primary ghost style. The schematic renamed the usages in your templates to btn-tertiary-ghost, so they keep the previous look. Change a usage to btn-ghost only if you want the new primary ghost style.

Chat input: actions now render inline, so move items that belong in the menu to secondaryActions.

Root font size: The default remains 16px. To use the browser default, set $element-root-font-size to initial, which becomes the default in Element v52:

@use '@siemens/element-theme/src/theme' with (
  $element-root-font-size: initial
);

For everything else, see the changelog.

Except where otherwise noted, content on this site is licensed under MIT License.