{"id":21773,"date":"2013-05-29T05:02:59","date_gmt":"2013-05-29T12:02:59","guid":{"rendered":"http:\/\/css-tricks.com\/?p=21773"},"modified":"2020-01-09T22:54:15","modified_gmt":"2020-01-10T05:54:15","slug":"sass-style-guide","status":"publish","type":"post","link":"https:\/\/css-tricks.com\/sass-style-guide\/","title":{"rendered":"Sass Style Guide"},"content":{"rendered":"

With more people than ever writing in Sass, it bears some consideration how we format it. CSS style guides<\/a> are common, so perhaps we can extend those to cover choices unique to Sass. <\/p>\n

Here are some ideas that I’ve been gravitating toward. Perhaps they are useful to you or help you formulate ideas of your own. If you’re looking for more examples, Sass Guidelines<\/a> is another good place to look.<\/p>\n

<\/p>\n

Use Your Regular CSS Formatting Rules \/ Style Guide<\/h3>\n

This post is about Sass-specific stuff, but as a base to this, you should follow a whatever good CSS formatting guidelines you are already following. If you aren’t yet, this roundup of style guides<\/a> may help you. This includes things like:<\/p>\n

    \n
  1. Be consistant with indentation<\/li>\n
  2. Be consistant about where spaces before\/after colons\/braces go<\/li>\n
  3. One selector per line, One rule per line<\/li>\n
  4. List related properties together<\/li>\n
  5. Have a plan for class name naming<\/li>\n
  6. Don’t use ID’s #hotdrama<\/li>\n
  7. etc<\/li>\n<\/ol>\n

    List @extend(s) First<\/h3>\n
    .weather {\r\n  @extend %module; \r\n  ...\r\n}<\/code><\/pre>\n
    Knowing right off the bat that this class inherits another whole set of rules from elsewhere is good. Another benefit is that overriding styles for that inherited set of rules becomes much easier.<\/p>\n
    Knowing when to use @extend versus @include can be a little tricky. Harry does a nice job of differentiating the two<\/a> plus offers thoughts on how to use them both.<\/p>\n
    List @include(s) Next<\/h3>\n
    .weather {\r\n  @extend %module; \r\n  @include transition(all 0.3s ease-out);\r\n  ...\r\n}<\/code><\/pre>\n
    Next up is your @includes for mixins and other functions. Again, this is nice to have near the top for reference, but also allows for overrides. You might also want to make the call on separating user-authored @includes and vendor-provided @includes.<\/p>\n
    List “Regular” Styles Next<\/h3>\n
    .weather {\r\n  @extend %module;\r\n  @include transition(all 0.3s ease-out);\r\n  background: LightCyan;\r\n  ...\r\n}<\/code><\/pre>\n
    Adding out regular styles after the @extends and @includes allows us to properly override those properties, if needed.<\/p>\n
    Nested Pseudo Classes and Pseudo Elements Next<\/h3>\n
    .weather {\r\n  @extend %module;\r\n  @include transition(all 0.3s ease-out);\r\n  background: LightCyan;\r\n  &:hover {\r\n    background: DarkCyan;\r\n  }\r\n  &::before {\r\n    content: \"\";\r\n    display: block;\r\n  }\r\n  ...\r\n}<\/code><\/pre>\n
    Pseudo elements and pseudo classes directly related to the element itself so, for that reason, we nest them first before other selectors. Having pseudo elements come before classes seems to be a bit easier to read, but whether one comes before the other is totally a preference. Either way, it might be best to keep elements with other elements and classes with other classes.<\/p>\n
    Nested Selectors Last<\/h3>\n
    .weather {\r\n  @extend %module; \r\n  @include transition(all 0.3s ease);\r\n  background: LightCyan;\r\n  &:hover {\r\n    background: DarkCyan;\r\n  }\r\n  &::before {\r\n    content: \"\";\r\n    display: block;\r\n  }\r\n  > h3 {\r\n    @include transform(rotate(90deg));\r\n    border-bottom: 1px solid white;\r\n  }\r\n}<\/code><\/pre>\n
    Nothing goes after the nested stuff. And the same order as above within the nested selector would apply.<\/p>\n
    Never Write Vendor Prefixes<\/h3>\n
    Vendor prefixes are a time-sensitive thing. As browsers update over time, the need for them will fall away. If you use Autoprefixer<\/a>, when compiling Sass, then you should never have to write them.<\/p>\n
    Alternatively, you can use @mixins provided by libraries like Compass and Bourbon. Or roll your own. Although using @mixins for vendor prefixes is still less convenient than Autoprefixer and still requires some maintenance, it still beats having to write things out manually.<\/p>\n
    Maximum Nesting: Three Levels Deep<\/h3>\n
    .weather {\r\n  .cities {\r\n    li {\r\n      \/\/ no more!\r\n    }\r\n  }\r\n}<\/code><\/pre>\n
    Chances are, if you’re deeper than that, you’re writing a crappy selector. Crappy in that it’s too reliant on HTML structure (fragile), overly specific (too powerful), and not very reusable (not useful). It’s also on the edge of being difficult to understand.<\/p>\n
    If you really want to use tag selectors because the class thing is getting too much for you, you may want to get pretty specific about it to avoid undesired cascading. And possibly even make use of @extend so it has the benefit on the CSS side of re-usability.<\/p>\n
    .weather\r\n  > h3 {\r\n    @extend %line-under;\r\n  }\r\n}<\/code><\/pre>\n
    Maximum Nesting: 50 Lines<\/h3>\n
    If a nested block of Sass is longer than that, there is a good chance it doesn’t fit on one code editor screen, and starts becoming difficult to understand. The whole point of nesting is convenience and to assist in mental grouping. Don’t use it if it hurts that.<\/p>\n
    Global and Section-Specific Sass Files Are just Table of Contents<\/h3>\n
    In other words, no styles directly in them. Force yourself to keep all styles organized into component parts.<\/p>\n
    List Vendor\/Global Dependencies First, Then Author Dependencies, Then Patterns, Then Parts<\/h3>\n
    It ends up being an easy to understand table of contents:<\/p>\n
    \/* Vendor Dependencies *\/\r\n@import \"compass\";\r\n\r\n\/* Authored Dependencies *\/\r\n@import \"global\/colors\";\r\n@import \"global\/mixins\";\r\n\r\n\/* Patterns *\/\r\n@import \"global\/tabs\";\r\n@import \"global\/modals\";\r\n\r\n\/* Sections *\/\r\n@import \"global\/header\";\r\n@import \"global\/footer\";<\/code><\/pre>\n
    The dependencies like Compass, colors, and mixins generate no compiled CSS at all, they are purely code dependencies. Listing the patterns next means that more specific “parts”, which come after, have the power to override patterns without having a specificity war.<\/p>\n
    Break Into As Many Small Files As Makes Sense<\/h3>\n
    There is no penalty to splitting into many small files. Do it as much as feels good to the project. I know I find it easier to jump to small specific files and navigate through them than fewer\/larger ones.<\/p>\n
    ...\r\n\r\n@import \"global\/header\/header\/\";\r\n@import \"global\/header\/logo\/\";\r\n@import \"global\/header\/dropdowns\/\";\r\n@import \"global\/header\/nav\/\";\r\n@import \"global\/header\/really-specific-thingy\/\";<\/code><\/pre>\n
    I’d probably do this right in the global.scss, rather than have global @import a _header.scss file which has its own sub-imports. All that sub-importing could get out of hand. <\/p>\n
    Globbing<\/a> might help if there starts to be too many to list.<\/p>\n
    Partials are named _partial.scss<\/h3>\n
    This is a common naming convention that indicates this file isn’t meant to be compiled by itself. It likely has dependencies that would make it impossible to compile by itself. Personally I like dashes in the “actual” filename though, like _dropdown-menu.scss.<\/p>\n
    Locally, Compile with Source Maps<\/h3>\n
    In development, it probably doesn’t matter which format you compile your Sass in (e.g. expanded, compressed, etc) locally as long as you are producing source maps. <\/p>\n
    It’s a flag when you compile Sass:<\/p>\n
    $ sass sass\/screen.scss:stylesheets\/screen.css --sourcemap<\/code><\/pre>\n
    Although you probably don’t compile Sass like that typically, there is always some kind of way to configure the thing you’re using to compile Sass to do it with source maps. When you have them, that means DevTools shows you where the Sass code is, which is super (duper) useful:<\/p>\n
    <\/figure>\n
    Here’s a few relevant links on this:<\/p>\n