‏راهنمای سبک Airbnb CSS / Sass

یک رویکرد عمدتا معقول به CSS و Sass

فهرست مطالب

1. ترمینولوژی
   • اعلامیه قوانین
   • انتخابگرها
   • ویژگی ها
2. CSS
   • قالب بندی
   • توضیحات
   • OOCSS و BEM
   • انتخابگرهای شناسه ای
   • قلاب های جاوا اسکریپتی
   • حاشیه
3. Sass
   • سینتکس
   • مرتب سازی
   • متغیر ها
   • میکسین ها(Mixins)
   • گسترش بخشنامه
   • انتخابگرهای تو در تو
4. ترجمه ها
5. مجوز

ترمینولوژی

اعلامیه قوانین

"اعلامیه قوانین" نامی است که به یک انتخابگر (یا گروهی از انتخابگرها) با گروهی از ویژگی ها داده می شود. برای مثال:

.listing {
  font-size: 18px;
  line-height: 1.2;
}

انتخابگرها

در یک اعلان قانون، “انتخابگرها“ بیت‌هایی هستند که تعیین می‌کنند کدام عناصر در درخت DOM با ویژگی‌های تعریف‌شده استایل‌بندی شوند. انتخابگرها می توانند عناصر HTML و همچنین کلاس یک عنصر، شناسه یا هر یک از ویژگی های آن را مطابقت دهند. در اینجا چند نمونه از انتخابگرها آورده شده است:

.my-element-class {
  /* ... */
}

[aria-hidden] {
  /* ... */
}

ویژگی ها

در نهایت، ویژگی‌ها چیزی هستند که به عناصر انتخابی یک اعلان قانون سبک خود را می‌دهند. ویژگی ها جفت های کلید-مقدار هستند و یک اعلان قانون می تواند حاوی یک یا چند اعلان ویژگی باشد. تعریف ویژگی ها به شرح زیر است:

/* some selector */ {
  background: #f1f1f1;
  color: #333;
}

⬆ بازگشت به بالا

‏CSS

قالب بندی

• از زبانه های نرم (2 فاصله) برای فرورفتگی استفاده کنید.
• در نام کلاس ها خط تیره را به camelCasing ترجیح دهید.
  • اگر از BEM استفاده می کنید، زیرخط و PascalCasing مشکلی ندارد (به OOCSS and BEM در زیر مراجعه کنید).
• از انتخابگرهای ID استفاده نکنید.
• هنگام استفاده از چند انتخابگر در یک اعلان قانون، به هر انتخابگر خط خاص خود را بدهید.
• قبل از بریس باز { در اعلان‌های قوانین یک فاصله قرار دهید.
• در ویژگی ها، یک فاصله بعد از کاراکتر : قرار دهید، اما نه قبل از آن.
• بریس بسته } اعلان‌های قوانین را در یک خط جدید قرار دهید.
• خطوط خالی بین اعلامیه های قوانین قرار دهید.

بد

.avatar{
    border-radius:50%;
    border:2px solid white; }
.no, .nope, .not_good {
    // ...
}
#lol-no {
  // ...
}

خوب

.avatar {
  border-radius: 50%;
  border: 2px solid white;
}

.one,
.selector,
.per-line {
  // ...
}

توضیحات

