Version 2 Upgrade Guide

Since launching in summer 2017, the MDS library has continued to grow and evolve to meet customer needs. While the vast majority of updates are compatible with earlier releases, a handful of revisions have required breaking changes to the design and code API. As a result, MDS launched a second major release version 2.0.0 in June 2018. Teams upgrading from any version of MDS prior to v2.0.0 must take specific steps to upgrade as described in this guide.

It is recommmended that teams always upgrade to the most recent MDS version. For details see the release history. Unless otherwise specified, information in this guide applies to all versions of MDS v2.x.x up to and including the most recent.

Please refer to this page over time or even print it as a checklist as you complete your upgrade.

Version 2 Highlights

The MDS v2 release significantly evolves how adopting product squads consume the MDS package and includes updates to the visual language (like Color) and UI component library (like Button or List Group).

Packaging Code

MDS reduced the complexity of the package by optimizing assets so that adopting teams consume the visual language and UI component library more easily. The changes include:

  • Removing redundant files to significantly reduce installation time.
  • Simplifying top-level folders per asset type: constants, components, fonts, icons, & styles.
  • Reorganizing SCSS mixins so product teams can use each without producing unwanted CSS.
  • Applying relative file paths to fix 1.x pathing defects.
  • Separating the MDS doc-site from the library package.

Evolving Visual Language

MDS fortified tooling that applies the visual language of color, typography, space, and more, including:

  • How color is applied to component element text, borders, and fills relative to background settings.
  • Removing space applied outside a component’s boundary—usually, the margin of the outermost containing element—so that components are unopinionated about how they are spaced relative to adjacent elements.
  • Reorganizing and namespacing mixins with mds-, as well as improving their documentation.

MDS Web Components

MDS web components are Custom Elements that internalize HTML markup within each component, which greatly streamlines integration and maintenance. As alternative to upgrading the HTML markup, teams can choose to adopt MDS web components when available. Currently only a subset of UI components are have been released as web components. See the Component Status page for details on availability.

Normalizing Components

In addition to the release of web components, other significant changes to the component library include:

  • Removing default component widths so that component blocks fill available width, whether simple elements like form inputs and selects or layered components like dialogs and modals.
  • Aligning component heights across the library so that form inputs, selects, pagination, data table cells and other elements are consistently sized.
  • Removing deprecated components, including (the older version of) Notification.

Namespacing

Namespacing makes it possible to use multiple versions of MDS within the same application by specifying the MDS version used by each component. See namespacing style dependencies for more information.

Planning an Upgrade

Upgrading to version 2 should not require a significant investment for adopting teams.

  • Is this a redesign? No. The visual language and UI components are mostly unchanged. Upgrading is mostly technical work for engineers with light designer coordination.
  • Will upgrading to version 2 be as expensive as adopting version 1? No, not even close. The breaking changes are itemized and small in scope. Effort required to upgrade should be far, far lower than transitioning from another framework like MUI-Bootstrap.
  • Why should I upgrade? In addition to fixes and new features offered, no new features will be made available on version 1.x once version 2 is released. Upgrading in a timely manner ensures a more enduring and easy-to-use toolkit for years to come.
  • When do I have to upgrade? Adopting teams are encouraged to upgrade to version 2.x by Q3 2019, at which time version 1.x will be phased out.
  • Should I adopt MDS web components? When upgrading to version 2 components, as alternative to upgrading the HTML markup, teams can choose to adopt MDS web components when available. Currently only a subset of UI components are have been released as web components. For details see the Component Status page.
  • Will multiple MDS versions coexist? Namespacing makes it possible to use multiple versions of MDS within the same application by specifying the MDS version used by each component. For example, this makes it possible to upgrade specific components to take advantage of new functionality, while other components continue to use the older version. See namespacing style dependencies for more information.

How to Upgrade, Per Feature

For existing MDS adopters, upgrading is mostly a technical exercise to revise how your product installs MDS code followed by itemized changes to the visual language and UI components.


