diff --git a/manual/en-US/coding-standards/chapters/css.md b/manual/en-US/coding-standards/chapters/css.md index d3fb28b0..91979236 100644 --- a/manual/en-US/coding-standards/chapters/css.md +++ b/manual/en-US/coding-standards/chapters/css.md @@ -1,3 +1,220 @@ ## CSS +These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, namely: -@TODO - Add style guide \ No newline at end of file +1. [OOCSS Code Standards](https://github.com/stubbornella/oocss-code-standards) +2. [Oneweb Style Guide](https://github.com/nternetinspired/OneWeb/blob/master/STYLEGUIDE.md) +3. [Idiomatic CSS](https://github.com/necolas/idiomatic-css) + + +## Commenting + +### Major sections +Major code sections should be named in caps and within a full comment block, eg: +```css +/* ========================================================================== + PRIMARY NAVIGATION + ========================================================================== */ +``` + +### Sub sections +Subsections should be normally cased and within an open comment block. +```css +/* Mobile navigation + ========================================================================== */ +``` + +### Verbose comments +```css +/** + * 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. + */ + ``` + +### Basic comments +```css +/* Basic comment */ +``` + +### Uncompiled LESS/Scss comments +```css +// These are stripped on compile. +``` + +## Class naming +Use dashes to create compound class names: + +```css +/* Good - use dashes */ +.compound-class-name {…} + +/* Bad - uses underscores */ +.compound_class_name {…} + +/* Bad - uses camelCase */ +.compoundClassName {…} + +/* Bad - does not use seperators */ +.compoundclassname {…} +``` + +### Indentation +Rules should be indented one tab (equal to 4 spaces): + +```css +/* Good */ +.example { + color: #000; + visibility: hidden; +} + +/* Bad - all on one line */ +.example {color: #000; visibility: hidden;} +``` + +LESS/Scss should also be nested , with child selectors and rules indented again. Nested rules should also be spaced by one line: + +```css +/* Good */ +.example { + + > li { + float: none; + + + li { + margin-top: 2px; + margin-left: 0; + } + + } + +} +/* Bad - nested rules not indented */ +.example { + + > li { + float: none; + + + li { + margin-top: 2px; + margin-left: 0; + } + + } + +} +/* Bad - nested rules not spaced */ +.example { + > li { + float: none; + + li { + margin-top: 2px; + margin-left: 0; + } + } +} +``` + +### Alignment +The opening brace must be on the same line as the last selector and preceded by a space. The closing brace must be on its own line after the last property and be indented to the same level as the opening brace. + +```css +/* Good */ +.example { + color: #fff; +} + +/* Bad - closing brace is in the wrong place */ +.example { + color: #fff; + } + +/* Bad - opening brace missing space */ +.example{ + color: #fff; +} +``` + +### Property Format +Each property must be on its own line and indented one level. There should be no space before the colon and one space after. All properties must end with a semicolon. + +```css +/* Good */ +.example { + background: black; + color: #fff; +} + +/* Bad - missing spaces after colons */ +.example { + background:black; + color:#fff; +} + +/* Bad - missing last semicolon */ +.example { + background: black; + color: #fff +} +``` + +### HEX values +HEX values must be declared in lowercase and shorthand: +```css +/* Good */ +.example { + color: #eee; +} + +/* Bad */ +.example { + color: #EEEEEE; +} +``` + +### Attribute selectors +Always use double quotes around attribute selectors. + +```css +/* Good */ +input[type="button"] { + ... +} + +/* Bad - missing quotes */ +input[type=button] { + ... +} + +/* Bad - using single quote */ +input[type='button'] { + ... +} +``` + +### Zero value units +Zero values should not carry units. + +```css +/* Good */ +.example { + padding: 0; +} + +/* Bad - uses units */ +.example { + padding: 0px; +} +```