v14 Migration Guide

v14 released 10th of November, and here is the migration guide.

The release includes, but not limited to features, documentation, refactoring and bug fixes. For any questions, please contact us!

Overview

This guide includes everything you need to migrate from If Design System v13 to v14.

Transitioning to v14

The transition to v14 should be straight forward, since it’s basically a search and replace, some re-installs and minor adjustments to markup.

Feedback

To improve this guide, please contact us on our MS Teams channel or create an issue.

Design

The changes from v13 to v14 is mostly internal, but we've added some new spacing guidelines.

Elements

Spacing

We added new spacing guidelines and created a new separate set of spacing tokens. These tokens are only used for spacing (paddings and margins).

Most of the changes are done internally, but if you are using the tokens, here is the token convert table:

Previous spacing token	New Token
`$size-2`	`$size-spacing-2`
`$size-4`	`$size-spacing-4`
`$size-8`	`$size-spacing-8`
`$size-12`	`$size-spacing-12`
`$size-16`	`$size-spacing-16`
`$size-20`	`$size-spacing-24`
`$size-24`	`$size-spacing-24`
`$size-28`	`$size-spacing-32`
`$size-32`	`$size-spacing-32`
`$size-36`	`$size-spacing-40`
`$size-40`	`$size-spacing-40`
`$size-44`	`$size-spacing-48`
`$size-48`	`$size-spacing-48`
`$size-52`	`$size-spacing-56`
`$size-56`	`$size-spacing-56`
`$size-60`	`$size-spacing-64`
`$size-64`	`$size-spacing-64`
`$size-68`	`$size-spacing-64`
`$size-72`	`$size-spacing-64`
`$size-76`	`$size-spacing-64`
`$size-80`	`$size-spacing-88`
`$size-84`	`$size-spacing-88`
`$size-88`	`$size-spacing-88`
`$size-92`	`$size-spacing-88`
`$size-96`	`$size-spacing-88`
`$size-100`	`$size-spacing-120`
`$size-104`	`$size-spacing-120`
`$size-120`	`$size-spacing-120`

Design migration strategy

The fastest approach to v14 migration starts with the front-end developer. Developers should update the front end code to v14 and conduct a visual review with team designers. The transition should not cause any major breaks in the UI but there might be some small layout issues. Product teams using v13 components in their code should see a mostly seamless code transition.

Throughout visual review and iteration process, ask:

Is the spacing between components correct?
Does the general layout still work, and does it express the If Visual Identity accurately and effectively?

Following this review, work any development and design issues into your team’s planning workflow.

Develop

For v14, we extracted out and separated JavaScript libraries and Web Components into separate repositories and scopes.

Repository architecture

We now have 4 repositories, and 4 scopes:

ids-core / @ids-core
ids-js / @ids-js
ids-wc / @ids-wc
ids-react / @ids-react

Update remotes

If you've cloned the repositories, please update the remotes:

For Core:

git remote set-url origin git@ssh.dev.azure.com:v3/if-it/If%20Design%20Hub/ids-core

For JavaScript libraries:

git remote set-url origin git@ssh.dev.azure.com:v3/if-it/If%20Design%20Hub/ids-js

For Web Components:

git remote set-url origin git@ssh.dev.azure.com:v3/if-it/If%20Design%20Hub/ids-wc

For React:

git remote set-url origin git@ssh.dev.azure.com:v3/if-it/If%20Design%20Hub/ids-react

Update `.npmrc`

To be able to use the new packages, you need to update your projects .npmrc-file:

; For external packages, i.e. from npmjs.com
registry=https://pkgs.dev.azure.com/if-it/_packaging/common-external-packages/npm/registry/
; For our css components, to be deprecated
@if-design-system:registry=https://pkgs.dev.azure.com/if-it/40e35854-e791-490e-bec8-da33c65c3187/_packaging/if-design-system/npm/registry/
; For our React components, to be deprecated
@if-design-components-react:registry=https://pkgs.dev.azure.com/if-it/40e35854-e791-490e-bec8-da33c65c3187/_packaging/if-design-system/npm/registry/
@ids-js:registry=https://pkgs.dev.azure.com/if-it/40e35854-e791-490e-bec8-da33c65c3187/_packaging/if-design-system/npm/registry/
; For our web components
@ids-wc:registry=https://pkgs.dev.azure.com/if-it/40e35854-e791-490e-bec8-da33c65c3187/_packaging/if-design-system/npm/registry/
; For our css components
@ids-core:registry=https://pkgs.dev.azure.com/if-it/40e35854-e791-490e-bec8-da33c65c3187/_packaging/if-design-system/npm/registry/
; For our react components
@ids-react:registry=https://pkgs.dev.azure.com/if-it/40e35854-e791-490e-bec8-da33c65c3187/_packaging/if-design-system/npm/registry/
; Use this if you still use older versions of the packages
@guybrush:registry=https://waypoint.myget.org/F/relax/auth/f9d9d4a0-b43f-4925-9d6c-424360fbc698/npm/
always-auth=true

Update dependencies

And you need to search and replace @if-design-system/ with @ids-core/, in most likely your package.json, as example:

From:

{
  …
  "dependencies": {
    "@if-design-system/button": "…",
  }
  …
}

To:

{
  …
  "dependencies": {
    "@ids-core/button": "…",
  }
  …
}

And then do a reinstall:

npm i

Components

Extracted packages

We've separated out the already existing js and webcomponent packages from @if-design-system, now known as @ids-core:

From	To
`@if-design-system/autocomplete-js`	`@ids-js/autocomplete`
`@if-design-system/tag-js`	`@ids-js/tag`
`@if-design-system/util-js`	`@ids-js/utils`
`@if-design-system/datepicker-js`	`@ids-js/datepicker`
`@if-design-system/datepicker-webcomponent`	`@ids-wc/datepicker`
`@if-design-system/faq-webcomponent`	`@ids-wc/faq`
`@if-design-system/modal-webcomponent`	`@ids-wc/modal`
`@if-design-system/phonenumber-webcomponent`	`@ids-wc/phonenumber`
`@if-design-system/toast-webcomponent`	`@ids-wc/toast`
`@if-design-system/help-tooltip-webcomponent`	`@ids-wc/help-tooltip`

Info Card markup change

To be able to let the arrow animation effect on hover for Info Card as links and to let the arrows be a part of the content flow so we could align the content better, we altered the markup accordingly:

From

<ul class="if cards info three">
  <li class="if">
    <a href="#" target="_blank" class="if info-card">
      <span class="if title number"> 20% </span>
      <span class="if text">When you buy insurance online</span>
      <span class="if link">Calculate your price<span className="if axe sr-only">, Opens in new window</span></span>
    </a>
  </li>
  …
</ul>

To

<ul class="if cards info three">
  <li class="if">
    <a href="#" target="_blank" class="if info-card">
      <span class="if title number"> 20% </span>
      <span class="if text">When you buy insurance online</span>
      <span class="if link">Calculate your price<span className="if axe sr-only">, Opens in new window</span></span>
+      <span class="if arrow-animation"></span>
    </a>
  </li>
  …
</ul>

Token renaming

We renamed some internal design tokens that might be used externally:

Core

From	To
`$baseline-grid`	`$layout-grid-baseline-low`
`$baseline-grid-px`	`$layout-grid-baseline-high`
`$baseline-grid-8`	`$layout-grid-baseline-low-px`
`$baseline-grid-8-px`	`$layout-grid-baseline-high-px`

Grid

From	To
`$grid-gutter-width`	`$size-grid-gutter-width`
`$grid-gutter-half-width`	`$size-grid-gutter-half-width`
`$grid-gutter-half-width-negative`	`$size-grid-gutter-half-width-negative`
`$grid-number-of-columns`	`$size-grid-columns`

Spacing

We added new spacing guidelines and created a new separate set of spacing tokens. These tokens are only used for spacing (paddings and margins).

Most of the changes are done internally, but if you are using the tokens, see the token conversion table above.

AuthorAlexander Vassbotn Røyne-Helgesen

v14 Migration Guide

Overview

Transitioning to v14

Feedback

Design

Elements

Spacing

Design migration strategy

Develop

Repository architecture

Update remotes

Update .npmrc

Update dependencies

Components

Extracted packages

Info Card markup change

From

To

Token renaming

Core

Grid

Spacing

Update `.npmrc`