General

Introduction

• Front-end code should be valid and compliant with W3C and WCAG standards, as well as the standards outlined in this site
  • No deprecated or non-standard code
  • No console errors
  • All front-end code should be tested across supported browsers and operating systems, and with assistive technology, e.g.: screen readers
• Front-end code should maintain a separation of concerns
  • Semantic HyperText Markup Language (HTML) for structure
  • Cascading Style Sheets (CSS) for presentation
  • JavaScript (JS) for behavior and interaction
• Front-end code should be as simple, as clear, and as clean as possible
  • Clever code does not mean good code; readability is critical
  • Maintain an organized and logical structure in the file system
  • Leave the code a little better than you found it
  • Address tech debt
  • Delete legacy files and dead code
  • Delete commented out code
  • Avoid code comments. Code never lies; comments do. Writing self-explanatory code is a better use of time
• Front-end code should look like a single person typed it, even when many people are contributing to it
  • Establish conventions for white space, indentation, nesting, capitalization, quote styles, etc. at the start of a project or during major cleanup/refactoring efforts
  • Use automated code quality tools, e.g.: linters, browser extensions, etc., to provide real-time feedback, reduce the amount of human code review needed, and enforce best practices and coding standards
  • Configure editor settings to align with front-end code standards and linter rules in order to avoid common code inconsistencies and dirty diffs, and to “show invisibles” in order to make white space changes more visible
  • Refer to the automated code quality tools page for links to our configs

Casing

• Elements, attributes, and attribute values should be lowercase
• CSS class names should be kebab-case
• IDs should be camelCase
• Hex values should be lowercase — only use hex values in global variable files
• JavaScript variable names should be camelCase
• JavaScript objects, classes, and namespaces should be TitleCase
• TypeScript interfaces, types, and enums should be PascalCase
• Components and their files — including component-specific stylesheets — should be PascalCase
• Hooks and non-component JavaScript and TypeScript files should be camelCase
• Assets — like folders, fonts, images, and stylesheets — should be kebab-case

Responsive

Responsive means the layout is flexible, fluid, and device agnostic, and the content reflows and adapts to almost any screen.

Since screen dimensions and width in CSS pixels vary widely between devices, and how people interact with the web across screens continues to evolve rapidly, content should not rely on a particular device type, screen size, viewport width, resolution, orientation, etc. to render well. Instead of thinking about specific devices and dimensions, think about sizes conceptually, e.g.: extra-small, small, medium, large, extra-large, and focus on creating flexible, fluid, device-agnostic layouts that adapt to almost any screen.

• Use a responsive layout grid and media queries
• Take a device-agnostic approach to responsive
• Start with the smallest breakpoint and work upwards
• Never hide content
• Avoid setting fixed dimensions
• Test on real hardware

Third-party libraries

The selection of third-party libraries should be carefully considered and verified with the project team as the appropriate solution to a given problem. "Adding another plug-in" is not always the best solution.

In general, third-party libraries should be actively-maintained, open source, lightweight, accessible libraries with no dependencies. The feature set should be understood and appropriate. Whenever possible, the same third-party library should be used across applications to keep the UX consistent and speed up development. For apps using modern JavaScript frameworks, third-party libraries should be built using TypeScript.

Adding multiple front-end frameworks, e.g.: Bootstrap and Material UI, in the same application is not recommended. Having multiple frameworks that solve the same problem exponentially increases the size of the application and introduces inconsistent interactions, animations, styles, etc. that are difficult to reconcile and maintain.

Single responsibility principle

The single responsibility principle states that every class, module, or function should have one responsibility/purpose. All code — whether it be HTML, CSS, or JavaScript — should follow the single responsibility principle.