From 7107647815038d6967f13ed555337eb624761937 Mon Sep 17 00:00:00 2001 From: James Stuckey Weber Date: Tue, 26 Aug 2025 16:17:29 -0400 Subject: [PATCH 1/2] [ CodeStyle ] Add class conventions --- docs/style-guide.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/style-guide.md b/docs/style-guide.md index 84c3d21..e45fb63 100644 --- a/docs/style-guide.md +++ b/docs/style-guide.md @@ -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 +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* From 8b58af5f852f3b488afea0bb28b8c37cce775819 Mon Sep 17 00:00:00 2001 From: James Stuckey Weber Date: Wed, 27 Aug 2025 08:55:47 -0400 Subject: [PATCH 2/2] Remove has, update wording --- docs/style-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/style-guide.md b/docs/style-guide.md index e45fb63..b11b20e 100644 --- a/docs/style-guide.md +++ b/docs/style-guide.md @@ -84,16 +84,16 @@ BEM stands for "Block Element Modifier". Here's a breakdown of what that means: OUI extends BEM's conventions to create even more explicit, encapsulated class names. -### Class prefixes +#### 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 -prefix conventions: +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: - **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` +- **is** - for specific states, such as `.oui-is-active` *TODO: Add property usage rules, for instance preference for logical properties*