Spacing

Chassis CSS includes a wide range of shorthand responsive margin, padding, and gap utility classes to modify an element’s appearance.

Margin and padding

Assign responsive-friendly margin or padding values to an element or a subset of its sides with shorthand classes. Includes support for individual properties, all properties, and vertical and horizontal properties. Classes are built from a default Sass map ranging from 0.0625rem (1px) to 3rem (48px).

Using the CSS Grid layout module? Consider using the gap utility instead.

Notation

Spacing utilities that apply to all breakpoints, from xsmall to 2xlarge, have no breakpoint prefix in them. This is because those classes are applied from min-width: 0 and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint prefix.

The classes are named using the format {property}{sides}-{size} for xsmall and {breakpoint}:{property}{sides}-{size} for small, medium, large, xlarge, and 2xlarge.

Where property is one of:

m - for classes that set margin
p - for classes that set padding

Where sides is one of:

t - for classes that set margin-top or padding-top
b - for classes that set margin-bottom or padding-bottom
s - (start) for classes that set margin-left or padding-left in LTR, margin-right or padding-right in RTL
e - (end) for classes that set margin-right or padding-right in LTR, margin-left or padding-left in RTL
x - for classes that set both *-left and *-right
y - for classes that set both *-top and *-bottom
blank - for classes that set a margin or padding on all 4 sides of the element

Where size is one of:

zero or 0 - for classes that eliminate the margin or padding by setting it to 0
4xsmall - default token value is 0.0625rem (1px).
3xsmall - default token value is 0.125rem (2px).
2xsmall - default token value is 0.25rem (4px).
xsmall - default token value is 0.5rem (8px).
medium - default token value is 1rem (16px).
large - default token value is 1.25rem (20px).
xlarge - default token value is 1.5rem (24px).
2xlarge - default token value is 1.75rem (28px).
3xlarge - default token value is 2rem (32px).
4xlarge - default token value is 2.25rem (36px).
5xlarge - default token value is 2.5rem (40px).
6xlarge - default token value is 3rem (48px).
auto - for classes that set the margin to auto

(You can add more sizes by adding entries to the $spacers Sass map variable.)

Examples

Here are some representative examples of these classes:

.mt-0, .mt-zero {
  margin-top: 0 !important;
}

.ms-2xsmall {
  margin-left: ($spacer * .25) !important;
}

.px-xsmall {
  padding-left: ($spacer * .5) !important;
  padding-right: ($spacer * .5) !important;
}

.p-medium {
  padding: $spacer !important;
}

Horizontal centering

Additionally, Chassis CSS also includes an .mx-auto class for horizontally centering fixed-width block level content—that is, content that has display: block and a width set—by setting the horizontal margins to auto.

Centered element

<div class="mx-auto p-xsmall" style="width: 200px;">
  Centered element
</div>

Negative margin

In CSS, margin properties can utilize negative values (padding cannot). These negative margins are disabled by default, but can be enabled in Sass by setting $enable-negative-margins: true.

The syntax is nearly the same as the default, positive margin utilities, but with the addition of n before the requested size. Here’s an example class that’s the opposite of .mt-2xsmall:

.mt-n2xsmall {
  margin-top: -0.15rem !important;
}

Gap

When using display: grid or display: flex, you can make use of gap utilities on the parent element. This can save on having to add margin utilities to individual children of a grid or flex container. Gap utilities are responsive by default, and are generated via our utilities API, based on the $spacers Sass map.

Grid item 1

Grid item 2

Grid item 3

Grid item 4

html

<div class="grid gap-medium">
  <div class="p-xsmall g-col-6">Grid item 1</div>
  <div class="p-xsmall g-col-6">Grid item 2</div>
  <div class="p-xsmall g-col-6">Grid item 3</div>
  <div class="p-xsmall g-col-6">Grid item 4</div>
</div>

Support includes responsive options for all of Chassis CSS’s grid breakpoints, as well as six sizes from the $spacers map (0–5). There is no .gap-auto utility class as it’s effectively the same as .gap-0.

row-gap

row-gap sets the vertical space between children items in the specified container.

Grid item 1

Grid item 2

Grid item 3

Grid item 4

html

<div class="grid gap-0 row-gap-medium">
  <div class="p-xsmall g-col-6">Grid item 1</div>
  <div class="p-xsmall g-col-6">Grid item 2</div>
  <div class="p-xsmall g-col-6">Grid item 3</div>
  <div class="p-xsmall g-col-6">Grid item 4</div>
</div>

column-gap

column-gap sets the horizontal space between children items in the specified container.

Grid item 1

Grid item 2

Grid item 3

Grid item 4

html

<div class="grid gap-0 column-gap-medium">
  <div class="p-xsmall g-col-6">Grid item 1</div>
  <div class="p-xsmall g-col-6">Grid item 2</div>
  <div class="p-xsmall g-col-6">Grid item 3</div>
  <div class="p-xsmall g-col-6">Grid item 4</div>
</div>

CSS

Sass variables

