Merge pull request #10 from bensmithett/dev

Version 3

Gemfile

@@ -1,6 +1,12 @@
 source 'https://rubygems.org'
 
 gem "sass", "~> 3.3.4"
+
+# Lets you import plain CSS files with Sass @import
 gem "sass-css-importer", "~> 1.0.0.beta.0"
-gem "sass-globbing", "~> 1.1.0"     # Not required for Rails 3.1+
+
+# Lets you do glob @imports in Sass
+# Not required for Rails 3.1+
+gem "sass-globbing", "~> 1.1.0"
+
 gem "susy", "~> 2.1.1"

Makefile

@@ -16,7 +16,7 @@ sass: stylesheets/*.sass
 				-r sass-globbing \
 				-r susy \
 				stylesheets/application.sass:css/application.css \
-				stylesheets/application-lt-ie9.sass:css/application-lt-ie9.css
+				stylesheets/application-lt-ie9.sass:css/application-lt-ie9.css --trace
 
 autoprefixer: css/**
 	@echo "Autoprefixing..."

README.md

@@ -31,17 +31,30 @@ Install dependencies:
 
 Then run `make` or `make watch` to compile CSS into `css/`
 
-## Modules
+## Outline
 
-Modules are the core of Style's architecture. A module:
+Styles are organised into three basic categories:
+
+- Base 
+- Modules
+- Utilities
+
+### Base
+
+The number of core default styles that you build the rest of your application on top of should be kept as low as possible. [Normalize.css](http://necolas.github.com/normalize.css/) plus the small number of other base styles specified in this repo are usually enough.
+
+### Modules
+
+Modules (you might also know them as Components, Objects or Blocks) are the core of Style's architecture. A module:
 
 - Is defined in its own file (eg `modules/_my_module.sass`)
 - Is isolated, reusable & disposable.
+- Depends only on your base styles (in this case, Normalize + a small number of additional defaults)
 - Has no knowledge of its context (i.e. doesn't depend on styles from a particular parent element - it can be rendered anywhere)
 - Minimises its own [depth of applicability](http://smacss.com/book/applicability) so that it can safely contain other modules
 - Has no context-specific dimensions. Read [Objects in Space](https://medium.com/objects-in-space/f6f404727) for more on this.
 
-### Simple module
+#### Simple module
 
 Here's what a simple module, `/stylesheets/modules/_simple_widget.sass`, might look like:
 
@@ -50,9 +63,10 @@ Here's what a simple module, `/stylesheets/modules/_simple_widget.sass`, might l
   color: goldenrod
 ```
 
-### Complex module
+#### Complex module
 
 Here's a slightly more complex module, `/stylesheets/modules/_comment.sass`:
+
 ```sass
 .comment
   color: fuchsia
@@ -65,9 +79,8 @@ Here's a slightly more complex module, `/stylesheets/modules/_comment.sass`:
   &[data-state=loading]
     background: url(spinner.gif)
 
-// A modified comment
+// Modifier classes can add extra styles for certain situations.
 .comment--important
-  @extend .comment
   font-weight: bold
 
 // A submodule (some module that *must* be a child of .comment)
@@ -78,6 +91,16 @@ Here's a slightly more complex module, `/stylesheets/modules/_comment.sass`:
   width: 100px
 ```
 
+For a more in-depth look at how to use modifier classes, state classes & state data attributes, read [BEM Modifiers: multiple classes vs @extend](http://bensmithett.com/bem-modifiers-multiple-classes-vs-extend/).
+
+### Utilities
+
+Utilities are borrowed directly from [SUIT](https://github.com/suitcss/suit/blob/master/doc/utilities.md). They are helper classes that define common utility styles and can be used anywhere on any element.
+
+`!important` is OK in utility classes, as you'll usually want them to override a module's styles. E.g., I'd always expect `u-hidden` to hide an element even if it also has module class that specifies `display: block`.
+
+I tend to use them sparingly. Don't be afraid to write `float: left` in a module even if you have a utility class that does the same thing. Instead of using utility classes to avoid duplicating any styles, use them in situations where you would otherwise need to define a new module class.
+
 ## Media queries
 Media queries in CSS are for chumps. [Use metaquery](http://glenmaddern.com/metaquery-and-the-end-of-media-queries/) for mobile-first responsive modules:
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "style",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "A starting point for scalable, maintainable CSS architecture.",
   "main": "index.html",
   "devDependencies": {

stylesheets/application.sass

@@ -1,40 +1,38 @@
 @charset "utf-8"
 
-
-// Module dependencies
-// ------------------------------------------------
-// TODO: Nuke this section & import dependencies in modules where required (using import-once)
-// import-once currently isn't working with globbing https://github.com/chriseppstein/compass/issues/1529
-
 // Vendor mixin/function libraries
 @import "susy"
 
 // Your mixins & functions
 // @import "functions/**/*"
 @import "mixins/**/*"
 
