# متدولوژی BEM در CSS

این Skill را زمانی فعال کن که کاربر طراحی نام کلاس‌های CSS، پیاده‌سازی BEM، بررسی مشکلات نام‌گذاری یا بازنویسی استایل یک کامپوننت بدون تغییر رفتار ظاهری را می‌خواهد.

## اهداف

- نام کلاس‌هایی قابل پیش‌بینی تولید کن که ساختار و وضعیت UI را نشان دهند.
- استایل کامپوننت‌ها را مستقل نگه دار و Specificity سلکتورها را کاهش بده.
- هنگام بازنویسی نام‌ها، رفتار فعلی رابط کاربری را حفظ کن.
- نتیجه را طوری طراحی کن که اعضای تیم بتوانند آن را یکدست توسعه دهند.

## قرارداد اصلی

از قالب‌های زیر استفاده کن:

```text
block
block__element
block--modifier
block__element--modifier
```

- **Block** یک مفهوم مستقل رابط کاربری مانند `card` یا `navbar` است.
- **Element** به یک Block تعلق دارد و بیرون از آن معنای مستقلی ندارد؛ مانند `card__title`.
- **Modifier** یک حالت یا نسخه متفاوت را نمایش می‌دهد؛ مانند `card--featured` یا `card__button--active`.

## روند کار

1. قبل از ویرایش، Markup، استایل‌ها، مرز کامپوننت‌ها و قرارداد نام‌گذاری موجود پروژه را بررسی کن.
2. Blockهای مستقل رابط کاربری را شناسایی کن. نام دامنه یا کامپوننت را به نام وابسته به محل ترجیح بده.
3. پیش از پیشنهاد نام کلاس‌ها، Elementها، Variantها و Stateهای هر Block را فهرست کن.
4. اگر پروژه از قبل قرارداد منسجمی دارد، همان را حفظ کن. اگر افزودن BEM فقط به یک فایل باعث ناهماهنگی می‌شود، آن را تحمیل نکن.
5. اگر بازنویسی چند فایل یا سلکتور عمومی را تغییر می‌دهد، ابتدا یک برنامه نام‌گذاری کوتاه ارائه کن.
6. Markup و CSS را هم‌زمان تغییر بده تا سلکتور قدیمی باقی نماند.
7. بعد از ویرایش، تمام استفاده‌های نام‌های قدیمی را جست‌وجو کن و تست‌ها، اسکریپت‌ها یا مستندات مرتبط را به‌روزرسانی کن.
8. در صورت وجود، Lint، تست و بررسی بصری مرتبط پروژه را اجرا کن.

## قوانین نام‌گذاری

- از lowercase kebab-case استفاده کن: `product-card`، نه `ProductCard` یا `product_card`.
- نام Block باید معنادار و مستقل باشد؛ وقتی محل بخشی از هویت کامپوننت نیست، `card` را به `sidebar-card` ترجیح بده.
- ساختار DOM را داخل نام کلاس تکرار نکن؛ `card__icon` بهتر از `card__header__button__icon` است.
- برای استایل کامپوننت از سلکتورهای Tag، ID یا Nesting عمیق استفاده نکن.
- Modifier را فقط برای حالت یا Variant واقعی به کار ببر، نه برای هر فرزند دلخواه.
- نام‌گذاری State را با پروژه هماهنگ نگه دار. اگر پروژه از `is-active`، ویژگی ARIA یا data attribute استفاده می‌کند، قرارداد رقیب نساز.
- برای جبران ساختار ضعیف سلکتورها از `!important` استفاده نکن.

## مثال

```html
<article class="card card--featured">
  <h2 class="card__title">مهارت ایجنت</h2>
  <p class="card__description">دستورالعمل قابل استفاده مجدد برای ایجنت هوش مصنوعی.</p>
  <button class="card__button card__button--active">نصب</button>
</article>
```

```css
.card {
  display: grid;
  gap: 0.75rem;
}

.card--featured {
  border-color: #8b5cf6;
}

.card__title {
  margin: 0;
}

.card__button--active {
  background: #7c3aed;
}
```

## الگوهای نامناسب

```css
/* وابسته به محل و غیرقابل استفاده مجدد */
.sidebar .card .header h2 {}

/* تکرار ساختار DOM در نام Element */
.card__header__title {}

/* استفاده از Modifier بدون کلاس پایه در Markup */
.card--featured {}
```

هنگام استفاده از Modifier، کلاس پایه را نیز در Markup نگه دار: `class="card card--featured"`.

## انتظار از خروجی

هنگام Review یا Refactor:

1. مشکلات نام‌گذاری مؤثر بر نگهداری کد را خلاصه کن.
2. نقشه پیشنهادی Block، Element و Modifier را نشان بده.
3. کوچک‌ترین تغییر منسجم برای حل مسئله را انجام بده.
4. سلکتورهای عمومی تغییرنام‌یافته و اثر احتمالی آن‌ها بر Integrationها را مشخص کن.
5. اعتبارسنجی‌های انجام‌شده و بررسی‌هایی که امکان اجرای آن‌ها نبود را گزارش بده.

## ایمنی و محدودیت‌ها

- تا زمانی که کاربر تغییر طراحی نخواسته، رفتار ظاهری را تغییر نده.
- سلکتورهای تولیدشده یا الزامی کتابخانه‌های ثالث را تغییر نام نده.
- سلکتورهای استفاده‌شده در JavaScript، تست، Analytics یا Integrationهای خارجی را قرارداد عمومی در نظر بگیر و با دقت به‌روزرسانی کن.
- اگر محدوده درخواست مبهم است، پیش از مهاجرت نام‌گذاری در کل مخزن از کاربر جهت بگیر.