Skip to content

Latest commit

 

History

History
44 lines (27 loc) · 4.35 KB

MIGRATION.md

File metadata and controls

44 lines (27 loc) · 4.35 KB
Raw

Migration Guide

This guide will serve as a reference for migrating from this @momentum-ui/design-tokens project to the superseding @momentum-design/tokens project.

Conversion - Web

As a consumer of this project developing web applications, the following can be used as a reference:

Theme tokens generated by this project were initially inclusive of component tokens along side theme tokens. The superseding implementation does not include any component tokens in its 1:1 distributable for this project. Instead, it includes exclusively theme tokens for the webex-light and webex-dark themes.

These themes can be located at the following locations local to where the distributable is installed:

  • webex-dark - ./dist/{css|scss}/theme/webex/dark-stable.{css|scss}
  • webex-light - ./dist/{css|scss}/theme/webex/light-stable.{css|scss}

In order to migrate your existing consumption of Momentum Design tokens to the consumption of the superseding Momentum Design tokens, the following steps must be performed:

  • Change all currently implemented component tokens to the superseding theme token namespaces
    • Since the superseding package does not include any component tokens, all component tokens being used within your application must be updated to reflect the superseding theme tokens.
    • Example - --avatar-color-avatar-background-pink => --mds-color-theme-avatar-pink
  • Replace all currently implemented theme tokens with their superseding theme token namespaces
    • Since the superseding package uses a different naming convention for all tokens, while still containing a 1:1 reference of the existing tokens, all theme tokens being used within your application must be updated to reflect the superseding theme tokens.
    • Most, if not all, theme tokens from this package's distributable can be updated by simply changing the prefix of the reference to the distributable from --theme to --mds-color-theme.
    • Example - --theme-button-primary-normal => --mds-color-theme-button-primary-normal

Thanks to the rather direct conversion flow, the following steps can be performed using any common scripting language against your project:

  • Convert all component tokens into their theme tokens - Running a script that maps all component tokens to their assigned theme tokens can be performed by using the references available in this project. Notice that the component tokens include @theme-path-to-theme-token in their key:value pairs. Use this to knowledge to help perform this step in the process.
  • Convert all theme tokens within this project to their superseding theme tokens - Running a script that mutates all theme token references to this project to their superseding values can be mostly performed by updating the prefix from --theme to --mds-color-theme. Use this to cover a majority of the ground in your application.

Conversion - Native

As a consumer of this project developing native client applications, the following can be used as a reference:

Theme tokens generated by this project were initially inclusive of component tokens along side theme tokens. The superseding implementation does not include any component tokens in its 1:1 distributable for this project. Instead, it includes exclusively theme tokens for the webex-light and webex-dark themes.

These themes can be located at the following locations local to where the distributable is installed:

  • webex-dark - ./dist/json/theme/webex/dark-stable.json
  • webex-light - ./dist/json/theme/webex/light-stable.json

Note: The superseding project distributes swift class files, android xml files, and minimal json files in addition to the standard json files mentioned above. These formats have not been validated for consumption, but can be investigated by teams that would like to consume files formatted closer to their applications interfaces.

Migrating to the superseding token values for native clients has not been fully investigated, and may require some inovative flows depending on the consuming client. If any tooling is generated to help users migrate to the superseding tokens from the existing tokens, amendments to this MIGRATION.md guide are welcome.