• برای بلوکی کردن نظرات، نظرات خط (// در Sass-land) را ترجیح دهید.
• نظرات را در خط خود ترجیح دهند. از اظهار نظرهای آخر خط خودداری کنید.
• برای کدهایی که مستندسازی نمی‌شوند، نظرات دقیق بنویسید:
  • موارد استفاده از z-index
  • سازگاری یا کد های خاص مرورگر

‏OOCSS و BEM

ما ترکیبی از OOCSS و BEM را به دلایل زیر تشویق می کنیم:

• این به ایجاد روابط واضح و دقیق بین CSS و HTML کمک می کند
• این به ما کمک می کند تا اجزای قابل استفاده مجدد و قابل ترکیب را ایجاد کنیم
• این امکان لانه سازی کمتر و ویژگی کمتر را فراهم می کند
• این به ساختن شیوه نامه های مقیاس پذیر کمک می کند

OOCSS، یا "CSS شی گرا"، رویکردی برای نوشتن CSS است که شما را تشویق می کند تا به شیوه نامه های خود به عنوان مجموعه ای از "اشیاء" فکر کنید: قطعات قابل استفاده مجدد و تکرار شونده که می توانند به طور مستقل در یک وب سایت استفاده شوند.

• Nicole Sullivan's راهنمای OOCSS
• Smashing Magazine's مقدمه ای بر OOCSS

BEM یا "Block-Element-Modifier" یک قرارداد نامگذاری برای کلاس های HTML و CSS است. این در ابتدا توسط Yandex با پایگاه های کد بزرگ و مقیاس پذیری در ذهن توسعه داده شد و می تواند به عنوان مجموعه ای محکم از دستورالعمل ها برای پیاده سازی OOCSS باشد.

• CSS Trick's BEM 101
• Harry Roberts' مقدمه ای بر BEM

ما یک نوع BEM را با "بلوک‌های PascalCased" توصیه می‌کنیم، که وقتی با کامپوننت‌ها (به عنوان مثال React) ترکیب می‌شود، به‌خوبی کار می‌کند. زیرخط و خط تیره هنوز برای اصلاح کننده ها و کودکان استفاده می شود.

مثال ها

// ListingCard.jsx
function ListingCard() {
  return (
    <article class="ListingCard ListingCard--featured">

      <h1 class="ListingCard__title">Adorable 2BR in the sunny Mission</h1>

      <div class="ListingCard__content">
        <p>Vestibulum id ligula porta felis euismod semper.</p>
      </div>

    </article>
  );
}

/* ListingCard.css */
.ListingCard { }
.ListingCard--featured { }
.ListingCard__title { }
.ListingCard__content { }

• ‏.ListingCard «بلوک» است و کامپوننت‌ سطح بالاتر را نشان می دهد
• ‏.ListingCard__title یک "عنصر" است و نشان دهنده نسل .ListingCard است که به ترکیب بلوک به عنوان یک کل کمک می کند.
• ‏.ListingCard--featured یک «تغییردهنده» است و وضعیت یا تغییر دیگری را در بلوک .ListingCard نشان می‌دهد.

انتخابگرهای شناسه ای

در حالی که امکان انتخاب عناصر توسط ID در CSS وجود دارد، به طور کلی باید آن را یک ضد الگو در نظر گرفت. انتخابگرهای شناسه سطح غیرضروری بالایی از ویژگی را به اعلامیه‌های قوانین شما معرفی می‌کنند و قابل استفاده مجدد نیستند.

برای اطلاعات بیشتر در مورد این موضوع، مقاله CSS Wizardry را در مورد پرداختن به ویژگی بخوانید.

قلاب های جاوا اسکریپتی

از اتصال به یک کلاس در CSS و JavaScript خودداری کنید. تلفیق این دو اغلب منجر به اتلاف زمان در طول بازسازی مجدد می شود، زمانی که یک توسعه دهنده باید به هر کلاسی که در حال تغییر است ارجاع دهد، و در بدترین حالت، توسعه دهندگان از ترس شکستن عملکرد می ترسند که تغییراتی ایجاد کنند.

توصیه می‌کنیم کلاس‌های اختصاصی جاوا اسکریپت را برای اتصال به آن‌ها با پیشوند .js- ایجاد کنید:

<button class="btn btn-primary js-request-to-book">Request to Book</button>

حاشیه

از 0 به جای none استفاده کنید تا مشخص کنید یک سبک حاشیه ندارد.

بد

.foo {
  border: none;
}

خوب

.foo {
  border: 0;
}

⬆ بازگشت به بالا

‏Sass

سینتکس

• از نحو .scss استفاده کنید، نه از نحو اصلی .sass.
• اعلان‌های CSS معمولی و @include خود را به صورت منطقی ترتیب دهید (به زیر مراجعه کنید)

مرتب سازی ویژگی ها

1. تعریف ویژگی ها

   همه تعریف ویژگی های استاندارد، هر چیزی که @include یا انتخابگر تودرتو نیست را لیست کنید.

    .btn-green {
      background: green;
      font-weight: bold;
      // ...
    }

2.‏@include تعریف

گروه بندی @include ها در پایان خواندن کل انتخابگر را آسان تر می کند.

    .btn-green {
      background: green;
      font-weight: bold;
      @include transition(background 0.5s ease);
      // ...
    }

3. انتخابگرهای تو در تو

   انتخابگرهای تودرتو، اگر لازم باشد، به آخر می‌روند، و هیچ چیز به دنبال آنها نمی‌رود. بین اعلان‌های قوانین و انتخابگرهای تودرتو و همچنین بین انتخابگرهای تودرتوی مجاور، فضای خالی اضافه کنید. همان دستورالعمل های بالا را برای انتخابگرهای تودرتو اعمال کنید.

    .btn {
      background: green;
      font-weight: bold;
      @include transition(background 0.5s ease);

      .icon {
        margin-right: 10px;
      }
    }

متغیر ها

نام متغیرهای dash-cased (مانند $my-variable) را به نام متغیر camelCased یا snake_cased ترجیح دهید. پیشوند نام متغیرهایی که قرار است فقط در یک فایل مورد استفاده قرار گیرند با زیرخط (مثلاً $_my-variable) قابل قبول است.

‏Mixins

میکسین ها باید برای جلوگیری از تکرار کد شما، اضافه کردن وضوح یا پیچیدگی انتزاعی استفاده شوند - به همان روشی که توابع نام‌گذاری شده خوب هستند. ترکیب‌هایی که هیچ آرگومانی را نمی‌پذیرند می‌توانند برای این کار مفید باشند، اما توجه داشته باشید که اگر بار خود را فشرده نمی‌کنید (به عنوان مثال gzip)، ممکن است باعث تکرار کدهای غیرضروری در سبک‌های حاصل شود.

گسترش بخشنامه

از @extend باید اجتناب شود، زیرا رفتار نامشهود و بالقوه خطرناکی دارد، به‌ویژه وقتی با انتخابگرهای تودرتو استفاده می‌شود. حتی اگر ترتیب انتخابگرها بعداً تغییر کند (مثلاً اگر در فایل‌های دیگر باشند و ترتیب بارگذاری فایل‌ها تغییر کند) می‌تواند باعث ایجاد مشکل شود. Gzipping باید بیشتر صرفه‌جویی‌هایی را که با استفاده از @extend به دست می‌آورید، انجام دهد، و می‌توانید با میکس‌ها تکرار کد در برگه‌های سبک خود را به خوبی کم کنید.

انتخابگرهای تو در تو

انتخابگرها را بیش از سه سطح در عمق قرار ندهید!

.page-container {
  .content {
    .profile {
      // ‎!توقف کنید
    }
  }
}

وقتی انتخابگرها اینقدر طولانی می شوند، احتمالاً CSS می نویسید که:

• به شدت با HTML (شکننده) همراه است — یا —
• بیش از حد خاص (قدرتمند) — یا —
• قابل استفاده مجدد نیست

تاکید میکنیم: هرگز انتخابگرهای شناسه را تودرتو نکنید

اگر در وهله اول باید از انتخابگر ID استفاده کنید (و واقعاً باید سعی کنید از این کار استفاده نکنید)، آنها هرگز نباید تو در تو باشند. اگر متوجه شدید که این کار را انجام می‌دهید، باید دوباره به نشانه‌گذاری خود مراجعه کنید یا بفهمید که چرا به چنین ویژگی قوی نیاز است. اگر HTML و CSS خوب می نویسید، هرگز نباید این کار را انجام دهید.

⬆ بازگشت به بالا

ترجمه ها

این راهنمای سبک به زبان های دیگر نیز موجود است:

• باهاسا اندونزی: mazipan/css-style-guide
• چینی (سنتی): ArvinH/css-style-guide
• زبان چینی ساده شده: Zhangjd/css-style-guide
• فرانسوی: mat-u/css-style-guide
• گرجی: DavidKadaria/css-style-guide
• ژاپنی: nao215/css-style-guide
• کره ای: CodeMakeBros/css-style-guide
• پرتغالی (برزیل): felipevolpatto/css-style-guide
• پرتغالی (پرتغال): SandroMiguel/airbnb-css-style-guide
• روسی: rtplv/airbnb-css-ru
• اسپانیایی: ismamz/guia-de-estilo-css
• ویتنامی: trungk18/css-style-guide
• ایتالیایی: antoniofull/linee-guida-css
• آلمانی: tderflinger/css-styleguide

⬆ بازگشت به بالا

مجوز

(مجوز MIT)

Copyright (c) 2015 Airbnb

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

⬆ بازگشت به بالا