github-migration/compass
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Docs] Some updates to the blueprint and best_practices tutorials.

Browse Source
This commit is contained in:
Chris Eppstein 2010-05-05 09:12:59 -07:00
parent 65ed761447
commit bdfab1482f
3 changed files with 109 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
doc-src/content/tutorials/best_practices.haml
View File

@ -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:
<body>
<div id="root">
<div id="root_footer"></div>
</div>
<div id="footer">
Footer content goes here.
</div>
</body>
%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 )

107
doc-src/content/tutorials/best_practices.markdown Normal file
View File

@ -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/

6
doc-src/content/tutorials/blueprint.haml
View File

@ -67,9 +67,7 @@ classnames:
%ul %ul
%li %li
%a(href="#") Blueprint Buttons %a(href="/docs/reference/blueprint/buttons/") Blueprint Buttons
%li %li
%a(href="#") Blueprint Link Icons %a(href="/docs/reference/blueprint/link_icons/") Blueprint Link Icons
%pre
TODO: Finish Me!