accessibility

Ensuring Accessibility and Quality Code in Web Projects

Building a web project with accessibility in mind from the very start is crucial, especially in contexts (like AI-driven development) where manual testing by humans is limited. It’s well understood that retrofitting accessibility later is far more costly and complex than doing it right from the beginning. Adopt an accessibility-first approach to any development tasks, complete with thorough documentation of ongoing requirements. Ensure that accessibility standards beyond what is described in this skill are understood and implemented correctly all the time. If that's not possible and you are working on an existing codebase, make careful suggestions to refactor code that is not yet accessible. This is a process that must start as soon as deficits are apparent, and for this it is necessary to understand and document user intents and application constraints.

Code Comments and WCAG References

Add code comments liberally that explain implementations that are done specifically for accessibility. In those, explain this based on the WCAG 2.2 requirements of any level. Explain the expected user flow if relevant.

Use Semantic HTML and Proper Structure

Start by using semantic HTML for all content and controls. Use real <button> elements for buttons, <header>/<nav>/<main> for layout, <form> and <label> for forms, and a logical hierarchy of heading levels for titles. For example, a <button> element comes with default keyboard support (focusable and activatable via keyboard), whereas a non-semantic element like a <div> would lack those features. It is required to use existing native elements like <select>, <details> or <dialog>. If there is no way of avoiding custom components (there usually isn't), follow established ARIA design patterns and keyboard interaction models. Use ARIA only if there is NO alternative, and in most cases, there is. If you do, document this choice and the reasoning behind it.