CSS

General rules

  • All styles for a component should live within an scss file in that component’s directory. Styles within these files should not affect any other component.
  • Blocks should be listed in the same source order as their corresponding markup. Follow the scssLint rules run during compilation for ordering styles within the blocks.
  • Thanks to BEM, no styles should be nested unless they need a different treatment while inside of a particular modifier/container or are being altered by a js-* class. This reduces compiled CSS and makes any truly necessary overrides much easier.
  • If one style needs to differ between brands, create a variable for it and assign values within _variables-mauijim.scss and _variables-zeal.scss. Larger differences can be accommodated with @if and the $brand variable. See existing styles for examples.
  • Reference cssguidelin.es for all other decisions, such as when to use !important.

Breakpoints

Specific breakpoint sizes can be found in variables.scss. When styling an individual element, they should be ordered smallest to largest. This is because they produce min-width queries and as a result, will affect all page sizes larger than its width (except for the *-only breakpoints). All styles should be placed in the smallest possible breakpoint and overridden within larger ones. For example:

.example-element {
  // Default/mobile styles go here.
  font-size: 1.9rem;
  line-height: 2.0rem;

  @include breakpoint($breakpoint-sm-only) {
    // This breakpoint should only be used for styles that are drastically
    // different than any other breakpoint, and as a result, hard to override
    // in larger breakpoints. In this example we should _not_ be defining the
    // `font-size` or `line-height` here. There is also a `$breakpoint-md-only`
    // breakpoint and the same guidelines apply to it.
  }

  @include breakpoint($breakpoint-md) {
    // Styles that should override the default/mobile styles starting at this
    // page width should go here. The designs delivered for "tablet" typically
    // start to be applied in this breakpoint.
    font-size: 2.7rem;
    line-height: 3.0rem;
  }

  @include breakpoint($breakpoint-lg) {
    // Styles that should override previous styles starting at this page width
    // should go here. If a given breakpoint isn't needed for an element, it
    // shouldn't be included. They're all listed here for demonstration
    // purposes.
  }

  @include breakpoint($breakpoint-xl) {
    // Styles that should override previous styles starting at this page width
    // should go here. The designs delivered for "desktop" typically start to be
    // applied in this breakpoint.
    font-size: 3.2rem;
    line-height: 3.6rem;
  }

  @include breakpoint($page-width-max) {
    // Styles that should override previous styles starting at this page width
    // should go here. This is used for any styles that should take effect when
    // the larger page container has reached its maximum width.
  }
}

File organization/implementation

Maui Jim

In the interest of performance (CSS is render-blocking), all Sass files within the component library compile into 4 different CSS files:

File Pages
global-mauijim.css Add to every single page.
account-mauijim.css Add to every Account page.
checkout-mauijim.css Add to every Cart, Checkout, and Confirmation page.
products-mauijim.css Add to every PLP, PDP, Search, and Customize (i.e., MyMaui) page.

When creating a Sass partial within 02-components or 03-pages, add it to the appropriate scss file given the above criteria (01-elements partials are automatically globbed into global-mauijim.css). List non-globbed partials in alphabetical order.

All components that need styles from a file other than global-mauijim.css will need to add the necessary file to the page preview. This can be done by adding the following in that component’s context (using account-mauijim.css as an example):

"pageCss": [
  "account"
]

Observing that array in existing components can also help determine if it is relying on any styles outside of global-mauijim.css.

Zeal

All Sass partials within the component library compile into one CSS file, app-zeal.css. This file should be added to every page that uses any markup from the component library.

Adding a Sass partial for a new component requires no further action because all files within 01-elements, 02-components, and 03-pages are automatically globbed into app-zeal.css.