An engineer on your team should:

  1. Review this Upgrade Guide.
  2. Discuss potential design impacts with UX and visual designer(s) on the team.
  3. Conduct the upgrade's three steps in order: installation, visual language, and UI components.
    • Tip: Per item, search code for key terms, such as a component name or block-level class (such as mds-button) to find all instances.
  4. Run automated test(s) such as automated visual regression, if your team employs such tools.
  5. Pair with designer(s) to manually review results across your product experience, with a focus on but not limited to known component updates.
    • Tip: Many updates involve confirming the change “doesn't degrade visual display.” Review your application’s use of each comprehensively, with attention paid to the feature’s size and spacing relative to adjacent elements.

Step 1: Installation & Packaging

  • CSS: node_modules/morningstar-design-system/dist/mds.css
  • Icon Sprite: node_modules/morningstar-design-system/dist/mds.svg
  • Fonts: node_modules/morningstar-design-system/fonts/*
  • Constants: node_modules/morningstar-design-system/constants/constants.css
  • Components: node_modules/morningstar-design-system/components/**/*.scss
  • Visual Language and Utils: node_modules/morningstar-design-system/styles/**/*.scss

CSS Compilation and Optimization

For AutoPrefixer, use the following configuration:

{
    browsers: ['last 2 versions'],
    grid: true
}

For CleanCSS, use the following configuration:

{
    level: 2
}

Step 2: Visual Language Checklist

The version 2 release includes many updates across the MDS visual language. Impacted features include Constants, mixins, and CSS classes that are applied throughout the component library as well as adopting products creating their own style, components, and layout.

Follow the checklist items below to trace breaking changes relative to your team’s implementation.

Color

Background Color

MDS-3240 PR-663 Renamed background color constant names.

v1 Constant
v2 Constant

$mds-background-color-default

$mds-background-color-white

$mds-background-color-light

$mds-background-color-light-gray

$mds-background-color-dark

$mds-background-color-dark-gray

MDS-3920 PR-676 Renamed background and container class names.

v1 Class
v2 Class

.mds-container--default

.mds-container--white

.mds-container--light

.mds-container--light-gray

.mds-container--dark

.mds-container--dark-gray

.mds-background--default

.mds-background--white

.mds-background--light

.mds-background--light-gray

.mds-background--dark

.mds-background--dark-gray

Visualization Color

MDS-3839 PR-659 Altered tense of asset allocation color constants.
MDS-3006 PR-611 Renamed Asset Allocation colors and removed $mds-visualization-color-asset-allocation-non-local-stocks.

v1 Constant
v2 Constant

$mds-visualization-color-asset-allocation-stocks

$mds-visualization-color-asset-allocation-equity

$mds-visualization-color-asset-allocation-real-estate

$mds-visualization-color-asset-allocation-alternative

$mds-visualization-color-asset-allocation-bonds

$mds-visualization-color-asset-allocation-fixed-income

Feedback Color

MDS-3681 PR-643 Updated the error text colors on light and dark backgrounds.

MDS-3898 PR-674 Removed feedback constants in background color group.

v1 Constant
v2 Constant

$mds-background-feedback-color-error

$mds-feedback-color-error

$mds-background-feedback-color-warning

$mds-feedback-color-warning

Text Color

MDS-4233 PR-731 Removed mds-disabled-text() mixin.

Typography

MDS-2685 PR-629 Removed deprecated typography constants.

MDS-3435 PR-641 Removed text anchor class.

MDS-3893 PR-672 Removed text coloring mixin from typography mixins applied for headings and body text.

In MDS version 1.x, the mds-level-2-heading() mixin included a reference to the mds-text-color-primary() mixin.

[.your-custom-css-rule-using-v1] {
    @include mds-level-2-heading(); // includes text coloring
}

In MDS version 2, the mds-level-2-heading() mixin does not reference the mds-text-color-primary() mixin, which therefore must be invoked separately.

[.your-custom-css-rule-using-v2] {
    @include mds-level-2-heading(); // omits text coloring
    @include mds-text-color-primary();
}

