Standards for developing contributiong HTML, CSS, and JavaScript to W3 WAI-ARIA APG.
These standards are provided as a guide to contributing to W3 WAI-ARIA APG
They are based on Code Guide by @mdo.
The following priorities have been used to determine these standards:
</li>
or </body>
).Enforce standards mode and more consistent rendering in every browser possible with this simple doctype at the beginning of every HTML page.
From the HTML5 spec:
Authors are encouraged to specify a lang attribute on the root html element, giving the document's language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth.
Read more about the lang
attribute in the spec.
Head to Sitepoint for a list of language codes.
Quickly and easily ensure proper rendering of your content by declaring an explicit character encoding. When doing so, you may avoid using character entities in your HTML, provided their encoding matches that of the document (generally UTF-8).
Per HTML5 spec, typically there is no need to specify a type
when including CSS and JavaScript files as text/css
and text/javascript
are their respective defaults.
Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.
A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement.
For further reading, consult the WhatWG section on boolean attributes:
The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.
If you must include the attribute's value, and you don't need to, follow this WhatWG guideline:
If the attribute is present, its value must either be the empty string or [...] the attribute's canonical name, with no leading or trailing whitespace.
In short, don't add a value.
Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. Take the following example:
Writing markup in a JavaScript file makes the content harder to find, harder to edit, and less performant. Avoid it whenever possible.
:
for each declaration.box-shadow
).rgb()
, rgba()
, hsl()
, hsla()
, or rect()
values. This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space).0.5
instead of .5
and -0.5px
instead of -.5px
).#fff
. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes.#fff
instead of #ffffff
.input[type="text"]
. They’re only optional in some cases, and it’s a good practice for consistency.margin: 0;
instead of margin: 0px;
.Questions on the terms used here? See the syntax section of the Cascading Style Sheets article on Wikipedia.
Related property declarations should be grouped together following the order:
Positioning comes first because it can remove an element from the normal flow of the document and override box model related styles. The box model comes next as it dictates a component's dimensions and placement.
Everything else takes place inside the component or without impacting the previous two sections, and thus they come last.
For a complete list of properties and their order, please see Recess.
@import
Compared to <link>
s, @import
is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach:
<link>
elementsFor more information, read this article by Steve Souders.
Place media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future. Here's a typical setup.
When using vendor prefixed properties, indent each property such that the declaration's value lines up vertically for easy multi-line editing.
In Textmate, use Text → Edit Each Line in Selection (⌃⌘A). In Sublime Text 2, use Selection → Add Previous Line (⌃⇧↑) and Selection → Add Next Line (⌃⇧↓).
Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values. Common overused shorthand properties include:
padding
margin
font
background
border
border-radius
Often times we don't need to set all the values a shorthand property represents. For example, HTML headings only set top and bottom margin, so when necessary, only override those two values. Excessive use of shorthand properties often leads to sloppier code with unnecessary overrides and unintended side effects.
The Mozilla Developer Network has a great article on shorthand properties for those unfamiliar with notation and behavior.
Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others. Great code comments convey context or purpose. Do not simply reiterate a component or class name.
Be sure to write in complete sentences for larger comments and succinct phrases for general notes.
.btn
and .btn-danger
)..btn
is useful for button, but .s
doesn't mean anything..js-*
classes to denote behavior (as opposed to style), but keep these classes out of your CSS.It's also useful to apply many of these same rules when creating Sass and Less variable names.
Use K&R 1TBS variant positioning of braces, except for not using a cuddled else (similar to Stroustrup style)
Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:
Consider documenting and applying these preferences to your project's .editorconfig
file. For an example, see the one in Bootstrap. Learn more about EditorConfig.