HTML – Web Development Standards

In spite of its being “only” markup, HTML is a large and complicated subject. Most of it is outside the scope of this page. As a practice, SHC FED is chiefly concerned that the HTML we produce should be:

  • valid
  • conformant with best practices
  • well structured and semantically meaningful
  • consistent throughout the codebase.

Our standards and guidelines exist to help meet those goals. They apply whether we produce component-level production HTML for inclusion within templated systems, or complete HTML pages meant for design review and handoff.

As with all code, remember when you write HTML that inevitably one or another of your colleagues will have to work with it at some point. As a favor to them, do your best to make your code readable and to format it predictably. Making code readable is the first step to making it maintainable.


Basic Conformance

The latest officially endorsed HTML5 spec (a Technical Recommendation, in W3C parlance) will be found here: http://www.w3.org/TR/html5/. The document is long and not exactly written for readability, but well worth exploring. Every developer should bookmark it and use it as a reference.

General Approach

Even though it lives in the presentation layer, HTML should be thought of first and foremost as an information resource. That is, the first aspect of “design” in HTML isn’t visual, it’s the design of the information the markup is structuring.

What this means in practice is that you should initially try to mark up a new page or a new component as cleanly and concisely as possible, in a way that seems to fit the information being presented. Your goal in writing HTML should be parsimony: expressing information content with the least markup necessary.

Of course, your minimal markup often won’t meet presentation needs, either for visual design or for interactivity. But working from parsimony to greater complexity (and then attempting from there to work back toward parsimony, as possible) helps guarantee that things don’t get out of hand as you move toward your deliverable.

Again, the goal is clarity and maintainability. Parsimonious HTML, limiting itself as much as possible to structuring an information payload, is always easier to read and change than HTML that contains unnecessary or poorly thought-out markup.

Doctype

All newly-created SHC pages must declare the HTML5 doctype and begin with an HTML tag + language attribute:

<!DOCTYPE html>
<html lang="en">

The doctype declaration is required by the HTML5 spec; it is also (more practically) necessary to ensure consistent rendering across browsers.

By spec, only HTML comments and whitespace characters are permitted before the doctype declaration, or between the doctype and the <html> element. To avoid confusion, do NOT place comments before the doctype declaration.

Some legacy pages may exist on SHC properties that declare obsolate doctypes, but these are exceptions to current practice and will be phased out over time.

Validation

Any HTML you create should validate in the W3C validator tool, located at http://validator.w3.org/. (Using this tool to explore a variety of web pages is a good way of ramping yourself up on common HTML5 issues and practices.) Do not deliver HTML that you have not validated.

For a variety of reasons (such as inclusion of third-party and legacy code), pages on SHC websites likely will not validate and are not expected to.


Code Format

HTML Tags

For consistency, all HTML tag and attribute names should be lower-cased in your source code. Attribute values are enclosed in double quotes. Do not add whitespace before or after the attribute equals sign, or between the value of the last attribute in the tag and the end bracket. Do not add whitespace to the tag close.

THIS:

<a href="/some/place/to/go.html">Link text</a>

NOT THIS:

<A href = '/some/place/to/go.html' >Link text< /A >

Be certain all tags are properly nested (though the validator will catch this).

THIS (all tags nested):

<em>Some <strong>bold</strong> and italic text.</em>

NOT THIS (tags improperly nested):

<em>Some <strong>bold and italic text.</em></strong>

Tag Closure

Rules for tag closure have changed with HTML5; some tags (notably P and LI) no longer require explicit closing tags.

What counts as a “paragraph” in HTML5 is, as it turns out, a surprisingly complicated question that requires substantial documentation. For example, the following code snippet validates, and contains two HTML5 paragraphs (see the preceding link for discussion):

<section>
  <h1>Example of paragraphs</h1>
  This is the <em>first</em> paragraph in this example.
  <p>This is the second.
  <!-- This is not a paragraph. -->
</section>

