debian-mirror-gitlab/doc/development/fe_guide/style_guide_scss.md

240 lines
4.6 KiB
Markdown
Raw Normal View History

2016-06-02 11:05:42 +05:30
# SCSS styleguide
This style guide recommends best practices for SCSS to make styles easy to read,
easy to maintain, and performant for the end-user.
## Rules
### Naming
2018-03-27 19:54:05 +05:30
Filenames should use `snake_case`.
2016-06-02 11:05:42 +05:30
CSS classes should use the `lowercase-hyphenated` format rather than
`snake_case` or `camelCase`.
```scss
// Bad
.class_name {
color: #fff;
}
// Bad
.className {
color: #fff;
}
// Good
.class-name {
color: #fff;
}
```
### Formatting
You should always use a space before a brace, braces should be on the same
line, each property should each get its own line, and there should be a space
between the property and its value.
```scss
// Bad
2017-08-17 22:00:37 +05:30
.container-item {
2016-06-02 11:05:42 +05:30
width: 100px; height: 100px;
margin-top: 0;
}
// Bad
.container-item
{
width: 100px;
height: 100px;
margin-top: 0;
}
// Bad
.container-item{
width:100px;
height:100px;
margin-top:0;
}
// Good
.container-item {
width: 100px;
height: 100px;
margin-top: 0;
}
```
2017-08-17 22:00:37 +05:30
Note that there is an exception for single-line rulesets, although these are
2016-06-02 11:05:42 +05:30
not typically recommended.
```scss
p { margin: 0; padding: 0; }
```
### Colors
2017-08-17 22:00:37 +05:30
HEX (hexadecimal) colors should use shorthand where possible, and should use
2016-06-02 11:05:42 +05:30
lower case letters to differentiate between letters and numbers, e.g. `#E3E3E3`
vs. `#e3e3e3`.
```scss
// Bad
p {
color: #ffffff;
}
// Bad
p {
color: #FFFFFF;
}
// Good
p {
color: #fff;
}
```
### Indentation
Indentation should always use two spaces for each indentation level.
```scss
// Bad, four spaces
p {
color: #f00;
}
// Good
p {
color: #f00;
}
```
### Semicolons
2017-08-17 22:00:37 +05:30
Always include semicolons after every property. When the stylesheets are
2016-06-02 11:05:42 +05:30
minified, the semicolons will be removed automatically.
```scss
// Bad
.container-item {
width: 100px;
height: 100px
}
// Good
.container-item {
width: 100px;
height: 100px;
}
```
### Shorthand
The shorthand form should be used for properties that support it.
```scss
// Bad
margin: 10px 15px 10px 15px;
padding: 10px 10px 10px 10px;
// Good
margin: 10px 15px;
padding: 10px;
```
### Zero Units
2017-08-17 22:00:37 +05:30
Omit length units on zero values, they're unnecessary and not including them
2016-06-02 11:05:42 +05:30
is slightly more performant.
```scss
// Bad
.item-with-padding {
padding: 0px;
}
// Good
.item-with-padding {
padding: 0;
}
```
### Selectors with a `js-` Prefix
2017-08-17 22:00:37 +05:30
Do not use any selector prefixed with `js-` for styling purposes. These
selectors are intended for use only with JavaScript to allow for removal or
2016-06-02 11:05:42 +05:30
renaming without breaking styling.
2017-08-17 22:00:37 +05:30
### IDs
Don't use ID selectors in CSS.
```scss
// Bad
#my-element {
padding: 0;
}
// Good
.my-element {
padding: 0;
}
```
### Variables
2018-12-23 12:14:25 +05:30
2017-08-17 22:00:37 +05:30
Before adding a new variable for a color or a size, guarantee:
2018-12-23 12:14:25 +05:30
- There isn't already one
- There isn't a similar one we can use instead.
2017-08-17 22:00:37 +05:30
2016-06-02 11:05:42 +05:30
## Linting
2017-08-17 22:00:37 +05:30
We use [SCSS Lint][scss-lint] to check for style guide conformity. It uses the
ruleset in `.scss-lint.yml`, which is located in the home directory of the
2016-06-02 11:05:42 +05:30
project.
2017-08-17 22:00:37 +05:30
To check if any warnings will be produced by your changes, you can run `rake
scss_lint` in the GitLab directory. SCSS Lint will also run in GitLab CI to
2016-06-02 11:05:42 +05:30
catch any warnings.
2017-08-17 22:00:37 +05:30
If the Rake task is throwing warnings you don't understand, SCSS Lint's
2016-06-02 11:05:42 +05:30
documentation includes [a full list of their linters][scss-lint-documentation].
### Fixing issues
2017-08-17 22:00:37 +05:30
If you want to automate changing a large portion of the codebase to conform to
2016-06-02 11:05:42 +05:30
the SCSS style guide, you can use [CSSComb][csscomb]. First install
2017-08-17 22:00:37 +05:30
[Node][node] and [NPM][npm], then run `npm install csscomb -g` to install
CSSComb globally (system-wide). Run it in the GitLab directory with
2016-06-02 11:05:42 +05:30
`csscomb app/assets/stylesheets` to automatically fix issues with CSS/SCSS.
Note that this won't fix every problem, but it should fix a majority.
### Ignoring issues
2017-08-17 22:00:37 +05:30
If you want a line or set of lines to be ignored by the linter, you can use
2016-06-02 11:05:42 +05:30
`// scss-lint:disable RuleName` ([more info][disabling-linters]):
```scss
2018-11-08 19:23:39 +05:30
// This lint rule is disabled because it is supported only in Chrome/Safari
// scss-lint:disable PropertySpelling
body {
text-decoration-skip: ink;
2016-06-02 11:05:42 +05:30
}
2018-11-08 19:23:39 +05:30
// scss-lint:enable PropertySpelling
2016-06-02 11:05:42 +05:30
```
Make sure a comment is added on the line above the `disable` rule, otherwise the
2017-08-17 22:00:37 +05:30
linter will throw a warning. `DisableLinterReason` is enabled to make sure the
style guide isn't being ignored, and to communicate to others why the style
2016-06-02 11:05:42 +05:30
guide is ignored in this instance.
[csscomb]: https://github.com/csscomb/csscomb.js
[node]: https://github.com/nodejs/node
[npm]: https://www.npmjs.com/
[scss-lint]: https://github.com/brigade/scss-lint
[scss-lint-documentation]: https://github.com/brigade/scss-lint/blob/master/lib/scss_lint/linter/README.md
[disabling-linters]: https://github.com/brigade/scss-lint#disabling-linters-via-source