-
Notifications
You must be signed in to change notification settings - Fork 8.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[docs] Add css style guide section on open/closed principle #12276
Changes from 1 commit
4fa3418
c6a0df7
3599cb0
0044cc5
3ea1877
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
<div class="kuiCardGroup"> | ||
<div class="kuiCard kuiCardGroup__card"> | ||
<div class="kuiCard__description kuiCardGroup__cardDescription"> | ||
Card Description | ||
</div> | ||
</div> | ||
</div> | ||
``` | ||
|
||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Whoa, what happened with this sentence? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. oops, fixed |
||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What do you mean by re-using a selector so that the styles can be integrated into the project? Are there examples of this in the codebase? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I was thinking of more generic selectors like There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Oh that makes a lot of sense. Could we reword this part? I usually think of this in terms of overriding selectors which we don't control. My suggestion:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. absolutely, thanks for the improvement! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
its
reads weirdly here. Should it betheir
? Isit
referringa block
?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍 it is referring to
groupings
, sotheir
would be correct