To keep things simple and predictable, ALL text content within an SHC HTML page must be enclosed in an appropriate tag. All non-empty tags, even when the spec is lenient, must be given explicit closing tags.

<section>
  <h1>Example of paragraphs</h1>
  <p>This is the <em>first</em> paragraph in this example.</p>
  <p>This is the second.</p>
  <!-- This is not a paragraph. -->
</section>

Avoiding Legacy XHTML Habits

The now-obsolete XHTML spec was the SHC standard until relatively recently, and a great deal of our code retains XHTML features. In most cases, HTML5 is lenient towards XHTML-style code forms and will validate them. Nevertheless it’s good practice to avoid the reflex of writing such code, and to note its existence and fix it wherever possible.

Attribute minimization

XML constraints required that boolean attributes be given explicit values, in a style that was sort of obtuse and tended to create confusion.

<input type="checkbox" checked="checked" />

HTML5 restores attribute minimization for boolean attributes, so the following is correct and encouraged:

<input type="checkbox" checked>

Closing empty elements

Empty elements–elements without content (text, or other elements)–required XML-style closure in XHTML.

<br />
<img />

Again, HTML5 restores the prior state of play for empty elements.

<br>
<img>

XHTML-style closure isn’t incorrect, but it should be avoided.


HTML Semantics

Even though it lives in the presentation layer, HTML should be thought of first and foremost as an information resource. That is, the first aspect of “design” in HTML isn’t visual, it’s the design of the information the markup is structuring. (Yes, this is repeated from the top of the page, because it’s important enough to warrant it.)

HTML5 Semantics

All FEDs should become familiar with the semantic aspects of HTML5, particularly the new elements (ARTICLE, SECTION, HEADER/FOOTER, NAV etc.) added to the spec to improve HTML’s structural vocabulary. Congruent with this are changes to the HTML content model, which are substantial and meaningful. Though there’s some complexity, it’s especially useful to understand what the spec calls transparent content models, and what paragraphing means in HTML5. Pay particular attention to the semantics of headings and sectioning, and take note of the set of elements defined in HTML5 as grouping content.

Use cases and patterns can be difficult to derive from specs, of course, even careful and well-written ones (which the HTML5 spec definitely is). The online book Dive into HTML5 has a chapter on semantics that illustrates taking a page marked up in XHTML and using HTML5 markup to refactor it. It’s a very practical and useful discussion.

You should prefer HTML5 semantic markup to the old DIV-plus-css class (<div class=”header”>) wherever possible. Be aware that HTML5 elements will not be recognized or rendered in IE8 without being shimmed. Fortunately such shims are common and well understood and require very little code overhead. If you don’t know whether the stack you’re working in has a shim available, ask somebody. (And at the ever-approaching point where SHC drops IE8 support entirely the whole issue becomes moot.)

CSS Semantics

SHC’s standard Enterprise CSS augments HTML semantics with CSS patterns that have been developed to meet the common UI and structural needs of pages across our sites. Please bookmark/watch the Enterprise project wiki as a reference, and familiarize yourself with the code examples and resources there.

Code Parsimony

A great deal of HTML in our codebase can be significantly improved simply by removing unnecessary markup. A place to start is in understanding which elements are block and which are inline and avoiding redundant wrappings.

NOT THIS:

<div>
  <ul>
    <li>Some line item content</li>
  </ul>
</div>

THIS:

<ul>
  <li>Some line item content</li>
</ul>

The extra DIV added no information content. UL is already a block-level tag and doesn’t need any further wrapping here.

NOT THIS:

<span><img src="/some/src/path/img.jpg"></span>
<a href="/some/path"><span>Link text</span></a>

THIS:

<img src="/some/src/path/img.jpg">
<a href="/some/path">Link text</a>

SPAN is an inline element, as are IMG and A. Again, the extra elements added no information content in this scenario and compromised the readability of the markup.

