Space

Space helps organize content, permitting consistent density and visual order that telegraphs our brand.

The Morningstar Design System applies space within and between components—even differently sized ones—to consistently render harmonious visual displays. The spatial standards and concepts described below are woven through the entire library and can help product teams compose custom views and components.

System components are composed with consistent spatial applications using a few reusable concepts: insetting, stretching an inset, stacking, and separating items inline.

Inset

An inset applies padding equal on all four sides to block or inline elements.

Examples

Tag

Equity

Alert

Card

Funds

Core Bond Funds

These intermediate-term taxable-bond funds earn Morningstar Analyst Ratings of Gold.

Here is where we want an accurate description about the data displayed and/or the table's intent
Fund Name	Ticker
Dodge & Cox Income	DODIX
Western Asset Core Plus Bond I	WACPX
Vanguard GNMA Inc	VFIIX

Constants

Apply inset constants to component and element padding, like an item in a List Group or a cell in a Data Table.

Constant Name	Value	Result
$mds-space-inset-quarter-x	2px	Text
$mds-space-inset-half-x	4px	Text
$mds-space-inset-three-quarter-x	6px	Text
$mds-space-inset-1-x	8px	Text
$mds-space-inset-1-and-a-half-x	12px	Text
$mds-space-inset-2-x	16px	Text
$mds-space-inset-3-x	24px	Text
$mds-space-inset-4-x	32px	Text
$mds-space-inset-8-x	64px	Text

Implementation Example 1: Simple Inset

Text

<div class="mds-doc-space__inset-example">Text</div>

.mds-doc-space__inset-example {
    @include mds-text-crop();
    background-color: $mds-background-color-dark-gray;
    color: $mds-text-color-primary-on-dark;
    padding: $mds-space-inset-1-x;
}

Implementation Example 2: Insets With Left and Right Edge Cropped

Some element arrangements conform to inset spacing conventions, but need left-most and right-most elements to align with an element’s edge. In that case, zero out the left edge of the left-most cell and right edge of the right-most cell, as is done within the Data Table component.

Here is where we want an accurate description about the data displayed and/or the table’s intent
Ticker	Price($)	Selected
FSHBX	8.60	0
HAINX	60.32	-0.59

Inset Stretch

Many System components “stretch” the inset, adding more padding to the left and right of the contained text and/or elements.

Examples

Button, Small Inset Stretch

Button, Medium Inset Stretch

Pagination, Small Inset Stretch

Constants

Apply inset-stretch constants to component and element padding.

Constant Name	Value	Result
$mds-space-inset-stretch-s	6px 12px	Text
$mds-space-inset-stretch-m	8px 16px	Text
$mds-space-inset-stretch-l	12px 24px	Text

Stack

Use the stack concept to apply bottom margin consistently to separate block-level, 100%-wide items, arranged vertically.

Constants

Apply stack constants to a component or element’s margins.

Constant Name	Value	Result
$mds-space-stack-quarter-x	0 0 2px	A B C
$mds-space-stack-half-x	0 0 4px	A B C
$mds-space-stack-three-quarter-x	0 0 6px	A B C
$mds-space-stack-1-x	0 0 8px	A B C
$mds-space-stack-1-and-a-half-x	0 0 12px	A B C
$mds-space-stack-2-x	0 0 16px	A B C
$mds-space-stack-3-x	0 0 24px	A B C
$mds-space-stack-4-x	0 0 32px	A B C
$mds-space-stack-8-x	0 0 64px	A B C

Omit this space from the :last-child component or element item in a set.

Implementation Example 1: Nesting Stack Within Inset Spacing

Avoid indenting each item from the left and right when stacking components. Instead, apply inset padding to the container of the stacked items.

In the following example, two list-group groups are stacked, and the space surrounding both applies an inset to a container.

First List
Item 1
Item 2

Second List
Item 1
Item 2

<div class="mds-container--dark-gray mds-doc-space__inset-stack-container">
    <ul class="mds-list-group">
        <li class="mds-list-group__item mds-list-group__item--header">
            First List
        </li>
        <li class="mds-list-group__item ">
            <a href="#" class="mds-list-group__link">
                <span class="mds-list-group__item-text">
                    Item 1
                </span>
            </a>
        </li>
        <li class="mds-list-group__item ">
            <a href="#" class="mds-list-group__link">
                <span class="mds-list-group__item-text">
                    Item 2
                </span>
            </a>
        </li>
    </ul>
    <ul class="mds-list-group">
        <li class="mds-list-group__item mds-list-group__item--header">
            Second List
        </li>
        <li class="mds-list-group__item ">
            <a href="#" class="mds-list-group__link">
                <span class="mds-list-group__item-text">
                    Item 1
                </span>
            </a>
        </li>
        <li class="mds-list-group__item ">
            <a href="#" class="mds-list-group__link">
                <span class="mds-list-group__item-text">
                    Item 2
                </span>
            </a>
        </li>
    </ul>
