-
Notifications
You must be signed in to change notification settings - Fork 5
HTML coding guidelines
The adidas rules for HTML are based on the Google HTML style guide which is a good reading to know HTML good practices as well.
These HTML rules apply as much to HTML files as to templates using any technology such as Mustache, AngularJS, React JSX or Vue.js templates.
Another good document for HTML good practices is the code guide by @mdo.
List of main rules, customized ones and examples.
Rules related to spaces, indentation, braces and punctuation.
- Indent with whitespaces:
- 2 spaces block indent.
- 4 spaces attribute continuation indent.
- The line length should not exceed 120 characters.
- If the line length gets over 120 characters the new line must be indented using 2 tabs (4 spaces).
- Upon splitting attributes in multiple lines, place just one attribute per line.
- The first one can be placed in the same line as the element or in a new one.
- Closing tags should be placed in a different line if the element is multiline.
- Self closing tags should go on the same line of the last attribute.
<!-- Block indentation (2 whitespaces) -->
<tag>
<other-tag>
<element><element/>
<element><element/>
<self-closing/>
</other-tag>
<element><element/>
</tag>
<element><element/>
<!-- New line indentation (4 whitespaces) -->
<tag attribute1="value1"
attribute2="value2"
attribute3="value3"
attribute4="value4">
<self-closing attribute1="value1" attribute2="value2"/>
<self-closing attribute1="value1"
attribute2="value2"
attribute3="value3"/>
<element attribute1="value1"
attribute2="value2"
attribute3="value3"
attribute4="value4">
<element/>
<element>value<element/>
</tag>
<element>value<element/>The element tags must satisfy:
- The tags must always be closed.
- The simple tags are closed in the same element-
- There is no whitespace between the last attribute and the slash character.
<!-- Tags closed -->
<complex-tag>
<complex-tag>
<simple-tag data-attr="attr-value"
data-long-attribute-name="long-attribute-value"/>
<simple-tag data-attr="attr-value"/>
</complex-tag>
<complex-tag>
<simple-tag data-attr="attr-value"/>
<complex-tag>value<complex-tag/>- Use always double-quotes to wrap the attribute values.
- Use simple-quotes, if they are necessary, inside an attribute value.
<!-- Invalid quotes -->
<div attribute1='value1' attribute2='value "2"'>
<element/>
</div>
<!-- Valid quotes -->
<div attribute1="value1" attribute2="value '2'" attribute3="value3">
<element/>
</div>There are two types of attributes, the ones given by the standard and the other ones created by the user as custom attributes.
- The attribute name must be written in dash-delimited format.
- The custom attributes should use the
data-prefix.- It allows the linting tools to validate them.
<!-- Invalid attributes -->
<body app="adidas">
<div stunning-attribute>
<element class="adidas-class" custom-class="adidas-custom-class"/>
</div>
</body>
<!-- Valid attributes -->
<body data-app="adidas">
<div data-stunning-attribute>
<element class="adidas-class" data-custom-class="adidas-custom-class"/>
</div>
</body>Some frameworks allows to work with custom elements, such as AngularJS, however it is not a good practice to use them because this feature is not supported by the standard. Other frameworks, such as React or Vue.js, transform the custom elements into other supported elements in the build process, so the custom elements are allowed and it is recommended to be used.
In order to do compatible with all the browsers, these new elements cannot be used as HTML tags, the solution is to use only as attributes, using <div/>/<span/> for example to wrap the element.
Working with frameworks:
- AngularJS: the directives must only be used as attributes, using
restrict: 'A', which is the default value. - React and Vue.js: the templates are compiled and the system replaces the custom elements by a simple
<div/>element, then it is possible to work with custom elements as ReactJS/Vue.js proposes.
<!-- Invalid element tag -->
<stunning-element>
<element data-attr="attr-value"/>
</stunning-element>
<!-- Valid elements as an attribute -->
<section data-stunning-element>
<div data-element data-attr="attr-value"/>
</section>Commented HTML code is now allowed in repositories, so, the commented code has to be removed or not pushed.
Note: if there is a important reason in order not to remove the commented code, it has to be added to the commented block with a TODO: reason.
<!-- TODO: enable when the feature `green connection` is available
<stunning-element>
<element/>
</stunning-element>
-->There is not yet a configuration available to be used to lint the HTML code.