Installing and Integrating MDS

Engineers integrate MDS by installing and configuring NPM dependencies, integrating MDS UI components, and applying MDS visual language.

Installing MDS using Node package management (NPM) is recommended. Alternatively, you can download a ZIP file to install MDS manually.

Using NPM

  1. Add an .npmrc file to your product (or update your existing one) with the following line:

    registry = https://msnexus.morningstar.com/content/repositories/npm-all/

    This will point your product to Morningstar‘s internal NPM server where the latest version of MDS can be retrieved.

  2. Then, install MDS in your product via NPM:

    npm install morningstar-design-system --save

Manual Installation

If you cannot use NPM, install MDS by downloading a ZIP file containing the latest release. This process will be repeated each time you upgrade MDS.

What’s Included

├── behaviors
└── components
    └── button
        ├── button_dependencies.scss
        ├── button_mixins.scss
        ├── button_variables.scss
        ├── button.js
        └── button.scss
├── constants           
├── data
└── dist  
    ├── mds.css
    ├── mds.es5.js
    ├── mds.es5.js.map
    ├── mds.js
    ├── mds.svg
    └── mds.v2.css
├── fonts
├── icons
├── includes
└── styles
    └── visual-language
        ├── borders.scss
        ├── color.scss
        ├── fonts.scss
        ├── layering.scss
        ├── shape.scss      
        ├── size.scss
        ├── space.scss
        └── typography.scss      
 package.json
 README.md

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:

├── fonts
└── styles
    └── mds.css

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.25.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:

/* your-project.scss */
@import 'node_modules/morningstar-design-system/components/form/form';
@import 'node_modules/morningstar-design-system/components/button/button';

To include all MDS components using full NPM package paths:

@import 'node_modules/morningstar-design-system/constants/constants';

@import 'node_modules/morningstar-design-system/styles/utils/accessibility';
@import 'node_modules/morningstar-design-system/styles/utils/import_once';
@import 'node_modules/morningstar-design-system/styles/visual-language/borders';
@import 'node_modules/morningstar-design-system/styles/visual-language/color';
@import 'node_modules/morningstar-design-system/styles/visual-language/fonts';
@import 'node_modules/morningstar-design-system/styles/visual-language/layering';
@import 'node_modules/morningstar-design-system/styles/visual-language/shape';
@import 'node_modules/morningstar-design-system/styles/visual-language/size';
@import 'node_modules/morningstar-design-system/styles/visual-language/space';
@import 'node_modules/morningstar-design-system/styles/visual-language/typography';

@import 'node_modules/morningstar-design-system/components/accordion/accordion';
@import 'node_modules/morningstar-design-system/components/alert/alert';
@import 'node_modules/morningstar-design-system/components/article/article';
@import 'node_modules/morningstar-design-system/components/button/button';
@import 'node_modules/morningstar-design-system/components/button_group/button_group';
@import 'node_modules/morningstar-design-system/components/card/card';
@import 'node_modules/morningstar-design-system/components/combo_box/combo_box';
@import 'node_modules/morningstar-design-system/components/container/container';
@import 'node_modules/morningstar-design-system/components/data_table/data_table';
@import 'node_modules/morningstar-design-system/components/dialog/dialog';
@import 'node_modules/morningstar-design-system/components/exhibit/exhibit';
@import 'node_modules/morningstar-design-system/components/form/form';
@import 'node_modules/morningstar-design-system/components/header/header';
@import 'node_modules/morningstar-design-system/components/icon/icon';
@import 'node_modules/morningstar-design-system/components/layout_grid/layout_grid';
@import 'node_modules/morningstar-design-system/components/link/link';
@import 'node_modules/morningstar-design-system/components/list_group/list_group';
@import 'node_modules/morningstar-design-system/components/loader/loader';
@import 'node_modules/morningstar-design-system/components/masthead/masthead';
@import 'node_modules/morningstar-design-system/components/menu/menu';
@import 'node_modules/morningstar-design-system/components/modal/modal';
@import 'node_modules/morningstar-design-system/components/module_container/module_container';
@import 'node_modules/morningstar-design-system/components/navigation_container/navigation_container';
@import 'node_modules/morningstar-design-system/components/notification/notification';
@import 'node_modules/morningstar-design-system/components/page_shell/page_shell';
@import 'node_modules/morningstar-design-system/components/pagination/pagination';
@import 'node_modules/morningstar-design-system/components/popover/popover';
@import 'node_modules/morningstar-design-system/components/profile_image/profile_image';
@import 'node_modules/morningstar-design-system/components/range_slider/range_slider';
@import 'node_modules/morningstar-design-system/components/search_field/search_field';
@import 'node_modules/morningstar-design-system/components/site_navigation/site_navigation';
@import 'node_modules/morningstar-design-system/components/stepper/stepper';
@import 'node_modules/morningstar-design-system/components/switch/switch';
@import 'node_modules/morningstar-design-system/components/tag/tag';
@import 'node_modules/morningstar-design-system/components/tooltip/tooltip';
@import 'node_modules/morningstar-design-system/components/top_hat/top_hat';

