2. HTML and CSS guidelines
2.1. HTML
Section titled “2.1. HTML”2.1.1. Document Type
Section titled “2.1.1. Document Type”Use the following document type:
<!doctype html>Always put your HTML in no-quirks mode by
including <!doctype html> at the beginning of the document.
2.1.2. HTML Validity
Section titled “2.1.2. HTML Validity”Use valid HTML where possible.
Use valid HTML code unless that is not possible due to otherwise unattainable performance goals regarding file size.
Use tools such as the W3C HTML validator to test.
Recommended
<!doctype html><html lang="en"><body> <title>Test</title> <article>This is only a test.</article></body></html>Not recommended
<title>Test</title><article>This is only a test.2.1.3. HTML Structure
Section titled “2.1.3. HTML Structure”Use the following structure for the HTML document:
<!doctype html><html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Document</title> </head> <body> <h1>Test</h1> <article>This is only a test.</article> </body></html>2.1.4. HTML Formatting Rules
Section titled “2.1.4. HTML Formatting Rules”Use a new line for every block, list, or table element, and indent every such child element.
Separate elements of the same level with a blank line.
HTML tag attributes should not be placed on a new line, unless there are more than one attribute. If there are more than one attribute, place each attribute on a new line; also, the content of the HTML tag should be placed on a new line.
Wrapped HTML tag attributes should be indented by two spaces.
Recommended
<div class="main"> <h1>Title</h1>
<p id="paragraph" class="paragraph" > Paragraph </p></div>Not recommended
<div class="main"><h1>Title</h1><p id="paragraph" class="paragraph">Paragraph</p></div>2.1.5. Multimedia Fallback
Section titled “2.1.5. Multimedia Fallback”Provide alternative content for multimedia.
For images that means use of meaningful alternative text (alt) and for video and audio transcripts and captions, if available.
Recommended
<img src="avatar.png" alt="John Doe's avatar">Not recommended
<img src="avatar.png">2.1.6. Entity References
Section titled “2.1.6. Entity References”Do not use entity references.
The only exceptions apply to characters with special meaning in HTML (like < and &) as well as control or “invisible” characters (like no-break spaces).
Recommended
The currency symbol for the Euro is “&eur;”.Not recommended
The currency symbol for the Euro is “€”.2.1.7. id and class Attributes
Section titled “2.1.7. id and class Attributes”Avoid unnecessary id attributes.
Prefer class attributes for styling and data attributes for scripting.
Where id attributes are strictly required, always include a hyphen in the value to ensure it does not match the JavaScript identifier syntax,
e.g. use user-profile rather than just profile or userProfile.
Recommended
<div id="user-profile"> <h1>John Doe</h1></div>Not recommended
<div id="userProfile"> <h1>John Doe</h1></div>2.2. CSS
Section titled “2.2. CSS”2.2.1. CSS Validity
Section titled “2.2.1. CSS Validity”Use valid CSS where possible.
Use tools such as the W3C CSS validator to test.
2.2.2. Class Naming
Section titled “2.2.2. Class Naming”Use class names that are as descriptive as possible.
Use ID attributes only when necessary.
Prefer to use BEM (Block, Element, Modifier) naming convention.
Recommended
/* Recommended: specific */.gallery__item { }/* Recommended: generic */.container { }Not recommended
/* Not recommended: meaningless */.g-727712 { }/* Not recommended: presentational */.button-green { }2.2.3. Class Name Style
Section titled “2.2.3. Class Name Style”Use class names that are as short as possible but as long as necessary.
Recommended
/* Not recommended */.navigation { }.atr { }Not recommended
/* Recommended */.nav { }.author { }2.2.4. Class Name Delimiters
Section titled “2.2.4. Class Name Delimiters”Use a double underscore (__) as a delimiter between the block and element names.
Use a single underscore (_) as a delimiter between the element and modifier names.
Recommended
.gallery__item { }.gallery__item_selected { }Not recommended
.item { }.-selected { }2.2.5. Type Selectors
Section titled “2.2.5. Type Selectors”Avoid using type selectors.
Unless necessary (for example with helper classes), do not use element names in conjunction with classes.
Avoiding unnecessary ancestor selectors is useful for performance reasons.
Recommended
.example {}.error {}Not recommended
ul.example {}div.error {}2.2.6. ID Selectors
Section titled “2.2.6. ID Selectors”Avoid using ID selectors.
Class selectors should be preferred in all situations.
Recommended
.example {}.error {}Not recommended
#example {}#error {}2.2.7. Important Declarations
Section titled “2.2.7. Important Declarations”Avoid using important declarations.
These declarations break the natural cascade of CSS and make it difficult to reason about and compose styles
Recommended
.example { color: red;}Not recommended
.example { color: red !important;}2.2.8. Vendor Specific Prefixes
Section titled “2.2.8. Vendor Specific Prefixes”Avoid using vendor specific prefixes.
Use the standard properties instead.
Recommended
.example { border-radius: 10px;}Not recommended
.example { -webkit-border-radius: 10px; -moz-border-radius: 10px; border-radius: 10px;}2.2.8. CSS Formatting Rules
Section titled “2.2.8. CSS Formatting Rules”2.2.8.1. Declaration Order
Section titled “2.2.8.1. Declaration Order”Prefer to alphabetize declarations when possible.
Recommended
.example { background: fuchsia; border: 1px solid; border-radius: 4px; color: black; text-align: center; text-indent: 2em;}Not recommended
.example { text-align: center; border-radius: 4px; color: black; background: fuchsia; text-indent: 2em; border: 1px solid;}2.2.8.2. Selector and Declaration Separation
Section titled “2.2.8.2. Selector and Declaration Separation”Separate selectors and declarations by new lines.
Always start a new line for each selector and declaration.
Recommended
h1,h2,h3 { color: blue; font-weight: 900;}Not recommended
h1,h2,h3 { color: blue; font-weight: 900; }2.2.8.3. Block Content Indentation
Section titled “2.2.8.3. Block Content Indentation”Indent the content of blocks by two spaces.
Separate blocks with a blank line.
Recommended
.example { color: red; font-size: 16px;
.example__item { color: blue; font-size: 12px; }}Not recommended
.example {color: red;font-size: 16px;}.example__item {color: blue;font-size: 12px;}2.2.8.4. Other Conventions
Section titled “2.2.8.4. Other Conventions”Use a semicolon after every declaration.
Recommended
.example { color: red; font-size: 16px;}Not recommended
.example { color: red; font-size: 16px}Use a space after a property name’s colon.
The opening brace should be on the same line as the last selector in a given rule.
Recommended
.example { font-size: 16px;}Not recommended
.example { font-size:16px;}2.2.8.5. Section Comments
Section titled “2.2.8.5. Section Comments”Group sections by a section comment (optional).
/* Header */
h1,h2,h3 { color: blue; font-weight: 900;}
/* Main content */
.main { color: red; font-size: 16px;}