MUI-B to MDS Migration Guide

While the MUI-B and MDS UI libraries appear to be similar, they are significantly different in terms of design, code, and supported features. Use this guide to understand the differences and plan your migration to MDS.

Some key things to consider when migrating to MDS:

Different HTML Markup & CSS Code: MDS is built bespoke using custom markup and the BEM CSS methodology. Migrating to MDS will require refactoring CSS dependencies and updating markup.
New Visual Language: MDS establishes a new visual language foundation, with new neutral, interactive, and background colors, and new approaches to space and iconography. Only typography is very similar.
Accessible UI Components: MDS improves accessibility and features within the MUI-B UI components that are approved for use in future development and retires other components.

Code

CSS

MDS UI components use the BEM CSS methodology to apply class names for component Blocks (mds-button), Elements within blocks (mds-button__icon), and scenario-specific Modifiers (mds-button--primary).
MDS prepends UI component classes with mds- to prevent collisions with other libraries and CSS within an HTML page.

HTML Markup

Example #1: Single Element Components

For simple components like a button or text box, HTML markup updates may be limited.

In MUI-B:

<button class="btn btn-primary"> Button Text </button>

In MDS:

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

Example #2: Multi-Element Components

For components that include multiple elements like icons, expect to update HTML markup predictably to apply MDS features.

In MUI-B, where an icon is added via a class:

<button class="btn btn-default btn-menu"> Continue </button>

In MDS, where an icon is added via <svg> markup:

<button class="mds-button mds-button--primary" type="button" role="button">
    <span class="mds-button__text"> Continue </span>
    <svg class="mds-icon mds-button__icon mds-button__icon--right" aria-labelledby="title">
        <title>caret-right--s</title>
        <use xlink:href="/icons/mds.svg#caret-right--s"></use>
    </svg>
</button>

Example #3: Complicated Components

For more components with many elements, expect to make considerable changes to HTML markup.

In MUI-B:

<div class="modal-dialog" role="document">
    <div class="modal-content">
        <div class="modal-body">Turning off logic mode will remove all parentheses and change the connection between all widgets back to &#34;and&#34;. Are you sure want to proceed? </div>
        <div class="modal-footer">
            <button class="btn btn-default" type="button" data-dismiss="modal"> Cancel </button>
            <button class="btn btn-primary" type="button"> Continue </button>
        </div>
    </div>
</div>

In MDS:

<div class="mds-dialog ">
    <span class="mds-dialog__message">Turning off logic mode will remove all parentheses and change the connection between all widgets back to &#34;and&#34;. Are you sure want to proceed?</span>
    <div class="mds-dialog__action-buttons">
        <div class="mds-dialog__cancel-resolve-buttons-holder">
            <button class="mds-button mds-dialog__cancel-button" type="button" role="button"> Cancel </button>
            <button class="mds-button mds-dialog__resolve-button mds-button--primary" type="button" role="button"> Continue </button>
        </div>
    </div>
</div>

Visual Language

While MUI-B and MDS appear nearly identical at first glance, the MDS library changes a considerable number of visual language fundamentals in order to provide a more accessible and refined visual language.

Color

New Neutrals: While MUI-B and MDS apply neutrals similarly, MDS pared down the number of available neutrals, changed the HEX values for some, and applied neutrals far more systematically to text color, background color, and border colors. For more detail, refer to Color documentation.
New Interactive Blue: In order to meet accessibility criteria, the cyan blue of MUI-B was retired in favor of a darker MDS interactive blue that’s applied to components like Links, Buttons, and Forms.

Typography

Header and body typography remain consistent across the two libraries. However, MDS does not directly apply heading styles to header tags, such as <h1>. Instead, MDS offers mixins for your use as you build your own components. For more detail, refer to Typography documentation.

Icons

While MUI-B used an ic- appended class attribute to apply an icon to a pseudo ::before element, MDS uses a modern SVG implementation that applies icons via markup, while leveraging Svg4everybody to ensure legacy browser support. For more detail, refer to Iconography documentation.

Space

MDS uses a custom system of space for applying padding and margins within and between components. For more detail, refer to Space documentation.

Components

Accessibility