Font Asset Path

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

$mds-font-asset-path: 'my/path/to/fonts/';
@import 'node_modules/morningstar-design-system/styles/visual-language/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:

{
    browsers: ['last 2 versions'],
    grid: true
}
CleanCSS Config

Configure CleanCSS with the following:

{
    level: 2
}

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.
<!-- Sample inline SVG content -->
<span id="mds-svg-icons" style="display: none">
    <?xml version="1.0" encoding="utf-8"?>
    <!--[MDS Icon Sprite Markup]-->
</span>
  • 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.
<!-- Define a hidden container for your SVG content -->
<span id="mds-svg-icons" style="display:none"></span>
<!-- Create an HTTPRequest and inject the content into your SVG container -->
<script>
    var xhr = new XMLHttpRequest();
    xhr.open("GET", "path/to/mds.svg", false);
    xhr.send("");
    document.getElementById("mds-svg-icons").appendChild(xhr.responseXML.documentElement);
</script>
<!-- Define a hidden container for your SVG content in your template -->
<span id="mds-svg-icons" style="display:none"></span>
<!-- Use the inline-svg-loader to load svg file in your script file  -->
<script>
    var mdsSVG = require("svg-inline-loader!./node_modules/morningstar-design-system/dist/mds.svg");

    // Add the SVG as HTML into your template
    document.getElementById("mds-svg-icons").innerHTML = mdsSVG;
</script>
  • If you are using a framework cli you may need to override the default svg loading mechanism. For example in vue-cli:
// Create a vue.config.js file in your root directory and override SVG loader using chainWebpack
module.exports = {
    chainWebpack: config => {
        // remove the default loader
        config.module.rules.delete('svg')
    }
}

// In your Vue template use v-html and the inline svg loader to render the svg as HTML
<span id="mds-svg-icons" style="display:none" v-html="require(`svg-inline-loader!./node_modules/morningstar-design-system/dist/mds.svg`)"></span>

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.

MDS UI Components provide reusable building blocks to deliver web-based user experiences. See the Component Status page for a complete list of available components.

When integrating UI components, product teams can choose from two approaches:

  • Use MDS Web Components

  • Copy and paste HTML markup from the MDS doc site

Both give similar results from the user’s perspective, but differ in the level of supported functionality, and in how adopting teams manage the underlying code. When viewing examples on MDS component pages, you can toggle between HTML and web component markup when available.

Web Components

MDS web components are Custom Elements built to Morningstar’s specific requirements. This approach greatly streamlines integration and maintenance, since the required HTML markup is internalized within each component. Many web components also include built-in support for common interactions and behaviors, which further simplifies implementation. Currently only a subset of UI components have been released as web components. See the Component Status page for details on availability.

