Skip to content

[ CodeStyle ] Add class conventions #22

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.

Sign up for GitHub

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[ CodeStyle ] Add class conventions #22

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7107647
[ CodeStyle ] Add class conventions
jamesnw Aug 26, 2025
8b58af5
Remove has, update wording
jamesnw Aug 27, 2025
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
View file
Open in desktop
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 [`oui-` namespace](#namespace), OUI uses class prefixes to
provide context about the role a class plays within the design system. OUI uses
the following class prefix conventions:
Comment on lines +89 to +91
Copy link
Collaborator

@gfellerph gfellerph Sep 2, 2025

Choose a reason for hiding this comment

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

While there is a definite technological and logical reason to use a prefix for class names, I'm not so sure about the Hungarian Notation on top of that. I'm wondering in what ways it's useful for beginners to have that distinction (that has to be learned first for c, l and u) and if experienced users even need it because they might already know the categorisation by the class name itself.

I could see some points from the disadvantages section on the Hungarian Notation also be brought up by future users, especially around redundancy, readability and deductibility. I'm not sure if it's clear all the time if something belongs to the layout or component category and I could see myself guessing wrong in the heat of the moment.

Are there, besides the added clarity, also technological or other types of benefits to this notation?

On the other hand, the is and has part of the story do make sense to me due to clearly enhanced readability and could also be extended to more verbs (.oui-makes-loopings or whatever).


- **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** - for specific states, such as `.oui-is-active`
Copy link
Contributor Author

@jamesnw jamesnw Aug 27, 2025

Choose a reason for hiding this comment

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

Suggested change
- **is** - for specific states, such as `.oui-is-active`
- **is** - for specific states, such as `.oui-is-active`
All classes must use one of these categories.

Should this be a requirement? I'm not thinking of exceptions- sections within a component would still have c, for instance .oui-c-card__header. We may need to add more prefixes in that case.


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

Expand Down