rsBEM v2.0.0

A layered CSS naming system for MVC projects.

Three layers — one convention — zero ambiguity.

🏗️ The Three Layers

Layer	Name	Pattern	Scope
1	Template (rsBEM)	folder-file__element--modifier	Styles for a single .tpl file
2	Component (BEM)	block__element--modifier	Shared, reusable UI components
3	Utility	prefix-value	Single-purpose global helper classes

Decision Flowchart

Is this style for a single template file?
├── YES → Layer 1 (Template / rsBEM)
│         .sale-return_request__save-btn
└── NO → Is it a reusable UI component (library or project-specific)?
         ├── YES → Layer 2 (Component / BEM)
         │         .modal__header  .btn--pri  .admin-heading__title
         └── NO → Is it a single-purpose CSS property?
                  └── YES → Layer 3 (Utility)
                            .d-flex  .padding-sm  .text-center

📐 Layer 1: Template (rsBEM)

Why hyphen as the separator? Underscores are used within folder and file names (snake_case). The hyphen (-) is reserved exclusively as the folder↔file separator, making parsing unambiguous.

Segment	Separator	Case	Description
folder	start	preserves original	Template directory name (keeps snake_case if the directory uses it)
file_name	- after folder	preserves original	Template file name (keeps snake_case if the file uses it)
element-name	__	kebab-case	Describes what the element is
modifier	--	kebab-case	State or variant

🔗 File Mapping

The class prefix maps 1:1 to the template path. A Ctrl + Shift + F search on any class locates both the template and its styles.

Multi-Word Folder

Nested Folder

When templates live in nested directories, each folder segment is separated by a hyphen — the same separator used between folder and file. The last segment before __ is always the file:

🧠 Core Principles

1. Flat Hierarchy — No DOM Nesting

The HTML tree is not mirrored in class names. The element name describes what it is, not where it sits.

2. Semantic Grouping — Hyphens Group, Underscores Separate

Hyphens express logical grouping within element names. Underscores are not used for sub-elements.

3. Descriptive Names — No Ambiguity

Element names are specific enough to understand without surrounding context.

✅ Correct vs ❌ Incorrect

🔀 rsBEM vs BEM

Aspect	BEM	rsBEM
Block naming	Free-form	File-route prefix
File location	Unknown from class	Readable from class name
Scope	Component-scoped	File/template-scoped
Reusability	Cross-project	Within project
Searchability	Requires convention	Built-in (grep friendly)

⚙️ Stylelint Rule

{
  "rules": {
    "selector-class-pattern": [
      "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*(?:-[a-z][a-z0-9]*(?:_[a-z0-9]+)*)+__[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$",
      {
        "message": "Class names must follow rsBEM: [folder]-[file_name]__[element-name]--[modifier]"
      }
    ]
  }
}

🧩 Layer 2: Component (Standard BEM)

Shared, reusable UI components (library or project). No file-path prefix — just standard BEM.

Rule	Correct	Incorrect
Sub-elements use __	.tooltip__arrow	.tooltip-arrow
Modifiers use --	.tooltip--top	.tooltip.top
Block name is kebab-case	.slide-menu__header	.slide-menu-header

Examples: .modal__header, .btn--pri, .switch__slider, .tab__head--active, .admin-heading__title, .status--danger

🔧 Layer 3: Utility

Single-purpose, composable classes. Pattern: prefix-value. No BEM structure.

Category	Prefix	Examples
Display	d-	d-flex, d-grid, d-none
Flex	flex-	flex-center, flex-col, flex-gap-md
Padding	padding-	padding-sm, padding-y-md
Margin	margin-	margin-sm, margin-t-md
Text	text-	text-center, text-upper, text-nowrap
Font Size	fsi-	fsi-14, fsi-16, fsi-20
Font Weight	fwe-	fwe-semibold, fwe-bold
Image	img-	img-responsive, img-circle
Theme Color	tc-	tc-pri-500, tc-text-dark-1
Theme BG	tbc-	tbc-pri-100, tbc-grey-300
Width / Height	w- / h-	w-full, h-auto
Position	pos-	pos-relative, pos-absolute
Cursor	cursor-	cursor-pointer, cursor-default