Utilities

Utilities handle a range common use cases that help us avoid custom Sass. Each utility class should do one job only, and are immutable.

  1. Margins & Padding
  2. Borders & Rounded Corners
  3. Text
  4. Backgrounds
  5. Positioning
  6. Display

Margin & Padding

Basecoat has margin and padding utility classes that you can add to any element. The spacing values are defined in a Sass map in the _variables.scss file, and classes are generated by a function in _utilities.scss. Additionally, Basecoat includes responsive utility classes, in case you want padding or margin only to kick in at certain breakpoints.

// These are our margin and padding utility spacers. The default step size we
// use is 6px. This gives us a key of:
//    0 => 0px
//    1 => 3px
//    2 => 6px (default value)
//    3 => 12px
//    4 => 24px
//    5 => 36px
//    6 => 48px
//    7 => 60px

<div class="m-2">
  This div will have a margin all the way around, with the default value of 6px.
</div>

<div class="pb-5">
  This div will have 36px of padding on its bottom.
</div>

<div class="m-sm-y-2 m-lg-y-5">
  At the sm breakpoint and above, his div will have a margin of 6px on top and bottom. At the lg breakpoint and above, it will have margins of 36px on top and bottom.
</div>

Borders & Rounded Corners

The below utility classes can be added to elements to give them a border or rounded corners.

// Border utilities
.border        { border: $border !important; }
.border-top    { border-top: $border !important; }
.border-right  { border-right: $border !important; }
.border-bottom { border-bottom: $border !important; }
.border-left   { border-left: $border !important; }

.border-y {
  border-top: $border !important;
  border-bottom: $border !important;
}

// Border colors
.border-blue       { border-color: $border-blue !important; }
.border-gray-light { border-color: $border-gray-light !important; }
.border-gray-dark  { border-color: $border-gray-dark !important; }

// Without borders
.border-0        { border: 0 !important; }
.border-top-0    { border-top: 0 !important; }
.border-right-0  { border-right: 0 !important; }
.border-bottom-0 { border-bottom: 0 !important; }
.border-left-0   { border-left: 0 !important; }

// Rounded corners
.rounded-0 { border-radius: 0 !important; }
.rounded-1 { border-radius: $border-radius !important; }
.rounded-2 { border-radius: $border-radius * 2 !important; }

.rounded-top {
  border-top-left-radius: $border-radius !important;
  border-top-right-radius: $border-radius !important;
}

.rounded-bottom {
  border-bottom-right-radius: $border-radius !important;
  border-bottom-left-radius: $border-radius !important;
}

Text

Text Color

You can put the class .text-white on any element to make its text white. Make sure to only apply this class on backgrounds that meet accessibility guidelines.

This text is white and border-bottom

I'm also white, even links like me will work.

<div class="bg-black">
  <h3 class="text-white border-bottom border-white">This text is white and white border below it.</h3>
  <p class="text-white">I'm also white, even <a href="">links like me</a> will work.</p>
</div>

Text Size

If you need your text to be small, use .text-small

I'm little tiny text, smaller than other paragraphs.

<p class="text-small">I'm little tiny text, like a little mouse.</p>

Text Alignment

By default, text is aligned on the left. If you need it to be centered or on the right, you can use a utility class. These alignment classes are responsive, for mobile-first styles.

I'm in the center.

I'm on the left on small screens, but centered on large screens.

<p class="text-center">I'm in the center.</p>
<p class="text-left text-md-center">I'm on the left on small screens, but centered on large screens.</p>

Backgrounds

For applying a color to an element’s background that is different from the body background color.

Use .bg-black to give something a black background.

<div class="bg-black">
  <p class="text-white">Use .bg-black to give something a black background.</p>
</div>

Use .bg-white to give something a white background.

<div class="bg-white">
  <p>Use .bg-white to give something a white background.</p>
</div>

Use .bg-gray-light to give something a gray background.

<div class="bg-gray-light">
  <p>Use .bg-gray-light to give something a gray background.</p>
</div>

Use .bg-theme-color to give something you project's theme color as a background.

