Getting Started

For Designers

The System is organized into three primary sections: Visual Language, Libraries, and About MDS. Exploring these sections will help familiarize you with Morningstar design principles and patterns, and show you which existing components you can use in your product.

Visual Language contains the critical building blocks of the look and feel of Morningstar products. Here, you will find details and guidelines on Color, Typography, Iconography, and Space, defined as reusable variables called Constants. Constants are threaded throughout MDS components to maintain a consistent visual style.

Libraries are collections of pre-built components, concepts, and guidelines that solve common design challenges in Morningstar products. To ensure consistency and reusability, components are built using Constants defined in the Visual Language section, and are accompanied by detailed documentation and guidelines for use.

About MDS includes a plethora of useful information on topics like Accessibility, Contributing to MDS, Reporting Bugs, and the MDS team’s Development Process.

Sketch Design Assets

• Sketch Design Assets (Current Version, 1.1)
• MDS Craft Library (Current Version, 1.1)

How to Use the Craft Library

1. Download and unzip the MDS Craft Library, and place the MDS Craft Library v1.1.library folder in a directory that won't change or move in the future.

2. Download and install the Craft by InVision plugin.

If you experience issues or bugs when using the Craft library, updating Craft and restarting Sketch will almost always solve the problem. To update Craft, search your machine for the Craft Manager application, and click Update. You will be prompted to restart Sketch after the update is complete.

Icon Creation Templates

• Icons Template Default (Current Version, 1.0)
• Icons Template Small (Current Version, 1.0)

For Engineers

The System provides a unified language between design and engineering teams, and it enables developers to quickly implement consistent user interface components across Morningstar web user interfaces. It also exposes a set of variable tokens that allow engineers to style custom-built application components that adhere to the Morningstar-branded style definitions within MDS.

• MDS dependencies are declared in the package.json file.
• MDS is CSS and markup driven.
• MDS is javascript and application framework agnostic.
• MDS uses Sass for CSS preprocessing.
• MDS’ documentation is compiled from Nunjucks templates, macros, and markdown.

Installing MDS

We encourage MDS consumers to use the Node package to install the library code within your environment.

Via NPM

npm install morningstar-design-system --save

Via Bower

bower install morningstar-design-system --save

Building MDS Locally

Building MDS locally enables you to configure which components you would like to include in your application.

The MDS repo is located on our Morningstar Tech Standards Bitbucket server.

Dependencies

• Node - Version 4.5 or later
• Node Version Manager - NVM may be needed if your primary app is dependent on a specific version of Node that is earlier than 4.5.
• Gulp version 4 - If Gulp is already installed, make sure that it has been upgraded to version 4.
• Gulp CLI version 1.2.2

Choosing Components

You can use the YAML configuration file to choose which components to include in a local build of MDS. The configuration is located in mds/src/library/component_config.yaml. Setting the true/false flags per component will either include or exclude the given component inside of the compiled CSS file.

Build Steps

1. Clone the repo to your local machine.
2. From the root directory of mds/ run npm install.
3. After installation is complete, run gulp.
4. Include the following files in your application:
   • dist/assets/styles/mds_library.css
   • dist/assets/styles/mds_library_print.css (optional)

Latest Release

The latest MDS release can be found at http://designsystem.morningstar.com/release-history.html.

MDS as a Dependency

To add a dependency to MDS as an NPM package, follow these steps:

1. In your application’s package.json file, add mds to your dependencies list, for example:

2. Run npm install to pull MDS into your node_modules directory.
3. Manually include MDS components and overrides within SCSS files in your own app.

If your product does not use NPM, you’ll need to manually manage upgrading the library by downloading a ZIP file containing the MDS library package from the MDS site or from the code repository.

Using MDS Sass

Option #1. Partial Library and Targeted Overrides (Recommended)

If you are planning on bringing in a select number of components, and potentially overriding some styles more systematically, you should isolate overrides per component to better maintain your library use as your product – and MDS – change over time.

Option #2. Partial Library & General Overrides

