@trilogyeducation/bcs-style-library

BCS-Next-Styles

Documentation

Installation

npm install @trilogyeducation/bcs-style-library

Philosophy

A mobile-first approach is applied to all media queries and classes. Styles are initially applied to the smallest screen size described and then overwritten for larger screen sizes.

We use rems and ems often to describe sizes and spaces for consistency throughout various devices and screen sizes.

Staging

BCS-Next-Styles provides a clean canvas through a CSS reset and a box-sizing border-box all declaration. All Elements are cleared of default browser styling and then customized to match our style guide.

Variables and Mixins

Common design patterns are initially defined using Sass variables and mixins, and are then applied to utility classes throughout the library.

Variables

public/scss/variables/

Mixins

public/scss/mixins/

Grid

Grid framework provided by Sass Flexbox Grid.

A grid container element must first be declared with a .row class. Rows' direct descendants must all be columns, meaning container elements with some .col class.

We have customized our grid to use gutters with padding declared in BCS variables.

Optional .col-no-gutter and .col-gutter-lr classes exist for custom padding and nested grids. This is great for inner content spacing.

Here's an example of a responsive grid of card components:

<div class="row">
  <div class="col-xs-12 col-md-6 col-lg-4">
    <div class="card">
      Lorem Khaled Ipsum is a major key to success. Give thanks to the most high. Let me be clear, you have to make it through the jungle to make it to paradise, that’s the key, Lion!
    </div>
  </div>
  <div class="col-xs-12 col-md-6 col-lg-4">
    <div class="card">
      They don’t want us to win.
    </div>
  </div>
  <div class="col-xs-12 col-md-6 col-lg-4">
    <div class="card">
      I told you all this before, when you have a swimming pool, do not use chlorine, use salt water, the healing, salt water is the healing.
    </div>
  </div>
</div>

Visibility

Use visibility classes from Sass Flexbox Grid to hide and show content.

Typography

When BCS-Next-Styles is installed, common typographical elements will be styled appropriately when used in markup. Things like font family, font size, line height, etc will automatically match our style guide.

Type can be customized using built-in utility classes or through custom stylesheets.

Typography Utility classes

public/scss/classes/_typography.scss

Containers

Container classes can be used to stlye BCS components, and to apply border styles and background treatments.

You can view all of the container modifyers here:

public/scss/classes/_containers.scss

Cards

Cards should be used in a grid system. Start with a .row element and nest .col elements inside of it.

Each .card element must be nested inside it's own .col element.

When creating a grid of cards that should all be equal height to their horizontal neighbors, apply an optional .card-group class to the outer .row.

When cards are inside of a .card-group container row, the card should be the only element inside of the .col element because a height: 100%; declaration is applied to all cards in a card group.

Below is an example of several responsive .card elements, some are plain .card containers, others are .card-with-title containers.

.card-with-title containers should each have the following descendants:

• .card-title
• .card-content

.card-title containers can have optional .card-title-month, .card-title-date, and .card-title-time descendants.

And any card can have an optional .card-footer.

Also, notice the derivatives of .card-title: .card-title-icon and .card-title-grade.

<div class="row">
  <div class="col-xs-12 col-md-6">
    <div class="card-with-title">
      <div class="card-title">
        <h4>Wed</h4>
        <p class="card-title-month">September</p>
        <p class="card-title-date">20</p>
        <p class="card-title-time">5:30p - 8:30p</p>
      </div>
      <div class="card-content">
        Lorem Khaled Ipsum is a major key to success. Give thanks to the most high. Let me be clear, you have to make it through the jungle to make it to paradise, that’s the key, Lion!
      </div>
      <div class="card-footer">
        <i class="fa fa-comments text-purple margin-r-2" aria-hidden="true"></i>footer content
      </div>
    </div>
  </div>
  <div class="col-xs-12 col-md-6">
    <div class="card">
      They don’t want us to win.
    </div>
  </div>>
  </div>
  <div class="col-xs-12 col-md-6">
    <div class="card-with-title">
      <div class="card-title-code">
        <i class="fa fa-code" aria-hidden="true"></i>
      </div>
      <div class="card-content">
        They don’t want us to win.
      </div>
      <div class="card-footer">
        <i class="fa fa-comments text-purple margin-r-2" aria-hidden="true"></i>footer content
      </div>
    </div>
  </div>
  <div class="col-xs-12 col-md-6">
    <div class="card-with-title">
      <div class="card-title-grade">
        A+
      </div>
      <div class="card-content">
        I told you all this before, when you have a swimming pool, do not use chlorine, use salt water, the healing, salt water is the healing.
      </div>
    </div>
  </div>
  <div class="col-xs-12 col-md-6 col-lg-4">
    <div class="card">
      Let me be clear, you have to make it through the jungle to make it to paradise.
      <div class="card-footer">
        <i class="fa fa-comments text-purple margin-r-2" aria-hidden="true"></i>footer content
      </div>
    </div>
  </div>
</div>

When you would like to override the default responsive nature of a card you can use the .card-skinny class on a .card element to keep everything vertically stacked as it would be on xs screens.

Video in Card

Any <video> element inside a .card will automatically fill it's container at any breakpoint.

Spacing

Common spacing declarations can be applied through responsive utility classes.

Margins

We use a bank of preset values called margin numbers (1, 2, 3, 4, 5, 6) to define margins. Smaller margin numbers define smaller margin values, larger numbers provide larger values.