<div class="bg-theme-color">
  <p class="text-white">Use .bg-theme-color to give something you project's theme color as a background.</p>
</div>

Use .bg-shade-gradient to give something a shadowed bg. This can be used in combination with any other background utility class.

<div class="bg-shade-gradient">
  <p>Use .bg-shade-gradient to give something a shadowed bg that slowly fades to the inherited bg color.</p>
</div>

Positioning

You can use the following utility classes to set positioning on elements.

I'm always a block element. I'm hidden on small screens, then medium-sized screens, I am inline, and on medium screens and above I become a block element. You can only see me on a small screen. 
<div class="example py-3">
  <span class="d-block">I'm always a block element.</span>
  <span class="d-none d-sm-inline d-lg-block">I'm hidden on small screens, then medium-sized screens, I am inline, and on medium screens and above I become a block element.</span>
  <span class="d-sm-none">You can only see me on a small screen.</span>
</div>

Additional positioning and alignment utilities

// Vertical alignment
.v-align-top { vertical-align: top !important; }
.v-align-middle { vertical-align: middle !important; }

// Whitespace
.ws-normal { white-space: normal !important; }
.ws-nowrap { white-space: nowrap !important; }

// Floats
.right, // legacy
.float-right { float: right !important; }

@each $breakpoint in map-keys($grid-breakpoints) {
  @include breakpoint($breakpoint) {
    .float-#{$breakpoint}-right  { float: right !important; }
  }
}

.left, // legacy
.float-left { float: left !important; }

@each $breakpoint in map-keys($grid-breakpoints) {
  @include breakpoint($breakpoint) {
    .float-#{$breakpoint}-left  { float: left !important; }
  }
}

// Visually hidden
.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0 0 0 0);
  border: 0;

  &.focusable:active,
  &.focusable:focus {
    position: static;
    width: auto;
    height: auto;
    margin: 0;
    overflow: visible;
    clip: auto;
  }
}

Display

Basecoat has utility classes for displaying elements. The mobile-first responsive classes are generated by a Sass function, which creates a class for each of the breakpoints in the breakpoint map.

// Display utilites
.d-block        { display: block !important; }
.d-inline       { display: inline !important; }
.d-inline-block { display: inline-block !important; }
.d-table { display: table !important; }
.d-table-cell { display: table-cell !important; }
.hidden, // legacy
.d-none         { display: none !important; }

// Responsive display utlities
// .d-sm-none, .d-lg-inline, ...
@each $breakpoint in map-keys($grid-breakpoints) {
  @include breakpoint($breakpoint) {
    .d-#{$breakpoint}-block  { display: block !important; }
    .d-#{$breakpoint}-inline  { display: inline !important; }
    .d-#{$breakpoint}-inline-block  { display: inline-block !important; }
    .d-#{$breakpoint}-table  { display: table !important; }
    .d-#{$breakpoint}-table-cell  { display: table-cell !important; }
    .d-#{$breakpoint}-none  { display: none !important; }
  }
}

Media Object

Media Objects as described here can be created using utility classes.

I'm a media element!

Just a regular old, non-responsive media object. The kind that Stubbornella talked about here.

I'm also a media element!

On smaller screens my image stacks, but on larger screens it floats to the left. This text is long to show that it doesn't wrap. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

<div class="clearfix mb-4">
  <div class="float-left mr-3">
    <img src="http://placehold.it/100x100">
  </div>
  <div class="overflow-hidden">
    <h4>I'm a media element!</h4>
    <p>Just a regular old, non-responsive media object. The kind that <a href="http://www.stubbornella.org/content/2010/06/25/the-media-object-saves-hundreds-of-lines-of-code/">Stubbornella talked about here</a>.</p>
  </div>
</div>
<div class="clearfix mb-4">
  <div class="float-lg-left mr-lg-3">
    <img src="http://placehold.it/100x100">
  </div>
  <div class="overflow-hidden">
    <h4>I'm also a media element!</h4>
    <p>On smaller screens my image stacks, but on larger screens it floats to the left. This text is long to show that it doesn't wrap. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
  </div>
</div>