Swiss Post

Design System

The Swiss Post Design System pattern library for a unified and accessible user experience across the web platform.

Compatibility

List of compatible version numbers with external dependencies.

Styles

Package @swisspost/design-system-styles
VersionBootstrapAngularNg-Bootstrap
5.x5.014.x13.x
6.25.215.x14.x
6.45.316.x15.x

Common Web Frontend

Package @ch-post-common/common-web-frontend
VersionBootstrapAngularNg-Bootstrap
4.x4.612.x9.x

Setup for migration instructions

What environment is your application for?
What technology is your application built with?

Migration from v5 to v6

  1. Package Update 🩺

    1. Use https://update.angular.io/ to update Angular to version 16

    2. Update Bootstrap to version 5.3.x and ng-bootstrap to version 15.x.x : npm install bootstrap@5.3 @ng-bootstrap/ng-bootstrap@15

    3. Update Design System style package to version 6: npm install @swisspost/design-system-styles@6

  2. Automatic Migration ⚙️

    If you are migrating an Angular application, you can take advantage of our migration schematics.

    1. Commit all the changes you have made so far
    2. Make sure you are running on a node version >= 16
    3. You should now be able to run the following command to apply all automatic migrations to your application: npm install @swisspost/design-system-migrations npx ng update @swisspost/design-system-migrations --from=5 --to=6 --migrate-only --allow-dirty npm uninstall @swisspost/design-system-migrations
  3. Component Migration 🤓

    Changes flagged with the ⚙️ symbol should be automatically migrated with our migration tool.

    Accessibility
    • Stepper breaking

      The markup of the stepper component has been changed in order to be more accessible.

      • ⚙️ The stepper container no longer has an aria-label attribute but contains a hidden header instead
      • ⚙️ The progress bar is hidden and no longer requires a type attribute
      • ⚙️ The stepper has a list role
      • Completed steps require an additional hidden "Completed: " text
      • Current and incomplete steps should not be links
    Deprecations
    • ngbButton ⚙️ breaking

      The ngbButton and ngbButtonLabel directives are no longer a part of ng-bootstrap.
      The markup and styles have changed and everything now works with CSS Bootstrap classes only.

      See the documentation for more detailed information.

    • Removed variables breaking

      The following Sass variables have been removed because they are not being used anymore.

      • $table-head-bg

Migration from v4 to v5

  1. Clean Start 🧹

    Create a branch and commit all changes to have a clean, reversible starting point. If you like to upgrade from a Design System version lower than 4.0.0, it might be necessary to upgrade to v4 first.

  2. Old Package Uninstallation 🗑️

    Uninstall the old styles package.

    npm uninstall @******/common-web-frontend
  3. New Package Installation 📦

    npm install @swisspost/design-system-styles@5
  4. Package Update 🩺

    1. If your Angular version is lower than 13, use https://update.angular.io/ to update Angular step by step to version 13.
    2. Update Bootstrap to version 5.1.x and ng-bootstrap to version 12.x.x : npm install bootstrap@5.1 @ng-bootstrap/ng-bootstrap@12
  5. Automatic Migration ⚙️

    If you are migrating an Angular application, you can take advantage of our migration schematics.

    1. Commit all the changes you have made so far
    2. Make sure you are running on a node version >= 16
    3. You should now be able to run the following command to apply all automatic migrations to your application: npm install @swisspost/design-system-migrations npx ng update @swisspost/design-system-migrations --from=4 --to=5 --migrate-only --allow-dirty npm uninstall @swisspost/design-system-migrations
  6. Component Migration 🤓

    Changes flagged with the ⚙️ symbol should be automatically migrated with our migration tool.

    Deprecations
    • Dropped jQuery dependency
      Replace all jQuery components with the given one or integrate jQuery by your own (not recommended).

    • The Custom-Select component has been marked as deprecated. For the moment there is only the alternative to use the Form-Select component instead. An alternative is being implemented.

    Migrations list

    Some changes cannot be migrated automatically.
    Check the list of changes below and apply the transformations manually if your application is affected.

    Paths & Files
    Variables
    Mixins
    Classes
    ⚙️
    Alert / Notification

    See the documentation for more detailed information.

    Badge

    See the documentation for more detailed information.

    Background

    See the documentation for more detailed information.

    Blockquote

    See the documentation for more detailed information.

    Button

    See the documentation for more detailed information.

    Button Close

    See the documentation for more detailed information.

    Card

    See the documentation for more detailed information.

    Forms

    See the documentation for more detailed information.

    From Control

    See the documentation for more detailed information.

    From Select

    See the documentation for more detailed information.

    From Textarea

    See the documentation for more detailed information.

    Form File

    See the documentation for more detailed information.

    From Checkbox

    See the documentation for more detailed information.

    From Radio

    See the documentation for more detailed information.

    Form Switch

    The switch component has been moved to the Bootstrap section since Bootstrap version 5.x now provides such a component. If you import this component manually, you need to update to the new file path.

    See the documentation for more detailed information.

    ⚙️
    Buttons

    See the documentation for more detailed information.

    DatePicker

    See the documentation for more detailed information.

    Modal

    See the documentation for more detailed information.

    ⚙️
    Accordion

    One might think: "When it is so easy to migrate, why don't you offer an automatic migration?"
    The short answer: because it is no longer the same component!

    Accordion
    Custom-Select

    See the documentation for more detailed information.

    Subnavigation

    See the documentation for more detailed information.

    Topic Teaser

    See the documentation for more detailed information.

    ⚙️
  7. Treat yourself to a 🍺, you've done a great job! 🚀