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.

Version 2 Highlights
Planning an Upgrade
How to Upgrade, Per Feature
Step #1: Installing and Packaging
Step #2: Visual Language Checklist
Step #3: UI Components Checklist

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.

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.

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:

Review this Upgrade Guide.
Discuss potential design impacts with UX and visual designer(s) on the team.
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.
Run automated test(s) such as automated visual regression, if your team employs such tools.
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

In your project's package.json, change the version of morningstar-design-system to ^2.0.0. Use the caret as shown to ensure the most recent minor version is automatically used. If it exists, remove the package-lock.json file to force npm to pull in the latest version of MDS. Run npm install. Update paths to assets your product uses:

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/*

If using SCSS, update SCSS import paths:

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

If compiling SCSS, add CleanCSS and AutoPrefixer to your build toolchain.

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.

Revise applied constants including:

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.

Revise applied classes including:

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.

Replace any references to $mds-visualization-color-asset-allocation-non-local-stocks with a custom style in your product, following asset allocation tinting guidelines. Revise applied constants including:

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.

Review application of $mds-text-color-error-default, $mds-text-color-error-on-light, $mds-text-color-error-on-dark to ensure the change doesn’t degrade visual display.

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

Revise applied constants including:

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.

Replace any instances of the mds-disabled-text() mixin with the $mds-opacity-disabled constant.

Typography

MDS-2685 PR-629 Removed deprecated typography constants.

Replace references to $mds-font-size-base and $mds-font-size-default with $mds-font-size-m.

MDS-3435 PR-641 Removed text anchor class.

Remove references to CSS classes beginning with mds-text-anchor.

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

To sustain text coloring as achieved in v1, add the mds-text-color-primary() mixin in every location where the following mixins are invoked: mds-level-1-heading(), mds-level-2-heading(), mds-level-3-heading(), mds-level-4-heading(), mds-level-5-heading(), mds-level-6-heading(), mds-eyebrow-heading(), mds-body-text-l(), mds-body-text-m(), and mds-body-text-s().

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.

Correct for impacts to styling of elements referring to mds-doc-long-form-text classes.

Iconography

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

Remove references to the following icons: asterisk, asterisk--s, esg-globe, morningstar-logo. For appropriate alternatives, contact the MDS team. Update references to the following 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.

Replace the mds-overlay--active class with the mds-overlay--fadeout when applying an overlay.

Space

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

Replace references to T-Shirt constants (such as $mds-space-inset-m) with proportional constants (such as $mds-space-inset-1x), based on constants documented on the Space page.

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

Review use of mds-accessibility-hidden() mixin to ensure change had no visible impacts.

Mixins

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

Revise applied mixins by name including:

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.

Replace any use of the clearfix() mixin with CSS in your product.

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.

Update the markup of any implemented Alerts to use aside and strong instead of div and h4.

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.

Replace div and span elements applying mds-button class with supported element types such as button, input or a.

MDS-2679 PR-652 Removed deprecated flat button.

Replace use of mds-button--flat-no-background with mds-button--flat. Review visual style where mds-button--flat is used, since this class was used for the deprecated flat button design but now applies the revised, enhanced flat button design.

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

Review adjusted icon sizing within large- and medium-sized flat buttons doesn’t degrade visual display.

Card

MDS-3433 PR-625 Removed card focus mixin.

Remove dependency on the mds-card-focus-outline() mixin. Instead, hard code the mixin and/or properties in your product.

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

Update the markup of any implemented Card titles to use h2 instead of div.

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.

Review use of Combo Box, ensuring that a lack of max width doesn’t degrade visual display.

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

Review use of all combo boxes, ensuring that adjusted heights don’t degrade visual display.

Data Table

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

Review Data Table spacing to ensure removed bottom margin doesn’t degrade visual display. Instead, add Space constants to achieve a consistent component bottom margin.

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

Review column header vertical alignment doesn’t degrade visual display.

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

Review that adjusted spacing above and below text in data tables doesn’t degrade visual display.

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.

Review use of Dialog, ensuring the new default max-width doesn’t degrade visual display. Replace use of mds-dialog--popup modifier class with mds-dialog--active class. Replace use of mds-dialog-popup-container class with mds-dialog-wrapper class. Replace use of mds-dialog-popup-container__overlay class with mds-overlay class. Apply .mds-dialog--width-500px modifier class in conditions where a wide dialog is appropriate. Apply .mds-dialog__cancel-button and/or mds-dialog__reject-button element classes to buttons included in a dialog. Wrap Dialog content in a div instead of span element.

Forms

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

Review form layouts to ensure removed bottom margin doesn’t degrade visual display.

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

Review required field indicators to ensure proper visual display.

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

Review use of all form elements, ensuring that a lack of max-width doesn’t degrade visual display.

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

Wrap all radio button and checkbox groups with a field group wrapper.

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

Update use of form Sass files to refer to files corresponding to form elements in use.

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

Remove use of mds-form-select__input--disabled 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.

Review use of all form elements, ensuring that adjusted line height, font-weight, and other sizing properties don’t degrade visual display.

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

Review use of all form inputs and selects, ensuring that adjusted heights don’t degrade visual display.

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.

Wrap metadata block inside a mds-list-group__item-text element. Revise applied classes including:

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.

Review that adjusted spacing above and below text in list groups doesn’t degrade visual display.

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

Replace all instances of class mds-list-group__link-icon with mds-list-group__active-icon.

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

Revise references in implemented Mastheads from mds-button--flat-no-background to mds-button--flat.

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

Review the icon display of indicating a selected item to ensure it doesn’t overlap within existing menus.

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

Update the markup of any implemented Menus to use section, header, and h2 instead of div, header, and h3.

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.

Remove references to existing modal sizing properties, size modals as needed with your product, and ensure that the modal layout isn’t degraded.

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

Replace all instances of mds-modal__body with mds-modal__content. Correct for impacts to styling of elements contained within the mds-modal__body element.

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

Update all instances of Navigation Containers to include a container class to set the background color.

Notification

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

Migrate uses of the deprecated notification to use the v2 version of the component. Remove -enhanced from existing markup of the “Notification Enhanced” component to correspond to the promoted v2.x version of the component.

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

Update the markup of any implemented Notification titles to use strong instead of h4.

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.

Review Pagination spacing to ensure removed bottom margin doesn’t degrade visual display. Instead, use Space constants to apply consistent component bottom margin.

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

Review that adjusted spacing above and below text in pagination doesn’t degrade visual display.

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

Revise references in implemented Popovers from mds-button--flat-no-background to mds-button--flat.

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

Remove dependence on modifier classes of mds-popover--sticky, mds-popover--width-s, mds-popover--width-m, mds-popover--width-l, mds-popover--width-xl. Instead, use modifier classes indicating the specific width such as those ending in --200px, --300px, or --500px. Rename the triggering element from the mds-popover__target to mds-popover__trigger class.

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

Replace use of the mds-popover-pseudo-pad() mixin with hard-coded CSS properties applied to :before and :after elements.

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

Replace all instances of mds-popover__paragraph with a custom class in your product. Correct for impacts to styling of elements contained within the mds-popover__content element.

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

Update the markup of any implemented Popovers to use section, header, and h2 instead of div, header, and h3.

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.

Review Range Slider spacing to ensure updated padding doesn’t degrade visual display.

Search Fields

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

Review use of all search fields, ensuring that adjusted heights don’t degrade visual display.

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

Replace use of the mds-site-navigation-medium-button() and mds-site-navigation-large-button() mixins with hard-coded CSS properties.

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

Revise references in implemented Site Navigation from mds-button--flat-no-background to mds-button--flat.

Switch

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

Revise references in Range Slider from mds-switch--standalone to mds-switch--hide-label.

Link Template