Skip to content

GitLab

css and sass coding standards · Changes

Page history
mmclin created page: css-and-sass-coding-standards authored by Mike McLin's avatar Mike McLin
Show whitespace changes
Inline Side-by-side
css-and-sass-coding-standards.markdown
View page @ e35f77e8
......@@ -26,7 +26,8 @@ Comment style should be simple and consistent within a single code base.
Tip: configure your editor to provide you with shortcuts to output agreed-upon comment patterns.
CSS Example:
#### CSS Example:
```css
/* ==========================================================================
......@@ -39,26 +40,22 @@ CSS Example:
/**
* Short description using Doxygen-style comment format
*
* The first sentence of the long description starts here and continues on this
* line for a while finally concluding here at the end of this paragraph.
*
* The long description is ideal for more detailed explanations and
* documentation. It can include example HTML, URLs, or any other information
* that is deemed necessary or useful.
*
* @tag This is a tag named 'tag'
*
* TODO: This is a todo statement that describes an atomic task to be completed
* at a later date. It wraps after 80 characters and following lines are
* indented by 2 spaces.
* indented into a block.
*/
/* Basic comment */
```
For Sass, double-slash comments should be used instead
Sass Example:
#### Sass Example:
For Sass, double-slash comments should be used instead
```js
// ==========================================================================
......@@ -72,18 +69,13 @@ Sass Example:
// Short description using Doxygen-style comment format
//
// The first sentence of the long description starts here and continues on this
// line for a while finally concluding here at the end of this paragraph.
//
// The long description is ideal for more detailed explanations and
// documentation. It can include example HTML, URLs, or any other information
// that is deemed necessary or useful.
//
// @tag This is a tag named 'tag'
//
// TODO: This is a todo statement that describes an atomic task to be completed
// at a later date. It wraps after 80 characters and following lines are
// indented by 2 spaces.
// indented into a block.
// Basic comment
......@@ -91,12 +83,7 @@ Sass Example:
<a name="format"></a>
## 4. Format
The chosen code format must ensure that code is: easy to read; easy to clearly
comment; minimizes the chance of accidentally introducing errors; and results
in useful diffs and blames.
## 3. Format
* Use one discrete selector per line in multi-selector rulesets.
* Include a single space before the opening brace of a ruleset.
......@@ -104,16 +91,12 @@ in useful diffs and blames.
* Use one level of indentation for each declaration.
* Include a single space after the colon of a declaration.
* Use lowercase and shorthand hex values, e.g., `#aaa`.
* Use single or double quotes consistently. Preference is for double quotes,
e.g., `content: ""`.
* Use single or double quotes consistently. Preference is for double quotes, e.g., `content: ""`.
* Quote attribute values in selectors, e.g., `input[type="checkbox"]`.
* _Where allowed_, avoid specifying units for zero-values, e.g., `margin: 0`.
* Include a space after each comma in comma-separated property or function
values.
* Include a semi-colon at the end of the last declaration in a declaration
block.
* Place the closing brace of a ruleset in the same column as the first
character of the ruleset.
* Include a space after each comma in comma-separated property or function values.
* Include a semi-colon at the end of the last declaration in a declaration block.
* Place the closing brace of a ruleset in the same column as the first character of the ruleset.
* Separate each ruleset by a blank line.
```css
......@@ -136,51 +119,9 @@ in useful diffs and blames.
}
```
#### Declaration order
If declarations are to be consistently ordered, it should be in accordance with
a single, simple principle.
Smaller teams may prefer to cluster related properties (e.g. positioning and
box-model) together.
```css
.selector {
/* Positioning */
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* Display & Box Model */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* Other */
background: #000;
color: #fff;
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
```
Larger teams may prefer the simplicity and ease-of-maintenance that comes with
alphabetical ordering.
#### Exceptions and slight deviations
Large blocks of single declarations can use a slightly different, single-line
format. In this case, a space should be included after the opening brace and
before the closing brace.
Large blocks of single declarations can use a slightly different, single-line format. In this case, a space should be included after the opening brace and before the closing brace.
```css
.selector-1 { width: 10%; }
......@@ -188,10 +129,17 @@ before the closing brace.
.selector-3 { width: 30%; }
```
Long, comma-separated property values - such as collections of gradients or
shadows - can be arranged across multiple lines in an effort to improve
readability and produce more useful diffs. There are various formats that could
be used; one example is shown below.
You can align a declarations block containing multiple property-value pairs by the colon for readability. If you format your declaration block this way, you must have at least one space before each colon, at only one space after each colon.
```css
.selector-1 {
display : block;
font-family : helvetica, arial, sans-serif;
color : #333;
background : #fff;
}
Long, comma-separated property values - such as collections of gradients or shadows - can be arranged across multiple lines in an effort to improve readability and produce more useful diffs. There are various formats that could be used; one example is shown below.
```css
.selector {
......@@ -204,38 +152,25 @@ be used; one example is shown below.
}
```
### Preprocessors: additional format considerations
Different CSS preprocessors have different features, functionality, and syntax.
Your conventions should be extended to accommodate the particularities of any
preprocessor in use. The following guidelines are in reference to Sass.
* Limit nesting to 1 level deep. Reassess any nesting more than 2 levels deep.
This prevents overly-specific CSS selectors.
* Avoid large numbers of nested rules. Break them up when readability starts to
be affected. Preference to avoid nesting that spreads over more than 20
lines.
* Always place `@extend` statements on the first lines of a declaration
block.
* Where possible, group `@include` statements at the top of a declaration
block, after any `@extend` statements.
* Consider prefixing custom functions with `x-` or another namespace. This
helps to avoid any potential to confuse your function with a native CSS
function, or to clash with functions from libraries.
### Sass-specific
* Limit nesting to 2 levels deep. Reassess any nesting more than 2 levels deep. This prevents overly-specific CSS selectors.
* Always place `@extend` statements on the first lines of a declaration block.
* Where possible, group `@include` statements at the top of a declaration block, after any `@extend` statements.
```scss
.selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
width: 20em;
// other declarations
}
```
<a name="example"></a>
## 5. Practical example
## 4. Practical example
An example of various conventions.
......