Skip to content

Commit 56ee01a

Browse files
mdomdo
committed
readme
1 parent 0b6ea5d commit 56ee01a

File tree

1 file changed

+272
-16
lines changed

1 file changed

+272
-16
lines changed

‎README.md

Lines changed: 272 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ Standards for developing flexible, durable, and sustainable HTML and CSS.
33

44

55

6+
----------
7+
8+
9+
610
## Table of contents
711

812
* [Golden rule](#golden-rule)
@@ -13,6 +17,10 @@ Standards for developing flexible, durable, and sustainable HTML and CSS.
1317

1418

1519

20+
----------
21+
22+
23+
1624
## Golden rule
1725

1826
> All code in any code base should look like a single person typed it, no matter how many people contributed.
@@ -21,8 +29,13 @@ This means strictly enforcing these agreed upon guidelines at all times. For add
2129

2230

2331

32+
----------
33+
34+
35+
2436
## HTML
2537

38+
2639
### HTML syntax
2740

2841
* Use soft-tabs with two spaces
@@ -36,46 +49,289 @@ This means strictly enforcing these agreed upon guidelines at all times. For add
3649
<!DOCTYPE html>
3750
<html>
3851
<head>
39-
<title&gt;Page title&lt;/title>
52+
<title>Page title</title>
4053
</head>
4154
<body>
4255
<img src='images/company-logo.png' alt='Company' />
43-
<h1 class='hello-world'&gt;Hello, world!&lt;/h1>
56+
<h1 class='hello-world'>Hello, world!</h1>
4457
</body>
4558
</html>
4659
````
4760

4861
**Correct example:**
4962

5063
````
51-
&lt;!DOCTYPE html&gt;
52-
&lt;html&gt;
53-
&lt;head&gt;
54-
&lt;title&gt;Page title&lt;/title&gt;
55-
&lt;/head&gt;
56-
&lt;body&gt;
57-
&lt;img src="images/company-logo.png" alt="Company"&gt;
58-
&lt;h1 class="hello-world"&gt;Hello, world!&lt;/h1&gt;
59-
&lt;/body&gt;
60-
&lt;/html&gt;
64+
<!DOCTYPE html>
65+
<html>
66+
<head>
67+
<title>Page title</title>
68+
</head>
69+
<body>
70+
<img src="images/company-logo.png" alt="Company">
71+
<h1 class="hello-world">Hello, world!</h1>
72+
</body>
73+
</html>
74+
````
75+
76+
77+
### HTML5 doctype
78+
79+
Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.
80+
81+
````
82+
<!DOCTYPE html>
83+
````
84+
85+
86+
### Pragmatism over semantics
87+
88+
Strive to maintain HTML standards and semantics, but don't sacrifice pragmatism. Use the least amount of markup with the fewest intricies whenever possible.
89+
90+
91+
### Attribute order
92+
93+
HTML attributes should come in this particular order for easier reading of code.
94+
95+
* class<
96+
* id<
97+
* data-*<
98+
* for|type|href<
99+
100+
Such that your markup looks like:
101+
102+
````
103+
<a class="" id="" data-modal="" href="">Example link</a>
61104
````
62105

106+
### JavaScript generated markup
107+
108+
Writing markup in a javascript file makes the content harder to find, harder to edit, and less performant. Don't do it.
109+
110+
111+
112+
----------
113+
63114

64115

65116
## CSS
66117

118+
### CSS syntax
119+
120+
* Use soft-tabs with two spaces
121+
* When grouping selectors, keep individual selectors to a single line
122+
* Include one space before the opening brace of declaration blocks
123+
* Place closing praces of declaration blocks on a new line
124+
* Include one space after <code>:</code> in each property
125+
* Each declaration should appear on its own line
126+
* End all declarations with a semi-colon
127+
* Comma-separated values should include a space after each comma
128+
* Don't include spaces after commas in RGB or RGBa colors, and don't preface values with a leading zero
129+
* Lowercase all hex values, e.g., <code>#fff</code> instead of <code>#FFF</code>
130+
* Use shorthand hex values where available, e.g., <code>#fff</code> instead of <code>#ffffff</code>
131+
* Quote attribute values in selectors, e.g., <code>input[type="text"]</code>
132+
* Avoid specifying units for zero values, e.g., <code>margin: 0;</code> instead of <code>margin: 0px;</code>
133+
134+
**Incorrect example:**
135+
136+
````
137+
.selector, .selector-secondary, .selector[type=text] {
138+
padding:15px;
139+
margin:0px 0px 15px;
140+
background-color:rgba(0, 0, 0, 0.5);
141+
box-shadow:0 1px 2px #CCC,inset 0 1px 0 #FFFFFF
142+
}
143+
````
144+
145+
**Correct example:**
146+
147+
````
148+
.selector,
149+
.selector-secondary,
150+
.selector[type="text"] {
151+
padding: 15px;
152+
margin: 0 0 15px;
153+
background-color: rgba(0,0,0,.5);
154+
box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
155+
}
156+
````
157+
158+
Questions on the terms used here? See the [syntax section of the Cascading Style Sheets article](http://en.wikipedia.org/wiki/Cascading_Style_Sheets#Syntax) on Wikipedia.
159+
160+
161+
### Declaration order
162+
163+
Related declarations should be grouped together, placing positioning and box-model properties closest to the top, followed by typographic and visual properties.
164+
165+
````
166+
.declaration-order {
167+
/* Positioning */
168+
position: absolute;
169+
top: 0;
170+
right: 0;
171+
bottom: 0;
172+
left: 0;
173+
z-index: 100;
174+
175+
/* Box-model */
176+
display: block;
177+
float: right;
178+
width: 100px;
179+
height: 100px;
180+
181+
/* Typography */
182+
font: normal 13px "Helvetica Neue", sans-serif;
183+
line-height: 1.5
184+
color: #333;
185+
text-align: center;
186+
187+
/* Visual */
188+
background-color: #f5f5f5;
189+
border: 1px solid #e5e5e5;
190+
border-radius: 3px;
191+
192+
/* Misc */
193+
opacity: 1;
194+
}
195+
````
196+
197+
For a complete list of properties and their order, please see [Recess](http://twitter.github.com/recess).
198+
199+
200+
### Formatting exceptions
201+
202+
In some cases, it makes sense to deviate slightly from the default [syntax](#css-syntax).
203+
204+
#### Prefixed properties
205+
206+
When using vendor prefixed properties, indent each property such that the value lines up vertically for easy multi-line editing.
207+
208+
````
209+
.selector {
210+
-webkit-border-radius: 3px;
211+
-moz-border-radius: 3px;
212+
border-radius: 3px;
213+
}
214+
````
215+
216+
In Textmate, use **Text &rarr; Edit Each Line in Selection** (&#8963;&#8984;A). In Sublime Text 2, use **Selection &rarr; Add Previous Line** (&#8963;&#8679;&uarr;) and **Selection &rarr; Add Next Line** (&#8963;&#8679;&darr;).
217+
218+
#### Rules with single declarations
219+
220+
In instances where several rules are present with only one declaration each, consider removing new line breaks for readability and faster editing.
221+
222+
````
223+
.span1 { width: 60px; }
224+
.span2 { width: 140px; }
225+
.span3 { width: 220px; }
226+
227+
.sprite {
228+
display: inline-block;
229+
width: 16px;
230+
height: 15px;
231+
background-image: url(http://github.com/img/sprite.png);
232+
}
233+
.icon { background-position: 0 0; }
234+
.icon-home { background-position: 0 -20px; }
235+
.icon-account { background-position: 0 -40px; }
236+
````
237+
238+
239+
### Human readable
240+
241+
Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.
242+
243+
#### Comments
244+
245+
Great code comments convey context or purpose and should not just reiterate a component or class name.
246+
247+
**Bad example:**
248+
249+
````
250+
/* Modal header */
251+
.modal-header {
252+
...
253+
}
254+
````
255+
256+
**Good example:**
257+
258+
````
259+
/* Wrapping element for .modal-title and .modal-close */
260+
.modal-header {
261+
...
262+
}
263+
````
264+
265+
#### Class names
266+
267+
* Keep classes lowercase and use dashes (not underscores or camelCase)
268+
* Avoid arbitrary shorthand notation
269+
* Keep classes as short and succinct as possible
270+
* Use meaningful names; use structural or purposeful names over presentational
271+
* Prefix classes based on the closest parent component's base class
272+
273+
**Bad example:**
274+
275+
````
276+
.t { ... }
277+
.red { ... }
278+
.header { ... }
279+
````
280+
281+
**Good example:**
282+
283+
````
284+
.tweet { ... }
285+
.important { ... }
286+
.tweet-header { ... }
287+
````
288+
289+
#### Selectors
290+
291+
* Use classes over generic element tags
292+
* Keep them short and limit the number of elements in each selector to three
293+
* Scope classes to the closest parent when necessary (e.g., when not using prefixed classes)
294+
295+
**Bad example:**
296+
297+
````
298+
span { ... }
299+
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
300+
.avatar { ... }
301+
````
302+
303+
**Good example:**
304+
305+
````
306+
.avatar { ... }
307+
.tweet-header .username { ... }
308+
.tweet .avatar { ... }
309+
````
310+
311+
### Organization
312+
313+
* Organize sections of code by component
314+
* Develop a consistent commenting hierarchy
315+
* If using multiple CSS files, break them down by component
316+
317+
318+
319+
----------
320+
67321

68322

69323
## Copy
70324

325+
### Sentence case
71326

327+
Always write copy, including headings and code comments, in [sentence case](http://en.wikipedia.org/wiki/Letter_case#Usage_. In other words, aside from titles and proper nouns, only the first word should be capitalized.
72328

73-
-----
74329

75330

331+
----------
332+
76333

77-
### Thanks
78334

79-
Heavily inspired by [Idiomatic CSS](https://github.com/necolas/idiomatic-css) and the [GitHub Styleguide](http://github.com/styleguide).
335+
### Thanks
80336

81-
Designed and built with all the love in the world by [@mdo](http://twitter.com/mdo).
337+
Heavily inspired by [Idiomatic CSS](https://github.com/necolas/idiomatic-css) and the [GitHub Styleguide](http://github.com/styleguide). Made with all the love in the world by [@mdo](http://twitter.com/mdo).

0 commit comments

Comments
 (0)