MDS-3376 PR-597 Removed support for documentation site-specific long from text.

Iconography

MDS-3327 PR-667 Updated the names of, revised the design of, and removed icons.

v1 Icon Name
v2 Icon Name

person-add

person-plus

person-add--s

person-plus--s

filter

funnel

filter--s

funnel--s

object-add

object-plus

clock-revert

clock-back

Layering

MDS-3392 PR-650 Renamed overlay modifier class and adjusted overlay opacity.

Space

MDS-2901 PR-606 Removed deprecated space constants based on T-Shirt sizings (S, M, L).

MDS-4016 PR-716 Removed border-box reset from the mds-accessibility-hidden() mixin.

Mixins

MDS-3432 PR-620 Prefixed all MDS style mixins with mds-.

v1 Mixin Name
v2 Mixin Name

border-box()

mds-border-box()

disabled()

mds-disabled()

opposite-direction()

mds-opposite-direction()

tail()

mds-tail()

bubble()

mds-bubble()

bubble-positioner()

mds-bubble-positioner()

incremental-spacing()

mds-incremental-spacing()

incremental-font-sizes()

mds-incremental-font-sizes()

icon-height-removal()

mds-icon-height-removal()

level-1-heading()

mds-level-1-heading()

level-2-heading()

mds-level-2-heading()

level-3-heading()

mds-level-3-heading()

level-4-heading()

mds-level-4-heading()

level-5-heading()

mds-level-5-heading()

level-6-heading()

mds-level-6-heading()

eyebrow-heading()

mds-eyebrow-heading()

MDS-3432 PR-620 Removed the clearfix() mixin.

Step 3: UI Component Checklist

When upgrading UI components, teams have two options:

  • Upgrade existing HTML markup on a per-component basis as detailed in this section.
  • Upgrade to MDS web components when available. MDS web components are Custom Elements that internalize HTML markup within each component, which greatly streamlines integration and maintenance. Currently only a subset of UI components are have been released as web components. See the Component Status page for details on availability.

These approaches are not mutually-exclusive. Adoption of MDS web components may be done gradually on a per-component basis as new web components become available.

Alert

MDS-4090 PR-733 Updated Alert markup to improve out-of-the-box accessibility of the component.

Alert markup in 1.x:

...
<div class="mds-alert__content">
    <h4 class="mds-alert__title">[Alert Title]</h4>
    ...

Alert markup in 2.x:

...
<aside class="mds-alert__content">
    <strong class="mds-alert__title">[Alert Title]</strong>
    ...

Button

MDS-3363 PR-618 Removed button styling support for div and span.

MDS-2679 PR-652 Removed deprecated flat button.

MDS-2354 PR-681 Adjust button icon size to properly show the correct medium icon for large and medium size flat buttons.

Card

MDS-3433 PR-625 Removed card focus mixin.

MDS-4090 PR-733 Updated Card title markup to improve out-of-the-box accessibility of the component.

Card markup in 1.x:

...
<div class="mds-card__title"> Core Bond Funds </div>
...

Card markup in 2.x:

...
<h2 class="mds-card__title"> Core Bond Funds </h2>
...

Combo Box

MDS-3628 PR-658 Removed combo box max width.

MDS-3671 PR-695 Standardized height of small, medium, and large combo boxes.

Data Table

MDS-3477 PR-616 Removed data table bottom margin spacing.

MDS-3525 PR-623 Vertically aligned column headers to bottom of header cell.

MDS-3668 PR-689 Adjusted vertical spacing of text included within the Data Table component.

Dialog

MDS-3406 PR-630 Applied dialog max width of 350px and added a width: 100% rule to account for responsiveness.
MDS-3392 PR-650 Refactored Dialog class names and styling.

Forms

MDS-3878 PR-664 Removed bottom margin from all form elements.

MDS-3821 PR-651 Added distinct required field indicator color on dark backgrounds.

MDS-2908 PR-627 Removed form field max widths.