</div>

.mds-doc-space__inset-stack-container {
    padding: $mds-space-inset-1-x;

    .mds-list-group {
        margin: $mds-space-stack-1-x;
    }
}

Inline Left and Right

Use inline-left spacing to separate inline elements flowing together from the left edge. This applies right margin to each item. The opposite is true for inline-right.

Constants

Apply inline-left and inline-right constants to a component or element’s margins.
Omit this space from the :last-child component or element item in a set.
Combine relevant stack and inline concepts when inline items wrap.

Constant Name	Value	Result
$mds-space-inline-left-half-x	0 4px 0 0	A B C
$mds-space-inline-left-three-quarter-x	0 6px 0 0	A B C
$mds-space-inline-left-1-x	0 8px 0 0	A B C
$mds-space-inline-left-1-and-a-half-x	0 12px 0 0	A B C
$mds-space-inline-left-2-x	0 16px 0 0	A B C
$mds-space-inline-right-half-x	0 0 0 4px	A B C
$mds-space-inline-right-three-quarter-x	0 0 0 6px	A B C
$mds-space-inline-right-1-x	0 0 0 8px	A B C
$mds-space-inline-right-1-and-a-half-x	0 0 0 12px	A B C
$mds-space-inline-right-2-x	0 0 0 16px	A B C

Generic

Use generic spacing constants when creating spaces which don’t relate to any of the existing concepts documented above.

Constants

Constant Name	Value
$mds-space-quarter-x	2px
$mds-space-half-x	4px
$mds-space-three-quarter-x	6px
$mds-space-1-x	8px
$mds-space-1-and-a-half-x	12px
$mds-space-2-x	16px
$mds-space-2-and-a-half-x	20px
$mds-space-3-x	24px
$mds-space-4-x	32px
$mds-space-5-x	40px
$mds-space-6-x	48px
$mds-space-7-x	56px
$mds-space-8-x	64px

Implementing Space

Line Height and Cropping Text

In order to unify spacing concepts across the library, the System crops out the unpredictable impact of line-height at the top and bottom of text blocks.

This effect is achieved by the mds-text-crop() mixin available within the src/library/styles/shared/typography.scss file, which trims the margin-top and margin-bottom of an element using :before and :after pseudo elements.

Without Text Crop

Text

With Text Crop

Text

The mds-text-crop() mixin is applied to a component or element block:

.mds-form__microcopy {
    @include mds-text-crop();
    ...
}

Spacing by Size

Many System components are offered in two or more sizes, such as small, medium and large. Space is configured to adjust padding, margin and other concerns at each increment. These concepts enable multiple components to be positioned together vertically or horizontally with consistency regardless of size.

Small

Medium

Large

Incremental Spacing

Many components use the incremental-spacing() mixin within the src/library/styles/size.scss file. This macro enables an engineer to quickly apply System spacing concepts across component elements.

Parameter	Default	Examples	Outcome
`$component-name`	None	`list-group`	Includes component name within selectors.
`$spacing-type`	None	`inset`, `inset-stretch`, `stack`	Applies the spacing concept for use on margins or padding.
`$default-size`	`m`	`m`, `s`, `l`	Sets the “middle” size so that spacing is properly encoded across levels.
`$selector-level`	`element`	`element` or `block`	Applies spacing at the block- or element-level selectors, consistent with BEM methodology.
`$property-list`	false	`(‘padding-left’, ‘padding-top’)`	Accepts a SASS list of CSS properties that the space value will be applied to. If not provided, the mixin will select the CSS property based on the $spacing-type.
`$space-adjustment`	0	`$space-adjustment: 3px`	Used in conjunction with $property-list. A positive or negative px value that is added to the values. Output by the mixin. Used only in special cases to correct alignment issues.
`$text-cropped`	`true`		If set to false, the incremental-spacing mixin will recreate the same effect as the `mds-text-crop` mixin using custom padding sizes. Used exclusively on `<input>` elements which cannot use `mds-text-crop`. Do not set this argument to false if you are already using the `mds-text-crop` mixin.

Implementation Example 1: Form Spacing

For example, the System textbox Form element applies space as:

.mds-form__input {
    @include incremental-spacing('form__input',
    'inset',
    $selector-level: 'block',
        $text-cropped: false);
}

Implementation Example 2: List Group Spacing

Similarly, the subsection item variant of the List Group component applies space as:

.mds-list-group__item--sublist {
    @include incremental-spacing('list-group',
    'default',
    $property-list: ('padding-left'),
        $space-adjustment: 2px);
}

Link Template