mirror of
https://github.com/discourse/discourse.git
synced 2024-11-22 08:57:10 -06:00
UX: Add category & section for syntax & BEM (#24516)
This commit is contained in:
Jordan Vidrine
GitHub
parent
1e290eed7b
commit
fef14c004c
@ -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>
|
||||
@ -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 },
|
||||
|
||||
@ -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>
|
||||
@ -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"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user