Something similar applies to attributes, especially IDs. Don’t add IDs to elements unless there’s some particular need for them (typically because they need to be targets for jQuery code). Don’t add attributes with default values to elements if you’re not changing the default value. (But DO always add ALT and TITLE attributes where accessibility rules require them.)

Uniqueness Constraints

Do not reuse ID values. For any element with an ID attribute, that value must appear nowhere else in the page.

For image maps, all MAP elements must be given unique names that match the USEMAP value of the corresponding IMG.

<img src="sears.gif" width="145" height="126" alt="sears.gif" title="sears.gif" usemap="#searsMainPromotionMap" />
<map name="searsMainPromotionMap">
<area shape="rect" coords="0,0,82,126" href="link" alt="link1" title="link1" />
<area shape="circle" coords="90,58,3" href="link" alt="link2" title="link2" />
</map>


Miscellaneous

Comments

If you’re not sure whether it’s useful to add a comment: add it. If we get to the point where our code suffers from an excess of comments, that’s a classy problem to have.

Format multiline comments as follows:

<!--
This is a multiple line comment. The opening and closing
comments should be on their own lines, separate from
the text. This improves the comment's readability.
-->

Standard <meta> Block

The following block of code must be inserted in the <head> tag of each page:

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Language" content="en-us" />
<meta name="keywords" content="[Meta keywords block]" />
<meta name="description" content="[Meta description block]" />

Line Breaks

Insert line breaks to separate large logical chunks of code (between <head> and <body>, separating <div> tags, etc.).

Insert a line break between block-level elements (<p>, <h1>, <h2>,..., <h6>, <ol>, <ul>, <dl>, <div>, <noscript>, <blockquote>, <form>, <hr>, <pre>, <table>, <fieldset>, <address>).

Indentation

Insert a line break with an indent prior to every block-level start tag that is logically inside of another block-level tag. The indented code must be on its own line and indented four spaces from the beginning of the line. Instead of hitting the spacebar four times, use the Tab key and configure your editor to use four spaces. The indentation level of a closing tag must ALWAYS match the indentation level of the corresponding opening tag.

We indent to make it easier to eyeball a page of code for structure. Indentation levels more than four or five deep may make that harder, but sometimes that level of nesting is necessary. Optionally, deeply nested structures can be marked off by outdenting them, or by keeping the parent indentation level but adding line breaks. Use your best judgement as to what will make the code readable.

EXAMPLE (nested block-level elements):

In the following example, the <h1> and <ul>  block-level tags are indented inside of the <nav> block-level tag. The<p> tag is not indented because it is not inside of another block-level element. The <strong> tag does not require line breaks or indentation because it is an inline element, not a block-level element.

The NAV and P elements are not indented even tough they occur within the block-level BODY tag; that level of indentation is just fussy and might actually make the code less readable. The extra line break between BODY and its child tags is optional; so is the extra line break between the NAV and the P elements. As always, readability is your primary concern here.

<body>

<nav>
  <h1>My Article</h1>
  <ul>
    <li>A nav item</li>
    <li>Another nav item</li>
  </ul>
</nav>

<p>This is an awesome article. You <strong>must</strong> read it.</p>

</body>

EXAMPLE (lists):

The <ol>, <ul> and <dl> list elements are universally defined to be block-level elements. Using the W3C’s definition of block-level elements, the <li> element could also be categorized as a block-level element. In applying the above block-level indentation rules to the <ol>, <ul>, <dl> and <li> elements, you must indent each of those elements as follows:

<ol>
  <li>
  Morning
    <ul>
      <li>Wake up.</li>
      <li>Go to work.</li>
    </ul>
  </li>
  <li>
  Afternoon
    <ul>
      <li>Eat lunch.</li>
      <li>Try and stay awake.</li>
      <li>Go home and watch TV.</li>
    </ul>
  </li>
  <li>Evening</li>
</ol>

As shown above, when embedding a list inside of a list, the outer list’s end tag must be placed below the embedded list.

EXAMPLE (tables):