MDS-2680 PR-635 Added field group wrapper to checkboxes and radios.

MDS-3303 PR-660 Separated form Sass into separate files by element type.

MDS-2681 PR-621 Removed Select disabled modifier class.

MDS-3829 PR-669 Adjusted the size of many form elements, including checkbox, input, label, radio button, select, and textarea, to align with each other and other MDS components across the library, including changes to font-weight, line-height, and font sizes applied across small, medium and large component sizes.

MDS-3670 PR-695 Standardized heights of small, medium, and large form inputs and selects.

List Group

MDS-3305 PR-602 Added sizing features and support for icons per item. Removed and renamed element and modifier classes across many features including toggling and highlighting a selected item.

v1 Class
v2 Class

.mds-list-group__item--highlighted

.mds-list-group__item--active

.mds-list-group__sublist-toggle-input

.mds-list-group__toggle-input

.mds-list-group__sublist-toggle

.mds-list-group__toggle

.mds-list-group__sublist-toggle-icon

.mds-list-group__toggle-icon

.mds-list-group__sublist-toggle-text

.mds-list-group__toggle-text

.mds-list-group__link-left-icon

.mds-list-group__left-icon

.mds-list-group__item-label

.mds-list-group__item-text

MDS-3667 PR-688 Adjusted vertical spacing of text included within the List Group component.

MDS-4108 PR-722 Removed duplicative mds-list-group__link-icon class.

Masthead

MDS-2679 PR-652 Revised Masthead support to depend upon current Flat button.

MDS-3704 PR-683 Corrected the paired display of icon and label within the selected item of a list group item within a menu.

MDS-4090 PR-733 Updated Menu markup to improve out-of-the-box accessibility of the component.

Menu markup in 1.x:

...
<div class="mds-popover mds-popover--width-200px" role="tooltip">
    <header class="mds-popover__header">
        <h3 class="mds-popover__title"> Workbook </h3>
        ...

Menu markup in 2.x:

...
<section class="mds-popover mds-popover--width-200px" role="tooltip">
    <header class="mds-popover__header">
        <h2 class="mds-popover__title"> Workbook </h2>
        ...

MDS-3840 PR-685 Removed default modal dimensions and t-shirt sizes available from modals and updated MDS doc site demonstration displays and scripting to reflect less opinionated sizing.

MDS-4250 PR-730 Renamed mds-modal__body class to mds-modal__content and removed font style properties.

MDS-4302 PR-742 Removed the Navigation Container's default background color.

Notification

MDS-3362 PR-680 Removed the deprecated version of Notification, promoting “Notification Enhanced” (released previously) to be the default Notification component.

MDS-4090 PR-733 Updated Notification title markup to improve out-of-the-box accessibility of the component.

Notification markup in 1.x:

...
<h4 class="mds-notification-enhanced__title">[Notification Title]</h4>
...

Notification markup in 2.x:

...
<strong class="mds-notification__title">[Notification Title]</strong>
...

Pagination

MDS-3649 PR-614 Removed Pagination bottom margin spacing.

MDS-3666 PR-687 Adjusted vertical spacing of text included within the Pagination component.

Popover

MDS-2679 PR-652 Revised Popover support to depend upon current Flat button.

MDS-2684 PR-677 Removed default t-shirt sizes used to specify Popover width, and renamed the referenced trigger.

MDS-3433 PR-625 Removed support for the mds-popover-pseudo-pad() mixin.

MDS-4250 PR-730 Removed the mds-popover__paragraph class and removed font style properties from the mds-popover__content class.

MDS-4090 PR-733 Updated Popover markup to improve out-of-the-box accessibility of the component.

Popover markup in 1.x:

...
<div class="mds-popover mds-popover--width-200px" role="tooltip">
    <header class="mds-popover__header">
        <h3 class="mds-popover__title"> Workbook </h3>
        ...

Popover markup in 2.x:

