forked from google/styleguide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
htmlcssguide.xml
1117 lines (1070 loc) · 35.4 KB
/
htmlcssguide.xml
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
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="Google HTML/CSS Style Guide">
<p class="revision">
Revision 2.23
</p>
<OVERVIEW>
<CATEGORY title="Important Note">
<STYLEPOINT title="Displaying Hidden Details in This Guide">
<SUMMARY>
This style guide contains many details that are initially
hidden from view. They are marked by the triangle icon, which you
see here on your left. Click it now.
You should see “Hooray” appear below.
</SUMMARY>
<BODY>
<p>
Hooray! Now you know you can expand points to get more
details. Alternatively, there’s a “toggle all” at the
top of this document.
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="Background">
<p>
This document defines formatting and style rules for HTML and
CSS. It aims at improving collaboration, code quality, and
enabling supporting infrastructure. It applies to raw,
working files that use HTML and CSS, including GSS
files. Tools are free to obfuscate, minify, and compile as
long as the general code quality is maintained.
</p>
</CATEGORY>
</OVERVIEW>
<CATEGORY title="General Style Rules">
<STYLEPOINT title="Protocol">
<SUMMARY>
Omit the protocol from embedded resources.
</SUMMARY>
<BODY>
<p>
Omit the protocol portion (<code>http:</code>,
<code>https:</code>) from URLs pointing to images and other
media files, style sheets, and scripts unless the respective
files are not available over both protocols.
</p>
<p>
Omitting the protocol—which makes the URL
relative—prevents mixed content issues and results in
minor file size savings.
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
/* Not recommended */
.example {
background: url(https://www.google.com/images/example);
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
.example {
background: url(//www.google.com/images/example);
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="General Formatting Rules">
<STYLEPOINT title="Indentation">
<SUMMARY>
Indent by 2 spaces at a time.
</SUMMARY>
<BODY>
<p>
Don’t use tabs or mix tabs and spaces for indentation.
</p>
<CODE_SNIPPET>
<ul>
<li>Fantastic
<li>Great
</ul>
</CODE_SNIPPET>
<CODE_SNIPPET>
.example {
color: blue;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Capitalization">
<SUMMARY>
Use only lowercase.
</SUMMARY>
<BODY>
<p>
All code has to be lowercase: This applies to HTML element names,
attributes, attribute values (unless
<code>text/CDATA</code>), CSS selectors, properties, and
property values (with the exception of strings).
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<A HREF="/">Home</A>
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<img src="google.png" alt="Google">
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
/* Not recommended */
color: #E5E5E5;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
color: #e5e5e5;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Trailing Whitespace">
<SUMMARY>
Remove trailing white spaces.
</SUMMARY>
<BODY>
<p>
Trailing white spaces are unnecessary and can complicate
diffs.
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<p>What?_
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<p>Yes please.
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="General Meta Rules">
<STYLEPOINT title="Encoding">
<SUMMARY>
Use UTF-8 (no BOM).
</SUMMARY>
<BODY>
<p>
Make sure your editor uses UTF-8 as character encoding,
without a byte order mark.
</p>
<p>
Specify the encoding in HTML templates and documents via
<code><meta charset="utf-8"></code>. Do not specify
the encoding of style sheets as these assume UTF-8.
</p>
<p>
(More on encodings and when and how to specify them can be
found in <a href="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
character encodings in HTML and CSS</a>.)
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Comments">
<SUMMARY>
Explain code as needed, where possible.
</SUMMARY>
<BODY>
<p>
Use comments to explain code: What does it cover, what
purpose does it serve, why is respective solution used or
preferred?
</p>
<p>
(This item is optional as it is not deemed a realistic
expectation to always demand fully documented code. Mileage
may vary heavily for HTML and CSS code and depends on the
project’s complexity.)
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Action Items">
<SUMMARY>
Mark todos and action items with <code>TODO</code>.
</SUMMARY>
<BODY>
<p>
Highlight todos by using the keyword <code>TODO</code> only,
not other common formats like <code>@@</code>.
</p>
<p>
Append a contact (username or mailing list) in parentheses
as with the format <code>TODO(contact)</code>.
</p>
<p>
Append action items after a colon as in <code>TODO: action
item</code>.
</p>
<CODE_SNIPPET>
{# TODO(john.doe): revisit centering #}
<center>Test</center>
</CODE_SNIPPET>
<CODE_SNIPPET>
<!-- TODO: remove optional tags -->
<ul>
<li>Apples</li>
<li>Oranges</li>
</ul>
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="HTML Style Rules">
<STYLEPOINT title="Document Type">
<SUMMARY>
Use HTML5.
</SUMMARY>
<BODY>
<p>
HTML5 (HTML syntax) is preferred for all HTML documents:
<code><!DOCTYPE html></code>.
</p>
<p>
(It’s recommended to use HTML, as <code>text/html</code>. Do not use
XHTML. XHTML, as <a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>,
lacks both browser and infrastructure support and offers
less room for optimization than HTML.)
</p>
<p>
Although fine with HTML, do not close void elements, i.e. write
<code><br></code>, not <code><br /></code>.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="HTML Validity">
<SUMMARY>
Use valid HTML where possible.
</SUMMARY>
<BODY>
<p>
Use valid HTML code unless that is not possible due to
otherwise unattainable performance goals regarding file size.
</p>
<p>
Use tools such as the <a href="https://validator.w3.org/nu/">W3C
HTML validator</a> to test.
</p>
<p>
Using valid HTML is a measurable baseline quality attribute
that contributes to learning about technical requirements
and constraints, and that ensures proper HTML usage.
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<title>Test</title>
<article>This is only a test.
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Semantics">
<SUMMARY>
Use HTML according to its purpose.
</SUMMARY>
<BODY>
<p>
Use elements (sometimes incorrectly called “tags”) for what
they have been created for. For example, use heading
elements for headings, <code>p</code> elements for
paragraphs, <code>a</code> elements for anchors, etc.
</p>
<p>
Using HTML according to its purpose is important for
accessibility, reuse, and code efficiency reasons.
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<div onclick="goToRecommendations();">All recommendations</div>
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<a href="recommendations/">All recommendations</a>
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Multimedia Fallback">
<SUMMARY>
Provide alternative contents for multimedia.
</SUMMARY>
<BODY>
<p>
For multimedia, such as images, videos, animated objects via
<code>canvas</code>, make sure to offer alternative
access. For images that means use of meaningful alternative
text (<code>alt</code>) and for video and audio transcripts
and captions, if available.
</p>
<p>
Providing alternative contents is important for
accessibility reasons: A blind user has few cues to tell
what an image is about without <code>@alt</code>, and other
users may have no way of understanding what video or audio
contents are about either.
</p>
<p>
(For images whose <code>alt</code> attributes would
introduce redundancy, and for images whose purpose is purely
decorative which you cannot immediately use CSS for, use no
alternative text, as in <code>alt=""</code>.)
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<img src="spreadsheet.png">
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Separation of Concerns">
<SUMMARY>
Separate structure from presentation from behavior.
</SUMMARY>
<BODY>
<p>
Strictly keep structure (markup), presentation (styling),
and behavior (scripting) apart, and try to keep the
interaction between the three to an absolute minimum.
</p>
<p>
That is, make sure documents and templates contain only HTML
and HTML that is solely serving structural purposes. Move
everything presentational into style sheets, and everything
behavioral into scripts.
</p>
<p>
In addition, keep the contact area as small as possible by
linking as few style sheets and scripts as possible from
documents and templates.
</p>
<p>
Separating structure from presentation from behavior is
important for maintenance reasons. It is always more
expensive to change HTML documents and templates than it is
to update style sheets and scripts.
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
<u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
my website without doing everything all over again!</center>
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
<p>It’s awesome!
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Entity References">
<SUMMARY>
Do not use entity references.
</SUMMARY>
<BODY>
<p>
There is no need to use entity references like
<code>&mdash;</code>, <code>&rdquo;</code>, or
<code>&#x263a;</code>, assuming the same encoding
(UTF-8) is used for files and editors as well as among
teams.
</p>
<p>
The only exceptions apply to characters with special meaning
in HTML (like <code><</code> and <code>&</code>) as
well as control or “invisible” characters (like no-break
spaces).
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
The currency symbol for the Euro is “€”.
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Optional Tags">
<SUMMARY>
Omit optional tags (optional).
</SUMMARY>
<BODY>
<p>
For file size optimization and scannability purposes,
consider omitting optional tags.
The <a href="https://whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5
specification</a> defines what tags can be omitted.
</p>
<p>
(This approach may require a grace period to be established
as a wider guideline as it’s significantly different
from what web developers are typically taught. For
consistency and simplicity reasons it’s best served
omitting all optional tags, not just a selection.)
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<!DOCTYPE html>
<html>
<head>
<title>Spending money, spending bytes</title>
</head>
<body>
<p>Sic.</p>
</body>
</html>
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="type Attributes">
<SUMMARY>
Omit <code>type</code> attributes for style sheets and scripts.
</SUMMARY>
<BODY>
<p>
Do not use <code>type</code> attributes for style sheets
(unless not using CSS) and scripts (unless not using
JavaScript).
</p>
<p>
Specifying <code>type</code> attributes in these contexts is
not necessary as HTML5 implies
<a href="https://whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
and
<a href="https://whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a>
as defaults. This can be safely done even for older browsers.
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css"
type="text/css">
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"
type="text/javascript"></script>
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="HTML Formatting Rules">
<STYLEPOINT title="General Formatting">
<SUMMARY>
Use a new line for every block, list, or table element, and
indent every such child element.
</SUMMARY>
<BODY>
<p>
Independent of the styling of an element (as CSS allows
elements to assume a different role per <code>display</code>
property), put every block, list, or table element on a new
line.
</p>
<p>
Also, indent them if they are child elements of a block,
list, or table element.
</p>
<p>
(If you run into issues around whitespace between list items
it’s acceptable to put all <code>li</code> elements in one
line. A linter is encouraged to throw a warning instead of
an error.)
</p>
<CODE_SNIPPET>
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
</CODE_SNIPPET>
<CODE_SNIPPET>
<ul>
<li>Moe
<li>Larry
<li>Curly
</ul>
</CODE_SNIPPET>
<CODE_SNIPPET>
<table>
<thead>
<tr>
<th scope="col">Income
<th scope="col">Taxes
<tbody>
<tr>
<td>$ 5.00
<td>$ 4.50
</table>
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="HTML Quotation Marks">
<SUMMARY>
When quoting attributes values, use double quotation marks.
</SUMMARY>
<BODY>
<p>
Use double (<code>""</code>) rather than single quotation marks
(<code>''</code>) around attribute values.
</p>
<BAD_CODE_SNIPPET>
<!-- Not recommended -->
<a class='maia-button maia-button-secondary'>Sign in</a>
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
<!-- Recommended -->
<a class="maia-button maia-button-secondary">Sign in</a>
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="CSS Style Rules">
<STYLEPOINT title="CSS Validity">
<SUMMARY>
Use valid CSS where possible.
</SUMMARY>
<BODY>
<p>
Unless dealing with CSS validator bugs or requiring
proprietary syntax, use valid CSS code.
</p>
<p>
Use tools such as the <a href="https://jigsaw.w3.org/css-validator/">W3C
CSS validator</a> to test.
</p>
<p>
Using valid CSS is a measurable baseline quality attribute
that allows to spot CSS code that may not have any effect
and can be removed, and that ensures proper CSS usage.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="ID and Class Naming">
<SUMMARY>
Use meaningful or generic ID and class names.
</SUMMARY>
<BODY>
<p>
Instead of presentational or cryptic names, always use ID
and class names that reflect the purpose of the element in
question, or that are otherwise generic.
</p>
<p>
Names that are specific and reflect the purpose of the
element should be preferred as these are most understandable
and the least likely to change.
</p>
<p>
Generic names are simply a fallback for elements that have no
particular or no meaning different from their siblings. They are
typically needed as “helpers.”
</p>
<p>
Using functional or generic names reduces the probability of
unnecessary document or template changes.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended: meaningless */
#yee-1901 {}
/* Not recommended: presentational */
.button-green {}
.clear {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended: specific */
#gallery {}
#login {}
.video {}
/* Recommended: generic */
.aux {}
.alt {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="ID and Class Name Style">
<SUMMARY>
Use ID and class names that are as short as possible but as long as
necessary.
</SUMMARY>
<BODY>
<p>
Try to convey what an ID or class is about while being as
brief as possible.
</p>
<p>
Using ID and class names this way contributes to acceptable
levels of understandability and code efficiency.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
#navigation {}
.atr {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#nav {}
.author {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Type Selectors">
<SUMMARY>
Avoid qualifying ID and class names with type selectors.
</SUMMARY>
<BODY>
<p>Unless necessary (for example with helper classes), do not
use element names in conjunction with IDs or classes.
</p>
<p>
Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
reasons</a>.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
ul#example {}
div.error {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#example {}
.error {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Shorthand Properties">
<SUMMARY>
Use shorthand properties where possible.
</SUMMARY>
<BODY>
<p>
CSS offers a variety of <a href="https://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
properties (like <code>font</code>)
that should be used whenever possible, even in cases where
only one value is explicitly set.
</p>
<p>
Using shorthand properties is useful for code efficiency and
understandability.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="0 and Units">
<SUMMARY>
Omit unit specification after “0” values.
</SUMMARY>
<BODY>
<p>
Do not use units after <code>0</code> values unless they are
required.
</p>
<CODE_SNIPPET>
margin: 0;
padding: 0;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Leading 0s">
<SUMMARY>
Omit leading “0”s in values.
</SUMMARY>
<BODY>
<p>
Do not use put <code>0</code>s in front of values or lengths
between -1 and 1.
</p>
<CODE_SNIPPET>
font-size: .8em;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Hexadecimal Notation">
<SUMMARY>
Use 3 character hexadecimal notation where possible.
</SUMMARY>
<BODY>
<p>
For color values that permit it, 3 character hexadecimal
notation is shorter and more succinct.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
color: #eebbcc;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
color: #ebc;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Prefixes">
<SUMMARY>
Prefix selectors with an application-specific prefix (optional).
</SUMMARY>
<BODY>
<p>
In large projects as well as for code that gets embedded in
other projects or on external sites use prefixes (as
namespaces) for ID and class names. Use short, unique
identifiers followed by a dash.
</p>
<p>
Using namespaces helps preventing naming conflicts and can
make maintenance easier, for example in search and replace
operations.
</p>
<CODE_SNIPPET>
.adw-help {} /* AdWords */
#maia-note {} /* Maia */
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="ID and Class Name Delimiters">
<SUMMARY>
Separate words in ID and class names by a hyphen.
</SUMMARY>
<BODY>
<p>
Do not concatenate words and abbreviations in selectors by
any characters (including none at all) other than hyphens,
in order to improve understanding and scannability.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended: does not separate the words “demo” and “image” */
.demoimage {}
/* Not recommended: uses underscore instead of hyphen */
.error_status {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#video-id {}
.ads-sample {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Hacks">
<SUMMARY>
Avoid user agent detection as well as CSS “hacks”—try a different
approach first.
</SUMMARY>
<BODY>
<p>
It’s tempting to address styling differences over user
agent detection or special CSS filters, workarounds, and
hacks. Both approaches should be considered last resort in
order to achieve and maintain an efficient and manageable
code base. Put another way, giving detection and hacks a
free pass will hurt projects in the long run as projects
tend to take the way of least resistance. That is, allowing
and making it easy to use detection and hacks means using
detection and hacks more frequently—and more frequently
is too frequently.
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="CSS Formatting Rules">
<STYLEPOINT title="Declaration Order">
<SUMMARY>
Alphabetize declarations.
</SUMMARY>
<BODY>
<p>
Put declarations in alphabetical order in order to achieve
consistent code in a way that is easy to remember and
maintain.
</p>
<p>
Ignore vendor-specific prefixes for sorting purposes. However,
multiple vendor-specific prefixes for a certain CSS property should
be kept sorted (e.g. -moz prefix comes before -webkit).
</p>
<CODE_SNIPPET>
background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Block Content Indentation">
<SUMMARY>
Indent all block content.
</SUMMARY>
<BODY>
<p>
Indent all <a href="https://www.w3.org/TR/CSS21/syndata.html#block">block
content</a>, that is rules within rules as well as declarations, so to
reflect hierarchy and improve understanding.
</p>
<CODE_SNIPPET>
@media screen, projection {
html {
background: #fff;
color: #444;
}
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Declaration Stops">
<SUMMARY>
Use a semicolon after every declaration.
</SUMMARY>
<BODY>
<p>
End every declaration with a semicolon for consistency and
extensibility reasons.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
.test {
display: block;
height: 100px
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
.test {
display: block;
height: 100px;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Property Name Stops">
<SUMMARY>
Use a space after a property name’s colon.
</SUMMARY>
<BODY>
<p>
Always use a single space between property and value (but no
space between property and colon) for consistency reasons.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
h3 {
font-weight:bold;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
h3 {
font-weight: bold;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Declaration Block Separation">
<SUMMARY>
Use a space between the last selector and the declaration block.
</SUMMARY>
<BODY>
<p>
Always use a single space between the last selector and the opening
brace that begins the <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration
block</a>.
</p>
<p>
The opening brace should be on the same line as the last selector in a
given rule.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended: missing space */
#video{
margin-top: 1em;
}
/* Not recommended: unnecessary line break */
#video
{
margin-top: 1em;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#video {
margin-top: 1em;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Selector and Declaration Separation">
<SUMMARY>
Separate selectors and declarations by new lines.
</SUMMARY>
<BODY>
<p>
Always start a new line for each selector and declaration.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
a:focus, a:active {
position: relative; top: 1px;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
h1,
h2,
h3 {
font-weight: normal;