github-mirror/discourse
2
0
Fork 0
mirror of https://github.com/discourse/discourse.git synced 2024-11-23 03:09:00 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

UX: Add category & section for syntax & BEM (#24516)

Browse Source
This commit is contained in:
Jordan Vidrine 2023-11-22 17:44:04 -06:00 committed by GitHub
parent 1e290eed7b
commit fef14c004c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 86 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
plugins/styleguide/assets/javascripts/discourse/components/sections/syntax/00-bem.hbs Normal file
View File

@ -0,0 +1,80 @@
<div class="section-description">
<p>
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:
<ul>
<li>Block</li>
<li>Element</li>
<li>Modifier</li>
</ul>
</p>
<p>We use a slightly modified version of the BEM classname format.</p>
<h3>Block</h3>
For example
<strong><code>d-modal</code></strong>
<p>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.</p>
<h3>Element</h3>
For example
<strong><code>d-modal__header</code></strong>
<p>
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
<code>d-modal__header</code>
will only work within the d-modal block, but not when placed elsewhere.
</p>
<h3>Modifiers</h3>
Examples
<strong><code>--success</code>,
<code>--large</code>,<code>--inline</code>,
<code>--highlighted</code></strong>
<p>
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).
</p>
<p>In classic BEM, a modifier looks like:
<code>d-modal__header--success</code>. This can quickly turn into very
verbose HTML. Imagine an already long block-element name, for example:
<p>
<code>class="chat-message-creator__search-container"</code>
</p>
With classic BEM and 2 modifiers, it would look like this:
<p>
<code>class="chat-message-creator__search-container
chat-message-creator__search-container--highlighted
chat-message-creator__search-container--inline"</code>
</p>
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:
<p>
<code>class="chat-message-creator__search-container --highlighted
--inline"</code>
</p>
which is far more readable.
</p>
<h4>Special modifiers</h4>
Some special prefixes are useful to identify modifiers as temporary states or
condition. These are:
<ul>
<li><code>is-foo</code> = example: is-open</li>
<li><code>has-foo</code> = example: has-errors</li>
</ul>
<h3>In Code</h3>
<p>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.</p>
</div>

4
plugins/styleguide/assets/javascripts/discourse/lib/styleguide.js
View File

@ -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 },

80
plugins/styleguide/assets/javascripts/discourse/templates/styleguide/index.hbs
View File

@ -2,84 +2,4 @@
<div class="description">
{{i18n "styleguide.welcome"}}
</div>
<h1>Syntax</h1>
<h2>BEM</h2>
<p>
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:
<ul>
<li>Block</li>
<li>Element</li>
<li>Modifier</li>
</ul>
</p>
<p>We use a slightly modified version of the BEM classname format.</p>
<h3>Block</h3>
For example
<strong><code>d-modal</code></strong>
<p>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.</p>
<h3>Element</h3>
For example
<strong><code>d-modal__header</code></strong>
<p>
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
<code>d-modal__header</code>
will only work within the d-modal block, but not when placed elsewhere.
</p>
<h3>Modifiers</h3>
Examples
<strong><code>--success</code>,
<code>--large</code>,<code>--inline</code>,
<code>--highlighted</code></strong>
<p>
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).
</p>
<p>In classic BEM, a modifier looks like:
<code>d-modal__header--success</code>. This can quickly turn into very
verbose HTML. Imagine an already long block-element name, for example:
<p>
<code>class="chat-message-creator__search-container"</code>
</p>
With classic BEM and 2 modifiers, it would look like this:
<p>
<code>class="chat-message-creator__search-container
chat-message-creator__search-container--highlighted
chat-message-creator__search-container--inline"</code>
</p>
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:
<p>
<code>class="chat-message-creator__search-container --highlighted
--inline"</code>
</p>
which is far more readable.
</p>
<h4>Special modifiers</h4>
Some special prefixes are useful to identify modifiers as temporary states or
condition. These are:
<ul>
<li><code>is-foo</code> = example: is-open</li>
<li><code>has-foo</code> = example: has-errors</li>
</ul>
<h3>In Code</h3>
<p>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.</p>
</StyleguideSection>

3
plugins/styleguide/config/locales/client.en.yml
View File

@ -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"