From 72a6a502b64ba1f8215887d24b26b3353e88dd29 Mon Sep 17 00:00:00 2001 From: Zander Martineau Date: Sun, 13 Dec 2015 22:46:38 +0000 Subject: [PATCH 1/3] :smiling_imp: Modify to suit Kickoff's conventions Still needs a bit of work but this is close... --- README.md | 66 +++++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index c6446cd..b25e7d4 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) @@ -127,7 +127,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 +318,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. @@ -433,25 +433,25 @@ Always ensure classes are sensibly named; keep them as short as possible but as [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. 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-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 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 +487,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 +499,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 +508,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-`) @@ -562,21 +563,16 @@ If you use Sublime Text editor then install [this package](https://sublime.wbond Every `.scss` file should always have a main title comment at the very top of the file and formatted like this: ``` -/* ============================================================================ - @COMPONENTS -> PAGINATON - ========================================================================= */ -``` - -The first part, prefixed with an `@` symbol, represents the location of the file within the CSS architecture (see [Architecture Overview](#architecture-overview)). The second part represents what the `.scss` file is actually styling which in most cases will be a component. It's similar to a breadcrumb pattern, so for a more deeply nested file we'll have this: - -``` -/* ============================================================================ - @CORE -> MIXINS -> CONVERT PX TO EM/REM - ========================================================================= */ +/** + * Title + * Description + * - Table of contents item 1 + * - Table of contents item 2 + * - Table of contents item 3 + + */ ``` -Each main title is prefixed with an `@` symbol to allow us to perform more targeted searches (e.g. `grep`, etc.) and is always in uppercase. - **2 blank lines should always come after a main title comment.** ### Intro block @@ -690,12 +686,10 @@ Each major chunk of CSS in a file should begin with a sub title comment e.g. ``` /** - * Grid container. + * Grid container */ ``` -A full stop (period) should end the sub title comment. - **2 blank lines should come before and 1 blank line should come after these sub title comments.** ### Preprocessor comments @@ -767,9 +761,9 @@ This is the format to use: */ ``` -### BEM modifier comments +### Modifier comments -Whenever you're using BEM and you declare a modifier (see [Naming conventions -> BEM](#bem)) you need to include a comment and if required provide a brief explanation as to what it's doing, e.g. +Whenever you're using BEM and you declare a modifier (see [Naming conventions -> Kickoff](#kickoff)) you need to include a comment and if required provide a brief explanation as to what it's doing, e.g. ``` /** @@ -779,7 +773,9 @@ Whenever you're using BEM and you declare a modifier (see [Naming conventions -> */ .u-table--striped { - tbody tr:nth-of-type(odd) td {background-color: $u-table-striped-background-cell-colour;} + tbody tr:nth-of-type(odd) td { + background-color: $u-table-striped-background-cell-colour; + } } ``` @@ -823,7 +819,9 @@ Whenever you write some styles for non-JavaScript users always include a comment ``` // Non-JS users -.no-js .selector {position: static;} +.no-js .selector { + position: static; +} ``` ### `!important` comments From 573d2d1260312018b3e5eefcfea45e86ff8ddc1e Mon Sep 17 00:00:00 2001 From: Z&er Date: Tue, 28 Jun 2016 09:35:27 +0100 Subject: [PATCH 2/3] Update README.md --- README.md | 47 ++++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index b25e7d4..22e1dbf 100644 --- a/README.md +++ b/README.md @@ -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 ], ``` @@ -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,7 +432,7 @@ 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). @@ -442,13 +447,13 @@ Kickoff's naming convention is similar to BEM, it is a methodology for naming an 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://trykickoff.com/learn/css.html#namingscheme). @@ -520,10 +525,6 @@ Example: