From bdfab1482faac3b477ce9722ed64364788f22573 Mon Sep 17 00:00:00 2001 From: Chris Eppstein Date: Wed, 5 May 2010 09:12:59 -0700 Subject: [PATCH] [Docs] Some updates to the blueprint and best_practices tutorials. --- doc-src/content/tutorials/best_practices.haml | 92 --------------- .../content/tutorials/best_practices.markdown | 107 ++++++++++++++++++ doc-src/content/tutorials/blueprint.haml | 6 +- 3 files changed, 109 insertions(+), 96 deletions(-) delete mode 100644 doc-src/content/tutorials/best_practices.haml create mode 100644 doc-src/content/tutorials/best_practices.markdown diff --git a/doc-src/content/tutorials/best_practices.haml b/doc-src/content/tutorials/best_practices.haml deleted file mode 100644 index 0aa111ec..00000000 --- a/doc-src/content/tutorials/best_practices.haml +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Best practices -crumb: Best practices -layout: tutorial ---- - -%h3 - Use a Base stylesheet file -%p - Create a - %code - _base.scss - %a{ :href => "http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#partials" } - partial - to initialize your stylesheets with common variables and ( - %a{ :href => "http://groups.google.com/group/compass-users/browse_frm/thread/0ed216d409476f88" } - often - ) the framework utilities you plan to use: -%h4 - _base.scss -%pre - \$blueprint_grid_columns = 24 - \$blueprint_grid_width = 30px - \$blueprint_grid_margin = 10px - \$font_color = #333 - \ - @import compass/reset.scss - @import compass/utilities.scss - @import blueprint/screen.scss - \ - \// etc. -%p - The - %code - _base.scss - file is also a great place to keep your own custom mixins, so they’re available to any stylesheet that includes it. -%p - Then you can include this file in all other stylesheets: -%h4 - application.scss -%pre - @import base.scss - \ - \#wrapper - \ +container - \ - \// etc. -%p - It is important to define any compass/framework constants that you want to override in base.scss first, before @import-ing the framework files. See - %a{ :href => "http://wiki.github.com/chriseppstein/compass/overriding-constants" } - Overriding Constants - , for an example of where the number of grid columns for blueprint is overridden/set to 32. - %br - Note that you can refer to - %code - _base.scss - without the leading underscore, since it is a - %a{ :href => "http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#partials" } - partial - \. -%h3 - Write your own Custom Mixins -%p - Mixins let you insert any number of style rules into a selector (and its descendants!) with a single line. This is a great way to - %a{ :href => "http://c2.com/cgi/wiki?DontRepeatYourself" } - %span.caps - DRY - up your stylesheet source code and make it much more maintainable. Using mixins will also make your stylesheet look like self-documented source code — like using descriptive method names in a programming language. It’s much more obvious to read something like - %code - +round_corners(6px, #f00) - than the whole list of rules which define that appearance. -%h4 - Mixin Example - -:markdown - Mixin for the html element, so the footer stays at the bottom of the screen. - Relies on the following html structure, and a fixed-height `#footer` element: - - -
- -
- - - -%p - A single line is all that’s needed to use the mixin, which moves the implementation details out of the way and replaces them with a clear and concise label: -%pre - \html - \ @include attach_footer( 54px ) diff --git a/doc-src/content/tutorials/best_practices.markdown b/doc-src/content/tutorials/best_practices.markdown new file mode 100644 index 00000000..e4996d82 --- /dev/null +++ b/doc-src/content/tutorials/best_practices.markdown @@ -0,0 +1,107 @@ +--- +title: Best practices +crumb: Best practices +layout: tutorial +--- +### Use a Base stylesheet file + +Create a `_base.scss` [partial][1] to initialize your stylesheets with common +variables and ([often][2]) the framework utilities you plan to use: + +#### _base.scss + + $blueprint_grid_columns = 24 + $blueprint_grid_width = 30px + $blueprint_grid_margin = 10px + $font_color = #333 + + @import compass/reset.scss + @import compass/utilities.scss + @import blueprint/screen.scss + + // etc. + +The `_base.scss` file is also a great place to keep your own custom mixins, so +they’re available to any stylesheet that includes it. + +Then you can include this file in all other stylesheets: + +#### application.scss + + @import "base"; + + #wrapper { + @include container; + } + + // etc. + +It is important to define any compass/framework constants that you want to override +in base.scss first, before @import-ing the framework files. See [Overriding +Constants][3] , for an example of where the number of grid columns for blueprint +is overridden/set to 32. Note that you can refer to `_base.scss` without the +leading underscore and without the extension, since it is a [partial][1]. + +### Write your own Custom Mixins + +Mixins let you insert any number of style rules into a selector (and its +descendants!) with a single line. This is a great way to [DRY][4] up your +stylesheet source code and make it much more maintainable. Using mixins will +also make your stylesheet look like self-documented source code -- It’s much +more obvious to read something like `@include round-corners(6px, #f00)` than the whole +list of rules which define that appearance. + +#### Presentation-free Markup + +CSS was created to extract the presentational concerns of a website from the +webpage content. Following this best practice theoretically results in a website +that is easier to maintain. However, in reality, the functional limitations of +CSS force abstractions down into the markup to facilitate the [DRY][4] principle +of code maintainability. Sass allows us to move our presentation completely to +the stylesheets because it let's us create abstractions and reuse entirely in +that context. Read [this blog post][5] for more information on the subject. + +Once you have clean markup, style it using Mixins and Inheritance. With clean +and clear abstractions you should be able to read stylesheets and imagine what +the webpage will look like without even loading the page in your web browser. + +If you find your CSS is getting too bloated due to sharing styles between +semantic selectors, it may be time to refactor. For instance this stylesheet +will be unnecessarily bloated: + + @mixin three-column { + .container { @include container; } + .header, + .footer { @include column(24); } + .sidebar { @include column(6); } + article { @include column(10); } + .rightbar { @include column(8); } + } + body#article, + body#snippet, + body#blog-post { @include three-column; } + +Instead, ask yourself "what non-presentational quality do these pages share in +common?" In this case, they are all pages of content, so it's better to apply a +body class of "content" to these pages and then style against that class. + +#### Nest selectors, but not too much. + +It's easier to style a webpage from scratch or starting from some common base +point for your application than it is to contend with unwanted styles bleeding +into your new design. In this way, it is better to use some basic nesting of +styles using some selector early in the markup tree. And then to refactor as patterns of use emerge to reduce bloat. + +It's important to remember that long selectors incur a small rendering +performance penalty that in aggregate can slow down your web page. There is +no need to exactly mimic your document structure in your css. Instead nest +only deep enough that the selector is unique to that part of the document. +For instance, don't use `table thead tr th` when a simple `th` selector will +suffice. This might mean that you have to separate your styles into several +selectors and let the document cascade work to your advantage. + +[1]: http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#partials +[2]: http://groups.google.com/group/compass-users/browse_frm/thread/0ed216d409476f88 +[3]: http://wiki.github.com/chriseppstein/compass/overriding-constants +[4]: http://c2.com/cgi/wiki?DontRepeatYourself +[5]: http://chriseppstein.github.com/blog/2009/09/20/why-stylesheet-abstraction-matters/ diff --git a/doc-src/content/tutorials/blueprint.haml b/doc-src/content/tutorials/blueprint.haml index 2b6b47fe..839c91dd 100644 --- a/doc-src/content/tutorials/blueprint.haml +++ b/doc-src/content/tutorials/blueprint.haml @@ -67,9 +67,7 @@ classnames: %ul %li - %a(href="#") Blueprint Buttons + %a(href="/docs/reference/blueprint/buttons/") Blueprint Buttons %li - %a(href="#") Blueprint Link Icons + %a(href="/docs/reference/blueprint/link_icons/") Blueprint Link Icons -%pre - TODO: Finish Me!