Development

Overview

When building a new system feature—a card component, for example, or an additional button variation—we follow a five-step process. This process usually involves pairing a designer and an engineer. While, typically, a designer completes [Design] and an engineer completes [Build], either may complete the [Discovery], [Doc], and [Publish] steps.

* Indicates required reviewer

Collaboration Over Handoff

Although linear in nature, our process is one of deep collaboration, driven by the heavy overlap of most of the steps. Writing documentation isn’t the last step, but rather something worked on across the entire process. Design and engineering collaborate heavily through the [Design] and [Build] steps to ensure components and features of the highest quality and efficiency.

1. Discovery

The [Discovery] phase is used to gather requirements, research approaches, identify existing design standards, and plan out the remainder of the work for building a component.

Process

• Identify the product teams that would use the feature.
• Gather existing requirements across product teams using in-person meetings, email, and online surveys.
• Perform competitive analysis for the feature.
• Solicit feedback and review of your research by the MDS core team and relevant community members.
• Create subsequent [Design], [Build], [Doc], and [Publish] JIRA tickets, including detailed acceptance criteria based on your research.
  • Or, if [Discovery] reveals that a feature should not be pursued, document the reasons as a comment on the ticket before closing, and if applicable, communicate directly with the reporter about why the work is not being done.

Reviews

To complete the [Discovery] step, the research gathered and your suggested approach should be reviewed by:

• MDS core team (required)
• The prospective designer and engineer to be assigned the follow-up tasks (required)
• Community members with a vested interest in the feature (required)
• Design community, via Visual Critique and/or UX Critique (recommended)

2. Design

The [Design] task includes finalizing all design decisions of a UI element or other design consideration. This includes not just validation of the overall direction from the design community, but meticulously solving for variations, states, and other relevant design details.

Process

• Assign the [Design] ticket created during [Discovery].
• Create design concepts in Sketch, Adobe Illustrator, or code.
• Share the concepts for feedback in:
  • MDS Mid-Sprint Review
  • Visual Critique and/or UX Critique
  • MDS core team critique
• Make iterative enhancements based on feedback and, when relevant, share for additional rounds of feedback.
• Create dev-ready design artifacts of the approved design and attach them to the [Build] JIRA ticket.

Reviews

To complete the [Design] step, the designer must obtain approval from:

• Mid-Sprint Review group (required)
• Design community, via Visual Critique and/or UX Critique (required)
• Engineer assigned the [Build] task (required)
• MDS core team (recommended)

3. Build

The [Build] task includes the development and QA of MDS code, including library items, visual language, and other tooling.

Process

• Assign the [Build] ticket created during [Discovery].
• Create a new feature branch from the develop branch and label it as feature/MDS-###-[label], for example, feature/MDS-219-Split-Button.
• Follow the documented process for building a component.
• Create relevant AVR and unit tests.
• Test in all supported browsers.
• Create a PR and assign the designer who completed the [Design] task and one additional MDS engineer as reviewers.
• Merge approved feature branch back in to develop.

Reviews

To complete the [Build] step, an engineer must obtain approval via pull request from:

• Designer assigned the [Design] task (required)
• One additional engineer (required)
• Relevant community members (recommended)

4. Doc

The [Doc] task corresponds to authoring any content that communicates what the System provides and how it operates. This includes copy, imagery, and coded examples related to component variations, design guidelines, API documentation, and more.

Process

• Assign the [Doc] ticket created during [Discovery].
• Create a new Word Online document in /Components/ directory of the MDS OneDrive group and title it as MDS-###-[label] [Doc], for example, MDS-5234 Articles [Doc].
  • Tip: Copy a previously created document as a starting point, when useful.
• Write guidelines, reference tables, and other copy to be published on the system site. Consider how MDS documentation components, like the Do/Don't and Image with Caption, will be used to present this content.
• Create supplemental imagery (such as a Do/Don’t PNGs) and place them in /Components/MDS-###/Images/ directory of the MDS OneDrive group.
• For code samples to be revealed in example/code pairs, begin work on the documentation page at doc-site/components/[plural-component-name].njk that’s finalized in the [Publish] step.
• Task is complete when all reviews are finished and examples and artwork are placed in the proper locations.

Reviews

To complete the [Doc] step, the author must obtain approval from:

• Designer/engineer who completed [Design]/[Build] (required)
• One additional MDS team member (required)
• The assigned system editor, who provides both a technical (content accuracy and relevance) and editorial (tone and style) review of what's written (required)

5. Publish

The [Publish] step migrates content—copy, imagery, code examples, etc.—authored during the [Doc] step to the system site.

Process

• Assign the [Publish] ticket created during [Discovery].
• Integrate copy, images, and code samples into the documentation page at doc-site/components/[plural-component-name].njk. Leverage the MDS documentation components, like the Do/Don't and Image with Caption, to display content.
• To trigger review, create a pull request of the feature/MDS-###-[label] branch into the current develop branch with two reviewers, as well as JIRA subtasks for each assigned reviewer.
• Merge approved feature branch back in to develop.

Reviews

To complete the [Publish] step, the publisher must obtain approval via pull request from:

• Two members of the MDS team (required)

Releases

The Morningstar Design System will publish two main artifacts: the documentation site and the consumable library for application engineers.

Library Release

• All releases will be downloadable from the documentation site as zip files.
• Releases are also available as NPM packages
• For more detailed release information, please see the wiki article (Internal Use Only).

Documentation Release

• The production S3 environment will be accessible from designsystem.morningstar.com.
• This URL is cached by a CloudFront distribution.