@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-1-3-1-ii-tables.md

@@ -0,0 +1,106 @@
+## SC 1.3.1 - Info and Relationships (Level A)
+
+Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
+
+## SC: 1.3.1 (ii) - Tables Only
+
+Analyze the given files using the following framework:
+
+Review the provided HTML and JS files for accessibility violations per WCAG 2.2 SC 1.3.1 (ii), 'Tables'.
+(Only tables from this rule should be considered). For all tables on the components, ensure that any information conveyed through presentation is programmatically determinable in order to determine if they meet SC 1.3.1 (ii).
+
+For each of these elements, check if any of the following conditions of WCAG 2.2 SC 1.3.1 (ii), 'Tables' are true:
+
+- The objective of this technique is to present tabular information in a way that preserves relationships within the information even when users cannot see the table or the presentation format is changed. Information is considered tabular when logical relationships among text, numbers, images, or other data exist in two dimensions (vertical and horizontal). These relationships are represented in columns and rows, and the columns and rows must be recognizable in order for the logical relationships to be perceived.
+  Check for the presence of tabular information.
+  For each instance of the `<table>` element found, perform the following checks:
+- Verify the presence of table rows (`<tr>`): Ensure that each `<table>` element contains at least one `<tr>` element
+- Verify the presence of table data cells (`<td>`) within rows (`<tr>`): For each `<tr>` element within a `<table>`, confirm that it contains one or more `<td>` elements representing the data cells
+- Verify the presence of table header cells (`<th>`) when applicable: If the table includes headers, ensure that the header information is marked up using `<th>` elements, typically within the first `<tr>` element or within `<thead>` elements
+- Check that all data content within the table is enclosed within `<td>` cell elements and that header content (if present) is within `<th>` elements
+- For every `<table>` element identified, verify that it contains at least the following elements: `<tr>`, `<th>` (if headers are present, otherwise `<td>`), and `<td>`
+- Providing an accessible name for a table is considered a best practice that significantly enhances usability for all users, especially those relying on assistive technologies.The accessible name can be provided in various ways:
+- By either using a `aria-label` or `aria-labelledby` attributes or `<caption>` element in the table. Its a best practice and absence of accessible name is acceptable but not a violation.
+- The objective of this technique is to associate header cells with data cells in simple data tables using the `scope` attribute.
+- The `scope` attribute identifies whether the cell is a header for a row, column, or group of rows or columns
+- Valid `scope` values: `row`, `col`, `rowgroup`, `colgroup`
+
+For simple data tables:
+
+- If headers are in the first row or column:
+  - `th` elements without `scope` are sufficient
+- If headers are not in the first row or column:
+  - Check that all `th` elements have a `scope` attribute
+  - Verify `scope` values match the header's role (`row`/`col`/`rowgroup`/`colgroup`)
+    Note: For complex tables (multiple levels of headers, headers spanning rows/columns), use id and headers attributes instead (see H43)
+- The objective of this technique is to associate each data cell (in a data table) with the appropriate headers.
+  Check for layout tables and data tables:
+- For layout tables:
+  - Determine if content has a relationship with other content in both its column and row
+  - If "no", the table is a layout table
+- For data tables:
+  - Check that any cell associated with multiple row/column headers contains a headers attribute listing all associated header IDs
+  - For cells with id or headers attributes:
+    - Verify each id in headers attribute matches a header element's id
+    - Verify headers attribute contains all associated header IDs
+    - Ensure all IDs are unique within the component
+
+In order to fix a violation for a given element, you must examine the given component code and apply the most logical fix available such that the element satisfies one of the following conditions of WCAG 2.2 SC 1.3.1 (ii), 'Tables':
+
+- The objective of this technique is to present tabular information in a way that preserves relationships within the information even when users cannot see the table or the presentation format is changed. Information is considered tabular when logical relationships among text, numbers, images, or other data exist in two dimensions (vertical and horizontal). These relationships are represented in columns and rows, and the columns and rows must be recognizable in order for the logical relationships to be perceived.
+  Check for the presence of tabular information.
+  For each instance of the `<table>` element found, perform the following checks:
+- Verify the presence of table rows (`<tr>`): Ensure that each `<table>` element contains at least one `<tr>` element
+- Verify the presence of table data cells (`<td>`) within rows (`<tr>`): For each `<tr>` element within a `<table>`, confirm that it contains one or more `<td>` elements representing the data cells
+- Verify the presence of table header cells (`<th>`) when applicable: If the table includes headers, ensure that the header information is marked up using `<th>` elements, typically within the first `<tr>` element or within `<thead>` elements
+- Check that all data content within the table is enclosed within `<td>` cell elements and that header content (if present) is within `<th>` elements
+- For every `<table>` element identified, verify that it contains at least the following elements: `<tr>`, `<th>` (if headers are present, otherwise `<td>`), and `<td>`
+- Providing an accessible name for a table is considered a best practice that significantly enhances usability for all users, especially those relying on assistive technologies.The accessible name can be provided in various ways:
+- By either using a `aria-label` or `aria-labelledby` attributes or `<caption>` element in the table. Its a best practice and absence of accessible name is acceptable but not a violation.
+- The objective of this technique is to associate header cells with data cells in simple data tables using the `scope` attribute.
+- The `scope` attribute identifies whether the cell is a header for a row, column, or group of rows or columns
+- Valid `scope` values: `row`, `col`, `rowgroup`, `colgroup`
+
+For simple data tables:
+
+- If headers are in the first row or column:
+  - `th` elements without `scope` are sufficient
+- If headers are not in the first row or column:
+  - Check that all `th` elements have a `scope` attribute
+  - Verify `scope` values match the header's role (`row`/`col`/`rowgroup`/`colgroup`)
+    Note: For complex tables (multiple levels of headers, headers spanning rows/columns), use id and headers attributes instead (see H43)
+- The objective of this technique is to associate each data cell (in a data table) with the appropriate headers.
+  Check for layout tables and data tables:
+- For layout tables:
+  - Determine if content has a relationship with other content in both its column and row
+  - If "no", the table is a layout table
+- For data tables:
+  - Check that any cell associated with multiple row/column headers contains a headers attribute listing all associated header IDs
+  - For cells with id or headers attributes:
+    - Verify each id in headers attribute matches a header element's id
+    - Verify headers attribute contains all associated header IDs
+    - Ensure all IDs are unique within the component
+
+Note: A complex table is one where:
+
+- Headers span multiple rows or columns
+- Headers are not in the first row or column
+- Multiple levels of headers exist
+- Cells are associated with multiple headers
+- The table structure requires additional context to understand relationships between data
+
+If they do not meet this success criterion, then flag this as a violation.
+
+Rules to follow:
+
+- Find all violations of SC 1.3.1 (ii) 'Tables' in the provided HTML and JS files
+- Do not worry about violations of SC 1.3.1 that are not specific to tables (handled by other reviewers)
+- If no changes are needed, then produce an empty list
+  - For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-1-3-1-iii-form-labels.md