To create the same button shown above using the <mds-button> web component, the following markup could be used:

<mds-button icon="open-new--s" variation="primary">My Button</mds-button>

Alternatively, MDS web components can be instantiated via JS:

const myButton = document.createElement("mds-button");
myButton.icon = "open-new--s";
myButton.variation = "primary"
myButton.text = "My Button"
document.body.appendChild(myButton);

With this approach, HTML markup, scripted behaviors, and other interactions can all be internalized within the component. MDS web components are written in vanilla JavaScript for compatibility with React, Vue, and other frameworks.

Configuration

MDS web components are configured via props which can be set via attributes or slots. In all instances, props set via attributes will take precedence over props set via slots.

All available attributes and slots are documented in the component API.

Attributes

MDS web component attributes follow the same name/value pair pattern (e.g., name="value") as regular HTML attributes and can be set using both content or Interface Definition Language (IDL) methods. When setting prop values via content attributes, use kebab-style formatting for multi-word attribute names (e.g., my-long-name="value") and convert values to String type. When using the IDL method, attributes must be set using camel case notation (e.g., mycomponent.myLongName="value") and can reflect many value types not just values of type String.

To configure an MDS web component via attributes, define each attribute you want to set along with its value on the custom element tag:

<!--Using content attributes-->
<mds-button variation="secondary" size="large" text="My Button"></mds-button>
const myButton = document.createElement("mds-button");
// Using IDL attributes
myButton.size = "large";
myButton.variation = "secondary";
myButton.text = "My Button";

Slots

A slot is a placeholder inside of the web component DOM structure which can be filled with additional markup or content. Slot values can be overwritten by prop values in some cases, if a specific prop is assigned to override the slot. To configure an MDS web component via slots, pass your values to the corresponding default or named slots as documented in the component API.

Default Slot

MDS web components with a default slot inject any content between the start and end tags into the defined “slot” area within the component’s template.

<!-- Using default slot to assign button text -->
<mds-button variation=”secondary” size=”large”> My Button</mds-button>

Named Slots

MDS web components with named slots inject any element that contains a slot attribute into the defined “named slot” area within the component’s template.

<!-- Using named optional text slot to assign an optional text to the label element -->
<mds-label for="profession-select" optional="true">
    Profession
    <span slot="optional-text">(Optional)</span>
</mds-label>

HTML Markup

Frontend developers can copy and paste HTML markup directly from MDS component pages. This approach gives developers maximum flexibility to customize the HTML to their needs, but also requires more effort from adopting teams, particularly where maintenance is concerned.

For example, to create a simple button, the following HTML markup can be used:

<button class="mds-button mds-button--primary" type="button">
    <svg class="mds-icon mds-button__icon mds-button__icon--left" aria-hidden="true">
        <use xlink:href="/icons/mds.svg#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text">My Button</span>
</button>

With this approach, while the predefined CSS classes control the design and layout of the componenent, any scripted behaviors or interactions triggered by the component must be handled by the adopting team.

Further Documentation

Product teams can apply MDS Visual Language using MDS constants in combination with mixins. Guidance on mixins is provided on the relevant pages where they are used.

Constants

MDS threads global variables, or Constants, throughout the component library for visual consistency. Use MDS constants as SCSS variables to apply the MDS Visual Language to your product‘s components.

In the NPM package this file is found at: /constants/constants.scss

Overriding MDS Styles

By controlling which SCSS files you @import into your product, product teams can control when and how to override the styles MDS provides. This should be done only when necessary to align with product-specific requirements, and only after other approaches have been considered. Before doing this, consult with your product designer to confirm the override is necessary and consistent with the intent of the design. The MDS team is available to discuss alternative approaches.

  • The product team is responsible for tracking overrides when integrating future updates to MDS.

  • If a specific override is required by multiple product teams, consider making the change and submitting it as a contribution back to MDS.