experience-accessibility-validate

Web Component Accessibility

Accessibility (a11y) patterns and remediation guidance for web components. Reference any time work involves the visible or interactive surface of a component — generating, modifying, reviewing, or styling HTML, JS, or CSS — to apply WCAG 2.2 standards.

Review Context

Conduct a review specifically focused on enhancing web accessibility, guided by the WCAG (Web Content Accessibility Guidelines).

In order to mark code as a violation, it must have a direct correlation to the WCAG rule cited such that it is a clear violation of the criteria.

Key Review Criteria:

1. Focus Exclusively on Accessibility:

• Evaluate the component solely for accessibility.
• Only consider compliance with the cited WCAG Success Criteria, ignoring violations that can be attributed to other criteria.
• Avoid addressing general code style, patterns, or issues unrelated to accessibility.

1. Ensure Minimum and Sufficient Accessibility:

• Identify accessibility issues that prevent the component from meeting the minimum requirements outlined by WCAG.
• Avoid suggesting enhancements that go beyond the scope of WCAG compliance unless strictly necessary.

1. WAI-ARIA Usage:

• Use WAI-ARIA attributes only when strictly required to achieve accessibility that cannot otherwise be addressed with semantic HTML.
• Avoid unnecessary complexity or potential regressions caused by incorrect or overuse of ARIA attributes.

1. Component Library Usage

• Assume that well-known component libraries (e.g., Salesforce Lightning, Material UI, Chakra UI) are accessible out of the box when correctly implemented. Unless they are used specifically in conflict with WCAG, library-provided components can be ignored for this review, as they are implemented in an accessible way beneath the abstraction.
• Lightning base components (lightning-input, lightning-combobox, lightning-textarea, lightning-icon, and similar components) provide accessible labeling, ARIA, and error handling through dedicated attributes such as label and alternative-text. A label remains programmatic even with variant="label-hidden"; do not require a sibling or wrapper <label> to target the component. Navigation, button-icon, and other self-labeling base components likewise expose supplied label text as their accessible name and treat their internal icon as decorative. Do not report a missing association merely because that implementation is hidden inside the component.
• The same self-labeling logic applies to imported or custom control components in any framework (React/JSX, Angular, Vue, Web Components), not only Lightning. A capitalized or imported component tag (<Input>, <TextField>, <Button>, <Select>, <Checkbox>, <SearchField>, and design-system wrappers from Material UI, Chakra, Radix, or an internal library) is not a bare HTML element — assume it renders its own accessible label, ARIA, and error handling beneath the abstraction (see the component-library grounding rule). When such a component is given a labeling prop — label, aria-label, aria-labelledby, title, or visible child text/children — treat it as already programmatically labeled and do not flag it for a missing <label>, a missing for/id association, or a missing accessible name. Only flag when no labeling prop or text is supplied, or the supplied value is clearly empty or nonsensical. Do not demand a native <label for> for a component whose internal control you cannot see.
• Resolve dynamic id / htmlFor / for expressions before judging a label association. When a <label htmlFor={X}> (or for={X}) and its control's id={X} are bound to the same expression — the same variable, prop, useId() value, or template literal (e.g. both htmlFor and id set to the same interpolation such as ${id}-email) — treat the association as matching, even though the literal string cannot be resolved at review time. A dynamic id/htmlFor pair is a mismatch only when the two expressions are demonstrably different. Do not flag identical dynamic id/htmlFor expressions as unmatched or mismatched labels.