@@ -0,0 +1,78 @@
+## SC 1.3.1 - Info and Relationships (Level A)
+
+Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
+
+## SC: 1.3.1 (iii) - Info and Relationships - Form Labels
+
+Key Requirements:
+
+1. Every form control must have a programmatic label via one of these methods:
+
+- Label must be `<label>` with matching `for`/`id` attributes.
+- `aria-label`/`aria-labelledby` (when visual labels are not feasible)
+- `label` attribute, on `lightning-` prefixed namespace components (when applicable).
+
+2. Label Content:
+
+- Must be descriptive and meaningful
+- No nested interactive elements
+- Not just placeholder or title text
+- Group controls need group and individual labels
+
+3. Common Issues:
+
+- Missing or empty labels
+- Non-matching `for`/`id` attributes
+- Placeholder text as labels
+- Nested interactive elements in labels
+
+4. Improper Label Content: Nested Interactive Elements:
+
+- Examine the content of all label elements.
+- Ensure no `<label>` contains interactive HTML elements as direct children or descendants. This includes:
+  - `<a>`, `<button>`, `<summary>` or any custom elements with interactive roles.
+
+Following are some sufficient techniques that a user can use to meet this success criterion:
+
+Form controls must have programmatically associated labels that clearly identify their purpose.
+
+Required Label Associations:
+
+1. Standard HTML Elements:
+   - All input types (`text`, `date`, `email`, `number`, `password`, `search`, `checkbox`, etc.)
+   - `select`, `textarea` elements
+
+Some cases where the `label` HTML element is ignored:
+
+- `button` element when the label is provided by the content
+- `input type="button"` when the label is provided by the content
+- `input type="hidden"`
+- `input type="image"` when the label is provided by the `alt` attribute
+- `input type="reset"` when the label is provided by the `value` attribute
+- `input type="submit"` when the label is provided by the `value` attribute
+- `input type="search"` when there is a `button` element with label next to search `input`
+
+Exceptions (No Label Required):
+
+- Buttons with descriptive content
+- Hidden inputs
+- Image inputs with alt text
+- Submit/reset with value text
+
+If they do not meet this success criterion, then flag this as a violation.
+
+Rules to follow:
+
+- Find all violations of SC 1.3.1 (iii) 'Form Labels' in the provided HTML and JS files
+- Report only form label violations
+- Provide specific control and issue details
+- Keep reports concise and non-redundant
+
+- For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-1-3-1-iv-regions.md