MDS now adheres to the World Wide Web Consortium’s (W3C) Web Content Accessibility Guidelines (WCAG 2.0) to ensure our components are perceivable, operable, understandable, and robust. This includes:

Reusable color pairings that always meet contrast requirements.
Components that facilitate and often enhance the use of assistive technologies.
Full control of components with a keyboard or other input device.
Text-based alternatives for all non-text content, such as images, videos, and icons.

For more detail, refer to Accessibility documentation.

Mapping from MUI-B to MDS

For teams familiar with the MUI-B, the following list compares every MUI-B component with available MDS alternatives, additional considerations and features offered by MDS.

MUI-B	MDS	Considerations
Lists	List Group	MDS adds group Headings, Subsections, and Metadata. MDS wraps `<a>` tags around List Group items to enable and style interactions within navigation Menus.
Buttons	Buttons	MDS significantly alters the primary Button’s interactive blue color. MDS adds Flat, With Icon, and Icon Only variations.
Button Groups	Button Groups	MDS adds Full Width, With Icon, and Icon Only variations. MDS adds a flex-box display for cases where Button label content may overflow.
Text Inputs	Forms > Text Box	MDS offers modifier classes for large and small inputs. MDS adds a halo drop shadow for the focus state.
Dropdowns	Forms > Select (Dropdown)	MDS no longer styles the Menu available in a Dropdown. However, Menu items in a Combo Box are styled.
Combo-box	Combo Boxes	MDS and MUI-B combo boxes both use select2 JavaScript for interaction and search. MDS adds a more pronounced halo drop shadow for the focus state.
Radio Buttons	Forms > Radio Button	MDS adds separate support for Radio Group. MDS no longer uses icons to render the element.
Checkboxes	Forms > Checkbox	MDS Checkboxes are squared, not rounded as in MUI-B. MDS only uses an icon for the check itself and uses CSS to render the outer box containing the check-mark graphic.
Switches	Switches	MDS adds support for Without Label and vertical Switch Groups.
Pagination	Pagination	MDS adds With Labels and No Arrows variations.
Slider	Range Sliders	MDS adds associated textbox inputs for Single Selection and Range Selection variations.
Search Fields	Search Fields	MDS reduces the number of size options from 5 to 3: s, default, m, l, xl → s, m (default), l.
Tabs	List Groups	In MDS, use List Groups for Tabs.
Tooltips	Tooltips
Prompts	Tooltips	Prompts are a variation of the MDS Tooltips component.
Flags	Not supported	MDS excludes the Flag. As a chart-specific Tooltip variation, this styling is now handled by Morningstar Base Charts.
Popovers	Popovers	MDS adds With Close Icon, No Header, and Action Required variations.
Notifications	Notifications	MDS changes “Undo” action to a secondary Button. MDS adds a Default variation lacking an action.
Dialogs	Dialogs	MDS adds variations of no primary action (Default), With Third Action, and With Input.
Modals	Modals	MDS adds icon-only Buttons for actions in the upper right of the Modal. MDS adds a No Title variation. MDS adds three standard widths for Modals.
Panels	Not supported	While MDS offers Constants and other elements to construct panels easily, the system no longer supports this specific component display.
Tables	Data Tables	MDS adds a Tree Table variation. MDS alters the visual display of a selected column.
Links	Links	MDS also offers a `mds-link()` mixin.
Loaders	Loaders	MDS Loaders have a more refined/styled animation applied and 3 size options: s, m, l.
Breadcrumbs	Not supported	MDS excludes Breadcrumbs. Instead, use MDS Links.
Navs	Not supported	MDS excludes Navs. Instead, use icon-only Button variation, using icons `caret-circle-left` and `caret-circle-right`.
Progress Bar	Not supported	MDS currently excludes the MUI Progress Bar since that component was incomplete. Progress Bars may be prioritized in future MDS work.
Wells	Not supported	MDS excludes Wells, which was was not used in any product. Similar to Panels, apply MDS visual style to create Wells using MDS Constants.
Scaffolding	Not supported	MDS excludes MUI-B Scaffolding. Instead, apply this visual style using Constants.
Utilities	Space	Refer to MDS Space conventions and mixins for properly applying space to custom components and layouts.

Link Template