You are viewing legacy documentation. View the most recent documentation.

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.



  • 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.


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


<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">
        <use xlink:href="/icons/mds.svg#caret-right--s"></use>

Example #3: Complicated Components

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


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

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.


  • 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.


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.


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.


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



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.



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.



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.


Forms > Select (Dropdown)

MDS no longer styles the Menu available in a Dropdown. However, Menu items in a Combo Box are styled.


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.


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.



MDS adds support for Without Label and vertical Switch Groups.



MDS adds With Labels and No Arrows variations.


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.


List Groups

In MDS, use List Groups for Tabs.





Prompts are a variation of the MDS Tooltips component.


Not supported

MDS excludes the Flag. As a chart-specific Tooltip variation, this styling is now handled by Morningstar Base Charts.



MDS adds With Close Icon, No Header, and Action Required variations.



MDS changes “Undo” action to a secondary Button. MDS adds a Default variation lacking an action.



MDS adds variations of no primary action (Default), With Third Action, and With Input.



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.


Not supported

While MDS offers Constants and other elements to construct panels easily, the system no longer supports this specific component display.


Data Tables

MDS adds a Tree Table variation. MDS alters the visual display of a selected column.



MDS also offers a mds-link() mixin.



MDS Loaders have a more refined/styled animation applied and 3 size options: s, m, l.


Not supported

MDS excludes Breadcrumbs. Instead, use MDS Links.


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.


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.


Not supported

MDS excludes MUI-B Scaffolding. Instead, apply this visual style using Constants.



Refer to MDS Space conventions and mixins for properly applying space to custom components and layouts.

©2020 Morningstar, Inc. All rights reserved. Terms of Use