-
Notifications
You must be signed in to change notification settings - Fork 223
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
99845f8
commit ec5c2d2
Showing
2 changed files
with
89 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,26 +1,76 @@ | ||
|
||
# Too Long; Didn't read | ||
|
||
To sum up, we want: | ||
|
||
* Two (2) spaces indents, no tabs; | ||
* 80-characters wide lines; | ||
* Properly written multi-line CSS; | ||
* Meaningful use of whitespaces; | ||
* Quoted strings (single quotes) & URLs; | ||
* No trailing 0, mandatory leading 0; | ||
* Calculations wrapped in parentheses; | ||
* No magic numbers; | ||
* Colors expressed HSL > RGB > hexadecimal (lowercase and shortened), no keyword; | ||
* Lists separated with commas; | ||
* No trailing comma in lists (since they are inlined); | ||
* Trailing comma in maps; | ||
* No selector nesting except for pseudo-classes and pseudo-elements; | ||
* Hyphen-delimited naming; | ||
* Extensive comments; | ||
* SassDoc-powered API comments; | ||
* Limited usage of `@extend`; | ||
* Simple mixins; | ||
* As few loops as possible, no `@while`; | ||
* Reduced number of dependencies; | ||
* Meaningful use of warnings and errors. | ||
# Too Long; Didn’t read | ||
|
||
These guidelines are quite long and sometimes it is good to have them summed up in a shorter version. Below is this summary. | ||
|
||
## Key principles | ||
|
||
* Having a styleguide is all about **consistency**. If you disagree with some rules from Sass Guidelines, fair enough as long as you are consistent. [↩](#why-a-styleguide) | ||
* Sass should be kept as simple as it can be. Avoid building complex systems unless absolutely necessary. [↩](#key-principles) | ||
* Keep in mind that sometimes *KISS* (Keep It Simple, Stupid) is better than *DRY* (Don’t Repeat Yourself). [↩](#key-principles) | ||
|
||
## Syntax & formatting | ||
|
||
* An indentation is made of two (2) spaces, no tabs. [↩](#syntax--formatting) | ||
* Lines should be, as much as possible, shorter than 80 characters. Feel free to split them into several lines when necessary. [↩](#syntax--formatting) | ||
* CSS should be properly written, possibly following the [CSS Guidelines](http://cssguidelin.es) from Harry Roberts. [↩](#syntax--formatting) | ||
* Whitespace is free, use it to separate items, rules and declarations. Do not hesitate to leave empty lines, it never hurts. [↩](#syntax--formatting) | ||
|
||
### Strings | ||
|
||
* Declaring the `@charset` directive on top of the stylesheet is highly recommended. [↩](#encoding) | ||
* Unless applied as CSS identifiers, strings should be quoted using single quotes. URLs should also be quoted. [↩](#strings-as-css-values) | ||
|
||
### Numbers | ||
|
||
* Sass makes no distinction between numbers, integers, floats so trailing zeros (0) should be omitted. However, leading zeros (0) help readability and should be added. [↩](#zeros) | ||
* A zero (0) length should not have a unit. [↩](#units) | ||
* Units manipulation should be thought as arithmetic operations, not string operations. [↩](#units) | ||
* In order to improve readability, top-level calculations should be wrapped in parentheses. Also, complex math operations might be splitted into smaller chunks. [↩](#calculations) | ||
* Magic numbers dramatically hurt code maintainability and should be avoided at all time. When in doubt, extensively explain the questionable value. [↩](#magic-numbers) | ||
|
||
### Colors | ||
|
||
* Colors should be expressed in HSL when possible, then RGB, then hexadecimal (in a lowercase and shortened form). Color keywords should be avoided. [↩](#color-formats) | ||
* Prefer `mix(..)` instead of `darken(..)` and `lighten(..)` when lightening or darkening a color. [↩](#lightening-and-darkening-colors) | ||
|
||
### Lists | ||
|
||
* Unless used as a direct mapping to space-separated CSS values, lists should be separated with commas. [↩](#lists) | ||
* Wrapping parentheses should also be considered to improve readability. [↩](#lists) | ||
* Inlined lists should not have a trailing comma, multi-line lists should have it. [↩](#lists) | ||
|
||
### Maps | ||
|
||
* Maps containing more than a single pair are written on several lines. [↩](#maps) | ||
* To help maintainability, the last pair of a map should have a trailing comma. [↩](#maps) | ||
* Map keys that happen to be strings should be quoted as any other string. [↩](#maps) | ||
|
||
### Declaration sorting | ||
|
||
* The system used for declaration sorting (alphabetical, by type, etc.) doesn’t matter as long as it is consistent. [↩](#declaration-sorting) | ||
|
||
### Selector nesting | ||
|
||
* Avoid selector nesting when it is not needed (which represents most of the cases). [↩](#selector-nesting) | ||
* Use selector nesting for pseudo-classes and pseudo-elements. [↩](#selector-nesting) | ||
* Media queries can also be nested inside their relevant selector. [↩](#selector-nesting) | ||
|
||
## Naming conventions | ||
|
||
* It is best to stick to CSS naming conventions which are (except a few errors) lowercase and hyphen-delimited. [↩](#naming-conventions) | ||
|
||
## Commenting | ||
|
||
* CSS is a tricky language; do not hesitate to write very extensive comments about things that look (or are) fishy. [↩](#commenting) | ||
* For variables, functions, mixins and placeholders establishing a public API, use SassDoc comments. [↩](#documentation) | ||
|
||
## Variables | ||
|
||
* Do use the `!default` flag for any variable part of a public API that can be safely changed. [↩](#default-flag) | ||
* Do not use the `!global` flag at root level as it might constitue a violation of Sass syntax in the future. [↩](#global-flag) | ||
|
||
## Extend | ||
|
||
* Stick to extending placeholders, not existing CSS selectors. [↩](#extend) | ||
* Extend a placeholder as few times as possible in order to avoid side effets. [↩](#extend) |