Merge pull request #113 from cb-talent-development/topic/EM-1444-rear…

…range-style-base

EM-1444: Rearrange Style Base

README.md

@@ -12,10 +12,12 @@ Add and install with Yarn:
 $ yarn add employer-style-base
 ```
 
-Now, import `sass/base` after [Bourbon](http://bourbon.io/), and before any grids or application sources in your main `application.scss`. For example:
+Now, import `sass/base` after any resets, [Bourbon](http://bourbon.io/) and [FontAwesome](http://fontawesome.io/), and before any grids and application sources in your main `application.scss`. For example:
 
 ```scss
+@import 'reset';
 @import 'bourbon/app/assets/stylesheets/bourbon';
+@import 'font-awesome';
 @import 'employer-style-base/sass/base';
 @import 'some-grid-foundation';
 
@@ -30,23 +32,35 @@ You may use any grid framework of your choosing. We have, however, built a [Neat
 
 ### What's included
 
-At the moment, only uncompiled Sass source files are available for consumption. That means your application will need to perform the precompilation, whether it be through Webpack, Gulp, Grunt, Rails asset pipeline, etc. Do note that `employer-style-base` depends upon and includes [Bourbon](http://bourbon.io/) for basic Sass mixins. Additionally, this library includes its own reset, scoped to `employer-scope`.
+At the moment, only uncompiled Sass source files are available for consumption. That means your application will need to perform the precompilation, whether it be through Webpack, Gulp, Grunt, Rails asset pipeline, etc. Do note that `employer-style-base` depends upon and includes [Bourbon](http://bourbon.io/) for basic Sass mixins.
 
 The current layout of this library is heavily inspired by [Bitters](http://bitters.bourbon.io/), a wonderful boilerplate of common-sense Sass conventions and structure. Our outline looks a little something like this:
 
 ```
 dist/
 ├── ... >> Not yet used
 sass/ >> The bulk of the styling itself
-├── directives/ >> Mixins and @extend-only selectors, AKA useful functions to build a site with
-└── variables/ >> Re-usable color and sizing variables
+├── directives/ >> Useful mixins and functions to build a site with
+│   ├── 00_variables/ >> Re-usable color and sizing variables
+│   ├── 01_tools/ >> Globally used mixins and functions
+│   ├── 02_base_components/ >> Small components that are typically used in larger components
+│   ├── 03_components/ >> Large components and features; items that make use of 02_base_components
+│   └── 04_utilities/ >> Helper classes and overrides
+└── selectors/ >> Classes and element selectors which implement directives
 ```
 
 ### Contributing
 
+#### Mixins over Extends and Classes
+Our projects prefer semantic (BEM) class names that are specific to their use and which use the directives created here, over classes that are reused. For that reason, contributions should typically be added as mixins.
+
+*Adding Classes* - Reusable classes are primarily buttons, tooltips, and other commonly repeated elements. That said, do include a class or element counterpart to your directives in the `selectors/` directory for use by 3rd party projects that do not consume the Sass files.
+
+*Do Not Add Extends* - For [predictability](https://www.sitepoint.com/avoid-sass-extend/) and [performance](https://csswizardry.com/2016/02/mixins-better-for-performance/), use mixins instead.
+
 #### Adding Directives
 
-After adding a new directive to [`sass/directives/`](sass/directives/), `@import` it into the [`variables/_base.scss`](sass/_base.scss)
+After adding a new directive to [`sass/directives/`](sass/directives/), remember to `@import` it into the [`_base.scss`](sass/_base.scss) file.
 
 #### Updating the Version
 

sass/_base.scss

@@ -1,58 +1,79 @@
-// Variables
-@import "variables/breakpoints.scss";
-@import "variables/colors";
-@import "variables/sizing";
-@import "variables/animations";
-@import "typography";
-@import "variables/top_bar";
-
-// SASS Directives
-@import "directives/accents";
-@import "directives/accordion";
-@import "directives/aspect_ratio";
-@import "directives/boxes";
-@import "directives/button";
-@import "directives/cards";
-@import "directives/carousels";
-@import "directives/clearfix";
-@import "directives/ellipsis";
-@import "directives/flashes";
-@import "directives/flyout";
-@import "directives/gradients";
-@import "directives/groups";
-@import "directives/headers";
-@import "directives/headings";
-@import "directives/media";
-@import "directives/modals";
-@import "directives/speech_bubble";
-@import "directives/tabs";
-@import "directives/tables";
-@import "directives/toggles";
-@import "directives/tooltips";
-@import "directives/visibility";
-@import "directives/visual-guides";
-@import "directives/z_index";
-
-@import "buttons";
-
-@import "content_grids";
-@import "cta";
-@import "forms";
-@import "read_more";
-@import "tables";
+// 00 Variables - Re-usable color and sizing variables (Order is specific)
+@import "directives/00_variables/breakpoints.scss";
+@import "directives/00_variables/colors";
+@import "directives/00_variables/sizing";
+@import "directives/00_variables/animations";
+@import "directives/00_variables/typography";
+@import "directives/00_variables/top_bar";
 
-.employer-scope {
-  // Reset
-  // @import 'reset';
+// 01 Tools - globally used mixins and functions
+@import "directives/01_tools/aspect_ratio";
+@import "directives/01_tools/flashes";
+@import "directives/01_tools/z_index";
+
+// 02 Base Components - small components that are typically used in larger components
+@import "directives/02_base_components/type_styles";
+
+@import "directives/02_base_components/accents";
+@import "directives/02_base_components/boxes";
+@import "directives/02_base_components/button";
+@import "directives/02_base_components/ellipsis";
+@import "directives/02_base_components/gradients";
+@import "directives/02_base_components/groups";
+@import "directives/02_base_components/headings";
+@import "directives/02_base_components/modals";
+@import "directives/02_base_components/tabs";
+@import "directives/02_base_components/toggles";
+@import "directives/02_base_components/forms";
+
+// 03 Components - large components and features
+@import "directives/03_components/accordion";
+@import "directives/03_components/cards";
+@import "directives/03_components/carousels";
+@import "directives/03_components/flyout";
+@import "directives/03_components/headers";
+@import "directives/03_components/media";
+@import "directives/03_components/speech_bubble";
+@import "directives/03_components/tables";
+@import "directives/03_components/tooltips";
+@import "directives/03_components/visual-guides";
+
+// 04 Utilities - helper classes and overrides
+@import "directives/04_utilities/clearfix";
+@import "directives/04_utilities/visibility";
 
-  // Typography and Elements
+
+// Selectors - classes and element selectors which implement directives
+@import "selectors/accents";
+@import "selectors/accordions";
+@import "selectors/boxes";
+@import "selectors/buttons";
+@import "selectors/cards";
+@import "selectors/carousels";
+@import "selectors/content_grids";
+@import "selectors/cta";
+@import "selectors/flashes";
+@import "selectors/forms";
+@import "selectors/gradients";
+@import "selectors/headers";
+@import "selectors/media";
+@import "selectors/modals";
+@import "selectors/navigation";
+@import "selectors/read_more";
+@import "selectors/speech_bubble";
+@import "selectors/tables";
+@import "selectors/toggles";
+@import "selectors/tooltips";
+@import "selectors/typography";
+@import "selectors/utilities";
+
+
+.employer-scope {
   @include base-body-copy;
   @include font-feature-settings("kern", "liga", "frac", "pnum");
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
   background-color: $base-background-color;
   color: $text-color-grey;
   font-family: $base-font-family;
-
-  // @import "lists";
 }