Semantics
- Use the coding style guide to write consistent code
- Use
.envfiles to manage build variables, do not commit the files if they contain secure data - Use the
example-repositorytemplate for creating GitHub repositories; it includes.editorconfig,CODEOWNERS, andREADME.md - Follow the GitHub repository naming conventions (Google Doc)
Frameworks and build processes
- Use frameworks sparingly; if possible, remove any unused features to reduce bulk
- Minify CSS and JS, and remove unused/redundant code
Page structure
- Include
DOCTYPEstatement - Attribute a language to the entire page, i.e.
<html lang="en-us"> - Use [current page title] | [website name] for
<title> - All content inside
<body>must be within a proper HTML region:<header>,<nav>,<main>,<aside>,<footer>,<section> - Each region has an accessible label associated with it if more than one of that type of region is present, i.e.
<nav aria-label="Main">and<nav aria-label="Breadcrumbs"> - The
<h1>is the descriptive heading for the content on that page - Headings must be properly nested; do not use out of order to achieve styles, i.e.
<h3>is nested below an<h2>
Developing custom components
Adapted from Adrian Roselli’s basic custom control requirements.
- Internationalization support: correctly use
langattribute, has left-to-right (LTR) text support, uses writing modes (for more than LTR and RTL) where appropriate, using CSS logical properties - Keyboard: built-in keyboard support, uses defaults where known, includes obvious focus styles
- System settings: supports Windows high contrast mode (WHCM), honors people’s color scheme preferences (dark mode), honors reduced motion preferences, honors new user-preference-based feature queries as they become available
- Scaling: does not disable zoom, does not fall apart on zoom, does not override custom font size settings, uses relative sizing (for lines, text, borders, spacing...)
- ARIA: uses appropriate ARIA roles and attributes for its purpose, when no ARIA role fits treat it as a group of distinct controls with apprioriate ARIA roles for each smaller component, use ARIA states and properties (use expected ones for defined widgets), do not use ARIA to define native operating-system-style controls that are not a fit for a web control or web document
- Clearly convey disabled, read-only, and required states along with name, role, and value
- Maintain good contrast of content and contrast across use, states, and context
- Tested (by real people) screen reader support (beyond compliance)
- Use progressive enhancement
- Include print styles
- Does not have unnecessary dependencies (packages, libraries, images, styles...)
Inclusive design
Adapted from Heydon Pickering’s inclusive design checklist.
- Content must all be keyboard and screen reader navigable
- Make sure heading levels describe a logical section/subsection structure
- Honour DNT (Do Not Track) header
- Do not hijack standard scrolling behavior
- Make sure main body (paragraph) text is no smaller than the default (user agent) size
- Use relative units (em, rem, and ch), especially for font metrics
- Support “pinch zoom” (remove
user-scalable=noif present) - Make sure styles and scripts are not render blocking
- Use content-based, not device-specific, media queries
- Do not include third parties that compromise user privacy
- Make sure controls do not elicit unexpected or jarring behavior
- Do not recreate supported and expected browser behaviors with bespoke scripts
- Support Windows high contrast mode (use images, not background images)
- Provide large touch “targets” for interactive elements