Docs



Styleguide

This styleguide was created using Fabricator. It was primarily created for Blizzard OWL which uses it's dist folder as the public assets folder for the app.


Note: This documentation was created by Haven for the original outsourcing of the OWL project. Some of it may or may not be relevant anymore as we haven't fully updated the docs to match our new changes.


Styleguide Specific Styles

Sometimes there is a default style for a component that we know won't work in the context of the styleguide. For example, some component might need to be position: fixed in the app, but not in the styleguide.

In these cases, you can add overrides in the stylguide overrides file located at src/assets/fabricator/styles/partials/_blizzard-styleguide-only.scss

Bootstrap

This styleguide extends Bootstrap 3 SASS. You can use any of the Bootstrap classes provided from it's documention. Most layout and scaffolding is provide by Bootstrap.

Ex: Bootstrap Grid Classes

<div class="row">
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
  <div class="col-md-1">.col-md-1</div>
</div>
<div class="row">
  <div class="col-md-8">.col-md-8</div>
  <div class="col-md-4">.col-md-4</div>
</div>
<div class="row">
  <div class="col-md-4">.col-md-4</div>
  <div class="col-md-4">.col-md-4</div>
  <div class="col-md-4">.col-md-4</div>
</div>
<div class="row">
  <div class="col-md-6">.col-md-6</div>
  <div class="col-md-6">.col-md-6</div>
</div>
Usage of Bootstrap in workflow

We first import the base Bootstrap UI library, then we have a directory in src/assets/toolkit/styles/ called bootstrap-overwatch. This contains the OWL flavored Bootstrap overrides.

We import the Bootstrap base, then the OWL Bootstrap overrides, then finally our custom styles last.

Css Naming Convention

Our chosen naming convention for this styleguide is SuitCSS.


.MyComponent {}
.MyComponent.is-animating {}
.MyComponent--modifier {}

.MyComponent-part {}
.MyComponent-anotherPart {}

Namespacing

Namespacing is used to help group Sass files and classes by their purpose in the overall architecture of the styleguide. It is based on a technique by Harry Roberts.

Namespacing Guide:


// Object Namespace
.o-Object {}

// Component Namespace
.c-Component {}

// Utility Namespace
.u-utility {}

// Vendor Namespace
.v-Vendor {}

In addition to this, we namespace file names for settings, mixins, functions, etc.

  • Settings : _s
  • Elements : _e
  • General : _g
  • Tools : _t-mx, _t-fn

Javascript

This styleguide uses webpack to bundle ES6 javascript into browser compatible Javascript.

const foo = 'bar'

The main js file is toolkit.js, but there are some support files:

  • config.js Global settings for things like state, timings and easings.
  • util/ A collection of utility functions.
  • features/ Various features of the site are broken off into their own files for ease of maintenance. For example, extended lightbox functionality for PhotoSwipe.

Sliders

There are a number of use cases for a slider on OWL. For this we utilize Slick slider which gives us a bunch of configurable options on how to present. slider content. There is one basic configuration that most sliders will be able to use:

/* Default MediaSlider */
const $sliders = $('.js-slider');
const sliderOpts = {
    speed: timings.slower,
    cssEase: easings.easeOutExpo,
    dots: true,
    arrows: true,
    mobileFirst: true,
    infinite: false,
    variableWidth: true,
    draggable: true,
    customPaging: function(slider, i) {
        return sliderPaging;
    },
    prevArrow: sliderArrowTheme('prev'),
    nextArrow: sliderArrowTheme('next'),
    responsive: [
        {
            breakpoint: 1200,
            settings: {
                draggable: false,
                slidesToShow: 5,
                slidesToScroll: 5
            }
        }
    ]
};

// Initialize slider
$sliderSchedule.slick(sliderScheduleOpts);

By default, all sliders are variable width, which allows its slides to "peakaboo" around the edges of the main slider content. Also, by default, we set the max slides count to 5. To override these defaults, use a special data-attribute to pass the option through the HTML markup:

data-slick='{"responsive": [{"breakpoint": 1200, "settings": { "draggable": false, "slidesToShow": 3, "slidesToScroll": 3 }}]}'

In this example, we override the slides that should be framed in the slider to 3 instead of 5. Also note the use of double and single quotes used in the markup. This is important for Slick to parse the json.

For lightboxed content, we are extending PhotoSwipe. There are a few problems with the implementation though.

  • UI elements need to be customized to fit the design comps. The default UI bar does not fit the design aesthetic, so some custom solution is still needed.
  • PhotoSwipe is not built for HTML content, which is primarily what we are using it for. If the decision is made to continue on with PhotoSwipe then some handler for content overflow on small screens is needed.

To add elements to the array of lightbox elements on a page, you must add the following js class: js-lightbox

Additionally, we need data on what is being lightboxed.

For all content:

data-title : content title

data-desc : content description

For image content:

data-width : the lightbox needs to know the max width allowed for the HTML content

For video content:

data-youtube : the lightbox needs to know the YouTube ID.

Example of lightbox markup:
<a href="https://www.youtube.com/watch?v=YaLopjibdOY" class="btn btn-primary js-lightbox" data-youtube="YaLopjibdOY" data-title="Horizontal photo caption such text" data-desc="Lorem ipsum dolor sit amet...">Video</a>

Integration And Assets

For integration of this styleguide and it's assets into an app, uses a method to copy the 'dist' folder into the assets folder of your other project, via 'npm install' or 'npm link', depending on your setup.

Integration has been done on the blizzard-owl repo using npm link into its public folder.

The idea for blizzard-owl is that we copy the unminified, unoptimized assets into the repo, and let that project continue the workflow by using gulp to create production assets.

For more information on this concept, see the README.md for blizzard-owl.