Getting Started

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

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:

To include all MDS components using full NPM package paths:

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.

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.

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

Refer to UI Component pages such as Button for how to implement components individually. In general, you should:

• Structure component markup exactly as depicted in documentation examples. Any deviation in DOM structure may result in broken layouts and user interface bugs.
• Extend components using BEM CSS methodology that's used as the foundation of MDS.
• Use JavaScript conventions required for your application framework for creating and destroying elements within the DOM.

External Dependencies

Stylesheets

The Morningstar Design System has no external stylesheet dependencies. All the styles required to render UI Components are contained in mds.css.

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:

CleanCSS Config

Configure CleanCSS with the following:

JavaScript

Read more about the MDS approach to Javascript on the JavaScript in MDS page.

Three System UI Components require third-party JavaScript libraries to function:

• Icons: The SVG icons in the System depend on the svg4everybody polyfill for ie11 compatibility, version ^2.1.4.
• Range Slider: The Range Slider UI Component depends on the the noUiSlider JavaScript library, version ^10.1.0
• Combo Box: The Combo Box UI Component depends on the Select2 JavaScript library, version ^4.0.3.

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. Run npm install morningstar-design-system@beta --save or yarn add morningstar-design-system@beta to install the package into your project’s node_modules directory.

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.

• 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 package managers such as Webpack and an svg loader plugin such as SVG Inline Loader

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:

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 use kebab-style formatting for multi-word attribute names (e.g., my-long-name=”value”).

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

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

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.

Further Documentation

• MDS Web Component Overview
• Building an MDS Web Component
• MDS Web Component Coding Standards
• MDSWC Base API
• Unit Testing
• AVR Testing