From a564b43ef337842dd089c3ac987a6a8b24969242 Mon Sep 17 00:00:00 2001 From: Ben Smithett Date: Wed, 30 Jul 2014 23:36:05 +1000 Subject: [PATCH 1/4] Attempt to get import-once and sass-globbing working nicely together --- Gemfile | 12 ++++++- Gemfile.lock | 3 ++ Makefile | 3 +- stylesheets/_colors.sass | 12 +++++++ stylesheets/_config.sass | 9 ----- stylesheets/_fonts.sass | 1 - stylesheets/_global_state.sass | 21 ----------- stylesheets/application.sass | 40 ++++++++------------- stylesheets/base/_elements.sass | 14 ++++---- stylesheets/fonts/_bariol.sass | 23 ++++++++++++ stylesheets/fonts/_helvetica.sass | 1 + stylesheets/modules/_grid.scss | 2 ++ stylesheets/utilities/_cf.sass | 5 +++ stylesheets/utilities/_hidden.sass | 2 ++ stylesheets/utilities/_visually_hidden.sass | 10 ++++++ 15 files changed, 93 insertions(+), 65 deletions(-) create mode 100644 stylesheets/_colors.sass delete mode 100644 stylesheets/_config.sass delete mode 100644 stylesheets/_fonts.sass delete mode 100644 stylesheets/_global_state.sass create mode 100644 stylesheets/fonts/_bariol.sass create mode 100644 stylesheets/fonts/_helvetica.sass create mode 100644 stylesheets/utilities/_cf.sass create mode 100644 stylesheets/utilities/_hidden.sass create mode 100644 stylesheets/utilities/_visually_hidden.sass diff --git a/Gemfile b/Gemfile index e1b4ff1..7f42c2b 100644 --- a/Gemfile +++ b/Gemfile @@ -1,6 +1,16 @@ 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" + +# Changes the behaviour of Sass' @import so that files are only imported once +gem 'compass-import-once', :require => 'compass/import-once/activate' +# gem 'compass-import-once', '~> 1.0.4' + gem "susy", "~> 2.1.1" diff --git a/Gemfile.lock b/Gemfile.lock index 3f2d938..085af4c 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,6 +1,8 @@ GEM remote: https://rubygems.org/ specs: + compass-import-once (1.0.4) + sass (>= 3.2, < 3.5) sass (3.3.4) sass-css-importer (1.0.0.beta.0) sass (>= 3.1) @@ -13,6 +15,7 @@ PLATFORMS ruby DEPENDENCIES + compass-import-once sass (~> 3.3.4) sass-css-importer (~> 1.0.0.beta.0) sass-globbing (~> 1.1.0) diff --git a/Makefile b/Makefile index a15ae66..eec4a0a 100644 --- a/Makefile +++ b/Makefile @@ -14,9 +14,10 @@ sass: stylesheets/*.sass @echo "Compiling Sass..." @sass -r sass-css-importer \ -r sass-globbing \ + -r 'compass/import-once/activate' \ -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/stylesheets/_colors.sass b/stylesheets/_colors.sass new file mode 100644 index 0000000..64b8400 --- /dev/null +++ b/stylesheets/_colors.sass @@ -0,0 +1,12 @@ +// 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.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..84f04be 100644 --- a/stylesheets/application.sass +++ b/stylesheets/application.sass @@ -1,40 +1,30 @@ @charset "utf-8" +// You should only include base styles, modules & utilities in this top level file. -// 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/**/*" +// Whether you glob import everything, or manually import the modules & utilities +// required for this particular CSS bundle is up to you. -// Global config variables, colour palette, etc -@import "config" +// Everything else (functions, mixins, fonts, animations, color variables) should be +// @imported at the top of the module that actually requires it. Yay dependency management! -// @font-face declarations -@import "fonts" - -// Named keyframe animations -@import "animations/**/*" +// Base styles // ------------------------------------------------ - - - -// Vendor libraries that actually output 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..1491d14 100644 --- a/stylesheets/base/_elements.sass +++ b/stylesheets/base/_elements.sass @@ -1,14 +1,14 @@ -// Obvs from http://www.paulirish.com/2012/box-sizing-border-box-ftw/ -*, -*:before, -*:after - box-sizing: border-box - -// 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/fonts/_bariol.sass b/stylesheets/fonts/_bariol.sass new file mode 100644 index 0000000..e9c0e6c --- /dev/null +++ b/stylesheets/fonts/_bariol.sass @@ -0,0 +1,23 @@ +@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; +} + +$bariol: "Bariol", "Comic Sans", sans-serif diff --git a/stylesheets/fonts/_helvetica.sass b/stylesheets/fonts/_helvetica.sass new file mode 100644 index 0000000..09eb516 --- /dev/null +++ b/stylesheets/fonts/_helvetica.sass @@ -0,0 +1 @@ +$helvetica: "Helvetica Neue", Helvetica, Arial, sans-serif diff --git a/stylesheets/modules/_grid.scss b/stylesheets/modules/_grid.scss index 8ed03be..adb20b4 100644 --- a/stylesheets/modules/_grid.scss +++ b/stylesheets/modules/_grid.scss @@ -1,3 +1,5 @@ +@import "susy" + $grid: ( columns: 12, container: 1025px, 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..b23f0dd --- /dev/null +++ b/stylesheets/utilities/_hidden.sass @@ -0,0 +1,2 @@ +.u-hidden + display: none 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 From 71dab6c4baf6781f16e672c339fadcdc90f02fc2 Mon Sep 17 00:00:00 2001 From: Ben Smithett Date: Sat, 2 Aug 2014 19:35:56 +1000 Subject: [PATCH 2/4] Remove import-once and update README --- Gemfile | 4 --- Gemfile.lock | 3 -- Makefile | 1 - README.md | 35 +++++++++++++++---- package.json | 2 +- stylesheets/application.sass | 18 +++++++--- stylesheets/base/_elements.sass | 4 +++ stylesheets/{ => config}/_colors.sass | 1 - .../_font_stacks.sass} | 1 + .../{modules/_grid.scss => config/_susy.scss} | 7 ---- .../fonts/{_bariol.sass => _bariol.scss} | 2 -- stylesheets/modules/_grid.sass | 3 ++ stylesheets/modules/_page.sass | 1 - stylesheets/utilities/_hidden.sass | 2 +- 14 files changed, 52 insertions(+), 32 deletions(-) rename stylesheets/{ => config}/_colors.sass (99%) rename stylesheets/{fonts/_helvetica.sass => config/_font_stacks.sass} (57%) rename stylesheets/{modules/_grid.scss => config/_susy.scss} (59%) rename stylesheets/fonts/{_bariol.sass => _bariol.scss} (95%) create mode 100644 stylesheets/modules/_grid.sass diff --git a/Gemfile b/Gemfile index 7f42c2b..97fb579 100644 --- a/Gemfile +++ b/Gemfile @@ -9,8 +9,4 @@ gem "sass-css-importer", "~> 1.0.0.beta.0" # Not required for Rails 3.1+ gem "sass-globbing", "~> 1.1.0" -# Changes the behaviour of Sass' @import so that files are only imported once -gem 'compass-import-once', :require => 'compass/import-once/activate' -# gem 'compass-import-once', '~> 1.0.4' - gem "susy", "~> 2.1.1" diff --git a/Gemfile.lock b/Gemfile.lock index 085af4c..3f2d938 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,8 +1,6 @@ GEM remote: https://rubygems.org/ specs: - compass-import-once (1.0.4) - sass (>= 3.2, < 3.5) sass (3.3.4) sass-css-importer (1.0.0.beta.0) sass (>= 3.1) @@ -15,7 +13,6 @@ PLATFORMS ruby DEPENDENCIES - compass-import-once sass (~> 3.3.4) sass-css-importer (~> 1.0.0.beta.0) sass-globbing (~> 1.1.0) diff --git a/Makefile b/Makefile index eec4a0a..dc416f2 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,6 @@ sass: stylesheets/*.sass @echo "Compiling Sass..." @sass -r sass-css-importer \ -r sass-globbing \ - -r 'compass/import-once/activate' \ -r susy \ stylesheets/application.sass:css/application.css \ stylesheets/application-lt-ie9.sass:css/application-lt-ie9.css --trace diff --git a/README.md b/README.md index b68f81c..eb67cfe 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 in 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 writing any default 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..15a17d9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "style", - "version": "2.0.0", + "version": "2.0.1", "description": "A starting point for scalable, maintainable CSS architecture.", "main": "index.html", "devDependencies": { diff --git a/stylesheets/application.sass b/stylesheets/application.sass index 84f04be..9921e48 100644 --- a/stylesheets/application.sass +++ b/stylesheets/application.sass @@ -1,12 +1,20 @@ @charset "utf-8" -// You should only include base styles, modules & utilities in this top level file. +// Vendor mixin/function libraries +@import "susy" -// Whether you glob import everything, or manually import the modules & utilities -// required for this particular CSS bundle is up to you. +// Your mixins & functions +// @import "functions/**/*" +@import "mixins/**/*" -// Everything else (functions, mixins, fonts, animations, color variables) should be -// @imported at the top of the module that actually requires it. Yay dependency management! +// Global config variables: colors, font stacks, etc +@import "config/**/*" + +// @font-face webfonts +@import "fonts/**/*" + +// @keyframe animations +@import "animations/**/*" // Base styles diff --git a/stylesheets/base/_elements.sass b/stylesheets/base/_elements.sass index 1491d14..96ac8c0 100644 --- a/stylesheets/base/_elements.sass +++ b/stylesheets/base/_elements.sass @@ -1,3 +1,7 @@ +// 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. + html box-sizing: border-box font-family: $helvetica diff --git a/stylesheets/_colors.sass b/stylesheets/config/_colors.sass similarity index 99% rename from stylesheets/_colors.sass rename to stylesheets/config/_colors.sass index 64b8400..9856e6a 100644 --- a/stylesheets/_colors.sass +++ b/stylesheets/config/_colors.sass @@ -9,4 +9,3 @@ $white: #fff $green: #20e320 - diff --git a/stylesheets/fonts/_helvetica.sass b/stylesheets/config/_font_stacks.sass similarity index 57% rename from stylesheets/fonts/_helvetica.sass rename to stylesheets/config/_font_stacks.sass index 09eb516..3982358 100644 --- a/stylesheets/fonts/_helvetica.sass +++ b/stylesheets/config/_font_stacks.sass @@ -1 +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 59% rename from stylesheets/modules/_grid.scss rename to stylesheets/config/_susy.scss index adb20b4..07c80c8 100644 --- a/stylesheets/modules/_grid.scss +++ b/stylesheets/config/_susy.scss @@ -1,5 +1,3 @@ -@import "susy" - $grid: ( columns: 12, container: 1025px, @@ -7,8 +5,3 @@ $grid: ( gutters: 0.3, math: fluid ); - -.grid { - @include container( $grid ); - padding: 0 10px -} diff --git a/stylesheets/fonts/_bariol.sass b/stylesheets/fonts/_bariol.scss similarity index 95% rename from stylesheets/fonts/_bariol.sass rename to stylesheets/fonts/_bariol.scss index e9c0e6c..93d2870 100644 --- a/stylesheets/fonts/_bariol.sass +++ b/stylesheets/fonts/_bariol.scss @@ -19,5 +19,3 @@ font-weight: normal; font-style: normal; } - -$bariol: "Bariol", "Comic Sans", sans-serif 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/_hidden.sass b/stylesheets/utilities/_hidden.sass index b23f0dd..7abd243 100644 --- a/stylesheets/utilities/_hidden.sass +++ b/stylesheets/utilities/_hidden.sass @@ -1,2 +1,2 @@ .u-hidden - display: none + display: none !important From ed6c2f6ce0b985118b3b77805f96f52cd87aa974 Mon Sep 17 00:00:00 2001 From: Ben Smithett Date: Sat, 2 Aug 2014 19:38:54 +1000 Subject: [PATCH 3/4] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eb67cfe..2e763c3 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Styles are organised into three basic categories: ### Base -The number of core default styles that you build the rest of your application in 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. +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 @@ -99,7 +99,7 @@ Utilities are borrowed directly from [SUIT](https://github.com/suitcss/suit/blob `!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 writing any default styles, use them in situations where you would otherwise need to define a new module class. +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: From 272efdaf57b0fe1158eaecb02f46e0ec6b5f8cd4 Mon Sep 17 00:00:00 2001 From: Ben Smithett Date: Sat, 2 Aug 2014 19:40:23 +1000 Subject: [PATCH 4/4] Update version in package.json --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 15a17d9..cac4f81 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "style", - "version": "2.0.1", + "version": "3.0.0", "description": "A starting point for scalable, maintainable CSS architecture.", "main": "index.html", "devDependencies": {