MDS styles and icons must be loaded into the DOM on every page where they are used. Additionally, to make use of MDS web components the required JavaScript files must also be available.

Styles

Styles are loaded by compiling MDS SCSS files together with your own product SCSS. Using SCSS is required to ensure access to all MDS constants and mixins, which are essential to implementing MDS.

Compiling SCSS

Use MDS SCSS files to mix MDS constants, mixins, and components with your own product’s SCSS files. This approach requires an SCSS compiler.

In the NPM package these files are found at:

/constants/constants.scss
/components/[component_name]/[component].scss
/visual-language/[file_name].scss
/utils/[file_name].scss

Importing SCSS

You can @import individual MDS component SCSS files as needed. Each component’s SCSS file will automatically include all necessary dependencies. For example, if your project needs MDS form elements and buttons, include:

To include all MDS constants, utilities, and visual langauge mixins:

To include all MDS UI components:

Font Asset Path

By default, MDS SCSS expects font files to be located at ../fonts. When compiling CSS in your product, place it in a directory at the same level as the directory containing the MDS fonts, for example:

Alternately, you may override the default font asset path by setting the $mds-font-asset-path variable before importing MDS fonts, for example:

SCSS Post Processing

MDS optimizes for performance and widens browser support using two CSS post processors: CleanCSS and AutoPrefixer. If you’re compiling MDS SCSS files, add these post processors to your build toolchain to comply with MDS’ browser support and performance requirements.

AutoPrefixer Config

CleanCSS Config

Precompiled CSS

As an alternative to using the component SCSS files, MDS also ships a pre-compiled CSS file containing all UI component styles. Include these styles in your product by adding a link to the mds.css file in your HTML. If using the compiled CSS file or the CDN for component styles, you still need to import the constants, utils, and visual language SCSS files to ensure you have access to all MDS assets.

In the NPM package this file is found at: /dist/mds.css

Font Path

The mds.css file expects the MDS font files to be located at ../fonts. When adding mds.css to your product, place it in a directory at the same level as the directory containing the MDS fonts, for example:

Using MDS CDN

As alternative to NPM, you can load MDS styles externally by using Morningstar’s CDN service. Please note each major version of MDS has a different file path.

MDS v2

2.36.0 latest published on CDN

<link rel="stylesheet" href="https://mwc-cdn.morningstar.com/mc/morningstar-design-system/[version_number]/dist/mds.css">

MDS v1

1.16.0 latest published on CDN

<link rel="stylesheet" href="https://mwc-cdn.morningstar.com/mc/morningstar-design-system/[version_number]/dist/docs/assets/styles/mds_library.css">

• Update [version_number] in the URL address to reflect the version of MDS you would like to load.

Icons

The MDS icon sprite (mds.svg) must be injected into any page where MDS components containing icons are used. To avoid triggering a console warning, the icon sprite container must have an id of mds-svg-icons.

There are multiple ways to inject the icon sprite into your page:

• Render the SVG sprite content inline into the HTML template before the page is rendered in the browser.

• Load the SVG sprite file via an HTTPRequest and then inject the content into the DOM. This method comes with a performance cost of an additional request to load the file.

• Load the SVG sprite content inline using Webpack and the SVG Inline Loader plugin.

• If you are using a framework cli you may need to override the default svg loading mechanism. For example in vue-cli:

JavaScript

Before using MDS Web Components, the required JS files must be added to the DOM. MDS Web Components can be consumed as one ES5 bundle, or individual ES6 modules.

ES6 Modules

For better performance and control over which parts of MDS are being loaded, you can include individual components as ES6 modules into your project files.

In the NPM package these files are found at:

/components/[component_name]/[component].js
/behaviors/[file_name].js

For example, if your project only needs MDS Buttons, include:

Note: Consuming MDS web components as ES6 modules will require a transpilation step in your build process and additional polyfills to account for ES6 functionality that is not yet supported by all browsers.

Babel provides useful guides on how to setup transpilation for different build tools available.

ES5 Bundle

The ES5 MDS web components bundle contains all available MDS web components, as well as necessary polyfills for IE11 support. Add the file to the bottom of your pages using a script tag.

In the NPM package this file is found at: /dist/mds.es5.js

Favicons

MDS includes a set of favicon images to support the broad needs of browsers and mobile operating systems. In addition to the standard browser support, these assets will provide a solution for Morningstar URLs saved as home screen tiles on iOS and Android, as well as URLs pinned within the Windows operating system.

Implementation

Favicon assets can be found in the MDS NPM package at:

/favicons

Follow these steps to implement the favicons in your product:

1. Import the favicon image assets in to your prouduct out of the NPM package. Note: The favicon.ico file must be placed at your site’s root, even if you choose to store the other favicon assets in another directory.
2. Update your HTML to include the necessary references in the <head>
3. Create the site.webmanifest and browserconfig.xml files in your product. Note: The browserconfig.xml file must be placed at your site’s root.

HTML Favicon References

Use this code snippet to include the necessary favicon references in the <head> section of your HTML:

• Update the path/to references to reflect where you store the image assets.

Web Manifest File

Chrome for Android uses uses a Web App Manifest file to provide references to the necessary image files.

Create the site.webmanifest file in your product using the code snippet below. If your product already uses a .webmanifest file, you only need to include the "icons" object.

• Update the path/to references to reflect where you store the image assets.

Browserconfig File

Windows 8 and 10 uses a browserconfig.xml file at the root of your site to provide references to the necessary image file.

Create the browserconfig.xml file in your product using the code snippet below:

• Update the path/to references to reflect where you store the image assets.

Cache Busting

Favicon artwork can be difficult to clear from a browser’s cache. Consider implementing a cache busting technique to facilitate future updates to the favicon artwork. One method is to include a versioned URL parameter that you can update to force a cache clear for the image. For example:

<link rel="icon" type="image/png" sizes="32x32" href="path/to/favicon-32x32.png&v=[version_number]">

Updating the [version_number] in the path above to a new value will force a cache clear.