Spacing variables are declared by design tokens.

scss/_variables.scss

$space-zero:          $cx-space-context-zero;
$space-4xsmall:       $cx-space-context-4xsmall;
$space-3xsmall:       $cx-space-context-3xsmall;
$space-2xsmall:       $cx-space-context-2xsmall;
$space-xsmall:        $cx-space-context-xsmall;
$space-small:         $cx-space-context-small;
$space-medium:        $cx-space-context-medium;
$space-large:         $cx-space-context-large;
$space-xlarge:        $cx-space-context-xlarge;
$space-2xlarge:       $cx-space-context-2xlarge;
$space-3xlarge:       $cx-space-context-3xlarge;
$space-4xlarge:       $cx-space-context-4xlarge;
$space-5xlarge:       $cx-space-context-5xlarge;
$space-6xlarge:       $cx-space-context-6xlarge;

$spacer:              $space-medium;

Sass maps

Spacing utilities are declared via Sass map and then generated with our utilities API.

scss/maps/_index.scss

$spacers: (
  zero:           $space-zero,
  4xsmall:        $space-4xsmall,
  3xsmall:        $space-3xsmall,
  2xsmall:        $space-2xsmall,
  xsmall:         $space-xsmall,
  small:          $space-small,
  medium:         $space-medium,
  large:          $space-large,
  xlarge:         $space-xlarge,
  2xlarge:        $space-2xlarge,
  3xlarge:        $space-3xlarge,
  4xlarge:        $space-4xlarge,
  5xlarge:        $space-5xlarge,
  6xlarge:        $space-6xlarge,
  // Chassis Spacers
  // TODO: Should be removed later
  0:              0,
  1:              $spacer * .25,
  2:              $spacer * .5,
  3:              $spacer,
  4:              $spacer * 1.5,
  5:              $spacer * 3,
);

Sass utilities API

Spacing utilities are declared in our utilities API in scss/utilities/_padding.scss and scss/utilities/_margin.scss. Learn how to use the utilities API.

scss/utilities/_padding.scss

"padding": (
  responsive: true,
  property: padding,
  class: p,
  values: $spacers
),
"padding-x": (
  responsive: true,
  property: padding-right padding-left,
  class: px,
  values: $spacers
),
"padding-y": (
  responsive: true,
  property: padding-top padding-bottom,
  class: py,
  values: $spacers
),
"padding-top": (
  responsive: true,
  property: padding-top,
  class: pt,
  values: $spacers
),
"padding-end": (
  responsive: true,
  property: padding-right,
  class: pe,
  values: $spacers
),
"padding-bottom": (
  responsive: true,
  property: padding-bottom,
  class: pb,
  values: $spacers
),
"padding-start": (
  responsive: true,
  property: padding-left,
  class: ps,
  values: $spacers
),
// Gap utility
"gap": (
  responsive: true,
  property: gap,
  class: gap,
  values: $spacers
),
"row-gap": (
  responsive: true,
  property: row-gap,
  class: row-gap,
  values: $spacers
),
"column-gap": (
  responsive: true,
  property: column-gap,
  class: column-gap,
  values: $spacers
),

scss/utilities/_margin.scss

"margin": (
  responsive: true,
  property: margin,
  class: m,
  values: map-merge($spacers, (auto: auto))
),
"margin-x": (
  responsive: true,
  property: margin-right margin-left,
  class: mx,
  values: map-merge($spacers, (auto: auto))
),
"margin-y": (
  responsive: true,
  property: margin-top margin-bottom,
  class: my,
  values: map-merge($spacers, (auto: auto))
),
"margin-top": (
  responsive: true,
  property: margin-top,
  class: mt,
  values: map-merge($spacers, (auto: auto))
),
"margin-end": (
  responsive: true,
  property: margin-right,
  class: me,
  values: map-merge($spacers, (auto: auto))
),
"margin-bottom": (
  responsive: true,
  property: margin-bottom,
  class: mb,
  values: map-merge($spacers, (auto: auto))
),
"margin-start": (
  responsive: true,
  property: margin-left,
  class: ms,
  values: map-merge($spacers, (auto: auto))
),
// Negative margin utilities
"negative-margin": (
  responsive: true,
  property: margin,
  class: m,
  values: $negative-spacers
),
"negative-margin-x": (
  responsive: true,
  property: margin-right margin-left,
  class: mx,
  values: $negative-spacers
),
"negative-margin-y": (
  responsive: true,
  property: margin-top margin-bottom,
  class: my,
  values: $negative-spacers
),
"negative-margin-top": (
  responsive: true,
  property: margin-top,
  class: mt,
  values: $negative-spacers
),
"negative-margin-end": (
  responsive: true,
  property: margin-right,
  class: me,
  values: $negative-spacers
),
"negative-margin-bottom": (
  responsive: true,
  property: margin-bottom,
  class: mb,
  values: $negative-spacers
),
"negative-margin-start": (
  responsive: true,
  property: margin-left,
  class: ms,
  values: $negative-spacers
)