diff --git a/README.md b/README.md index c6446cd..b6c95a3 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ goals. - [Preprocessors: additional format considerations](#preprocessors-additional-format-considerations) - [Linting](#linting) - [Naming conventions](#naming-conventions) - - [BEM](#bem) + - [Kickoff](#kickoff) - [Namespacing](#namespacing) - [CSS frameworks](#css-frameworks) - [State hooks](#state-hooks) @@ -63,7 +63,7 @@ goals. Here are our rules for managing whitespace in Sass files: -- Use soft indents (spaces). +- Use hard indents (tabs). - Use 2 characters for the indentation level. - **Never** mix spaces and tabs for indentation. - Wrap at 80 characters wide. @@ -88,7 +88,7 @@ If you use Sublime Text editor then install [this package](https://github.com/Su ``` "tab_size": 2, -"translate_tabs_to_spaces": true, +"translate_tabs_to_spaces": false, "trim_automatic_white_space": true, "trim_trailing_white_space_on_save": true, "word_wrap": true, @@ -100,7 +100,8 @@ This is optional: ``` "rulers": [ - 80 + 80, + 100 ], ``` @@ -127,7 +128,7 @@ For reference here is an anatomy of a rule set: ### Formatting rules -- Class names to use BEM notation, see [Naming Conventions -> BEM](#bem), where BEM isn't used then hyphen delimited class names are to be used. +- Class names to use the Kickoff notation, see [Naming Conventions -> Kickoff](#kickoff), where Kickoff isn't used then hyphen delimited class names are to be used. - Use one discrete selector per line in multi-selector rule sets. **Good** @@ -318,15 +319,15 @@ For reference here is an anatomy of a rule set: ```scss @include box-shadow( 0 2px 2px rgba( 0, 0, 0, .2 ) ); ``` -- When a decimal mark is needed always include the zero. +- When a decimal mark is needed there is no need to include the zero. **Good** ```scss - 0.25rem + .25rem ``` **Bad** ```scss - .25rem + 0.25rem ``` - Don't write trailing zeros for numeric values with a decimal point. @@ -351,22 +352,26 @@ For reference here is an anatomy of a rule set: ### Declaration order -Declarations should be ordered alphabetically. +Declarations should be grouped by relationship where possible. Example: ``` .selector { - background-color: #000; - bottom: 0; - box-sizing: border-box; - color: #fff; - display: inline-block; - font-family: sans-serif; - font-size: 1em; - height: 100px; - text-align: right; - width: 100px; + position: absolute; + bottom: 0; + + display: inline-block; + box-sizing: border-box; + height: 100px; + width: 100px; + + background-color: #000; + + color: #fff; + font-family: sans-serif; + font-size: 1em; + text-align: right; } ``` @@ -427,31 +432,31 @@ If you use Sublime Text editor then install [this package](https://github.com/at ## Naming conventions -Always ensure classes are sensibly named; keep them as short as possible but as long as necessary. Ensure any utilities are very vaguely named (e.g. `.u-display-block`, `.u-divider`) to allow for greater reuse. Don’t worry about the amount or length of classes in your markup; gzip will compress well written code incredibly well. +Always ensure classes are sensibly named; keep them as short as possible but as long as necessary. Ensure any utilities are very vaguely named (e.g. `.text-center`, `.clearfix`) to allow for greater reuse. Don’t worry about the amount or length of classes in your markup; gzip will compress well written code incredibly well. **ID's cannot be used as style hooks**, [see](http://cssguidelin.es/#ids-in-css). [Further reading](http://cssguidelin.es/#naming-conventions). -### BEM +### Kickoff -We use the BEM (Block, Element, Modifier) naming convention. When BEM is not used e.g. [JavaScript hooks](#javascript-hooks) then we use hyphen delimited classes e.g. `.foo-bar`, not `.foo_bar` or `.fooBar`. +We use the [Kickoff naming convention](http://trykickoff.com/learn/css.html#namingscheme). When this is not used e.g. [JavaScript hooks](#javascript-hooks) then we use hyphen delimited classes e.g. `.foo-bar`, not `.foo_bar` or `.fooBar`. -BEM is a methodology for naming and classifying CSS selectors in a way to make them a lot more strict, transparent and informative. +Kickoff's naming convention is similar to BEM, it is a methodology for naming and classifying CSS selectors in a way to make them a lot more strict, transparent and informative. The naming convention follows this pattern: ``` -.block{} -.block__element{} -.block--modifier{} +.block {} +.block-element {} +.block--modifier {} ``` - `.block` represents the higher level of an abstraction or component. -- `.block__element` represents a descendent of `.block` that helps form `.block` as a whole. +- `.block-element` represents a descendent/child of `.block` that helps form `.block` as a whole. - `.block--modifier` represents a different state or version of `.block`. -[Further reading](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/). +[Further reading](http://trykickoff.com/learn/css.html#namingscheme). ### Namespacing @@ -487,7 +492,7 @@ This means that we can attach both JS and CSS to classes in our markup but there A common practice is to use data-* attributes as JS hooks, but this is incorrect. data-* attributes, as per the [spec](http://www.w3.org/TR/2011/WD-html5-20110525/elements.html#embedding-custom-non-visible-data-with-the-data-attributes), are used to store custom data private to the page or application (emphasis mine). data-* attributes are designed to store data, not be bound to. -**JS hooks do not use BEM.** +**JS hooks do not use the Kickoff naming convention.** #### Test and Tracking hooks @@ -499,7 +504,7 @@ Tracking hooks are used for tracking elements for analytics. They're simply classes namespaced like so: `.test-` (test) / `.track` (tracking) and follow the same naming convention as JS Hooks e.g. `.test-[component]-[UI-it's-affecting]` / `.track-[component]-[UI-it's-affecting]`. -**Test and Tracking hooks hooks do not use BEM.** +**Test and Tracking hooks hooks do not use the Kickoff naming convention.** ##### Order of the above hooks @@ -508,7 +513,8 @@ The order of the above hooks, within the `class` attribute, should be: 1. Style hooks: 1. Component hook (no namespace) 2. Layout hook (`.l-`) - 3. Utility hook (`u-`) + 3. Utility hook (`.u-`) + 3. Grid hook (`.g-`) 2. JS hooks (`.js-`) 3. Test hooks (`.test-`) 4. Tracking hooks (`.track-`) @@ -519,10 +525,6 @@ Example: