From 4fa3418a2cf8e0ae89d01f353ebbd4edcb16f83b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20St=C3=BCrmer?= Date: Mon, 12 Jun 2017 14:47:57 +0200 Subject: [PATCH 1/5] Add css style guide section on open/closed principle --- style_guides/css_style_guide.md | 108 ++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/style_guides/css_style_guide.md b/style_guides/css_style_guide.md index 61822d3217e3f..a2f9cd9a6136e 100644 --- a/style_guides/css_style_guide.md +++ b/style_guides/css_style_guide.md @@ -15,6 +15,7 @@ - [Don't use multiple modifier classes together](#dont-use-multiple-modifier-classes-together) - [How to apply DRY](#how-to-apply-dry) - [Compelling reasons for using mixins](#compelling-reasons-for-using-mixins) + - [The Open/Closed Principle](#the-openclosed-principle) ## Selecting elements @@ -103,6 +104,8 @@ Our CSS naming convention is based on BEM: * [BEM 101 (CSS Tricks)](https://css-tricks.com/bem-101/) * [Getting your head around BEM syntax (CSS Wizardry)](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) +* [CSS for BEM (bem.info)](https://en.bem.info/methodology/css/) +* [CSS Guidelines](https://cssguidelin.es/) ## Concepts @@ -461,3 +464,108 @@ border-radius changes for all buttons, you only need to change it there. Or if the designers anticipate that all new types of buttons should have the same border-radius, then you can just extend this mixin when you create a new button base class. + +### The Open/Closed Principle + +References: + +* [The Open/Closed Principle on bem.info](https://en.bem.info/methodology/css/#openclosed-principle) +* [The Open/Closed Principle in CSS Guidelines](https://cssguidelin.es/#the-openclosed-principle) +* [The Open/Closed Principle on Wikipedia](https://en.wikipedia.org/wiki/Open/closed_principle) + +Formally the open/closed principle reads + +> Software entities (classes, modules, functions, etc.) should be **open for +> extension**, but **closed for modification**. + +Applied to CSS, this means that CSS rulesets should be treated as immutable. +Once a declaration block for a specific selector has been defined, its style +should not be overridden in a different ruleset using the same selector: + +```css +// BAD +.button { + color: blue; + font-size: 1.5em; + padding: 16px; +} + +.header .button { + font-size: 1em; + padding: 4px; +} +``` + +Not only does this example violate the semantics of a BEM block, it also +**modifies** the meaning of `.button` depending on the context. Instead, this +could be expressed using a block modifier or a completely separate class which +is kept DRY using mixins: + +```css +// GOOD +.button { + color: blue; + font-size: 1.5em; +} + + .button--small { + font-size: 1em; + padding: 4px; + } +``` + +#### Exception: Block Groups + +It is a common occurrence that groups of blocks within a container should be +styled differently that single blocks in order to indicate their association. +But using pure BEM mixes of blocks and group modifiers would sometimes require +a large number of modifiers to be applied to multiple elements to achieve that, +e.g.: + +```css +.kuiCard { /* ... */ } + + .kuiCard__description { /* ... */ } + +.kuiCardGroup { /* ... */ } + + .kuiCardGroup__card { /* ... */ } + + .kuiCardGroup__cardDescription { /* ... */ } +``` + +```html +
+
+
+ Card Description +
+
+
+``` + +To avoid the combinatorial explosion of classes with such groupings and its +modifiers, it is permissible to nest a block's selector under another block's +selector if: + +* The relationship is a if a very narrow `element` to `elementGroup` kind that + is apparent from the block names. +* The rulesets are colocated in the same component directory. + +```css +.kuiCard { /* ... */ } + + .kuiCard__description { /* ... */ } + +.kuiCardGroup { /* ... */ } + +.kuiCardGroup .kuiCard { /* ... */ } + +.kuiCardGroup .kuiCard__description { /* ... */ } +``` + +#### Exception: Normalization/Reset + +When working with the browser default styles or third-party stylesheets the +selectors are sometimes overly broad so that they have to be re-used in order +to integrate the styles into the project. From c6a0df767196ea775c8f02d4e1733e519897bdcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20St=C3=BCrmer?= Date: Wed, 14 Jun 2017 14:13:41 +0200 Subject: [PATCH 2/5] Improve exception wording as per review feedback --- style_guides/css_style_guide.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/style_guides/css_style_guide.md b/style_guides/css_style_guide.md index a2f9cd9a6136e..b35ca1063c9fa 100644 --- a/style_guides/css_style_guide.md +++ b/style_guides/css_style_guide.md @@ -566,6 +566,14 @@ selector if: #### Exception: Normalization/Reset -When working with the browser default styles or third-party stylesheets the -selectors are sometimes overly broad so that they have to be re-used in order -to integrate the styles into the project. +We can not control the selectors introduced by third-party stylesheets and +these selectors may not adhere to our styleguide, e.g. `a` or +`input[type="text"]`. In these cases, we are forced to duplicate these +selectors within our own stylesheets and override those styles to control their +look and feel. + +When this happens, it is important to add comments that make it clear why these +selectors exist and which third-party dependencies they override. We should +also define these selectors in files which refer back to the dependency, e.g. a +file named `ui_select_overrides.less` will contain styles overriding those +introduced by the `ui-select` dependency. From 3599cb0bcd7d2e9e71fc17b99c3c4bfec8cf2653 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20St=C3=BCrmer?= Date: Thu, 15 Jun 2017 12:10:58 +0200 Subject: [PATCH 3/5] Fix garbled sentence --- style_guides/css_style_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style_guides/css_style_guide.md b/style_guides/css_style_guide.md index b35ca1063c9fa..eb5b126e93ebb 100644 --- a/style_guides/css_style_guide.md +++ b/style_guides/css_style_guide.md @@ -548,7 +548,7 @@ To avoid the combinatorial explosion of classes with such groupings and its modifiers, it is permissible to nest a block's selector under another block's selector if: -* The relationship is a if a very narrow `element` to `elementGroup` kind that +* The relationship is of a very narrow "`element` to `elementGroup`" kind that is apparent from the block names. * The rulesets are colocated in the same component directory. From 0044cc5909322e169a8b7b17783f61ec27cc364a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20St=C3=BCrmer?= Date: Thu, 15 Jun 2017 12:12:33 +0200 Subject: [PATCH 4/5] Use plural instead of singular possessive pronoun --- style_guides/css_style_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style_guides/css_style_guide.md b/style_guides/css_style_guide.md index eb5b126e93ebb..ddf465a80d76b 100644 --- a/style_guides/css_style_guide.md +++ b/style_guides/css_style_guide.md @@ -544,7 +544,7 @@ e.g.: ``` -To avoid the combinatorial explosion of classes with such groupings and its +To avoid the combinatorial explosion of classes with such groupings and thier modifiers, it is permissible to nest a block's selector under another block's selector if: From 3ea1877ff643b9308347a59223d4e2201e8a420b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20St=C3=BCrmer?= Date: Thu, 15 Jun 2017 12:13:22 +0200 Subject: [PATCH 5/5] Use "cannot" instead of "can not" --- style_guides/css_style_guide.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/style_guides/css_style_guide.md b/style_guides/css_style_guide.md index ddf465a80d76b..9c4cd6799a0cb 100644 --- a/style_guides/css_style_guide.md +++ b/style_guides/css_style_guide.md @@ -566,11 +566,10 @@ selector if: #### Exception: Normalization/Reset -We can not control the selectors introduced by third-party stylesheets and -these selectors may not adhere to our styleguide, e.g. `a` or -`input[type="text"]`. In these cases, we are forced to duplicate these -selectors within our own stylesheets and override those styles to control their -look and feel. +We cannot control the selectors introduced by third-party stylesheets and these +selectors may not adhere to our styleguide, e.g. `a` or `input[type="text"]`. +In these cases, we are forced to duplicate these selectors within our own +stylesheets and override those styles to control their look and feel. When this happens, it is important to add comments that make it clear why these selectors exist and which third-party dependencies they override. We should