The purpose of this document is to provide guidelines for writing HTML at PayPal. Code conventions are important for the long-term maintainability of code. Most of the time, developers are maintaining code, either their own or someone else’s. Code conventions provide a common dialect with which developers communicate through code with one another.
HTML Style Guide
Style guides provide basic syntax and formatting guidance. The goal is to have everyone’s code look the same, which allows any developer to easily work on another developer’s code.
Each indentation level is made up of one tab character. Do not use spaces.
All tag names on all elements must be all lowercase.
Elements for which a closing tag is forbidden in HTML must use XHTML self-closing style with an extra space before the slash.
Elements for which the closing tag is optional must always include the closing tag.
Attribute names must be in all lowercase.
There should be no space between the attribute name and attribute value.
Attribute values must always be quoted using double quotes.
Boolean attributes, those attributes that don’t require a value in HTML, must always include an attribute value.
Every HTML document must follow this basic structure:
The key parts of this document structure are:
. This is where the page content goes.
- Every HTML document must begin with the HTML5 doctype.
- Immediately following the doctype must be the
<html>element. The lang attribute must be set to the appropriate language for the page.
- The next element should be
<head>, which should contain
<meta charset="UTF-8">as the first two children. After that may come, in order, additional meta information, stylesheet and other
- All of these elements must be present and closed appropriately.
If the document's main language is a right-to-left language, include the
dirattribute on the
Do not use the CSS
directionproperty for this purpose.
typeattribute should not be included.
CSS style sheets should be included using the
typeattribute should not be included and the
mediaattribute isn't required unless the style sheet shouldn't be used by default (for example, if it only applies to print).
Tags to Avoid
Certain tags should not be used. All officially deprecated or obsoleted tags should not be used (see HTML5 Obsolete Elements).
In addition, the following tags should not be used:
Programming practices are another type of code convention. Where style guidelines are concerned with the appearance of code, programming practices are concerned with the outcome of the code. You can think of programming practices like recipes - they help developers write their code in such a way that the end result is already known. If you've ever used design patterns such as the observer pattern of the model-view-controller (MVC), then you're already familiar with programming practices. Design patterns are programming practices that solve specific problems related to software organization.
All pages must have just one
<h1>element. Do not use
Action (Non-navigational) Links
hrefmust contain either a valid URL for alternate content or an ID reference in the form
#id, such as
roleattribute equal to
buttonto indicate to screen readers that the link is non-navigational.
The title Attribute
titleattribute should be used sparingly, and only in cases where it's providing additional information that isn't apparent from the markup. For instance, there is no reason to provide a
titleattribute that duplicates a link's text or an image's
titleattribute is required when using the
patternattribute on an
Tables may only be used to structure tabular data–information organized in rows and columns, similar to a spreadsheet. In all other cases, CSS must be used.
Tables must contain a
<caption>element that contains the title of the table. If this content should not be displayed on the page, use the
accessAidCSS class on the
<th>element may have a
scopeattribute indicating whether it applies to a row or a column. Scope is optional but recommended.
For complex tables (more than 1 level of row or column headers), the scope or headers attributes must be used to make the content accessible. The summary attribute is no longer recommended.
Form Input Fields
All form input fields must be accompanied by a
<label>element describing their use regardless of UI design. If necessary, you may hide the
accessAidclass. Do not put the input element inside of
Form Input Types
<input>types may be used:
Avoid using the following
Form Radio Buttons
When radio buttons are used on a form, use a
<fieldset>element to enclose the options and use the
<legend>element to specify the text that corresponds to all radio buttons. Use an unordered list where each item is one radio button, and each radio button has its own
HTML5 Block Elements
Use HTML5 structural elements (
<nav>) for the main page grid.