Coding Standards

The Morningstar Design System team adheres to standard coding practices and tools to build components and other features. These standards do not serve as coding style standards to which other product teams must adhere. Instead, they express conventions used by MDS to create a maintainable, scalable library that other teams are welcome to emulate.

HTML

Semantics

The stand-alone HTML should have value and meaning.

  • If you are wrapping paragraph text with an element, use a <p> tag.
  • If it's tabular data, use a <table> tag.
  • If you have an unordered list, use a <ul> with nested <li>s wrapping each item.
  • If we write HTML using meaningful tags, we won’t have to rewrite the markup when the UI changes.

Header Tags

  • <!DOCTYPE html>: Use a doctype to force browsers to render in standards mode and prevent quirks-mode problems in Internet Explorer.
  • <html lang="en-us">: Set a lang attribute to assist browsers and search engines.
  • <meta charset="UTF-8">: Use UTF-8 encoding.
  • <meta http-equiv="X-UA-Compatible" content="IE=Edge">: Use the latest supported Microsoft browser mode.

Best Practices

  • Lowercase tag names.
  • Lowercase attribute names.
  • Use four spaces (not tabs) for indentation.
  • Use double (not single) quotation marks for attribute values.
  • Use as few <span>s and <div>s as possible.
  • Account for responsiveness. If a component requires responsive grid classes to render properly on smaller devices, apply those classes properly in demonstrations on a sink page and in documentation.
  • Minimize class=”” properties according to BEM methodology: https://en.bem.info/methodology/quick-start/.
  • Use id=”” names very sparingly and only if:
    • Using a label with a for=”” attribute
    • Using a third-party library that relies on id=””s to target specific elements
  • Use HTML 5 tags according to the spec for semantic purposes.
  • Never use inline styles unless leveraging a third-party framework that relies on inline styling (e.g. a tooltip/popover lib that positions the element using inline top, right, bottom, or left properties).
  • Don't include a trailing slash in self-closing elements – the HTML5 spec says they're optional.
  • Always include optional closing tags (i.e.,</li> or </body>).
  • Attribute order:
    • Put class attribute first (engineers read/write this most often).
    • For all other attributes, add them in the order that makes most sense to you, but keep in mind that the more consistent the attribute order, the easier the code will be to inherit.
    • Exception to class attribute first rule: When an attribute is critical to defining an element, put it first to improve readability – <input type="text" class="" id="" disabled name="" placeholder="" readonly value="">.

Tools

Inspiration

These principles were inspired by:

CSS

The MDS component library is written using BEM CSS Methodology.

Principles

  • Use longhand syntax wherever appropriate for properties. This will avoid accidental CSS resetting: https://css-tricks.com/accidental-css-resets/.
  • Use class name hyphenations and underscores according to BEM methodology: https://en.bem.info/methodology/quick-start/.
  • Code to a standards-compliant browser first, and then fix issues in IE.
  • Keep selectors as flat as possible with regard to chaining or nesting.
  • Never style raw HTML elements. Instead, use a class.

CSS Style

Readability

  • Alphabetize properties.
  • End all declarations with a semicolon.
  • Comma-separated property values should include a space after each comma, i.e., box-shadow.
  • Include spaces after commas within rgb(), rgba(), hsl(), hsla(), or rect() values.
  • Don't prefix property values or color parameters with a leading zero, i.e., .5 instead of 0.5 and -.5px instead of -0.5px.
  • Lowercase all hex values, e.g., #ffffff. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes.
  • Don’t use shorthand hex values; instead spell out all 6 characters #ffffff.
  • Quote attribute values in selectors, i.e., input[type="text"]. They’re only optional in some cases and it’s a good practice for consistency.
  • Avoid specifying units for zero values, i.e., margin: 0; instead of margin: 0px;.

CSS Tools

JavaScript

Inspiration

What are some general principles your team should follow when writing JavaScript?

Tools

Style

Fonts

The System does not use an icon font, but rather an SVG with an external reference technique. We reference custom fonts using @font-face and referencing a .eot and a fallback .woff.

Example

@font-face {
    font-family: "Univers";
    font-style: normal;
    font-weight: 300;
    src: url("../fonts/webfont-name.eot");
    src: url("../fonts/webfont-name.eot?#iefix") format("embedded-opentype"), url("../fonts/webfont-name.woff") format("woff");
}

Tooling

©2017 Morningstar, Inc. All rights reserved. Terms of Use