@@ -0,0 +1,26 @@
+## SC 1.3.1 - Info and Relationships (Level A)
+
+Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
+
+## SC: 1.3.1 (iv) - Info And Relationships - Regions (A)
+
+Review the provided HTML and JS files for accessibility violations per WCAG 2.2 SC 1.3.1 (iv), 'Info and Relationships'
+(Only regions from this rule should be considered). For all regions on the page, ensure that any information conveyed through presentation is programmatically determinable in order to determine if they meet SC 1.3.1 (iv).
+If they do not meet this success criterion, flag it as a violation.
+
+Rules to follow:
+
+- Find all violations of SC 1.3.1 'Info and Relationships - Regions' in the provided HTML and JS files.
+- Do not worry about violations of SC 1.3.1 that are not specific to regions. These will be handled by other reviewers.
+- Use semantic HTML elements (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`, `<section>`) to mark up regions. There cannot be more than one `<main>` element that does not have a hidden attribute specified.
+- When semantic elements cannot be used, use ARIA landmark roles (`role="banner"`, `role="navigation"`, `role="main"`, `role="complementary"`, `role="contentinfo"`, `role="region"`).
+- Each region should have a descriptive label or heading that identifies its purpose.
+- Regions should be properly nested and not overlap.
+  - For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-1-3-1-v-groups.md

@@ -0,0 +1,66 @@
+## SC 1.3.1 - Info and Relationships (Level A)
+
+Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
+
+## SC: 1.3.1 (v) - Info And Relationships - Groups only
+
+Analyze the files using following context:
+
+_Goal_: Information, structure and relationships conveyed through presentation can be programmatically determined or available in text.
+
+_What to do_: Review the provided HTML and JS files for accessibility violations per WCAG 2.2 SC 1.3.1, 'Info and Relationships' with focus on groups requirements only.
+
+Having structures and relationships programmatically determinable ensures that important information necessary for comprehension will be perceivable to all users. Grouping controls is most important for related radio buttons and checkboxes.
+
+Examples:
+
+- Form fields may be positioned as groups that share text labels.
+- A multiple choice test with a question and set of radio buttons to present possible answers; the radio buttons are contained within a `fieldset` while the question is tagged with `legend` element.
+- A user profile page allows users to indicate personal interests using checkboxes; the checkboxes are contained within a `fieldset`, and the `legend` element prompts the user to select one or more interests.
+
+Following are some sufficient techniques that WCAG working group deems sufficient to meet this success criterion:
+
+- ARIA17: Using grouping roles to identify related form controls within a form. Any label associated with group also serves as a common label for individual controls in this group.
+  This is a viable alternative to using `fieldset` / `legend` technique (H71). For a group of radio buttons, `role="radiogroup"` should be used instead of `role="group"` and is not meant to be used for wrapping all controls on a form within a single container with `role="group"`.
+
+- For groups of related controls where individual labels for each control do not provide sufficient description, and additional group level description is needed
+  - Check that group of logically related input or select elements are contained within an element with `role="group"`, or `role="radiogroup"` depending on the type of elements in group.
+  - Check that this group has an accessible name describing it's purpose using `aria-label` or `aria-labelledby` attribute.
+  - The objective of this technique is to allow users to understand the relationship of form controls by providing semantic grouping and interact quickly.
+    Form controls can be grouped by enclosing them within `fieldset` element. All controls within a given `fieldset` are then related. The first element inside `fieldset` must be a `legend` element. Avoid nesting fieldsets unnecessarily, as this can lead to confusion.
+    A set of radio buttons or checkboxes are said to be related when they all submit values to single named field.
+  - They work same as selection lists that allow users to choose from set of options, except selection lists are single controls while radio buttons and checkboxes are multiple controls.
+  - The individual label associated with each radio button or checkbox control may not fully convey group's descriptive context.
+    It can also be helpful to group other sets of controls less tightly related than radio buttons and checkboxes, like form fields that collect user address might be grouped together with `legend` of "Address".
+    Authors sometimes avoid using `fieldset` element because the default display style draws a border around the grouped controls. However, this style can be modified with CSS by overriding 'border' property of `fieldset` and 'position' property of `legend`.
+
+For groups of related controls where individual labels for each control do not provide sufficient context description, and additional group level description is needed; ensure following are true:
+
+- Check that the group of logically related elements, like either `input` or `select` elements are contained within `fieldset` elements.
+- Check that each `fieldset` has a `legend` element that is first child and includes a description for the group.
+- The objective of this technique is to group items in a selection list.
+  A selection list is a set of allowed values for a form control such as multi-select list or combo box. In semantic HTML, the `select` element is used to create both multi-select lists and combo boxes, where various allowed options are each indicated with `option` elements, grouped together using `optgroup` element, and labeled the group with `label`.
+
+For each selection list:
+
+- Check the set of options within the list to see if there are groups of related options.
+- If there are groups of related options, check that they are properly grouped (like using `optgroup` element)
+
+  - The objective of this technique is to group navigation links using HTML `nav` element or similar semantic sectioning elements. Using this markup can make groups of links easier to locate and navigate.
+    When such element is employed more than once on a page, distinguish navigation groups by using `aria-label` or `aria-labelledby` attribute.
+    Not all groups of links need to use `nav` element for markup. For example, links maybe grouped in other structures like lists or may use ARIA markup if do not present a discrete section of the page.
+
+- Check that links that are grouped and represent a section of page, are enclosed in a `nav` element or similar semantics.
+
+_Rules to follow_:
+
+- Require code to reinforce structure, relationships and information conveyed through presentation for groups of related elements, per this WCAG 2.2 SC 1.3.1 'Info and Relationships - Groups only' success criterion, in the provided HTML and JS files.
+- Do not worry about violations of SC 1.3.1 that are not specific to groups. These will be handled by other reviewers.
+  - For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-1-3-5-identify-input.md

@@ -0,0 +1,70 @@
+## SC 1.3.5 - Identify Input Purpose (Level AA)
+
+The purpose of each input field collecting information about the user can be programmatically determined when the input field serves a purpose identified in the Input Purposes for User Interface Components section, and the content is implemented using technologies with support for identifying the expected meaning for form input data.
+
+## SC: 1.3.5 - Identify Input Purpose Only
+
+Analyze the given file using the following framework:
+
+Review the provided HTML and JS files for accessibility violations per WCAG 2.2 SC 1.3.5, 'Identify Input Purpose'.
+
+Specific guidance on `autocomplete` for certain input fields:
+
+- **Non-personal information fields** (e.g., search, quantity selectors): These fields should EITHER have no `autocomplete` attribute OR use `autocomplete="off"`. Using any other specific `autocomplete` token on these fields is a violation.
+- **Security-sensitive fields** (e.g., security questions): These fields MUST use `autocomplete="off"`. If the `autocomplete` attribute is missing or has any other value, it is a violation.
+- **Fields for non-primary users** (e.g., spouse\'s name, emergency contact information such as emergency contact name, emergency contact phone etc):
+  - The ABSENCE of an `autocomplete` attribute on these fields is PERMISSIBLE and IS NOT a violation.
+  - IMPORTANT Instruction: DO NOT suggest adding an `autocomplete` attribute (such as `autocomplete="off"` or any other token) if it is missing for these fields simply because they pertain to a non-primary user.
+  - A violation should only be flagged for these fields if an `autocomplete` attribute is EXPLICITLY PRESENT AND uses an incorrect token (i.e., a token not from the H98Procedure list that doesn\'t match the input\'s apparent purpose, and is not `off`).
+
+Common violations to check:
+
+- Missing `autocomplete` attributes on personal information fields
+- Using generic "on/off" instead of specific tokens
+- Using invalid or non-standard `autocomplete` tokens. `Autocomplete` tokens must exactly match the standardized values listed in the H98Procedure (e.g., `given-name`, `email`, `tel`). Combinations of tokens (e.g., "email home") or more specific, non-standard variations (e.g., "tel mobile" instead of `tel`) are incorrect.
+- Using incorrect capitalization in `autocomplete` values
+- Using invalid formats (like "email, home")
+- Missing `autocomplete` on dynamic/conditional fields
+
+Following are some sufficient techniques that a user can use to meet this success criterion:
+
+- The objective of this technique is to programmatically link a pre-defined and published taxonomic term to the input, so that the inputs can also be machine-interpreted.
+  The technique works by adding the appropriate `autocomplete` token to each form field on the form to make the identified inputs programmatically determinable. This will help people with cognitive disabilities who may not immediately know the purpose of the field because the label used by the author is not familiar to them. When inputs have been programmatically assigned, third party plugins and software can manipulate these form fields to make them more accessible to people with cognitive disabilities.
+
+For each form field that collects information about the primary user and corresponds to an autocomplete field, check the following:
+
+- The form field has a valid and well-formed `autocomplete` attribute and value pair
+- The purpose of the form field indicated by the label corresponds with the `autocomplete` token on the input
+- The `autocomplete` token matches the standardized values:
+  - For name: `name`
+  - For first-name: `given-name`
+  - For last-name: `family-name`
+  - For email: `email`
+  - For phone number: `tel`, `tel-national`
+  - For birthdays: `bday`
+  - For addresses: `street-address`(for the full street address, potentially across multiple lines), `address-line1`(for the first line of the address, example "123, main st"), `address-level2`(for the city), `country`
+  - For credentials: `username`(for username), `current-password`(for the password ), `new-password` (for signing up)
+- Non-personal information fields such as search, quantity selectors should omit `autocomplete` or use `off`
+- Security-sensitive fields such as security questions should use `autocomplete="off"`
+
+For each form field that collects information about the other users, check the following:
+
+- Please disregard the absence of an `autocomplete` attribute for fields that collect information about individuals other than the primary user such as spouse's name, emergency contact name, emergency contact phone no etc. and do not flag this as a violation.
+
+If they do not meet this success criterion, then flag this as a violation.
+
+Rules to follow:
+
+- Find all violations of SC 1.3.5 'Identify Input Purpose' in the provided HTML and JS files
+- Focus on form inputs that collect user information
+- If no changes or action are needed, then produce an empty list.
+- Critically evaluate each field against the specific guidance above. Do not conclude 'no action is needed' or 'correctly implemented' if no violations found.
+
+- For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-1-4-3-contrast.md

@@ -0,0 +1,115 @@
+## SC 1.4.3 - Contrast (Minimum) (Level AA)
+
+The visual presentation of text and images of text has a contrast ratio of at least 4.5:1, except for large text (at least 3:1), incidental text (part of inactive components, purely decorative, not visible, or part of a picture containing significant other visual content), and logotypes.
+
+## SC: 1.4.3 - Contrast (Minimum) (Level AA)
+
+This reviewer focuses on ensuring enough contrast between text and its background so that it can be read by people with moderately low vision (who do not use contrast-enhancing assistive technology) as well as those with color deficiencies.
+
+### Analysis Framework (What to do):
+
+1.  Identify all visible text elements (e.g., in tags like `<h1>`, `<div>`, `<p>`, `<label>`, `<button>`, etc.).
+2.  Determine the **color** (foreground) and **background color** (background) for each text element.
+3.  Determine the **font size** and **weight** to classify the text as Standard or Large-Scale.
+4.  Compute the contrast ratio with the bundled helper — **do not calculate luminance by hand**:
+
+    ```bash
+    python3 scripts/contrast-ratio.py FOREGROUND BACKGROUND [--large]
+    ```
+
+    Pass the resolved foreground and background colors (`#RGB`, `#RRGGBB`, `rgb()`, or `rgba()`); add `--large` when the text is large-scale (≥24px, or ≥18.66px bold). The script alpha-composites a translucent *foreground* over the background, applies the exact WCAG formula $(L1 + 0.05) / (L2 + 0.05)$, and prints the ratio plus a `PASS`/`FAIL` verdict for both thresholds (exit code `0` = meets the applicable threshold, `1` = below it, `2` = parse error). The **background must be opaque** — a translucent `rgba()` background is rejected (exit code `2`) because its rendered color depends on the unknown layer beneath it; resolve the effective opaque background first and pass that. Use `--json` for a machine-readable object. The script's verdict is authoritative; use it rather than an estimate.
+5.  Treat the script's verdict against the required threshold (4.5:1 standard, 3:1 large) as the check result.
+
+> **Do not estimate luminance by hand.** Mentally approximating relative luminance is unreliable — it has produced false positives and even different ratios for the _same_ color. Run `scripts/contrast-ratio.py` for the exact value. The verified reference below (sRGB gray `#NNNNNN` on `#FFFFFF`) is a quick sanity check for the common grayscale-text-on-white case, not a substitute for the script:
+>
+> | Gray      | Ratio | Standard (4.5:1) | Large (3:1)     |
+> | --------- | ----- | ---------------- | --------------- |
+> | `#595959` | 7.00  | pass             | pass            |
+> | `#666666` | 5.74  | pass             | pass            |
+> | `#767676` | 4.54  | pass (boundary)  | pass            |
+> | `#777777` | 4.48  | **fail**         | pass            |
+> | `#808080` | 3.95  | fail             | pass            |
+> | `#959595` | 3.00  | fail             | pass (boundary) |
+> | `#999999` | 2.85  | fail             | **fail**        |
+> | `#AAAAAA` | 2.32  | fail             | fail            |
+> | `#BBBBBB` | 1.92  | fail             | fail            |
+>
+> Rule of thumb for grayscale on white: `#767676` is the standard-text boundary — anything **darker** (lower hex value) passes 4.5:1; `#959595` is the large-text boundary for 3:1. In particular, **`#666666` and darker pass standard-text contrast — do not flag them.** For non-grayscale colors, non-white backgrounds, gradients, or alpha compositing, compute the exact ratio; if you cannot, do not guess — only flag when you are confident the ratio is below threshold.
+
+### Goals for Contrast Compliance:
+
+1.  **Standard Text (Ratio 4.5:1):**
+    - **Good:** Black text on a white background (Ratio 21:1).
+    - **Bad:** Light gray text on a white background (e.g., #AAAAAA on #FFFFFF, Ratio 2.32:1).
+2.  **Large-Scale Text (Ratio 3:1):**
+    - **Good:** Medium gray text on a white background (e.g., #808080 on #FFFFFF, Ratio 3.95:1 — passes large-text 3:1 but fails standard-text 4.5:1).
+    - **Bad:** Light gray text on a white background (e.g., #BBBBBB on #FFFFFF, Ratio 1.92:1).
+3.  **Focus/Hover States:** While the primary check is for the default state, flag any explicit color changes defined in CSS that might reduce contrast below the minimum thresholds during focus or hover states. _(Note: Full dynamic state checking is complex, but hard-coded poor contrast colors must be flagged.)_
+
+### What to Look For:
+
+- Text elements where the foreground color is too similar to the background color.
+- Hard-coded color combinations in CSS or inline styles that fail the 4.5:1 or 3:1 ratio.
+- Text sizes that are small (Standard Text) but have a contrast ratio less than 4.5:1.
+- Text sizes that are large-scale but have a contrast ratio less than 3:1.
+- Usage of transparency/opacity that negatively impacts the calculated contrast ratio.
+
+### Common Violations for Contrast:
+
+- **Placeholder Text:** Placeholder text should have enough contrast.
+- **Secondary/Hint Text:** Secondary text (e.g., helper text or captions) styled with low-contrast gray colors.
+- **Disabled/Inactive Elements:** Though exempt under strict rules, _functional_ elements styled to look inactive when they are not.
+- **Text on Complex Backgrounds:** Text placed over gradient or patterned backgrounds where the minimum contrast requirement is not met across the entire text area.
+
+### To fix the Contrast Violations, Use the following techniques:
+
+• **Foreground Color (Text) Fix:**
+
+- **Action:** Locate the style rule (inline style, CSS file, or JS variable) defining the text color.
+- **Correction:** If the current color is a light color (e.g., #AAAAAA), change it to a darker, compliant color (e.g., #595959).
+- **Priority:** Prioritize using standard, dark text colors (e.g., #333333 or #000000) for accessibility whenever possible.
+
+• **Background Color Fix:**
+
+- **Action:** Locate the style rule defining the element's background-color.
+- **Correction:** If the current background-color is a dark color (e.g., #333333), change it to a lighter, compliant color (e.g., #CCCCCC).
+- **Priority:** Prioritize using standard, light background colors (e.g., #FFFFFF or #F5F5F5).
+
+• **Inline Style Correction Example:**
+
+- **Violation:** `<div style="color: #AAAAAA; background-color: #FFFFFF;">Low Contrast Text</div>`
+- **Fix:** `<div style="color: #444444; background-color: #FFFFFF;">Compliant Contrast Text</div>`
+
+• **Placeholder/Secondary Text Fix:**
+
+- **Action:** For elements like `<input placeholder="text">` or secondary helper text, find the dedicated style (often `:placeholder` or a class for secondary text).
+- **Correction:** Ensure the foreground color of the placeholder/secondary text is adjusted to meet at least the 4.5:1 ratio against the background of the input/container.
+
+• **Remediation Strategy:**
+
+- **Goal:** Modify the least number of color declarations (either `color` or `background-color`) necessary to achieve the target ratio (4.5:1 for standard text, 3:1 for large text).
+- **Method:** If foreground text is light, darken it. If foreground text is dark, lighten the background.
+- **Context:** Only modify color values (#RRGGBB, rgb(), hsl()) found in inline styles or referenced CSS blocks identified by the analysis.
+
+## Exemptions (DO NOT FLAG):
+
+1.  **Decorative:** Text used purely for decorative purposes, where its specific lettering is not essential to understanding the content (e.g., text used as a stylized border).
+2.  **Logotypes:** Text that is part of a logo or brand name.
+3.  **Inactive UI Components:** Text in components that are disabled (e.g., a grayed-out button).
+
+Rules to follow:
+
+- Focus specifically on **visible text** in HTML and JS files.
+- Only flag when the computed ratio falls below 4.5:1 for standard text or 3:1 for large-scale text
+- Flag color combinations that result in a contrast ratio **below 4.5:1 for Standard Text**.
+- Flag color combinations that result in a contrast ratio **below 3:1 for Large-Scale Text**.
+- **Ignore** text clearly marked as decorative, part of a logo, or permanently disabled/inactive components.
+- Do not assume or estimate the contrast ratio — compute it with `scripts/contrast-ratio.py` (which also handles alpha compositing), falling back to the grayscale-on-white reference table above only as a sanity check. When the resolved colors themselves are uncertain (gradients, images behind text, unknown background), do not flag.
+  - For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-2-1-1-keyboard.md

@@ -0,0 +1,47 @@
+## SC 2.1.1 - Keyboard (Level A)
+
+All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints.
+
+## SC: 2.1.1 - Keyboard
+
+Analyze the given file using the following framework:
+
+Review the provided HTML and JS files for accessibility violations per WCAG 2.2 SC 2.1.1, 'Keyboard'. For all elements on the page, ensure that the element exposes all interactivity that is achievable via mouse to keyboard in order to determine if they comply with SC 2.1.1. If they don't comply with the success criterion, then flag them a violation.
+
+Interactive controls must be accessible when using the keyboard alone, and when using a keyboard along with assistive technology, such as a screen reader, without requiring specific timings for keystrokes. The exception to this is when the underlying functionality requires path-based movement.
+
+Common modes of failure for this rule are:
+
+- Custom input implementations don't have an equivalent keyboard functionality. For example, an element with click or pointer handlers, but no equivalent functionality for keypress.
+- Elements that can't be navigated to via the keyboard but can be interacted with via the mouse. For example, an interactive element that's missing a `tabindex`, either because it doesn't have one by default or it hasn't been explicitly assigned.
+- Tooltips that are only accessible through mouse hover. For example, an element that displays a tooltip on mouse hover, however, there is no way to access the tooltip via keyboard. The tooltip should be accessible via hover, keyboard and click.
+- Anchor (`<a>`) elements that are used as interactive controls (e.g., with `onclick` or have an `onclick` attribute) and don't have an `href` attribute aren't focusable or operable via keyboard. This is a violation. Use a `button` element or ensure that the anchor has an `href` and is accessible via the keyboard.
+- **Incorrect Tab Indices**: When a parent element has `tabindex="0"` but its child interactive element has `tabindex="-1"`, this creates a keyboard trap. The parent becomes focusable but the child button/link cannot be activated via keyboard. Always flag this pattern as "Incorrect Tab Indices".
+- **Tabindex out of sequence**: When `tabindex` values are greater than 0, they disrupt the natural keyboard navigation order. Flag any `tabindex` with positive values (1, 2, 10, etc.) as violations that need to be removed.
+- **DIV elements with event handlers**: Non-semantic elements (`div`, `span`) with click handlers must have `tabindex="0"` to be keyboard accessible. Without `tabindex`, they cannot receive focus.
+
+Given the common modes of failure, consider:
+
+- Is the control using semantic HTML? If the semantic HTML default behaviors aren't overridden and new mouse functions aren't added, it will work with a keyboard. Don't flag this as a violation.
+- Is the control focusable? If the control is focusable, it can properly handle a keyboard event. Don't flag this as a violation.
+- Does anything override the focus event? If native focus is allowed, then nothing will override the focus event and elements should receive and handle focus events correctly. If the focus is altered, elements might not receive or handle focus events correctly.
+
+**SPECIFIC TABINDEX PATTERNS TO IDENTIFY:**
+
+1. **Parent-Child Tabindex Conflicts**: Scan for `<li tabindex="0">` containing `<button tabindex="-1">` or similar patterns where parent is focusable but child interactive element is not.
+2. **High Tabindex Values**: Look for any `tabindex="X"` where X > 0 (like `tabindex="10"`, `tabindex="5"`). These disrupt natural tab order.
+3. **Semantic Elements with Unnecessary Tabindex**: Buttons, links, and form controls don't need explicit `tabindex` values.
+
+Rules to follow:
+
+- Find all violations of SC 2.1.1 'Keyboard' in the provided HTML and JS files.
+- DO NOT flag issues when native HTML elements provide sufficient keyboard accessibility.
+
+- For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-2-4-4-link-purpose.md

@@ -0,0 +1,39 @@
+## SC 2.4.4 - Link Purpose (In Context) (Level A)
+
+The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general.
+
+## SC: 2.4.4 - Link Purpose (In Context)
+
+Analyze the given file using the following framework:
+
+Review the provided HTML file for accessibility violations per WCAG 2.2 SC 2.4.4, 'Link Purpose (In Context)'. For all anchor elements (`<a>`) and other interactive elements that function as links, ensure that the link text is descriptive enough to convey the purpose of the link, either on its own or with its immediate context (such as the same sentence, list item, or table cell). If the link purpose cannot be determined, flag this as a violation.
+
+Common modes of failure for this rule are:
+
+- Using vague link text such as 'click here', 'read more', or 'more' without sufficient context. (Type: "Vague Link Text")
+- Relying on context that is not programmatically associated with the link (e.g., context that is visually near but not in the same sentence, list item, or table cell).
+- Using only an icon or image as a link without accessible text or an appropriate accessible name, such as an `aria-label`. (Type: "Non-descriptive Icon Link")
+- Multiple links using the same non-descriptive text (e.g., "Read more") but pointing to different destinations. (Type: "Duplicate Link Text")
+
+For each violation, provide:
+
+- The exact type as listed above.
+- A detailed description of why it is a problem, referencing accessibility best practices.
+- An intent analysis explaining what the developer likely intended.
+- A suggested action, with precise recommendations (e.g., for icon links, recommend adding an `aria-label`, not just alt text).
+- For duplicate link text, identify and report all instances, not just the first.
+
+Rules to follow:
+
+- Find all violations of SC 2.4.4 'Link Purpose (In Context)' in the provided HTML file.
+- If no changes are needed, then produce an empty list.
+- Use the exact terminology for issue types as listed above.
+
+- For each issue found, provide a separate, detailed report.
+- Keep issues concise, avoid duplicated issues or unnecessary or non-applicable problems.
+- Assume that any imported functionality works as expected and was already analyzed.
+- Components do not supplement or provide global functionalities.
+- Lightning base components (`lightning-input`, `lightning-combobox`, `lightning-textarea`, `lightning-icon`, etc.) provide their own accessible labeling, ARIA, and error handling in shadow DOM via their dedicated attributes (`label`, `alternative-text`, field-level validation). When such a component is given a `label` attribute it is already programmatically labeled — even with `variant="label-hidden"`, which hides the label visually but keeps it for assistive technology. Do **not** flag a sibling/wrapper `<label>` or `<span>` for a missing `for`/`id` when the actual control is a self-labeling Lightning component, and do not treat a visible heading as if it were the control's only label. This also covers navigation and icon base components (`lightning-vertical-navigation-item`, `lightning-vertical-navigation-item-icon`, `lightning-button-icon`, etc.): when a `label` (or `alternative-text`) attribute is supplied, the base component renders it as the visible link/control text **and** exposes it as the accessible name, and any `icon-name` is decorative — do not emit a 4.1.2 "verify the label is associated with the icon" warning, even a hedged one. The presence of the `label` attribute is the association.
+- Resolve template bindings before judging them. A template expression like `{someValue}` refers to a property or getter on the component's controller (`.js`/`.ts`) — including `@api` properties and `get someValue()` getters — not to a module-level imported constant (which LWC templates cannot bind to). Check the controller for the binding's definition before concluding a value is undefined, empty, or missing. When reviewing a diff, verify which side is the corrected code; do not assume the change introduced the problem.
+- Prefer a real `<button>` for actions; for a link, `href="#"` with `event.preventDefault()` (the canonical SLDS pattern). Don't recommend `href="javascript:void(0)"` as a first-line remediation — it's a no-op-anchor anti-pattern. It is acceptable only as a last resort when moving `<a>` → `<button>` is genuinely impossible, and even then only when paired with the full set of attributes that make the anchor behave as an accessible button (`role="button"`, keyboard activation, etc.) — `void(0)` on its own is an incomplete fix. Don't flag existing `javascript:void(0)` as a violation.
+- ARIA attribute spelling depends on the element type. On a **plain HTML element** (`div`, `span`, `button`, `input`, `a`, `img`, `iframe`, …) the only valid spelling is the W3C form `aria-labelledby` / `aria-describedby`; the hyphen-split `aria-labelled-by` / `aria-described-by` there **is** a real bug — keep flagging it. But on an **LWC component tag** (`lightning-*` or a custom `ns-name` element), the hyphen-split form is the kebab-case binding of the component's `@api ariaLabelledBy` / `ariaDescribedBy` property (each capital letter maps to `-` + lowercase), and LWC reflects it to the spec-correct `aria-labelledby` in the rendered DOM. Do **not** flag `aria-labelled-by` on a component tag as a misspelling, and do not claim it "breaks the accessible name computation" — you cannot determine that from the attribute name alone, because both `aria-labelled-by` (via `@api` property kebab-casing) and `aria-labelledby` (via LWC's ARIA reflection) can wire to the same property depending on the component. Treat a hyphen-split ARIA attribute on a component tag as a valid binding, not a violation.