├── README.md
└── translations
├── cs-CZ
└── README.md
├── da-DK
└── README.md
├── de-DE
└── README.md
├── es-ES
└── README.md
├── fr-FR
└── README.md
├── id-ID
└── README.md
├── it-IT
└── README.md
├── ja-JP
└── README.md
├── ko-KR
└── README.md
├── nl-NL
└── README.md
├── pl-PL
└── README.md
├── pt-BR
└── README.md
├── ru-RU
└── README.md
├── sr-SR
└── README.md
├── tr-TR
└── README.md
├── zh-CN
└── README.md
└── zh-TW
└── README.md
/README.md:
--------------------------------------------------------------------------------
1 | # Principles of writing consistent, idiomatic CSS
2 |
3 | The following document outlines a reasonable style guide for CSS development.
4 | These guidelines strongly encourage the use of existing, common, sensible
5 | patterns. They should be adapted as needed to create your own style guide.
6 |
7 | This is a living document and new ideas are always welcome. Please
8 | contribute.
9 |
10 |
11 | ## Table of contents
12 |
13 | 1. [General principles](#general-principles)
14 | 2. [Whitespace](#whitespace)
15 | 3. [Comments](#comments)
16 | 4. [Format](#format)
17 | 5. [Practical example](#example)
18 |
19 | [Acknowledgements](#acknowledgements)
20 |
21 | [License](#license)
22 |
23 |
24 |
25 | ## 1. General principles
26 |
27 | > "Part of being a good steward to a successful project is realizing that
28 | > writing code for yourself is a Bad Idea™. If thousands of people are using
29 | > your code, then write your code for maximum clarity, not your personal
30 | > preference of how to get clever within the spec." - Idan Gazit
31 |
32 | * Don't try to prematurely optimize your code; keep it readable and
33 | understandable.
34 | * All code in any code-base should look like a single person typed it, even
35 | when many people are contributing to it.
36 | * Strictly enforce the agreed-upon style.
37 | * If in doubt when deciding upon a style use existing, common patterns.
38 |
39 |
40 |
41 | ## 2. Whitespace
42 |
43 | Only one style should exist across the entire source of your code-base. Always
44 | be consistent in your use of whitespace. Use whitespace to improve
45 | readability.
46 |
47 | * _Never_ mix spaces and tabs for indentation.
48 | * Choose between soft indents (spaces) or real tabs. Stick to your choice
49 | without fail. (Preference: spaces)
50 | * If using spaces, choose the number of characters used per indentation level.
51 | (Preference: 4 spaces)
52 |
53 | Tip: configure your editor to "show invisibles" or to automatically remove
54 | end-of-line whitespace.
55 |
56 | Tip: use an [EditorConfig](http://editorconfig.org/) file (or equivalent) to
57 | help maintain the basic whitespace conventions that have been agreed for your
58 | code-base.
59 |
60 |
61 |
62 | ## 3. Comments
63 |
64 | Well commented code is extremely important. Take time to describe components,
65 | how they work, their limitations, and the way they are constructed. Don't leave
66 | others in the team guessing as to the purpose of uncommon or non-obvious
67 | code.
68 |
69 | Comment style should be simple and consistent within a single code base.
70 |
71 | * Place comments on a new line above their subject.
72 | * Keep line-length to a sensible maximum, e.g., 80 columns.
73 | * Make liberal use of comments to break CSS code into discrete sections.
74 | * Use "sentence case" comments and consistent text indentation.
75 |
76 | Tip: configure your editor to provide you with shortcuts to output agreed-upon
77 | comment patterns.
78 |
79 | Example:
80 |
81 | ```css
82 | /* ==========================================================================
83 | Section comment block
84 | ========================================================================== */
85 |
86 | /* Sub-section comment block
87 | ========================================================================== */
88 |
89 | /**
90 | * Short description using Doxygen-style comment format
91 | *
92 | * The first sentence of the long description starts here and continues on this
93 | * line for a while finally concluding here at the end of this paragraph.
94 | *
95 | * The long description is ideal for more detailed explanations and
96 | * documentation. It can include example HTML, URLs, or any other information
97 | * that is deemed necessary or useful.
98 | *
99 | * @tag This is a tag named 'tag'
100 | *
101 | * TODO: This is a todo statement that describes an atomic task to be completed
102 | * at a later date. It wraps after 80 characters and following lines are
103 | * indented by 2 spaces.
104 | */
105 |
106 | /* Basic comment */
107 | ```
108 |
109 |
110 |
111 | ## 4. Format
112 |
113 | The chosen code format must ensure that code is: easy to read; easy to clearly
114 | comment; minimizes the chance of accidentally introducing errors; and results
115 | in useful diffs and blames.
116 |
117 | * Use one discrete selector per line in multi-selector rulesets.
118 | * Include a single space before the opening brace of a ruleset.
119 | * Include one declaration per line in a declaration block.
120 | * Use one level of indentation for each declaration.
121 | * Include a single space after the colon of a declaration.
122 | * Use lowercase and shorthand hex values, e.g., `#aaa`.
123 | * Use single or double quotes consistently. Preference is for double quotes,
124 | e.g., `content: ""`.
125 | * Quote attribute values in selectors, e.g., `input[type="checkbox"]`.
126 | * _Where allowed_, avoid specifying units for zero-values, e.g., `margin: 0`.
127 | * Include a space after each comma in comma-separated property or function
128 | values.
129 | * Include a semi-colon at the end of the last declaration in a declaration
130 | block.
131 | * Place the closing brace of a ruleset in the same column as the first
132 | character of the ruleset.
133 | * Separate each ruleset by a blank line.
134 |
135 | ```css
136 | .selector-1,
137 | .selector-2,
138 | .selector-3[type="text"] {
139 | -webkit-box-sizing: border-box;
140 | -moz-box-sizing: border-box;
141 | box-sizing: border-box;
142 | display: block;
143 | font-family: helvetica, arial, sans-serif;
144 | color: #333;
145 | background: #fff;
146 | background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));
147 | }
148 |
149 | .selector-a,
150 | .selector-b {
151 | padding: 10px;
152 | }
153 | ```
154 |
155 | #### Declaration order
156 |
157 | If declarations are to be consistently ordered, it should be in accordance with
158 | a single, simple principle.
159 |
160 | Smaller teams may prefer to cluster related properties (e.g. positioning and
161 | box-model) together.
162 |
163 | ```css
164 | .selector {
165 | /* Positioning */
166 | position: absolute;
167 | z-index: 10;
168 | top: 0;
169 | right: 0;
170 | bottom: 0;
171 | left: 0;
172 |
173 | /* Display & Box Model */
174 | display: inline-block;
175 | overflow: hidden;
176 | box-sizing: border-box;
177 | width: 100px;
178 | height: 100px;
179 | padding: 10px;
180 | border: 10px solid #333;
181 | margin: 10px;
182 |
183 | /* Other */
184 | background: #000;
185 | color: #fff;
186 | font-family: sans-serif;
187 | font-size: 16px;
188 | text-align: right;
189 | }
190 | ```
191 |
192 | Larger teams may prefer the simplicity and ease-of-maintenance that comes with
193 | alphabetical ordering.
194 |
195 | #### Exceptions and slight deviations
196 |
197 | Large blocks of single declarations can use a slightly different, single-line
198 | format. In this case, a space should be included after the opening brace and
199 | before the closing brace.
200 |
201 | ```css
202 | .selector-1 { width: 10%; }
203 | .selector-2 { width: 20%; }
204 | .selector-3 { width: 30%; }
205 | ```
206 |
207 | Long, comma-separated property values - such as collections of gradients or
208 | shadows - can be arranged across multiple lines in an effort to improve
209 | readability and produce more useful diffs. There are various formats that could
210 | be used; one example is shown below.
211 |
212 | ```css
213 | .selector {
214 | background-image:
215 | linear-gradient(#fff, #ccc),
216 | linear-gradient(#f3c, #4ec);
217 | box-shadow:
218 | 1px 1px 1px #000,
219 | 2px 2px 1px 1px #ccc inset;
220 | }
221 | ```
222 |
223 | ### Preprocessors: additional format considerations
224 |
225 | Different CSS preprocessors have different features, functionality, and syntax.
226 | Your conventions should be extended to accommodate the particularities of any
227 | preprocessor in use. The following guidelines are in reference to Sass.
228 |
229 | * Limit nesting to 1 level deep. Reassess any nesting more than 2 levels deep.
230 | This prevents overly-specific CSS selectors.
231 | * Avoid large numbers of nested rules. Break them up when readability starts to
232 | be affected. Preference to avoid nesting that spreads over more than 20
233 | lines.
234 | * Always place `@extend` statements on the first lines of a declaration
235 | block.
236 | * Where possible, group `@include` statements at the top of a declaration
237 | block, after any `@extend` statements.
238 | * Consider prefixing custom functions with `x-` or another namespace. This
239 | helps to avoid any potential to confuse your function with a native CSS
240 | function, or to clash with functions from libraries.
241 |
242 | ```scss
243 | .selector-1 {
244 | @extend .other-rule;
245 | @include clearfix();
246 | @include box-sizing(border-box);
247 | width: x-grid-unit(1);
248 | // other declarations
249 | }
250 | ```
251 |
252 |
253 |
254 | ## 5. Practical example
255 |
256 | An example of various conventions.
257 |
258 | ```css
259 | /* ==========================================================================
260 | Grid layout
261 | ========================================================================== */
262 |
263 | /**
264 | * Column layout with horizontal scroll.
265 | *
266 | * This creates a single row of full-height, non-wrapping columns that can
267 | * be browsed horizontally within their parent.
268 | *
269 | * Example HTML:
270 | *
271 | *
272 | *
273 | *
274 | *
275 | *
286 | *
287 | *
288 | *
289 | *
274 | *
275 | *
276 | *
277 | *
291 | *
292 | *
293 | *
294 | *
263 | *
264 | *
265 | *
266 | *
238 | *
239 | *
240 | *
241 | *