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.

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.