The <table> element is universally defined to be a block-level element. Using the W3C’s definition of block-level elements, the <thead>, <tbody> and <tr> elements could also be categorized as block-level elements. In applying the above block-level indentation rules to the <table>, <thead>, <tbody> and <tr> elements, you must indent each of those elements as follows:

<table>
<thead>
    <tr>
        <th>A</th>
        <th>B</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>one</td>
        <td>two</td>
    </tr>
    <tr>
        <td>three</td>
        <td>four</td>
    </tr>
</tbody>
</table>

When embedding a table inside of a table (not recommended), apply the table indentation rules recursively.

Images

Include width and height attributes for all <img> elements. This will cause pages to load faster and will not break the page in the case of a broken or missing image.

Include the alt attribute for all <img> elements. Use alt="" for decorative images or use in the background. See the Accessibility guidelines above for the reasoning behind this.

Other best practices

  • Whenever possible, use logical inline elements rather than physical inline elements.
    • Logical inline elements: <abbr>, <acronym>, <cite>, <code>, <del>, <dfn>, <div>, <em>, <ins>, <kbd>, <q>, <samp>, <span>, <strong>, <var>
    • Physical inline elements: <b>, <big>, <blink>, <font>, <i>, <s>, <small>, <strike>, <sub>, <sup>, <tt>, <u>
  • Whenever linking to another page, whether it is internal or external, use the title attribute to provide a brief description of the page being linked.
    EXAMPLE: <a href="/index.html" title="Return to homepage">Home</a>

Browser Support

Browser support for our sites is defined using a graded approach. Graded browser support is an approach to dealing with the variety of browsers (new and old) used by users and their widely varying capabilities. The graded browser support approach establishes levels of support for which we develop. Each grade provides a different level of access and fidelity to websites that we design.

Grade A support

Advanced functionality and visual fidelity: This level of support is provided to modern, standards-compliant browsers and is designed to provide “advanced functionality and visual fidelity.” These are browsers with fully capable and compliant CSS support and capable of Web 2.0 technologies, or that are so ubiquitous (Internet Explorer) that websites must be developed to work with them.

    The current list of Grade A browsers includes:

  • Firefox 11+ (Windows/Macintosh)
  • IPad/Webkit
  • Safari 5.0+ (Windows/Macintosh)
  • Chrome latest stable (Windows/Macintosh)

Grade B support

Basic functionality and visual approximation of design: This level of support is provided to browsers that are not quite fully standards-compliant, but are still capable of relative fidelity in the display of pages (not all visual elements will appear as in Grade A) and basic functionality with respect to modern Web technologies. This level of support is designed to provide a close, but not necessarily perfect, visual user experience along with basic functionality.

    The current list of Grade B browsers includes:

  • Internet Explorer 8 (Windows)
  • Firefox 4-10 (Windows/Macintosh)
  • Safari <5.0 (Windows/Macintosh)
  • Chrome <latest stable (Windows/Macintosh)

Grade C support

Core content and basic functionality: This level of support is provided to older, non-compliant browsers, and is designed to provide accessible pages “un-enhanced by decoration or advanced functionality.” This level of support provides only basic functionality and a minimal visual experience.

    The current list of Grade C browsers includes:

  • Firefox <4 (Windows/Macintosh)
  • Internet Explorer <7/MSN Explorer (Windows/Macintosh)
  • Netscape Navigator (all) (Windows/Macintosh)
  • Opera (all) (Windows/Macintosh)

Alternate / Mobile browsers

The W3C provides a list of alternative browsers and applications, particularly for disabled users. We do not test for these except in cases where access for disabled users is a high priority. In those cases, our typical procedure is to test using JAWS and the Fangs extension for Firefox. Otherwise, this list is strictly FYI.

http://www.w3.org/WAI/References/Browsing.html

Post a New Comment

Your feedback will help us improve this page. If you have a comment about the content of this page, use the form below, and the Patterns Team will get back to you within a business day.

For general questions or assistance, email the Patterns Team directly.