Installing and Integrating MDS

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

We recommend installing MDS using Node package management (NPM). 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 and placing these assets in your project. 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
    ├── constants.json
    ├── constants.scss
    └── constants.yaml
├── data
└── dist
    ├── mds.css
    ├── mds.es5.js
    ├── mds.es5.js.map
    ├── mds.js
    ├── mds.svg
    └── mds.v2.css
├── fonts
├── icons
├── includes
└── styles
    ├── utils
    │   ├── accessibility.scss
    │   ├── import_once.scss
    │   └── touch.scss
    └── 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. 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:

// Your SCSS: Importing only Forms and Buttons

@import 'node_modules/morningstar-design-system/components/form/form';
@import 'node_modules/morningstar-design-system/components/button/button';

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

// MDS Constants, utilties, and visual language mixins

@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/utils/touch';

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

To include all MDS UI components:

// All MDS UI components

@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/overlay/overlay';
@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

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:

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

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

// Your SCSS
$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
{
    browsers: ['last 2 versions'],
    grid: true
}
CleanCSS Config
{
    level: 2
}

Precompiled CSS

The precompiled mds.css file is deprecated and will be removed from our distributed package and CDN in the next major release. Using the Compiled SCSS files is required to ensure access to MDS constants and mixins, which are essential to implementing MDS. Teams are encouraged to adopt this method as early as possible, and will need to do so before upgrading to the next major release once available.

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

<!-- Your HTML -->
<link rel="stylesheet" href="/path/to/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:

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

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

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:

// Your JS: Importing only Buttons

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.

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

<!-- Your HTML -->
<script src="path/to/mds.es5.js"></script>

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:

<!-- Insert in your HTML <head> tag -->
<!-- Desktop browser assets -->
<link rel="icon" type="image/png" sizes="32x32" href="path/to/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="path/to/favicon-16x16.png">
<link rel="mask-icon" href="path/to/favicon.svg" color="#ff0000">
<!-- iOS assets -->
<link rel="apple-touch-icon" sizes="180x180" href="path/to/apple-touch-icon.png">
<!-- Android assets -->
<link rel="manifest" href="path/to/site.webmanifest">
<meta name="theme-color" content="#ffffff">
<!-- Microsoft assets -->
<meta name="msapplication-TileColor" content="#ff0000">
  • 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.

{
    "name": "Morningstar",
    "short_name": "Morningstar",
    "icons": [
        {
            "src": "path/to/android-chrome-192x192.png",
            "sizes": "192x192",
            "type": "image/png"
        },
        {
            "src": "path/to/android-chrome-512x512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ],
    "theme_color": "#ffffff",
    "background_color": "#ffffff",
    "display": "standalone"
}
  • 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:

<?xml version="1.0" encoding="utf-8"?>
<browserconfig>
    <msapplication>
        <tile>
            <square150x150logo src="path/to/mstile-150x150.png" />
            <TileColor>#ff0000</TileColor>
        </tile>
    </msapplication>
</browserconfig>
  • 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.

The System’s 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 in markup, product teams can choose from two approaches:

  1. Use MDS web components custom element markup and APIs, including built-in JavaScript functionality and support from the MDS team.
  2. Copy and paste HTML markup from the MDS site and implement JavaScript functionality yourself.

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 by internalizing components’ HTML markup, allowing structural changes and improvements to be made without introducing breaking changes.

Web components are written in vanilla JavaScript for compatibility with React, Vue, and other frameworks. They also include built-in support for common interactions and behaviors to further simplify 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 an <mds-button> web component the following custom element markup could be used:

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

Alternatively, web components can be instantiated via JavaScript:

const myButton = document.createElement("mds-button");
myButton.icon = "open-new--s";
myButton.variation = "primary"
myButton.text = "My 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 available on the code reference tab of each UI component page.

Attributes

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

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.

// Using IDL attributes 
const myButton = document.createElement("mds-button");

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

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

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

When using the HTML, teams are responsible for implementing all JavaScript behavior and interactions themselves. They must also manually update HTML markup following each major version release to stay current with new features and address breaking changes.

For example, to create a 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="#open-new--s">
        </use>
    </svg>
    <span class="mds-button__text">My Button</span>
</button>
Customizations to MDS HTML must be done cautiously and only when necessary as future updates to component code may break any product-side customizations.

Overriding MDS Styles

MDS styles should only be overriden when necessary to align with product-specific requirements, and only after other standard approaches have been considered.

Overrides usually result in technial debt since your team becomes responsible for:

  • Maintaining overrides when integrating future updates to MDS
  • Keeping overrides in sync with evolving design standards
  • Ensuring overrides meet accessibility requirements

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.

If you think that a specific override could benefit multiple product teams, consider making the change and submitting it as a contribution back to MDS.

MDS Version Conflicts

To support cases where multiple major versions of MDS are loaded on a single page we offer an optional feature to namespace MDS styles to avoid conflicts.

Further Documentation

Product teams can apply the MDS Visual Language within their code by using MDS constants and mixins. Two of the most common uses of these assets will be:

  • Applying padding and margin-based space using Space constants
  • Creating text styles in your product
  • Constructing custom features from scratch within your product using common constants, like Color, Border, and Typography
  • Customizing an existing MDS component

Note: UI components are delivered with all styling built in, no additional work is required to style components.

Constants

Constants are global variables used throught the component library to maintain visual consistency. Import the constants SCSS file in to your product’s SCSS to gain access to constants in your product styles.

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

// Your SCSS

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

Constants are named specific to their intended use. If you can’t find an appropriately named one for your use case, use the generic constants instead. For example, don’t use the constant $mds-text-color-primary-on-light for anything other than setting text color. Instead, you could use $mds-color-neutral-12, which is currently set to use the same color as $mds-text-color-primary-on-light.

For the full list of all available constants, see Constants visual language page.

Applying Space

Always use space constants when defining margin and padding within your product SCSS. For example, rather than apply a fixed margin specified in pixels below a button, choose a constant that achieves the desired spacing:

margin-bottom: $mds-space-4-x;

Do use space constants to define all spaces in your SCSS.

margin-bottom: 32px;

Don‘t use hardcoded pixel values to define spaces.

For more details and a full list of available space constants, see the Space visual language page.

Mixins

Mixins provide a simple method to apply more complex MDS styles within your product. You can find detailed mixin documentation on relevant UI component and visual language pages.

Typography

Mixins are critical to the proper application of typographic styles within your product. MDS provides mixins for multiple typographic concerns, including:

In the NPM package these files are found at:

/styles/visual-language/typography.scss
/styles/visual-language/color.scss

Always use mixins when creating text styles in your product. For example, if you were setting up basic heading and body text styles:

// Your SCSS

h1 {
    @include mds-level-2-heading();
    @include mds-text-color-primary();
    font-weight: $mds-font-weight-bold; // Override mixin styles using constants on an as-needed basis
}

h2 {
    @include mds-level-4-heading();
    @include mds-text-color-secondary();
}

p {
    @include mds-body-text-m();
    @include mds-text-color-primary();
}

Note: MDS heading mixins can be applied to HTML <h#> tags as needed to acheive design and accessibility requirements. For example, above we are applying the mds-level-2-heading mixin to the <h1>. See the Typography page for more information.