diff --git a/Gemfile b/Gemfile index e1b4ff1..97fb579 100644 --- a/Gemfile +++ b/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" diff --git a/Makefile b/Makefile index a15ae66..dc416f2 100644 --- a/Makefile +++ b/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..." diff --git a/README.md b/README.md index b68f81c..2e763c3 100644 --- a/README.md +++ b/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: diff --git a/package.json b/package.json index 850cc63..cac4f81 100644 --- a/package.json +++ b/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": { diff --git a/stylesheets/_config.sass b/stylesheets/_config.sass deleted file mode 100644 index 411d4aa..0000000 --- a/stylesheets/_config.sass +++ /dev/null @@ -1,9 +0,0 @@ -// Colour palette -// ------------------------------------------------ -$white: #fff -$green: #20e320 - - -// Font stacks -// ------------------------------------------------ -$helvetica: "Helvetica Neue", Helvetica, Arial, sans-serif diff --git a/stylesheets/_fonts.sass b/stylesheets/_fonts.sass deleted file mode 100644 index 05c31a9..0000000 --- a/stylesheets/_fonts.sass +++ /dev/null @@ -1 +0,0 @@ -// @font-face declarations go here diff --git a/stylesheets/_global_state.sass b/stylesheets/_global_state.sass deleted file mode 100644 index 22f382c..0000000 --- a/stylesheets/_global_state.sass +++ /dev/null @@ -1,21 +0,0 @@ -// Most states should be scoped to a module, e.g. -// -// .my-module.is-somestate {} -// or -// .my-module[data-state=somestate] {} -// -// These ones are the exception to the rule (they're super common and globally applicable) - -.is-hidden - display: none - -.is-visually-hidden - // Hide only visually, but have it available for screenreaders: h5bp.com/v - border: 0 - clip: rect(0 0 0 0) - height: 1px - margin: -1px - overflow: hidden - padding: 0 - position: absolute - width: 1px diff --git a/stylesheets/application.sass b/stylesheets/application.sass index 352c46b..9921e48 100644 --- a/stylesheets/application.sass +++ b/stylesheets/application.sass @@ -1,11 +1,5 @@ @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" @@ -13,28 +7,32 @@ // @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/**/*" diff --git a/stylesheets/base/_elements.sass b/stylesheets/base/_elements.sass index d6759a6..96ac8c0 100644 --- a/stylesheets/base/_elements.sass +++ b/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% diff --git a/stylesheets/config/_colors.sass b/stylesheets/config/_colors.sass new file mode 100644 index 0000000..9856e6a --- /dev/null +++ b/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 diff --git a/stylesheets/config/_font_stacks.sass b/stylesheets/config/_font_stacks.sass new file mode 100644 index 0000000..3982358 --- /dev/null +++ b/stylesheets/config/_font_stacks.sass @@ -0,0 +1,2 @@ +$helvetica: "Helvetica Neue", Helvetica, Arial, sans-serif +$bariol: "Bariol", "Comic Sans", sans-serif diff --git a/stylesheets/modules/_grid.scss b/stylesheets/config/_susy.scss similarity index 64% rename from stylesheets/modules/_grid.scss rename to stylesheets/config/_susy.scss index 8ed03be..07c80c8 100644 --- a/stylesheets/modules/_grid.scss +++ b/stylesheets/config/_susy.scss @@ -5,8 +5,3 @@ $grid: ( gutters: 0.3, math: fluid ); - -.grid { - @include container( $grid ); - padding: 0 10px -} diff --git a/stylesheets/fonts/_bariol.scss b/stylesheets/fonts/_bariol.scss new file mode 100644 index 0000000..93d2870 --- /dev/null +++ b/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; +} diff --git a/stylesheets/modules/_grid.sass b/stylesheets/modules/_grid.sass new file mode 100644 index 0000000..f953978 --- /dev/null +++ b/stylesheets/modules/_grid.sass @@ -0,0 +1,3 @@ +.grid + +container($grid) + padding: 0 10px diff --git a/stylesheets/modules/_page.sass b/stylesheets/modules/_page.sass index 9660d89..f5b8536 100644 --- a/stylesheets/modules/_page.sass +++ b/stylesheets/modules/_page.sass @@ -23,4 +23,3 @@ .breakpoint-desktop & +span(last 9 of 12) - \ No newline at end of file diff --git a/stylesheets/utilities/_cf.sass b/stylesheets/utilities/_cf.sass new file mode 100644 index 0000000..3068081 --- /dev/null +++ b/stylesheets/utilities/_cf.sass @@ -0,0 +1,5 @@ +// clearfix +.u-cf:after + content: "" + display: table + clear: both diff --git a/stylesheets/utilities/_hidden.sass b/stylesheets/utilities/_hidden.sass new file mode 100644 index 0000000..7abd243 --- /dev/null +++ b/stylesheets/utilities/_hidden.sass @@ -0,0 +1,2 @@ +.u-hidden + display: none !important diff --git a/stylesheets/utilities/_visually_hidden.sass b/stylesheets/utilities/_visually_hidden.sass new file mode 100644 index 0000000..c287cdf --- /dev/null +++ b/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