Create a SCSS Style Guide

[sfrisk]

Currently we do not have an SCSS Style Guide, which will be important moving forward in the project, since we'll be using a preprocessor. The idea is to have this be similar in style to the CSS style guide.

[battaglr]

@sfrisk: certainly it's an important thing to have a well defined style guide for the project. I have a couple of questions:

1. It's already defined the syntax flavor to use (Sass or SCSS)?
2. Are there already some "rules" defined?
3. Where can we start writing or collaborating if the document is already created?

[sfrisk]

1. We'll be using SCSS, specifically LibSass
2. Current rules that have been defined are for css only, which can be found on the css style guide. As for rules, mostly the one rule we have so far is to follow a BEM naming convention, which means avoiding cascading.
3. There is currently no document for the SCSS style guide. Even though currently most style guides are kept in the contribute repository, it might make sense to create the style guide in our repo/wiki for now, and when it's at a point that we want, then we make a PR for the contribute repo.

[arschmitz]

if we want this just for discussion purposes here before submitting to contribute. We should probably just do a pr here for a scss_style_guide.md or something ( even though it wont land here ). That way its easy to discuss and track. Then we can reference that pr in the pr for contribute.

One note on this though, i can't find the issue right now, but there is discussion somewhere about moving the style guides on contribute to individual project pages.

[trailofdad]

I thought this was a pretty good example of an scss style guide: https://github.com/mobify/mobify-code-style/tree/master/css/sass-best-practices

[ramasilveyra]

One of the more widely used sass style guide is this: http://sass-guidelin.es/. Its written by one of the most popular sass developer and based in his extensive knowledge. We can draw inspiration from this work (Sass Guidelines).

[handasolo]

Is there any reason that the current css style guide uses double quotes instead of single quotes?

[arschmitz]

Yes we prefer double quotes

[handasolo]

stays consistent with the JS guide?

[handasolo]

Things that are already established in the css style guide:

• Indentation with tabs.
• No trailing whitespace.
• Space after a colon.
• Space before opening parenthesis.
• Closing parenthesis on a new line.
• If using multiple selectors, each selector should be on a separate line.
• No space within ().
• Use of hex codes and possibly shorthand hex.
• lowercase when using hex code.
• use em over px.
• no units for 0.
• shorthand properties whenever possible.
• omit leading zeroes and trailing zeroes.
• double quotes instead of single.
• semicolon at end of a declaration.
• commenting rules.
• class name should be lowercase.
• use of classes over ids.

Things that are not established in the css style guide or are either SCSS specific:

• Avoid using magic numbers.If used, state that a magic number is used in a comment and state why you think it works.
• BEM naming convention.
• Don't nest deeper than 3 levels.
• Using the following order:
  • scoped variable.
  • @extend.
  • @include.
  • regular styles.
  • pseudo classes and elements.
  • nested selectors.
  • media queries.
• top level calculation in parentheses.
• naming media queries.
• @else in the same line as closing if brace.
• using not keyword instead of null or false.

[ghost]

I would suggest to write your styles in less, which has variables, css cannot

[sfrisk]

That's why we're using SCSS, so we can use variables.

[maikuru]

And mix-ins :+1:

[MichaelArestad]

I agree with just about everything in this set: http://sass-guidelin.es/

• Leading zeroes are a must
• em is cool, but px is logical when a thing shouldn't scale (avoids blurry icons)
• No shorthand properties (new and scary, but better)
• I like spaces between parenthesis
• I would also advocate pretty strongly against extend.

[arschmitz]

@MichaelArestad none of those except extend are scss specific and we have rules for all of them in our styleguide / csscomb / csslint settings already.

[MichaelArestad]

@arschmitz Gah! Gotta get leading zeroes added back in!

[battaglr]

JOOC, what's the rationale for using leading zeros?

[MichaelArestad]

@battaglr Primarily readability. A leading zero is a clear indicator of a decimal being used.

[battaglr]

@MichaelArestad: the dot shouldn't be enough to indicate that? I know that this may fall under the personal-preference category... I'm just trying to understand the reasons. :smiley:

[arschmitz]

Just for the record style guides are entirely about 1 of 2 things personal preference ( even what you consider readable is a preference ) , and how easy it is to enforce with automated tools. Since leading zeros can be easily enforced either way it is 100% preference.

[MichaelArestad]

In this case, it's not entirely just personal preference. It really is more readable and obvious.

.class {
  margin-top: 3em;
  margin-top: .3em;
}

.class {
  margin-top: 3em;
  margin-top: 0.3em;
}

[arschmitz]

@MichaelArestad i consider those more or less equally readable and do consider this preference

[MichaelArestad]

@arschmitz That's fine. I'm pretty confident in my preference. There's a reason leading zeros made it into the Sass guidelines. It wasn't because the author preferred them. We can probably do a poll.

[battaglr]

@arschmitz & @MichaelArestad: my intention wasn't to make a big deal out of this, just wanted to know the rationale —and while I agree with @arschmitz that there is not a huge difference in readability, I have to accept that the a leading zero stands out a bit more.

[arschmitz]

Just for the record on what different projects use for leading zero rules in css

jQuery UI - Omit (http://contribute.jquery.org/style-guide/css/ ) jQuery Mobile - Omit (http://contribute.jquery.org/style-guide/css/ ) Chassis - Omit (http://contribute.jquery.org/style-guide/css/ ) David Clark - Uses ( http://davidtheclark.com/scss-lint-styleguide/ ) Google - Omit ( http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml#Leading_0s ) Leamonly - Omit ( https://github.com/Lemonly/style-guides/blob/master/guides/scss.md ) Code Guide Aka Bootstrap - Omit ( http://codeguide.co/ ) Martin Wolf - Omit ( https://github.com/martinwolf/CSS-Styleguide#omit-units-and-leading-zeros ) applepie - omit ( http://www.apppie.org/pages/approach/styleguide.html ) sassguideline.es - uses ( http://sass-guidelin.es/ ) wordpress - uses ( https://make.wordpress.org/core/handbook/coding-standards/css/ ) Mozilla - Omit ( http://mozweb.readthedocs.org/en/latest/reference/css-style.html ) Tailcoat - Omit ( http://arcgis.github.io/tailcoat/styleguides/css/ ) Drupal - Uses ( https://www.drupal.org/node/2399303 )

It seems like the vast majority of style guides that actually list a preference choose to omit.

There's a reason leading zeros made it into the Sass guidelines

I'm sure we can ll agree there were good reasons for the choices made in each of these projects that have chosen to express an opinion

[maikuru]

Syntactically it doesn't matter. They are both interpreted by the processors/interpreters as being explicitly identical. Where it does matter is we mortal humans far more likely to create a typo when omitting the leading zero than that when we include it.

[arschmitz]

@maikuru

we mortal humans far more likely to create a typo when omitting the leading zero than that when we include it.

Do you actually have evidence for this? I would say this would seem unlikely given the list of major players above that chose to omit them.

[arschmitz]

Considering that this has been an established rule for this project for nearly a year, it was the very first work done for it, and that @sfrisk spent a lot of time researching style guides before setting these rules. I propose we move this back onto the actual topic SCSS. Any issues with the current CSS style guide should really be opened as an issue on contribute.jquery.org where the current style guide lives.

[battaglr]

@arschmitz: oops! Sorry for deviating the topic. And FWIW, I prefer no leading zeros.

[arschmitz]

@battaglr no problem just trying to keep things on topic and productive. This is not the place to debate the CSS style guide there is a different repo for that.

[sfrisk]

Based on our discussions in the meeting last week, SCSS comments should follow the valid CSS comment rules we have in the jQuery Style Guide