-// Global config variables, colour palette, etc
-@import "config"
+// Global config variables: colors, font stacks, etc
+@import "config/**/*"
 
-// @font-face declarations
-@import "fonts"
+// @font-face webfonts
+@import "fonts/**/*"
 
-// Named keyframe animations
+// @keyframe animations
 @import "animations/**/*"
 
-// ------------------------------------------------
-
-
 
-// Vendor libraries that actually output styles
+// Base styles
+// ------------------------------------------------
+// Normalize.css
 // Special syntax for importing plain CSS files via https://github.com/chriseppstein/sass-css-importer
 @import "CSS:./../bower_components/normalize-css/normalize"
 
-// Base element styles
+// Our own base styles
 @import "base/**/*"
 
+
 // Modules
+// ------------------------------------------------
 @import "modules/**/*"
 
-// Global state classes
-@import "global_state"
+
+// Utilities
+// ------------------------------------------------
+// See https://github.com/suitcss/suit/blob/master/doc/utilities.md
+@import "utilities/**/*"

stylesheets/base/_elements.sass

@@ -1,14 +1,18 @@
-// Obvs from http://www.paulirish.com/2012/box-sizing-border-box-ftw/
-*,
-*:before,
-*:after
-  box-sizing: border-box
+// Resist the temptation to define lots of default styles in here!
+// Most of the time, Normalize.css plus these few additions are all you need.
+// Scope all other styles to a module or utility so you're building on small, simple core base styles.
 
-// The basics
 html
+  box-sizing: border-box
   font-family: $helvetica
   height: 100%
 
+// http://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice/
+*,
+*:before,
+*:after
+  box-sizing: inherit
+
 body
   background-color: $white
   height: 100%

stylesheets/config/_colors.sass

@@ -0,0 +1,11 @@
+// Color palette
+// See http://bensmithett.com/stop-using-so-many-sass-variables/
+//
+// ())___Crayola___))>
+// ())___Crayola___))>
+// ())___Crayola___))>
+// ())___Crayola___))>
+// ())___Crayola___))>
+
+$white: #fff
+$green: #20e320

stylesheets/config/_font_stacks.sass

@@ -0,0 +1,2 @@
+$helvetica: "Helvetica Neue", Helvetica, Arial, sans-serif
+$bariol: "Bariol", "Comic Sans", sans-serif

stylesheets/modules/_grid.scss → stylesheets/config/_susy.scss

@@ -5,8 +5,3 @@ $grid: (
   gutters: 0.3,
   math: fluid
 );
-
-.grid {
-  @include container( $grid );
-  padding: 0 10px
-}

stylesheets/fonts/_bariol.scss

@@ -0,0 +1,21 @@
+@font-face {
+    font-family: 'Bariol';
+    src: url('fonts/bariol_bold-webfont.eot');
+    src: url('fonts/bariol_bold-webfont.eot?#iefix') format('embedded-opentype'),
+         url('fonts/bariol_bold-webfont.woff') format('woff'),
+         url('fonts/bariol_bold-webfont.ttf') format('truetype'),
+         url('fonts/bariol_bold-webfont.svg#bariol_boldbold') format('svg');
+    font-weight: bold;
+    font-style: normal;
+}
+
+@font-face {
+    font-family: 'Bariol';
+    src: url('fonts/bariol_regular-webfont.eot');
+    src: url('fonts/bariol_regular-webfont.eot?#iefix') format('embedded-opentype'),
+         url('fonts/bariol_regular-webfont.woff') format('woff'),
+         url('fonts/bariol_regular-webfont.ttf') format('truetype'),
+         url('fonts/bariol_regular-webfont.svg#bariol_regularregular') format('svg');
+    font-weight: normal;
+    font-style: normal;
+}

stylesheets/modules/_grid.sass

@@ -0,0 +1,3 @@
+.grid
+  +container($grid)
+  padding: 0 10px

stylesheets/modules/_page.sass

@@ -23,4 +23,3 @@
 
   .breakpoint-desktop &
     +span(last 9 of 12)
-

stylesheets/utilities/_cf.sass

@@ -0,0 +1,5 @@
+// clearfix
+.u-cf:after
+  content: ""
+  display: table
+  clear: both

stylesheets/utilities/_hidden.sass

@@ -0,0 +1,2 @@
+.u-hidden
+  display: none !important

stylesheets/utilities/_visually_hidden.sass

@@ -0,0 +1,10 @@
+// Hide only visually, but have it available for screenreaders: h5bp.com/v
+.u-visually-hidden
+  border: 0
+  clip: rect(0 0 0 0)
+  height: 1px
+  margin: -1px
+  overflow: hidden
+  padding: 0
+  position: absolute
+  width: 1px