Installing and Integrating MDS
Installing and Integrating MDS
Engineers integrate MDS by installing and configuring NPM dependencies, adopting MDS visual language, and integrating MDS UI components.
Overview
Installing MDS
Install MDS using Node package management (NPM).
Add an
.npmrcfile 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.
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.
Installing the MDS Beta Package
To test out new components or capabilities that have not yet been released for production, the beta package can be used. The contents of the beta package may vary as new capabilities become available. For details on the status of specific components, see the Component Status page and/or documentation for the relevant capabilities.
Install the package into your project’s
node_modulesdirectory via NPM or Yarn:npm install morningstar-design-system@beta --saveyarn add morningstar-design-system@beta
Watch our tutorial video for a step-by-step walkthrough of installing the beta package.
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.22.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.cssUsing 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>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: 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.
- 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 are have been released as web components. See the Component Status page for details on availability.
When viewing examples on MDS component pages, you can toggle between HTML and web component markup when available.
HTML Example
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.
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 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.
Using Web Components
Installation
MDS web components are currently shipped in the Morningstar Design System package which is available internally to Morningstar via the Sonatype Nexus package manager. Currently only a subset of UI components are have been released as web components. See the Component Status page for details on availability.
To test out web components that have not yet been released for production, the beta package can be used.
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>- Load the SVG sprite content inline using Webpack and the SVG Inline Loader plugin.
<!-- 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>