• .margin-<margin number>: include a number (1-6) to apply a margin to all sides on all breakpoints.
• .margin-t-<margin number>: include a number (1-6) to apply a margin to the top side on all breakpoints.
• .margin-r-<margin number>: include a number (1-6) to apply a margin to the right side on all breakpoints.
• .margin-b-<margin number>: include a number (1-6) to apply a margin to the bottom side on all breakpoints.
• .margin-l-<margin number>: include a number (1-6) to apply a margin to the left side on all breakpoints.

Ex:

// Apply a $margin-3 to the left side on all breakpoints
<div class="margin-l-3">content</div>

In addition to preset margin numbers, we use breakpoint prefixes to define a range for the styling declarations to be applied to (xs, sm, md, lg, xl).

• .margin-<margin number>-<breakpoint prefix>: include a number (1-6) and a breakpoint prefix to apply a margin to all sides on a specific breakpoint and up.
• .margin-t-<margin number>-<breakpoint prefix>: include a number (1-6) and a breakpoint prefix to apply a margin to the top side on a specific breakpoint and up.
• .margin-r-<margin number>-<breakpoint prefix>: include a number (1-6) and a breakpoint prefix to apply a margin to the right side on a specific breakpoint and up.
• .margin-b-<margin number>-<breakpoint prefix>: include a number (1-6) and a breakpoint prefix to apply a margin to the bottom side on a specific breakpoint and up.
• .margin-l-<margin number>-<breakpoint prefix>: include a number (1-6) and a breakpoint prefix to apply a margin to the left side on a specific breakpoint and up.

margin-number  // applies to all sides, all breakpoints
margin-sideprefix-number  // applies to specific side, all breakpoints
margin-sideprefix-number-breakpointprefix  // applies to specific side at a specific breakpoint and up

// Apply a $margin-3 to the top by default on extra small screens and up
// Then, set $margin-6 to the top on medium screens and up
<div class="margin-t-3 margin-t-6-md">content</div>

Padding

Padding utility classes work the same as margin classes. They have the same number of preset values (6) and use the same breakpoint prefixes.

Forms

Form input elements have default styling applied when the library is loaded. However, you can further customize form elements through utility classes.

public/scss/classes/_forms.scss

Buttons

Buttons elements also come with default styling applied. You can further customize buttons with button utility classes.

public/scss/classes/_buttons.scss

• input[type="submit"] elements are automatically styled to look like a submit button.
• You can also style a container to look like a button by applying the .btn class to any container.

Media queries

All necessary media queries are provided through mobile-first breakpoint range variables.

.element {
  padding: $padding-2;
  @media #{$breakpoint-sm-up} {
      padding: $padding-3;
  }
  @media #{$breakpoint-md-up} {
      padding: $padding-4;
  }
  @media #{$breakpoint-lg-up} {
      padding: $padding-5;
  }
  @media #{$breakpoint-xl-up} {
      padding: $padding-6;
  }
}

If you want to target one specific breakpoint range only, you can use these more specific breakpoint range variables that do not carry styles up:

.element {
  padding: $padding-2;
  @media #{$breakpoint-xs-only} {
      padding: $padding-3;
  }
  @media #{$breakpoint-sm-only} {
      padding: $padding-4;
  }
  @media #{$breakpoint-md-only} {
      padding: $padding-5;
  }
  @media #{$breakpoint-lg-only} {
      padding: $padding-6;
  }
}

Components

Header

The header is fairly simple. Just start with a <header> element, give it a child container with a class .header-content-well, and then nest .header-logo and .header-nav inside the content well.

<header>
  <div class="header-content-well">
    <div class="header-logo">
      <img src="assets/images/unc-logo.png" alt="">
    </div>
    <nav class="header-nav">
      <ul>
        <li><a href="#">Notifications</a></li>
        <li><a href="#">Class Contacts</a></li>
        <li><a href="#">Support</a></li>
        <li><a href="#">Logout</a></li>
      </ul>
    </nav>
  </div>
</header>

Notifications (header nav)

In order to add an unread notifications bubble to the "Notifications" link in the header, give the link <a> element a class of .link-with-unread. Next, nest a <span> with a class .unread inside the <a>.

<ul>
    <li>
        <a href="#" className="link-with-unread">
            <span className="unread">8</span>
            Notifications
        </a>
    </li>
    <li><a href="#">Class Contacts</a></li>
    <li><a href="#">Support</a></li>
    <li><a href="#">Logout</a></li>
</ul>

Modals

Modals require 4 things:

• An outer container with class .modal
• An inner container with class .modal-card
• A nested <i> element with class .modal-card-close
• Content

<div class="modal">
  <div class="modal-card">
    <i class="modal-card-close"></i>
    <h3>Modal Title</h3>
    <p>Lorem ipsum, dolor set modal content.</p>
  </div>
</div>

Modal styles are also provided for the following contexts. Just add the corresponding class to the outer .modal element.

• Warning: .modal-warn
• Error: .modal-error
• Success: .modal-success

Best Practices

We would like for BCS Next Styles to be versatile and to not require much customization on a per-project basis. In the case that you do find yourself writing custom classes, try to either write utility based classes (like text-bold which applies one declaration) or to namespace classnames based on their ancestors and descendants.

For example: .card > .card-title > .card-title-date

This way we can take certain applicable custom classes and easily add them to the library.

Development / Demo Page

Install, serve static files

First, make sure you have Nodemon installed locally. Next, clone the repo, install dependencies, and start the server.

git clone https://github.com/coding-boot-camp/bcs-next-styles.git
cd bcs-next-styles
npm install
npm start

• Navigate to http://localhost:8080/ in your browser.

Build

Build JS and CSS

npm run build

Watch JS and CSS

npm run watch