This repository was archived by the owner on Jan 5, 2026. It is now read-only.
forked from specialmoves/coding-standards-front-end
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
598 lines (581 loc) · 23.1 KB
/
index.html
File metadata and controls
598 lines (581 loc) · 23.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
<!DOCTYPE html>
<!--[if lt IE 10]><html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" class="no-js oldie"><![endif]-->
<!--[if gt IE 9]><!--><html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" class="no-js"><!--<![endif]-->
<head>
<meta charset="UTF-8" />
<meta name="description" content="A collection of web project and interface development standards and conventions" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Coding standards front end</title>
<link href="assets/styles/project.css" rel="stylesheet" />
<script src="assets/vendor/libs/modernizr.js"></script>
</head>
<body>
<header class="banner" role="banner">
<h1>Coding standards front end</h1>
</header>
<nav class="navigation" role="navigation">
<ul>
<li><a href="#code-formatting">Code formatting</a></li>
<li><a href="#development-guidelines">Development guidelines</a></li>
<li><a href="#development-process">Development process</a></li>
</ul>
</nav>
<div role="main" class="main">
<article id="code-formatting">
<h1>Code formatting</h1>
<section>
<h1 class="beta">HTML</h1>
<ul>
<li>
Use <a href="http://dev.w3.org/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html">Polygot Markup</a>
with the following emphasis:
<ul>
<li>
Use XHTML compliant Boolean attributes e.g. <code><input type="text"
required="required" /></code>.
</li>
<li>Use double quotation marks for attributes.</li>
<li>
Use the minimized tag syntax, with a space before the closing slash,
for void elements, e.g. <code><br /></code>.
</li>
</ul>
</li>
<li>
Use consistent line breaks:
<ul>
<li>Add line breaks only between sibling sectioning elements & ARIA landmark roles.</li>
<li>Place inline tags on the same line.</li>
<li>Place block-level tags on a new line and indented.</li>
<li>Include templating serverside code as part of the nesting of elements.</li>
<li>Wrap long lines of text and treat as block-level elements, using 150 char length as a guide.</li>
</ul>
</li>
</ul>
</section>
<section>
<h1 class="beta">CSS</h1>
<h2 class="gamma">Example of style</h2>
<pre class="example">
<span class="comment">/* header */</span>
<span class="selector">.action .action-information</span>,
<span class="selector">.button .information:last-child</span> {
<span class="property">background</span>: <span class="property-value">url("../images/generic-logo.png") no-repeat center 0 #fff</span>;
<span class="property">background-image</span>:
<span class="property-value">url("../images/generic-bg-bottom.png")</span>,
<span class="property-value">url("../images/generic-bg-top.png")</span>;
<span class="property">border</span>: <span class="property-value">1px solid #000</span>;
<span class="property">-webkit-box-shadow</span>: <span class="comment">/* multiple properties on different lines */</span>
<span class="property-value">0 1px 3px rgba(0, 0, 0, .2)</span>,
<span class="property-value">0 2px 6px rgba(0, 0, 0, .1)</span>;
<span class="property">-moz-box-shadow</span>:
<span class="property-value">0 1px 3px rgba(0, 0, 0, .2)</span>,
<span class="property-value">0 2px 6px rgba(0, 0, 0, .1)</span>;
<span class="property">-ms-box-shadow</span>:
<span class="property-value">0 1px 3px rgba(0, 0, 0, .2)</span>,
<span class="property-value">0 2px 6px rgba(0, 0, 0, .1)</span>;
<span class="property">-o-box-shadow</span>:
<span class="property-value">0 1px 3px rgba(0, 0, 0, .2)</span>,
<span class="property-value">0 2px 6px rgba(0, 0, 0, .1)</span>;
<span class="property">box-shadow</span>:
<span class="property-value">0 1px 3px rgba(0, 0, 0, .2)</span>,
<span class="property-value">0 2px 6px rgba(0, 0, 0, .1)</span>;
<span class="property">color</span>: <span class="property-value">#333</span>;
<span class="property">display</span>: <span class="property-value">block</span>;
<span class="property">font-family</span>: <span class="property-value">Helmet, Freesans, sans-serif</span>; <span class="comment">/* bbc glue font stack /*</span>
<span class="property">font-size</span>: <span class="property-value">1.3em</span>; <span class="comment">/* only use ems for font-sizes (including on the body) */</span>
<span class="property">padding</span>: <span class="property-value">5px 0 2% 0</span>;
<span class="property">-webkit-transition</span>: <span class="property-value">all 700ms ease</span>; <span class="comment">/* use ms for duration */</span>
<span class="property">-moz-transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">-ms-transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">-o-transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">z-index</span>: <span class="property-value">3</span>;
}
<span class="selector">.action a</span> {
<span class="property">color</span>: <span class="property-value">rgba(0, 0, 0, .2)</span>;
}
</pre>
<h2 class="gamma">Structure of a style</h2>
<p>Use "semi-expanded" structure.</p>
<pre class="structure">
<span class="selector">[selector]</span>[comma][carriage-return]
<span class="selector">[selector]</span>[space][open-curly-bracket][carriage-return]
[tab]<span class="property">[property]</span>[colon][space]<span class="property-value">[property-value]</span>[semi-colon][carriage-return]
[close-curly-bracket][carriage-return]
[carriage-return]
</pre>
<h2 class="gamma">Selector naming</h2>
<ul>
<li>Use only lowercase.</li>
<li>Use only hyphens to separate words.</li>
</ul>
<h2 class="gamma">Property order</h2>
<ul>
<li>Alphabetical.</li>
<li>By the length of prefix (long to short) for vendor prefixed properties.</li>
<li>
Carry on the alphabetical order for multiple properties (e.g. border-bottom, border-left...):
</li>
</ul>
<pre class="example">
<span class="selector">.download</span> {
<span class="property">border-bottom</span>: <span class="property-value">1px solid #000</span>;
<span class="property">border-left</span>: <span class="property-value">2px solid #000</span>;
<span class="property">border-right</span>: <span class="property-value">1px solid #000</span>;
<span class="property">border-top</span>: <span class="property-value">2px solid #000</span>;
}
</pre>
<h2 class="gamma">Property value order</h2>
<ul>
<li><code>background: [colour] ["url"] [scroll] [repeat] [position];</code></li>
<li><code>border: [size] [type] [colour];</code></li>
</ul>
<h2 class="gamma">Prefixed Property value spacing</h2>
<pre class="example">
<span class="selector">.download</span> {
<span class="property">-webkit-transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">-moz-transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">-ms-transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">-o-transition</span>: <span class="property-value">all 700ms ease</span>;
<span class="property">transition</span>: <span class="property-value">all 700ms ease</span>;
}
</section>
<section>
<h1 class="beta">Text formatting</h1>
<ul>
<li>
Use consistent, version-control-friendly text formatting:
<ul>
<li>Use tabs for indentation - length of 4 spaces.</li>
<li>Use <a href="http://help.github.com/line-endings/">UNIX-style line endings</a>.</li>
<li>Trim trailing whitespace from lines.</li>
<li>Ensure all text-based files end with a newline character.</li>
</ul>
</li>
</ul>
</section>
<section>
<h1 class="beta">Media assets</h1>
<h2 class="gamma">Naming conventions</h2>
<ul>
<li>Use only lowercase.</li>
<li>Use only hyphens to separate words e.g. "home-logo.png".</li>
</ul>
</section>
</article>
<article>
<h1 id="development-guidelines">Development Guidelines</h1>
<section>
<h1 class="beta">Foundation</h1>
<p>Use <a href="http://html5boilerplate.com/">HTML5 Boilerplate</a> as a foundation:</p>
<ul>
<li>Use <a href="http://www.modernizr.com">modernizr</a>.</li>
<li>
Use the non-semantic helper classes:
<ul>
<li>Use the <code>class="clearfix"</code> approach to clearing floats.</li>
<li>Use the image replacement and text hiding classes.</li>
</ul>
</li>
<li>
Adhere to the W3C's <a href="http://www.w3.org/TR/mobile-bp/">Mobile best practises</a>
on every project.
</li>
<li>Use <a href="https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-browser-Polyfills"> polyfills</a>.</li>
<li>Use HTML5 semantic tags e.g. sectioning and form elements.</li>
<li>
Use <a href="http://microformats.org/">Microformats</a> and <a href="http://www.w3.org/TR/microdata/">
HTML5 microdata</a>.
</li>
<li>
Use <a href="http://www.w3.org/TR/wai-aria/">WAI-ARIA</a> landmark roles -
see <a href="http://www.paciellogroup.com/blog/2010/10/using-wai-aria-landmark-roles/">this blog post</a>
for more information. Never use ARIA roles to target CSS styles.
</li>
<li>
Place all <a href="http://html5boilerplate.com/docs/The-markup/">Javascript</a> before the closing
<code></body></code> tag, except <a href="http://www.modernizr.com">modernizr</a>.
</li>
<li>Use Classes over IDs with the exception of:
<ul>
<li>In-page navigation.</li>
</ul>
</li>
</ul>
<p>With the following exceptions:</p>
<ul>
<li>Use an IE conditional class and <a href="http://mathiasbynens.be/notes/safe-css-hacks">"safe hacks"</a>.</li>
<li>
Order the <code><head></code> as follows:
<ol>
<li>
<code><meta></code>
<ol>
<li>Charset first.</li>
<li>Then alphabetically ordered.</li>
</ol>
</li>
<li><code><title></code></li>
<li><code><link></code></li>
<li><code><script></code></li>
</ol>
</li>
</ul>
</section>
<section>
<h1 class="beta">CSS</h1>
<h2 class="gamma">Structure of a stylesheet</h2>
<ol>
<li>fonts (including url to licence)</li>
<li>normalise html5</li>
<li>default styles (based on boilerplate/normalise)
<ol>
<li>html</li>
<li>body</li>
<li>links: <code>a, a:hover, a:active, a:visited</code></li>
<li>sectioning content: <code>aside, article, nav, section</code></li>
<li>heading content: <code>h1 – h6, hgroup</code></li>
<li>text-level semantics: <code>address, blockquote, code, em, pre, strong</code></li>
<li>
grouping content
<ol>
<li>lists: <code>dl, dt, dd, ul, ol, li</code></li>
<li>paragraphs</li>
<li>tables: <code>table, thead, tr, th, tbody, td</code></li>
</ol>
</li>
<li>form content: <code>form, fieldset, legend, label, input, textarea, select, option</code></li>
<li>embedding content: <code>audio, canvas, embed, iframe, img, object, video</code></li>
</ol>
</li>
<li>helper classes (non-semantic)</li>
<li>shared states</li>
<li>style patterns: ordered by complexity</li>
<li>layout patterns (non-semantic)</li>
<li>
@media queries
<ol>
<li>device width (linearised content first)
<ol>
<li>default styles (based on boilerplate/normalise)</li>
<li>helper classes (non-semantic)</li>
<li>shared states</li>
<li>style patterns: ordered by complexity</li>
<li>layout patterns (non-semantic)</li>
</ol>
</li>
<li>print</li>
</ol>
</li>
</ol>
<h3 class="delta">Comments and indentation</h3>
<p>Comment within a stylesheet to aid other developers.</p>
<ul>
<li>Title</li>
<li>Colour swatch</li>
<li>Index</li>
<li>Sectioning comments</li>
<li>Property comments</li>
</ul>
<pre class="example"><span class="comment">/*
* standards and conventions
*
* colour swatch:
* light blue = #005
* dark blue = #00C
*
* index:
* 1. fonts
* 2. normalise html5
* 3. default styles (based on boilerplate/normalise)
* 4. helper classes (non-semantic)
* 5. shared states
* 6. style patterns
* 7. layout patterns (non-semantic)
* 8. @mediaqueries
*/
</span>
</pre>
<p>Use indentation and comments to section a stylesheet. There are two types of comments:</p>
<ol>
<li>Sectioning comments.</li>
<li>Property comments.</li>
</ol>
<pre class="example">
<span class="comment">/* sectioning comment e.g. "header" */</span>
<span class="selector">header</span> {
<span class="property">margin</span>: <span class="property-value">0</span>;
}
<span class="comment">/* sectioning comment e.g. "primary navigation" */</span>
<span class="selector">header nav</span> {
<span class="property">float</span>: <span class="property-value">left</span>;
}
<span class="comment">/* sectioning comment e.g. "search box" */</span>
<span class="selector">header search</span> {
<span class="property">display</span>: <span class="property-value">inline</span>; <span class="comment">/* property comment e.g. ie double margin fix */</span>
}
</pre>
<h2 class="gamma">Selector naming</h2>
<ul>
<li>
Use:
<ul>
<li>Plurals for groupings.</li>
<li>Nouns for specific objects.</li>
<li>Adjectives (where possible) or verbs for variations</li>
<li>Past-participle verbs for states.</li>
<li>
The following for pattern parts:
<ul>
<li><code><pattern name>–inner</code> → for inner wrapper</li>
<li><code><pattern name>–item</code> → for the most common and repeating element in the pattern</li>
<li><code><pattern name>–content</code> → for containing both media and text</li>
<li><code><pattern name>–media</code> → for targeting imgs, swf, video</li>
<li><code><pattern name>–copy</code> → for containing only text e.g. headings and paragraphs</li>
</ul>
</li>
</ul>
</li>
<li>Do not mimic tag names when naming classes, unless they are prefixed. e.g. <code>.component-body</code>.</li>
</ul>
<pre class="example">
<span class="selector">.actions</span> (grouping - plural)
<span class="selector">.action</span> (pattern - noun) <span class="selector">.action-collapse</span> (sub pattern - verb)
<span class="selector">.action-inner</span> (pattern part)
<span class="selector">.action-item</span> (pattern part)
<span class="selector">.action-content</span> (pattern part)
<span class="selector">.action-media</span> (pattern part)
<span class="selector">.action-copy</span> (pattern part)
<span class="selector">.folder .is-collapsed</span> (state - past participle)
</pre>
<h2 class="gamma">Progressive enhancement in CSS</h2>
<h3 class="delta">Modernizr</h3>
<ul>
<li>
Use forward-facing support (i.e. assume feature support and target lack of with the "no-" classes") with the exceptions of:
<ul>
<li>JS → assume no JS and target support with the "js" class.</li>
<li>Touch → assume a no-touch device and target support with the "touch" class.</li>
</ul>
</li>
</ul>
<h3 class="delta">Backgrounds (language feature)</h3>
<pre class="example">
<span class="selector">.text-area</span> {
<span class="property">background</span>: <span class="property-value">url("/images/background-000-50.png") repeat</span>; <span class="comment">/* IE fix */</span>
<span class="property">background</span>: <span class="property-value">rgba(0, 0, 0, 0.5)</span>;
}
</pre>
<ul>
<li>Start with fall back definition to support older browsers.</li>
<li>Implement newer definition last.</li>
</ul>
<h2 class="gamma">Fonts and Font Face</h2>
<p>
Use tweaked (letter/word spacing etc) web-safe fonts first. Then webfonts, but sparingly, with the following caveats:
</p>
<ul>
<li>
Ensure the font is correctly licensed.
Find a licence using a <a href="http://sprungmarker.de/wp-content/uploads/webfont-services/">webfont service</a>.
</li>
<li>Ensure the rendering quality of the font is acceptable in all browsers.</li>
<li>Ensure acceptable loading times are maintained as fonts are added.</li>
<li>
Ensure the correct font weights are included and
<a href="http://www.fontspring.com/support/troubleshooting/style-linking">linked correctly</a>.
</li>
</ul>
</section>
<section>
<h1 class="beta">Media assets</h1>
<h2 class="gamma">File structure</h2>
<ul>
<li>Limit of 10 files per folder before subfolder is created</li>
<li>All vendor/3rd Party scripts to be found in "/vendor" including all assets.</li>
<li>Creation of child folders within structure below are on a per project basis</li>
</ul>
<pre class="structure">
/assets
/fonts
/images
/sprites
vignettes.png
background.jpg
spacer.gif
/scripts
project.js
jquery.standout.js
/styles
project-name.css
/swfs
/vendor
jquery.js
modernizr.js
/fancybox
jquery.scrollTo.js
</pre>
<h2 class="gamma">Images</h2>
<h3 class="delta">Spritesheets</h3>
<p>Use spritesheets only for <em>grouped sets of icons</em>.</p>
<h3 class="delta">Image Formats</h3>
<ul>
<li>Use JPEG for photos and complex images/icons.</li>
<li>Use PNG 8 for small and simple images/icons.</li>
<li>Use PNG 24 for multi-channel transparency.</li>
</ul>
</section>
<section>
<h1 class="beta">Accessibility</h1>
<ul>
<li>Adhere to the <a href="http://wcagsamurai.org/errata/errata.html">WCAG Samurai</a> checklist.</li>
<li>Do not check using accessibility validators.</li>
</ul>
</section>
</article>
<article id="development-process">
<h1 class="beta">Development Process</h1>
<ol>
<li>
Annotate designs to:
<ol>
<li>Identify a colour palette.</li>
<li>
Identify the "base styles" using a "typography-first" approach:
<ol>
<li>
Identify the body copy (the most common block of copy) and its following properties:
<ul>
<li>Font family.</li>
<li>Font size.</li>
<li>Line height.</li>
</ul>
</li>
<li>
Identify text-based grouping elements (and their box models):
<ul>
<li>Paragraphs.</li>
<li>Lists.</li>
<li>Heading groups.</li>
</ul>
</li>
<li>Identify six levels of headings.</li>
<li>
Identify form elements
<ul>
<li>Legends.</li>
<li>Labels.</li>
<li>Inputs.</li>
</ul>
</li>
</ol>
</li>
<li>
Identify style patterns, subpatterns and pattern parts (starting with most common and smallest first):
<ul>
<li>Actions</li>
<li>Navigation</li>
<li>Content blocks</li>
<li>etc...</li>
</ul>
</li>
<li>
Identify layout patterns:
<ul>
<li>Grids</li>
<li>Positioning</li>
<li>etc...</li>
</ul>
</li>
<li>
Identify animation patterns:
<ul>
<li>Colour transitions (e.g. on simple links)</li>
<li>Show & hide (e.g. reveals, slides, fades)</li>
<li>etc...</li>
</ul>
</li>
<li>
Identify interaction patterns:
<ul>
<li>Clicks</li>
<li>Drags</li>
<li>Hovers (including simple links)</li>
<li>etc...</li>
</ul>
</li>
</ol>
</li>
<li>Produce a draft mapping of the relationships between patterns in each set.</li>
<li>
Build a toolkit:
<ul>
<li>
with the following sections:
<ul>
<li>Base styles</li>
<li>Demo of style patterns.</li>
<li>Demo of layout patterns.</li>
<li>Demo of animation patterns.</li>
<li>Demo of interaction patterns.</li>
<li>Components built from the patterns.</li>
</ul>
</li>
<li>
and with the following features:
<ul>
<li>Self-annotating and with common language between design and development.</li>
<li>A reference for default typography, padding, margin etc.</li>
<li>Built-in relationship mapping.</li>
<li>Testable.</li>
</ul>
</li>
</ul>
</li>
</ol>
</article>
</div>
<aside class="complementary" role="complementary">
<h1 class="beta">A few notes on the why...</h1>
<details>
<summary>A collection of best practise standards from around the web and for our specific project needs.</summary>
<dl>
<dt>Why such specific standards for a style definition?</dt>
<dd>Assists with merges and diffs within version control.</dd>
<dt>Why those style convention?</dt>
<dd>
Widely used conventions and those used within <a href="http://html5boilerplate.com/">HTML5 Boilerplate</a>
and CSS3 generators like <a href="http://css3please.com/">css3please</a>.
</dd>
<dd>
Same as output from Firebug. Opera's Dragonfly breaks properties apart and Webkit's
Inspector preserves in the input format.
</dd>
<dd>Keeping each property on a separate line assists with merges and diffs within version control.</dd>
<dt>Why indentation?</dt>
<dd>Easer to scan document and helps with focusing.</dd>
<dt>Why that structure and one stylesheet?</dt>
<dd>Promotes the cascading nature of CSS.</dd>
<dt>Why the reduced role of spritesheets?</dt>
<dd>
These tend to be high maintenance and automated versions can be complex to implement.
Also, CSS styling can remove the need for button/form spritesheets.
</dd>
<dt>Why those webfont caveats?</dt>
<dd>Some earlier poor quality fonts render horribly in IE.</dd>
<dd>A single weight of font can be around 50k. Having 3 weights can add up 150k to a project.</dd>
</dl>
</details>
</aside>
<footer class="content-info" role="contentinfo">
<p>
<small>
This work is licensed under a
<a href="http://creativecommons.org/licenses/by-nc-sa/3.0/" rel="license">Creative Commons License</a>
by the <a href="https://github.com/specialmoves/coding-standards-front-end/contributors">contributors</a>.
</small>
</p>
</footer>
</body>
</html>