diff --git a/plugins/styleguide/assets/javascripts/discourse/components/sections/syntax/00-bem.hbs b/plugins/styleguide/assets/javascripts/discourse/components/sections/syntax/00-bem.hbs new file mode 100644 index 00000000000..4a0e648a0d9 --- /dev/null +++ b/plugins/styleguide/assets/javascripts/discourse/components/sections/syntax/00-bem.hbs @@ -0,0 +1,80 @@ +
+

+ The guidelines outlines below strive to bring structure and consistency to + our classnames. Additionally, with this approach the nesting of css is + firmly reduced. BEM stands for: +

+

+

We use a slightly modified version of the BEM classname format.

+

Block

+ For example + d-modal +

A block is a standalone component. Blocks can be used within blocks. It + should be a "top-level" element, which could be used in its entirety in + another place of the app. It has no dependencies on any parent class.

+

Element

+ For example + d-modal__header +

+ An element is a part of a block that can not be used outside that context. + They because it depends on the parent class and can not be used standalone + outside this context. In the example above, an element with class + d-modal__header + will only work within the d-modal block, but not when placed elsewhere. +

+

Modifiers

+ Examples + --success, + --large,--inline, + --highlighted +

+ A modifier is used mainly for changing the appearance, if different than the + default. It is less than an element, and has no html structure of it own. + Meaning, it can only exist when applied to an element (or potentially a + block). +

+

In classic BEM, a modifier looks like: + d-modal__header--success. This can quickly turn into very + verbose HTML. Imagine an already long block-element name, for example: + +

+ class="chat-message-creator__search-container" +

+ + With classic BEM and 2 modifiers, it would look like this: + +

+ class="chat-message-creator__search-container + chat-message-creator__search-container--highlighted + chat-message-creator__search-container--inline" +

+ + To avoid this, we decouple our modifiers from the BE parts of the classnames + and use them as separate classes. So in the previous case with 2 modifiers + this turns into: +

+ class="chat-message-creator__search-container --highlighted + --inline" +

+ + which is far more readable. +

+ +

Special modifiers

+ Some special prefixes are useful to identify modifiers as temporary states or + condition. These are: + + +

In Code

+

Even though the BEM convention avoids nesting, we can use SCSS to write the + code nested. This is to taste, but I find it easier to read and write, + because it will keep all relevant elements and modifiers grouped together + and avoids unnecessary repetition of the block class.

+
\ No newline at end of file diff --git a/plugins/styleguide/assets/javascripts/discourse/lib/styleguide.js b/plugins/styleguide/assets/javascripts/discourse/lib/styleguide.js index 000ad30e5e7..14b64e00d47 100644 --- a/plugins/styleguide/assets/javascripts/discourse/lib/styleguide.js +++ b/plugins/styleguide/assets/javascripts/discourse/lib/styleguide.js @@ -36,13 +36,15 @@ import navigation from "../components/sections/organisms/navigation"; import siteHeader from "../components/sections/organisms/site-header"; import suggestedTopics from "../components/sections/organisms/suggested-topics"; import userAbout from "../components/sections/organisms/user-about"; +import bem from "../components/sections/syntax/00-bem"; let _allCategories = null; let _sectionsById = {}; -export const CATEGORIES = ["atoms", "molecules", "organisms"]; +export const CATEGORIES = ["syntax", "atoms", "molecules", "organisms"]; const SECTIONS = [ + { component: bem, category: "syntax", id: "bem", priority: 0 }, { component: typography, category: "atoms", id: "typography", priority: 0 }, { component: fontScale, category: "atoms", id: "font-scale", priority: 1 }, { component: buttons, category: "atoms", id: "buttons", priority: 2 }, diff --git a/plugins/styleguide/assets/javascripts/discourse/templates/styleguide/index.hbs b/plugins/styleguide/assets/javascripts/discourse/templates/styleguide/index.hbs index 7d2b8c4e905..e0fe882bc2e 100644 --- a/plugins/styleguide/assets/javascripts/discourse/templates/styleguide/index.hbs +++ b/plugins/styleguide/assets/javascripts/discourse/templates/styleguide/index.hbs @@ -2,84 +2,4 @@
{{i18n "styleguide.welcome"}}
-

Syntax

-

BEM

-

- The guidelines outlines below strive to bring structure and consistency to - our classnames. Additionally, with this approach the nesting of css is - firmly reduced. BEM stands for: -

-

-

We use a slightly modified version of the BEM classname format.

-

Block

- For example - d-modal -

A block is a standalone component. Blocks can be used within blocks. It - should be a "top-level" element, which could be used in its entirety in - another place of the app. It has no dependencies on any parent class.

-

Element

- For example - d-modal__header -

- An element is a part of a block that can not be used outside that context. - They because it depends on the parent class and can not be used standalone - outside this context. In the example above, an element with class - d-modal__header - will only work within the d-modal block, but not when placed elsewhere. -

-

Modifiers

- Examples - --success, - --large,--inline, - --highlighted -

- A modifier is used mainly for changing the appearance, if different than the - default. It is less than an element, and has no html structure of it own. - Meaning, it can only exist when applied to an element (or potentially a - block). -

-

In classic BEM, a modifier looks like: - d-modal__header--success. This can quickly turn into very - verbose HTML. Imagine an already long block-element name, for example: - -

- class="chat-message-creator__search-container" -

- - With classic BEM and 2 modifiers, it would look like this: - -

- class="chat-message-creator__search-container - chat-message-creator__search-container--highlighted - chat-message-creator__search-container--inline" -

- - To avoid this, we decouple our modifiers from the BE parts of the classnames - and use them as separate classes. So in the previous case with 2 modifiers - this turns into: -

- class="chat-message-creator__search-container --highlighted - --inline" -

- - which is far more readable. -

- -

Special modifiers

- Some special prefixes are useful to identify modifiers as temporary states or - condition. These are: - - -

In Code

-

Even though the BEM convention avoids nesting, we can use SCSS to write the - code nested. This is to taste, but I find it easier to read and write, - because it will keep all relevant elements and modifiers grouped together - and avoids unnecessary repetition of the block class.

\ No newline at end of file diff --git a/plugins/styleguide/config/locales/client.en.yml b/plugins/styleguide/config/locales/client.en.yml index fc227051380..9247112fce6 100644 --- a/plugins/styleguide/config/locales/client.en.yml +++ b/plugins/styleguide/config/locales/client.en.yml @@ -5,11 +5,14 @@ en: welcome: "To get started, choose a section from the menu on the left." categories: + syntax: Syntax atoms: Atoms molecules: Molecules organisms: Organisms sections: + bem: + title: "BEM" typography: title: "Typography" example: "Welcome to Discourse"