Skip to content
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion docs/style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,32 @@ the primary implementations.

### CSS conventions

*TODO: Add class naming rules*
#### BEM syntax

OUI follows a [BEM](http://getbem.com/introduction/)-like syntax, extending it
further to follow more of
[BEMIT](http://csswizardry.com/2015/08/bemit-taking-the-bem-naming-convention-a-step-further/)-like
conventions.

BEM stands for "Block Element Modifier". Here's a breakdown of what that means:

- **Block** is the primary component block (e.g. .oui-c-button)
- **Element** is a child of the primary block (e.g. .oui-c-button__text)
- **Modifier** is a variation of a component style (e.g. .oui-c-button--secondary)

OUI extends BEM's conventions to create even more explicit, encapsulated class
names.

### Class prefixes

In addition to the [global `oui-` namespace](#namespace), OUI uses class prefixes to provide
additional clarity to the job a given class plays. OUI uses the following class
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we want to say “plays a role“ or “has a job”?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I played around with the wording a bit- is it clearer now?

prefix conventions:

- **c** - for UI components, such as `.oui-c-button`
- **l** - for layout-specific component styles, such as `.oui-l-container`
- **u** - for utilities, such as `.oui-u-margin-bottom-none`
- **is** - and has- for specific states, such as `.oui-is-active`

*TODO: Add property usage rules, for instance preference for logical properties*

Expand Down