...
<section class="mds-popover mds-popover--width-200px" role="tooltip">
    <header class="mds-popover__header">
        <h2 class="mds-popover__title"> Workbook </h2>
        ...

Range Slider

MDS-3878 PR-668 Revised Range Slider bottom padding.

Search Fields

MDS-3672 PR-695 Standardized height of small, medium, and large search fields.

MDS-3433 PR-625 Removed Site Navigation-specific mixins, integrating styling directly into CSS rules.

MDS-2679 PR-652 Revised Site Navigation support to depend upon current Flat button.

Switch

MDS-2682 PR-626 Renamed modifier class for hiding labels.

Namespacing MDS Styles

The Morningstar Design System uses SemVer versioning to signal that major versions of the system are not backwards compatible. To use multiple versions of MDS within the same application, style references can optionally be namespaced to specify the major MDS version used by specific components. For example, this makes it possible to upgrade specific components to take advantage of new functionality, while other components continue to use the older version.

Considerations

When namespacing styles, the following should be taken into consideration:

  • If using MDS HTML components, product teams need to update the HTML markup for each component instance they want to namespace. This may add to the cost of ongoing maintenance.

  • If using MDS Web Components, the logic to support namespacing is internalized within each component, and can be enabled by setting a property on the component instance. This approach streamlines implementation and maintenance because each component automatically resolves to the proper namespaced version.

  • Loading multiple major versions of MDS on the same page may cause performance concerns. Before implementing this approach, consider if loading multiple major versions of the MDS library on the same page is necessary.

  • Namespacing is optional, and only need be enabled on the specific components instances that need it. For example if you want to selectively upgrade buttons to a newer MDS version, or only upgrade components on specific pages within an application, all other components instances can be left as is. Style references that are not namespaced to a specific major version will default to the current installed MDS version.

Styles

These instructions assume MDS has already been installed in the product. If not, please follow the installation instructions before proceeding.

CSS

Beginning with MDS version 2.20.0, MDS includes a namespaced CSS file in addition to the standard compiled MDS CSS file. The file is named mds.v2.css and can be found at /dist/mds.v2.css in the MDS npm package.

  1. To take advantage of namespacing, load mds.v2.css in the application in addition to loading the standard mds.css before updating the markup files to make use of the namespaced styles. (Both versions are required to ensure support for both namespaced and non-namespaced components; specific requirements may vary by application.)

SCSS

If an application team is compiling the MDS SCSS files at built time, developers on that team will need to add the namespace at compile time. If using the MDS Web Components the namespace value needs to be set to mds-v[current major version of MDS] (e.g. for version 2.x.x, the value will be mds-v2).

Depending on the method used to compile SCSS to CSS, several solutions are already available:

HTML Markup

If using MDS HTML markup, developers will need to update MDS classnames to reference the namespaced version as shown in the following example:

Regular MDS HTML Component (Namespacing Not Used)

<button class="mds-button mds-button--primary" type="button">My Button</button>

Namespaced Component

// Set constant to manage MDS version (do this in a central location)
const namespace = "mds-v2";
// Update MDS HTML Component instance to use namespaced style
<button class="${namespace}-button ${namespace}-button--primary" type="button">My Button</button>
  • To streamline maintenance, the MDS namespace should be stored as a constant in a central location.
  • If the application is leveraging the namespaced CSS file provided with MDS, the value that should be stored will be mds-v[current major version of MDS] (e.g. for version 2.x.x, the value will be mds-v2).
  • If the application team chooses to compile the SCSS files, the value will be determined by whatever namespace was decided on by the application team.

Web Components

MDS web components provide built-in namespacing functionality. Web components will always be namespaced to the major version of MDS that matches the internal component template to ensure the correct style versions are used. To namespace a web component enable the Boolean prop namespaced on the component.

Regular MDS Web Component (Namespacing Not Used)

<mds-button>My Button</mds-button>

Namespaced MDS Web Component

`<mds-button namespaced>My Button</mds-button>`
©2019 Morningstar, Inc. All rights reserved. Terms of Use