diff --git a/README.md b/README.md index 0f3cab9..b8af69e 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,34 @@ -# Airbnb CSS / Sass Styleguide - -*A mostly reasonable approach to CSS and Sass* - -## Table of Contents - - 1. [Terminology](#terminology) - - [Rule Declaration](#rule-declaration) - - [Selectors](#selectors) - - [Properties](#properties) - 1. [CSS](#css) - - [Formatting](#formatting) - - [Comments](#comments) - - [OOCSS and BEM](#oocss-and-bem) - - [ID Selectors](#id-selectors) - - [JavaScript hooks](#javascript-hooks) - - [Border](#border) - 1. [Sass](#sass) - - [Syntax](#syntax) - - [Ordering](#ordering-of-property-declarations) - - [Variables](#variables) - - [Mixins](#mixins) - - [Extend directive](#extend-directive) - - [Nested selectors](#nested-selectors) - 1. [Translation](#translation) - -## Terminology - -### Rule declaration - -A “rule declaration” is the name given to a selector (or a group of selectors) with an accompanying group of properties. Here's an example: +# Airbnb CSS / Sass スタイルガイド + +*CSSとSASSを合理的に書くためのガイド* + +## 目次 + + 1. [用語](#terminology) + - [スタイルの宣言](#rule-declaration) + - [セレクタ](#selectors) + - [プロパティ](#properties) + 2. [CSS](#css) + - [フォーマット](#formatting) + - [コメント](#comments) + - [OOCSSとBEM](#oocss-and-bem) + - [IDセレクタ](#id-selectors) + - [JavaScriptフック](#javascript-hooks) + - [ボーダー](#border) + 3. [Sass](#sass) + - [シンタックス](#syntax) + - [順序](#ordering-of-property-declarations) + - [変数](#variables) + - [ミックスイン](#mixins) + - [Extend記法](#extend-directive) + - [セレクタのネスト](#nested-selectors) + 4. [翻訳](#translation) + +## 用語 + +### スタイルの宣言 + +"スタイルの宣言"とはセレクタ（もしくは複数のセレクタ）とそれに伴う１つ以上のプロパティのことである。 以下、例。 ```css .listing { @@ -37,9 +37,9 @@ A “rule declaration” is the name given to a selector (or a group of selector } ``` -### Selectors +### セレクタ -In a rule declaration, “selectors” are the bits that determine which elements in the DOM tree will be styled by the defined properties. Selectors can match HTML elements, as well as an element's class, ID, or any of its attributes. Here are some examples of selectors: +スタイルの宣言において、"セレクタ"はプロパティによってどのDOMにおける要素をスタイリングするかを決定するものである。セレクタはHTML要素のclass,id,もしくはその他のattributeのどれかにあたるものである。以下はセレクタの例である。 ```css .my-element-class { @@ -51,12 +51,13 @@ In a rule declaration, “selectors” are the bits that determine which element } ``` -### Properties +### プロパティ + +そして、プロパティは要素に対してスタイルを実際に定義するものである。プロパティはキーと値のセットであり、スタイルの宣言は１つ以上のプロパティの宣言を含むことができる。プロパティの定義は以下のようである。 -Finally, properties are what give the selected elements of a rule declaration their style. Properties are key-value pairs, and a rule declaration can contain one or more property declarations. Property declarations look like this: ```css -/* some selector */ { +/* ここにセレクタを記述する */ { background: #f1f1f1; color: #333; } @@ -64,19 +65,19 @@ Finally, properties are what give the selected elements of a rule declaration th ## CSS -### Formatting +### フォーマット -* Use soft tabs (2 spaces) for indentation -* Prefer dashes over camelCasing in class names. - - Underscores and PascalCasing are okay if you are using BEM (see [OOCSS and BEM](#oocss-and-bem) below). -* Do not use ID selectors -* When using multiple selectors in a rule declaration, give each selector its own line. -* Put a space before the opening brace `{` in rule declarations -* In properties, put a space after, but not before, the `:` character. -* Put closing braces `}` of rule declarations on a new line -* Put blank lines between rule declarations +* インデントは２スペース +* キャメルケースではなくダッシュを使うことを推奨 + - もしBEMを使っているのであればアンダースコアとパスカルケースは使用可能(下記の[OOCSS and BEM](#oocss-and-bem)をみてください) +* IDセレクタは使わない +* 複数セレクタのスタイルルールを宣言する場合は１行に１つのセレクタを記述する +* 中括弧の開始、つまり '{'の前にスペースを1つ入れる +* プロパティにおいて、`:`の前でなく後ろにスペースを１つ入れる +* 中括弧の終了、つまり `}`の前に改行を入れる +* スタイルの宣言の間には改行を入れること -**Bad** +**悪い例** ```css .avatar{ @@ -90,7 +91,7 @@ Finally, properties are what give the selected elements of a rule declaration th } ``` -**Good** +**良い例** ```css .avatar { @@ -105,36 +106,36 @@ Finally, properties are what give the selected elements of a rule declaration th } ``` -### Comments +### コメント -* Prefer line comments (`//` in Sass-land) to block comments. -* Prefer comments on their own line. Avoid end-of-line comments. -* Write detailed comments for code that isn't self-documenting: - - Uses of z-index - - Compatibility or browser-specific hacks +* コメントを記述する際は, ブロックコメント(`/* */`)ではなくラインコメント(`//`)を使う +* コメントはなるべく行末コメントを避け、コメント用に１行使う +* それ自身がドキュメントとなるように詳細にコメントを書く + - z-indexの使用 + - 互換性やブラウザ対応 -### OOCSS and BEM +### OOCSS と BEM -We encourage some combination of OOCSS and BEM for these reasons: +OOCSSとBEMの組み合わせを推奨。理由は以下の通り: - * It helps create clear, strict relationships between CSS and HTML - * It helps us create reusable, composable components - * It allows for less nesting and lower specificity - * It helps in building scalable stylesheets + * CSSとHTMLの間に明快で厳格な関係を生む + * 再利用しやすくなり、コンポーネントを組み立てやすくなる + * ネストの利用を減らし、詳細度を下げる + * 拡張性の高いスタイルシートを作り上げる -**OOCSS**, or “Object Oriented CSS”, is an approach for writing CSS that encourages you to think about your stylesheets as a collection of “objects”: reusable, repeatable snippets that can be used independently throughout a website. +**OOCSS**, もしくは “オブジェクト指向CSS”とは、スタイルシートをオブジェクトの集合として考えやすくするためにCSSを書く方法の一つである。ここでいうオブジェクトの集合の、 “オブジェクト”とはウェブサイトとは独立した再利用しやすいスニペットをさす。 * Nicole Sullivan's [OOCSS wiki](https://github.com/stubbornella/oocss/wiki) * Smashing Magazine's [Introduction to OOCSS](http://www.smashingmagazine.com/2011/12/12/an-introduction-to-object-oriented-css-oocss/) -**BEM**, or “Block-Element-Modifier”, is a _naming convention_ for classes in HTML and CSS. It was originally developed by Yandex with large codebases and scalability in mind, and can serve as a solid set of guidelines for implementing OOCSS. +**BEM**, もしくは“Block-Element-Modifier”, とはHTMLとCSSの命名規則である。Yandexのコードの拡張性についての思想から発展し、OOCSSを実装するためのガイドラインとして存在している。 * CSS Trick's [BEM 101](https://css-tricks.com/bem-101/) * Harry Roberts' [introduction to BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) -We recommend a variant of BEM with PascalCased “blocks”, which works particularly well when combined with components (e.g. React). Underscores and dashes are still used for modifiers and children. +BEMの変形であるパスカルケースを用いた “blocks”は、コンポーネント(Reactなど)を用いた時に特にうまく機能すると考えている。アンダースコアやダッシュはモディファーや子要素に使われている。 -**Example** +**例** ```jsx // ListingCard.jsx @@ -161,31 +162,31 @@ function ListingCard() { .ListingCard__content { } ``` - * `.ListingCard` is the “block” and represents the higher-level component - * `.ListingCard__title` is an “element” and represents a descendant of `.ListingCard` that helps compose the block as a whole. - * `.ListingCard--featured` is a “modifier” and represents a different state or variation on the `.ListingCard` block. - -### ID selectors + * `.ListingCard`は “block”であり、高階層のコンポーネントを表している + * `.ListingCard__title` は“element”であり、`.ListingCard`をblockとして構成するための構成要素である子孫要素として表される + * `.ListingCard--featured`は “modifier”であり、`.ListingCard`の異なる状態やブロックのバリエーションの一つとして表される -While it is possible to select elements by ID in CSS, it should generally be considered an anti-pattern. ID selectors introduce an unnecessarily high level of [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) to your rule declarations, and they are not reusable. +### IDセレクタ -For more on this subject, read [CSS Wizardry's article](http://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/) on dealing with specificity. +CSSではIDによってセレクタとして要素を決定することができるが、それはアンチパターンとして考えられるべきでもある。IDセレクタはスタイルの宣言に不必要に高い[詳細度](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity)をもたらし、再利用ができない。 -### JavaScript hooks +この詳細度の扱いについては [CSS Wizardry's article](http://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/)を読むと良い。 -Avoid binding to the same class in both your CSS and JavaScript. Conflating the two often leads to, at a minimum, time wasted during refactoring when a developer must cross-reference each class they are changing, and at its worst, developers being afraid to make changes for fear of breaking functionality. +### JavaScript フック -We recommend creating JavaScript-specific classes to bind to, prefixed with `.js-`: +同じクラスをCSSとJavaScriptの両方でバインディング（JSのイベントをつけつつスタイリングを行うなど）をするのは避けること。この２つを混同することは少なくとも開発者が変更を行うCSSとJavaScriptの両方を理解しなければならないことになり時間の無駄であるし、最悪の場合は機能が壊れることを恐れて変更をすることを躊躇してしまう。 + +`.js-`という接頭辞を持つJavaScriptバインド専用のクラスを作ることを推奨する。 ```html ``` -### Border +### ボーダーBorder -Use `0` instead of `none` to specify that a style has no border. +ボーダーのないスタイルには`none`の代わりに0を使うこと。 -**Bad** +**悪い例** ```css .foo { @@ -193,7 +194,7 @@ Use `0` instead of `none` to specify that a style has no border. } ``` -**Good** +**良い例** ```css .foo { @@ -203,16 +204,16 @@ Use `0` instead of `none` to specify that a style has no border. ## Sass -### Syntax +### シンタックス -* Use the `.scss` syntax, never the original `.sass` syntax -* Order your regular CSS and `@include` declarations logically (see below) +* scssシンタックスを使い、元のsassシンタックスは使わない +* 通常のCSS, `@include`記法の宣言などの順序（下記参照） -### Ordering of property declarations +### プロパティの宣言順序 -1. Property declarations +1. プロパティの宣言 - List all standard property declarations, anything that isn't an `@include` or a nested selector. + `@include`やネストセレクタなどではない通常のプロパティを全て並べる ```scss .btn-green { @@ -222,9 +223,9 @@ Use `0` instead of `none` to specify that a style has no border. } ``` -2. `@include` declarations +2. `@include`記法の記述 - Grouping `@include`s at the end makes it easier to read the entire selector. + `@include`のまとまりを作るとセレクタ全体を読むのが楽になる ```scss .btn-green { @@ -235,9 +236,9 @@ Use `0` instead of `none` to specify that a style has no border. } ``` -3. Nested selectors +3. セレクタのネスト - Nested selectors, _if necessary_, go last, and nothing goes after them. Add whitespace between your rule declarations and nested selectors, as well as between adjacent nested selectors. Apply the same guidelines as above to your nested selectors. + セレクタのネストは,_仮に必要なのであれば_, 中括弧の最後に記述しその後ろには何も書かない。ネストされたスタイルの宣言の前には１行空ける。また、上記の複数セレクタと同様に複数セレクタを記述する際は上記のガイドラインにしたがって１行に１セレクタの記述とする。 ```scss .btn { @@ -251,21 +252,23 @@ Use `0` instead of `none` to specify that a style has no border. } ``` -### Variables +### 変数 + +変数の名前にはキャメルケースやスネークケースではなくダッシュつなぎを使用する。接頭辞として同じファイル内でのみ使われる変数に関しては例外として使用を認める。(例. `$_my-variable`) -Prefer dash-cased variable names (e.g. `$my-variable`) over camelCased or snake_cased variable names. It is acceptable to prefix variable names that are intended to be used only within the same file with an underscore (e.g. `$_my-variable`). +### ミックスイン -### Mixins +ミックスインはDRY(Don't Repeat Yourselfの略)にし明快にするため、もしくは良い名前がつけられた関数のように複雑さを抽象化するために使われるべきだ。このためにミックスインを使うのは何ら問題ないが、もしファイル通信を圧縮していないのであれば（例. gzipなど）,　このことは余計なコードの重複をもたらすので注意しなければならない。 -Mixins should be used to DRY up your code, add clarity, or abstract complexity--in much the same way as well-named functions. Mixins that accept no arguments can be useful for this, but note that if you are not compressing your payload (e.g. gzip), this may contribute to unnecessary code duplication in the resulting styles. -### Extend directive +### Extend記法 -`@extend` should be avoided because it has unintuitive and potentially dangerous behavior, especially when used with nested selectors. Even extending top-level placeholder selectors can cause problems if the order of selectors ends up changing later (e.g. if they are in other files and the order the files are loaded shifts). Gzipping should handle most of the savings you would have gained by using `@extend`, and you can DRY up your stylesheets nicely with mixins. +`@extend` 記法は直感的ではなく、危険な振る舞いを引き起こす可能性があるため、特にネストさせている場合などは使うべきではない。たとえ一番上の階層で仮置きとしてのセレクタを拡張するのだとしても、もしセレクタの順序を後々変更してしまった場合などに問題を引き起こす。（例えば異なるファイルにその記述があり、ファイルのロード順序がずれた場合など） +gzipをかければ`@extend`を使うことによって得られる合理的な出力結果のメリットの大抵はカバーできるし、ミックスインを使えばDRYな素晴らしいコードを生み出すことができる。 -### Nested selectors +### セレクタのネスト -**Do not nest selectors more than three levels deep!** +**３階層以上ネストさせない** ```scss .page-container { @@ -277,20 +280,19 @@ Mixins should be used to DRY up your code, add clarity, or abstract complexity-- } ``` -When selectors become this long, you're likely writing CSS that is: - -* Strongly coupled to the HTML (fragile) *—OR—* -* Overly specific (powerful) *—OR—* -* Not reusable - +もしセレクタの階層がこれほど深くなった場合、あなたのCSSは以下のようになっていると考えられる: -Again: **never nest ID selectors!** +* HTMLとの結びつきが強くなりすぎている、もしくは +* セレクタの詳細度が高すぎる、もしくは +* 再利用できない -If you must use an ID selector in the first place (and you should really try not to), they should never be nested. If you find yourself doing this, you need to revisit your markup, or figure out why such strong specificity is needed. If you are writing well formed HTML and CSS, you should **never** need to do this. +もう一度： **決してIDセレクタはネストさせてはいけない!** -## Translation +もしIDセレクタを最初におきたい場合（本来やるべきではないが）、決してネストさせてはいけまない。もしあなた自身がこのようなことをしていると気づいた場合は、もう一度マークアップを見直すかなぜそのような強い詳細度にしなければならなかったのかを確認する必要がある。もしHTMLとCSSを正しいフォーマットで書いていればこのようなことをする必要は**絶対に**ない。 - This style guide is also available in other languages: +## 翻訳 + このスタイルガイドでは以下の言語でも読むことができます: + - ![us](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/United-States.png) **English**: [airbnb/css](https://github.com/airbnb/css) - ![cn](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/China.png) **Chinese (Simplified)**: [Zhangjd/css-style-guide](https://github.com/Zhangjd/css-style-guide) - ![ru](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Russia.png) **Russian**: [Nekorsis/css-style-guide](https://github.com/Nekorsis/css-style-guide)