Morningstar Design System

Installing and Integrating MDS

Overview Using Components

Installing and Integrating MDS

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

Overview Using Components

Overview

Installing MDS

Install MDS using Node package management (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

Manually

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.

Using MDS CDN

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.18.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 CSS

The easiest way to include MDS styles is by adding a link to the precompiled 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 SCSS

Use MDS source SCSS files to mix MDS constants, mixins and components with your own product‘s SCSS files.

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

Overriding MDS Styles with SCSS

By controlling which SCSS files you @import into your product, you can control when and how you override the styles MDS provides. The MDS Core team expects products to override and modify imported SCSS files on an as-needed basis.

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 Compiler

A SCSS compiler is required when using MDS constants. See the Using SCSS section for information about using .scss files in your project.

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
}

Applying Visual Style

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.

  • SCSS variables node_modules/morningstar-design-system/constants/constants.scss

Icons

MDS uses an SVG icon sprite that contains all MDS Icons. The icon sprite is located at:

node_modules/morningstar-design-system/dist/mds.svg

Place the sprite in the webroot of your product to use an absolute path reference.

<svg class="mds-icon" aria-hidden="true">
    <use xlink:href="/your/path/to/mds.svg#heart">
    </use>
</svg>

The icon sprite uses a hash syntax to retrieve the correct icon (in the example above, the #heart icon). Refer to the Icons documentation for all of the icon sprite names.

IE 11 Support

The MDS icons depend on the svg4everybody polyfill for IE 11 compatibility.

Using Components

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.

Integrating UI Components

Two approaches are available for integrating MDS components. Both give similar results from the user’s perspective, but differ in how adopting teams manage the underlying code.

  • HTML/CSS Markup: Frontend developers can copy and paste HTML/CSS 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.
  • 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/CSS markeup is encapsulated within each component. Many web components also include built-in support for common interactions and behaviors, which further simplifies implementation.

When viewing examples on MDS component pages, you can toggle between HTML and web component markup when available.

HTML Markup Example

For example, to create a simple button, the following HTML/CSS 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.

Web Component Example

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

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

With this approach, HTML/CSS markup, scripted behaviors, and other interactions can all be encapsulated within the component. MDS web components are written in vanilla JavaScript for compatibility with React, Vue, and other frameworks. See the following section for detailed instructions on installing and working with web components.

Using Web Components

Installation

MDS Web Components are currently shipped in the beta version of the Morningstar Design System package which is only available internally to Morningstar via the Sonatype Nexus package manager. Reference the Component Status page to see what components MDS supports and what the status of each component is.

To install MDS web components in your project:

  1. Update or set an .npmrc file in the root of your project and point the search registry to Nexus by including the following line:

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

  2. Install the package into your project’s node_modules directory via NPM or Yarn:

    npm install morningstar-design-system@beta --save

    yarn add morningstar-design-system@beta

Watch our tutorial video for a step-by-step walkthrough of installing the web components beta package.

Page Setup

CSS

MDS web components do not internalize any CSS and are dependent on the MDS CSS file. Before using the web components the MDS CSS file needs to be loaded on the page. This can be achieved either by including the external, precompiled MDS CSS file hosted on Morningstar's CDN in your template, including the precompiled CSS file from the MDS package in your template, or using the MDS SCSS files to compile your own CSS.

SVG Icon Sprite

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. 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 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="svgContainer" 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("svgContainer").appendChild(xhr.responseXML.documentElement);
</script>
<!-- Define a hidden container for your SVG content in your template -->
<span id="svgContainer" 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("svgContainer").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 style="display:none" v-html="require(`svg-inline-loader!./node_modules/morningstar-design-system/dist/mds.svg`)"></span>

Usage

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

Instantiation

Once the JS files are in the DOM, MDS web components can be instantiated via HTML or JS:

<mds-button></mds-button>
const myButton = document.createElement("mds-button");
document.body.appendChild(myButton);

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.icon = "heart";
myButton.text = "Hello World";
document.body.appendChild(myButton);

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>

Further Documentation