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

Styles

Styles can be loaded using the compiled CSS file provided with MDS, or by compiling MDS source SCSS files together with your own product SCSS.

Using CSS

The easiest way to include MDS styles is by adding a link to the compiled mds.css file:

<link rel="stylesheet" href="/path/to/mds.css">

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

Font Paths

mds.css 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:

Using MDS CDN

As alternative to NPM, you can load MDS styles externally by using Morningstar’s CDN service:

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

MDS v2

2.26.0 latest published on CDN

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

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

• Please note each major version of MDS has a different file path.

Using SCSS

Use MDS source SCSS files to mix MDS constants, mixins and components with your own product‘s SCSS files. This approach requires a SCSS compiler to ensure support for MDS constants.

Importing SCSS

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

To include all MDS components using full NPM package paths:

Font Asset Path

Override the default font asset path, ../fonts/, as needed by setting the $mds-font-asset-path variable before importing MDS fonts.

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

Configure AutoPrefixer with the following:

CleanCSS Config

Configure CleanCSS with the following:

Icons

The MDS icon sprite (mds.svg) must be injected into any page where MDS web components containing icons are used. Previous implementations of icons in MDS allowed loading of the icon sprite via an external reference, but that method has proved unreliable when used alongside custom elements. To avoid triggering a console warning, the icon sprite container must have an id of mds-svg-icons. There are multiple ways of achieving this:

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

ES5

If using ES5, add the ES5 MDS web components bundle. The bundle contains all available MDS web components, as well as necessary polyfills for IE11 support, and can be added to the bottom of your template using a script tag.

<script src="path/to/mds.es5.js"></script>

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

ES6

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

import MDSButton from ‘node_modules/morningstar-design-system/components/button/button.js

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.