You can use a limited set of MDS components, such as icons, buttons, and tooltips, and decalare any overrides in a single file. This limits the overall download weight of MDS styles, however, it generalizes your overrides into a single catch-all file which might be sub-optimal.

Option #3. Complete Library & General Override Files (Not Recommended)

Bring in the complete MDS library, and override everything with a single override file. With this approach, you might include more than you need and your catch-all override file could be difficult to maintain.

To @import the entire mds_library.scss file, add the following import path to your SCSS compiler:

• node_modules/morningstar-design-system/src/styles/auto_generated

Including MDS Sass In Your Build

There is a shortcut helper path that is exposed if you are referencing MDS .scss files in your build. You may have a need to include MDS .scss files into your application’s build process if you want to run a linter on the MDS code, for example.

In mds/index.js you will find libraryComponentStylePath and libraryBaseStylePath these can be used in place of node_modules/morningstar-design-system/src/styles and node_modules/morningstar-design-system/src/styles to more quickly target the Sass files that you want to pull in from MDS.

Using MDS CSS

Option #1. Include the Full Latest Release

• Download (http://designsystem.morningstar.com/assets/styles/mds_library.css), or copy from your local build, (/dist/assets/styles/mds_library.css) the compiled CSS library file.
• Include the compiled CSS reference in the <head> your application.

• Include your own overrides CSS file after the mds_library.css reference.

• Example:

Option #2. Include Selected Components Through Configuration

You’ll need to build MDS locally in order to compile a custom set of included components. Once you’ve customized your component list and you've built locally, you can then copy the output CSS file and include it in your own app. See the instructions for building MDS locally.

Applying Visual Style

Constants

MDS uses a set of global variables, or constants, that are threaded throughout the system to facilitate visual consistency across components.

The constants are declared in a .yaml file found at mds/src/library/constants/constants.yaml. At build time, the .yaml file is used to generate the name-spaced SASS variables here: /src/library/styles/auto_generated/_constants.scss. (This is a compiled file not committed to repo). These auto-generated variables are used throughout the component scss files found in /src/library/components.

Any adjustments, overrides, or extensions to the constants must be done in the .yaml file.

In addition to the SASS file, a .json file is generated at build time. It can be found at: /src/library/data/mds_constants.json. (This is also a compiled file, not checked into the repo.) This file exposes the system site to all of the constant variable names via .json. The .json object follows the same nested structure declared in the .yaml file with the parent object named constants.

Icons

When building locally, MDS uses a run-time-generated icon sprite to handle the use of icons throughout the system. The sprite is generated from a set of SVG files found at /src/library/icons.

As with constants, there is a .json file containing an array with all of the icon names generated at build time. The .json object is exposed for use within this site. The file is saved to /src/library/data/icons.json.

Please see the Iconography page to reference the recommended implementation approach for icons.

Mixins

Some components have their own Sass mixins scoped within their individual .scss file which are located in /src/library/components.

There are a number of shared mixins found in /src/library/styles/shared. These mixins are shared across two or more components in the system.

Importing the MDS Sass into your own app’s .scss file will enable you to use all of the MDS mixins within your own application’s Sass.

Using Components

Details for implementing the HTML and CSS for components can be found on the individual component pages.

General Rules for Implementations

• When composing component markup in your application, ensure that it is structured exactly in accordance with the markup examples found on the individual components pages.
  • Any DOM structure that doesn’t strictly adhere to the component examples may result in broken layout and user interface bugs.
• MDS uses the BEM naming convention: http://getbem.com/naming/
  • If you choose to extend any components within MDS inside of your own applications, we strongly recommend that you adhere to the same naming convention.
• If your application framework has a specific convention for using JavaScript and or creating and destroying elements within the DOM, adhere to that convention.

JavaScript in MDS

In documentation coding examples, MDS provides JavaScript examples to handle component interactions for your reference. You will also find third-party-library-driven interactions for some components:

Engineers should use their own JavaScript libraries and implementations that most appropriately fit within the requirements for their applications and environments.