@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-3-3-3-error-suggestion.md

@@ -0,0 +1,64 @@
+## SC 3.3.3 - Error Suggestion (Level AA)
+
+If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user, unless it would jeopardize the security or purpose of the content.
+
+## SC: 3.3.3 - Error Suggestion
+
+**What is a Sufficient Error Suggestion?**
+
+A suggestion is sufficient if it clearly states the correction needed. You should not flag messages that are already clear just to make them more verbose. The goal is to ensure a corrective suggestion exists, not to rewrite it.
+
+- **Sufficient Suggestion Examples (DO NOT FLAG these as violations):**
+
+  - For an input field that requires only numbers, use a clear and direct error message. For example, "Please enter numbers only."
+  - For a password confirmation that doesn't match, use a clear and direct error message: For example, "Passwords do not match."
+
+- **Insufficient Suggestion Examples (These SHOULD BE FLAGGED):**
+  - "Invalid input."
+  - "Access Denied."
+  - "Error."
+  - "Please fix this field."
+
+For each form field that can produce an input error, check the following:
+
+- The form field provides a clear error message that indicates what went wrong and how it can be fixed, when an input error is detected.
+- The error message includes a suggestion for correcting the error. Some examples include, requiring a specific format, requesting acceptable values, or defining a valid range of values.
+- If the input requires a specific format (for example, a date or email format), the error message suggests that the user input their information using that format. The error message suggestion can be present either in input error messages or validation error messages.
+- If the input requires a value from a limited set of values (for example, a drop-down menu) the error message suggests selecting from the available options.
+- If the user must validate that they're above a certain age (for example, 18 years or older), the error message must explicitly state that requirement in the error message (for example, "You must be 18 or older to proceed.").
+- If the input field has an error message, it must be programmatically associated with the field.
+- If error messages are displayed at the top of a component without a clear and direct association to the fields that require a correction, then flag this as an accessibility improvement/violation against WCAG 3.3.1. Also, recommend moving the error messages to a location that directly associates the error to the input field that needs to be corrected.
+
+Common violations to check:
+
+- Missing error messages for input fields that can produce errors.
+- Error messages that do not include suggestions for correction.
+- Error messages that are unclear or do not guide the user on how to correct the error.
+- Error messages that are not visually adjacent (exclude toast messages) to the input field(for example, error message at the top of the form), forcing users to scan the page to locate the field that needs correction.
+- Error messages which includes suggestions but are not conveyed to assistive technology. For example, the error suggestion messages and the field are not programmatically associated using `aria-describedby`.
+
+Special Rules:
+
+- Error suggestions should be persistent enough for all users to perceive and understand without arbitrary time limits. The error message must not disappear after certain time limit and should be visible at all times.
+- Toast notifications are designed to be accessible and the toast events are designed to follow accessibility guidelines.
+
+**ABSOLUTE AND STRICT EXCLUSION RULES FOR SC 3.3.3 'Error Suggestion':**
+
+- \*\*DO NOT flag that the field "cannot be empty" or that it needs a value for optional fields(not marked as required). The absence of a value is valid for an optional field.
+- **DO NOT flag for using `aria-describedby` that references conditionally rendered error messages is valid and common. When the referenced element is not in the DOM, browsers and screen readers handle this gracefully.
+  **DO NOT flag for components in the lightning namespace (prefixed with `lightning-`) if there is no form field validation or eror handling or programmatic association. They have built-in, accessible error handling and field validation that complies with WCAG standards.
+
+Rules to follow:
+
+- Find all violations of SC 3.3.3 'Error Suggestion' in the provided HTML and JS files (exclude CSS).
+- Focus on form inputs that can produce input errors.
+- If no changes or action are needed, then produce an empty list. Do not conclude 'no action is needed' or 'correctly implemented' if no violations found.
+- 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-4-1-2-i-name.md

@@ -0,0 +1,105 @@
+## SC 4.1.2 - Name, Role, Value (Level A)
+
+For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.
+
+## SC: 4.1.2 (i) - Name Only
+
+Analyze the files using following context:
+
+_Goal_ : People, including users using assistive technology understand the intent of all user interface components
+
+_What to do_ : Review provided HTML and JS code for accessibility violations per WCAG 4.1.2 (i) Name to ensure components have an accessible name. Ignore the Roles, States and Values parts of the Success Criterion for this review
+
+Name could be visible or invisible. Sometimes, name are required to be visible, in which case it is identified using attributes such as `label` or `aria-label`.
+
+Following are some preferred sufficient techniques that can help satisfy name-only success criterion:
+
+- ARIA14: Using `aria-label` attribute to provide an invisible label where a visible label cannot be used. For sighted users, the context and visual appearance can provide sufficient cues to determine the purpose and presence of control element on component. In other situations, elements are given `aria-label` to provide an accessible names when native labeling element is not supported by control. For elements that use `aria-label`, check that the value of attribute property properly describes the purpose of elements where user input is required
+
+- Note that `aria-label` may be disregarded in some situations where `aria-labelledby` is used for same object and for overriding native name, including `alt` and/or other attributes related authoring techniques
+  - ARIA16: Using `aria-labelledby` attribute to provide a name for user interface controls. For each user interface control element where an `aria-labelledby` attribute is present, check that the value of the `aria-labelledby` attribute is an id of an element or a space separated list of ids referenced on the web page. Also check that the text of the referenced element or elements accurately labels the user interface control
+- Like `aria-describedby`, `aria-labelledby` can accept multiple reference ids using a space seperated list, such as `label` and other elements, to allow for additional detail by concatenating multiple sources of information. This is useful in situations where sighted users use information from the surrounding context to identify a control. Also, a `label` element will always be exposed by accessibility API, while a `span` could have been used, it would lose the advantage of the larger clickable region
+- While `aria-labelledby` appears similar to native HTML `label` element, there are some differences:
+  - `aria-labelledby` can reference more than one text element while `label` element can only reference one
+  - `aria-labelledby` can be used for variety of elements while `label` element can only ever be used on form elements
+  - Clicking on a `label` element focussed the associated form field. Same is not true with `aria-labelledby` use. If focus behavior is required, use `label` or implement this using JS scripting
+  - G108: Use markup to expose name, or related user-settable properties to be set. Check for proper markup, such that the name for each user interface component can be determined and that user interface components that accept user input can all be operated from Assistive Technology
+- H91: For each instance of links and form elements, check that the name, value, and state are specified. In some instances, the text is associated with the control through a required HTML attribute. Like, Submit buttons using the button element text or image `alt` attribute as the name. In case of form control, label elements; `aria-label` or `aria-labelledby` properties; or the `title` attribute is used
+- H44: Use `label` elements to associate text labels with form controls. The objective is to use the label element to explicitly associate a form control with a label. A label is attached to a specific form control through the use of the `for` attribute. The value of the `for` attribute must be the same as the value of the `id` attribute of the form control. The `id` attribute may have the same value as the `name` attribute, but both must be provided, and the `id` must be unique in the same DOM tree
+  - Elements that use explicitly associated labels are as follows:
+    - input type(s) for text
+      - `input type="date"`
+      - `input type="datetime-local"`
+      - `input type="email"`
+      - `input type="month"`
+      - `input type="number"`
+      - `input type="password"`
+      - `input type="search"`
+      - `input type="tel"`
+      - `input type="text"`
+      - `input type="time"`
+      - `input type="url"`
+      - `input type="week"`
+    - `input type="checkbox"`
+    - `input type="color"`
+    - `input type="file"`
+    - `input type="radio"`
+    - `input type="range"`
+    - `select`
+    - `textarea`
+  - Some cases where the `label` HTML element is ignored:
+    - a `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 label provided by the `value` attribute
+    - `input type="submit"` when the label is label provided by the `value` attribute
+  - For all input elements of type `text`, `file` or `password`, for all `textarea` elements, and for all `select` elements in the Web page
+    - Check that there is a `label` element that identifies the purpose of control before `input`, `textarea` or `select` element
+    - Check that `for` attribute of `label` element matches `id` of `input`, `textarea` or `select` element
+    - Check that the `label` element is visible
+  - And, for all input elements of type `checkbox` or `radio` in Web page:
+    - Check for the presence of a `label` element that identifies the purpose of the control after the input element
+    - Check that the `for` attribute of the `label` element matches the `id` of the `input` element
+    - Check that `label` element is visible
+- H64: Check that each `iframe` element in HTML source code for the presence of a `title` attribute. Also, that the `title` attribute contains text that describes the `iframe`'s content. Note that `title` attribute is not interchangeable with the `name` attribute. The `name` is not presented to the user, only the `title` is
+- H65: For all form controls that are not associated with `label` element, check that the control has a `title` attribute, and that the purpose of form control is clear to users who can see the control and that `title` attribute identifies purpose and that it matches apparent visual purpose
+- H88: For each HTML page, check that the page uses only elements, attributes that are defined in the specification, used in manner prescribed by specification and that the page can be parsed correctly, according to rules of specification - G135: Using accessibility API features to expose name, to allow user-settable name to be directly set, and to provide notification of changes by rendering content. Additionally, check that the name for each user interface component can be found - G10: Changes to the name on the component, check that the accessibility tool is alerted of change and that the component continues to work with assistive technologies
+  _Rules to follow_ :
+
+* Require programmatically determinable name for all user interface components.
+* For each component that violates #1, compile a concise list of issues for user to review, along with an action report on sufficient technique that can help resolve violation for component under review.
+  - 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.
+
+**ABSOLUTE AND STRICT EXCLUSION RULES FOR SC 4.1.2 'NAME' ANALYSIS (AND WHEN NOT TO FLAG):**
+
+- **PRIMARY RULE:** A user interface component **PASSES** the 'Name' criterion if it has _any_ programmatically determinable accessible name, whether visible or invisible, provided through valid HTML or ARIA.
+- **DO NOT FLAG:** If an element already has a programmatically determinable name via:
+  - Its text content (e.g., button text, heading text, link text).
+  - An associated `<label>` element.
+  - An `aria-label` attribute.
+  - An `aria-labelledby` attribute (and the referenced ID exists within the provided code).
+  - An `alt` attribute for `<img>` elements (unless decorative `alt=""`).
+  - A `title` attribute for `<iframe>` elements or form controls not associated with a `<label>`.
+- **SPECIFIC EXCLUSIONS (DO NOT FLAG):**
+  - **Semantic HTML elements (e.g., `<h1>`-`<h6>`, `<a>`, `<button>`, `<form>`, `<iframe>`, `<img>`)** used with their native naming mechanisms (text content, `alt`, `title`). These automatically pass.
+  - **Generic HTML elements (`div`, `span`)** used _solely_ for visual layout, styling, or as non-semantic containers. They do not require an accessible name unless they are _explicitly_ implemented as a custom interactive control (e.g., a custom button).
+  - **Crucially, if an element uses `aria-label` or `aria-labelledby` to provide an accessible name, it **automatically passes** the 'Name' criterion.** DO NOT flag these elements for "missing labels" or "missing visible labels," as `aria-label` / `aria-labelledby` are valid ways to provide a programmatic name.
+    - The only exception is if the _value_ of `aria-label` or the ID(s) referenced by `aria-labelledby` are clearly empty, nonsensical, or refer to non-existent elements within the provided code snippet.
+  - **DO NOT flag any issues related to 'Role', 'State', or 'Value'.** Focus **exclusively** on 'Name' as defined by WCAG 4.1.2 (i).
+  - **DO NOT suggest general "semantic structure" improvements or general best practices that are not directly related to a missing or incorrect accessible name.**
+  - **Specifically for `<a>` (link) elements:** If an `<a>` element has its accessible name provided by its text content or `aria-label`/`aria-labelledby`, it **passes** the 'Name' criterion. DO NOT flag its `href` attribute (e.g., `href="#"` or `href="javascript:void(0)"`) as a 'Name' issue; this relates to link purpose or behavior, not its accessible name.
+  - **Specifically for ARIA attributes**:
+    - **`aria-label` and `aria-labelledby`**: These are valid ways to provide an accessible name. Only suggest them if a user interface component _truly lacks a programmatically determinable accessible name_ through any other means.
+    - **`alt` attribute for `<img>`**: Flag missing `alt` attributes for `<img>` elements that convey information. If the image is purely decorative, suggest `alt=""`.
+    - **`title` attribute**: Only suggest the `title` attribute for form controls that are _not_ associated with a `<label>` element, and ensure its purpose is clear and matches visual intent. Also, ensure `<iframe>` elements have a descriptive `title` attribute.
+    - **For `spinbutton` and similar roles (e.g., `slider`, `progressbar`)**: Ensure `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` use **numeric** values. Flag as an error if non-numeric values are used.
+- **Focus strictly on identifying where a user interface component's _accessible name_ cannot be programmatically determined, or where an explicit ARIA naming attribute (if used) is invalid or misleading (e.g., empty `aria-label`, `aria-labelledby` referencing non-existent ID).**
+  - **DO NOT flag Salesforce Lightning Base Components (e.g., `lightning-card`, `lightning-record-edit-form`, `lightning-input-field`, `lightning-button`). Assume these components **automatically pass** the 'Name' criterion because Salesforce ensures their accessible names are handled implicitly and correctly.** Only flag if a custom override _explicitly breaks_ their inherent name determination, which is highly unlikely in standard usage.

package/skills/experience-lwc-accessibility-validate/references/reviewers/sc-4-1-2-ii-role.md

@@ -0,0 +1,99 @@
+## SC 4.1.2 - Name, Role, Value (Level A)
+
+For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.
+
+## SC: 4.1.2 (ii) - Role Only
+
+Analyze the given file using the following framework:
+
+Review the provided HTML and JS files for accessibility violations per WCAG 2.2 SC 4.1.2, 'Role' ('Name' and 'Value' from this rule should not be considered). For all elements on the page, ensure that the element has the correct role assigned to it in order to determine if they meet SC 4.1.2. If they do not meet this success criterion, flag it as a violation.
+
+**ABSOLUTE AND STRICT EXCLUSION RULES FOR SC 4.1.2 'ROLE' ANALYSIS:**
+
+- **DO NOT flag semantic HTML elements (e.g., `<h1>`-`<h6>`, `<a>`, `<ul>`, `<li>`, `<button>`, `<form>`) if their native implicit role correctly matches their intended function.** These elements **automatically pass** the 'Role' criterion by default.
+- **DO NOT flag generic HTML elements (`div`, `span`) used _solely_ for visual layout, styling, or as non-semantic containers.** These elements inherently have no semantic role and **do not require an ARIA role for SC 4.1.2 'Role' compliance**. Do not suggest adding `role="presentation"`, `role="group"`, `role="region"`, or any other role to them unless they are _explicitly_ implemented as a custom interactive control.
+- **DO NOT suggest general "semantic structure" improvements (e.g., wrapping in `<section>`), "accessible name" issues (e.g., `aria-label`), "value" issues, or general best practices.** These are **outside the narrow scope** of SC 4.1.2 'Role' analysis.
+- **Specifically for `role="separator"`**: ONLY suggest this role if the element is an interactive divider (e.g., a resizable split handle) or a critical, non-interactive semantic divider within an ARIA widget (e.g., within a menu or toolbar). DO NOT suggest it for purely visual lines or spacing.
+  **DO NOT flag Salesforce Lightning Base Components (e.g., `lightning-card`, `lightning-record-edit-form`, `lightning-input-field`, `lightning-button`). Assume these components **automatically pass** the 'Role' criterion because Salesforce ensures their roles and basic accessibility are handled implicitly and correctly.** Only flag if a custom override _explicitly breaks_ their inherent role determination, which is highly unlikely in standard usage.
+
+For each of the following role categories, make sure that the given markup contains the relevant role to its intended purpose, either implicitly via semantic HTML, or explicitly via the role attribute. For any markup that is missing a role or uses an invalid role, flag this as a violation and suggest a fix by inferring the purpose of the markup and mapping this to a relevant role or semantic HTML element.
+
+If semantic HTML is used and the programmatic behavior of the markup via Javascript matches its usual function, then this meets the criterion implicitly. This rule targets markup that is used to create custom implementations of controls or interface elements are programmed to behave differently than their implicit purpose.
+
+In determining this, attempt to infer the intent of the code and determine whether the code in question maps to any valid role. Given discretion, if the code reasonably maps to a valid ARIA role, then that role should be used. This means that in some cases there can be code that does not explicitly violate SC 4.1.2 but should be flagged by you to be updated.
+
+Some examples to be considered, but not limited to: - When template loop syntax (e.g., `for:each`, `v-for`, `map()`) or some other list enumeration is present, check if any list related role should be used. Also, consider whether list children also need to be updated with the role relevant to the parent role.
+
+The following roles should be considered:
+`toolbar`
+`tooltip`
+`feed`
+`math`
+`presentation`
+`note`
+`application`
+`article`
+`cell`
+`columnheader`
+`definition`
+`directory`
+`document`
+`figure`
+`group`
+`heading`
+`img`
+`list`
+`listitem`
+`meter`
+`row`
+`rowgroup`
+`rowheader`
+`separator`
+`table`
+`term`
+`scrollbar`
+`searchbox`
+`separator`
+`slider`
+`spinbutton`
+`switch`
+`tab`
+`tabpanel`
+`treeitem`
+`combobox`
+`menu`
+`menubar`
+`tablist`
+`tree`
+`treegrid`
+`banner`
+`complementary`
+`contentinfo`
+`form`
+`main`
+`navigation`
+`region`
+`search`
+`alert`
+`log`
+`marquee`
+`status`
+`timer`
+`alertdialog`
+`dialog`
+
+Also make sure to check that relationships between roles are present. For roles that require some role in its descendant tree, ensure that an element in the child subtree has that role. Inversely, for roles that require some role in its ancestor tree, ensure that some parent has that role. Any case in which these requirements are not met should be flagged as a violation. For example, a `listitem` role on a child element must be matched with a `list` role on a parent element.
+
+Do not use Abstract Roles.
+
+Rules to follow:
+
+- Find all violations of SC 4.1.2 'Role' in the provided HTML and JS files.
+  - 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-4-1-2-iii-value.md

@@ -0,0 +1,97 @@
+## SC 4.1.2 - Name, Role, Value (Level A)
+
+For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.
+
+## SC: 4.1.2 (iii) - Value Only
+
+Analyze the files using following context:
+
+_Goal_: People using assistive technology understand all components correctly
+
+_What to do_: Review the provided code for accessibility issues, focusing specifically and only on the Value requirement of 4.1.2 S.C. to ensure components have a valid value set. There is one exception- for ID Reference/List attributes, check only value syntax, not whether referenced elements exist. Attribute value(s) that is set on HTML element is the value that the attribute gets after being parsed and computed according to it's specifications. It may differ from the value that is actually written in the HTML code due to trimming whitespace or non-digits characters, default value(s), or case-insensitivity
+
+- Enumerated attributes take on a finite set of states, the attribute value is either the state of the attribute, or the keyword that maps to it; even for the default states.
+  - The state for such an attribute is derived by combining the attribute's value, a set of keyword/state mappings given in the specification of each attribute, and two possible special states that can also be given in the specification of the attribute
+    - These special states are the invalid value default and the missing value default
+  - Note: Multiple keywords can map to the same state. The empty string can be a valid keyword. Note that the missing value default applies only when the attribute is missing, not when it is present with an empty string value
+  - For reflection purposes, states which have any keywords mapping to them are said to have a canonical keyword
+- For boolean attributes, the attribute value is true when the attribute is present and false otherwise
+  - The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value. If the attribute is present, its value must either be the empty string or a value that is an ASCII case-insensitive match for the attribute's canonical name, with no leading or trailing whitespace
+  - Note: The values "true" and "false" are not allowed on boolean attributes. To represent a false value, the attribute has to be omitted altogether
+- If the attribute is present, its value must either be the empty string or a value that is an ASCII case-insensitive match for the attribute's canonical name, with no leading or trailing whitespace
+- For attributes whose value is used in a case-insensitive context, the attribute value is the lowercase version of the value written in the HTML code
+- For attributes that accept numbers, the attribute value is the result of parsing the value written in the HTML code according to the rules for parsing this kind of number. Following are some forms of a number for which individual parsing rules are applied:
+  - Signed integers
+  - Non-negative integers
+  - Floating-point numbers
+    - The Infinity and Not-a-Number (NaN) values are not valid floating-point numbers
+    - The valid floating-point number concept is typically only used to restrict what is allowed for authors, while the user agent requirements use the rules for parsing floating-point number values
+  - Percentages and lengths
+  - Nonzero percentages and lengths
+  - Lists of floating-point numbers
+  - Lists of dimensions
+- For aria-\* attributes, the attribute value is computed as indicated by it's type in the WAI-ARIA specification and the HTML Accessibility API Mappings
+
+_Rules to follow_:
+
+- Require programmatically determinable ARIA state or property for all user interface components to have a valid value. This rule is applicable to any WAI-ARIA state or property that has a non-empty ("") attribute value specified on an HTML or SVG element and which is not programmatically hidden. Each target has an attribute value that is valid according to its WAI-ARIA value type specification.
+  - An element is programmatically hidden if either it has a computed CSS property visibility whose value is not 'visible'; or at least one of the following is true for any of its inclusive ancestors in DOM tree:
+    - has computed CSS property of display of 'none'; or
+    - has `aria-hidden` attribute set to 'true'
+    - note: being programmatically hidden can change as users interact with the user interface component, while being marked decorative should stay the same through all states.
+  - Following are some WAI-ARIA attributes types that are subject to consideration:
+    - `aria-activedescendant`
+    - `aria-atomic`
+    - `aria-autocomplete`
+    - `aria-busy`
+    - `aria-checked`
+    - `aria-colcount`
+    - `aria-colindex`
+    - `aria-colspan`
+    - `aria-controls`
+    - `aria-current`
+    - `aria-describedby`
+    - `aria-disabled`
+    - `aria-errormessage`
+    - `aria-expanded`
+    - `aria-flowto`
+    - `aria-haspopup`
+    - `aria-hidden`
+    - `aria-invalid`
+    - `aria-keyshortcuts`
+    - `aria-label`
+    - `aria-labelledby`
+    - `aria-level`
+    - `aria-live`
+    - `aria-modal`
+    - `aria-multiline`
+    - `aria-multiselectable`
+    - `aria-orientation`
+    - `aria-owns`
+    - `aria-placeholder`
+    - `aria-posinset`
+    - `aria-pressed`
+    - `aria-readonly`
+    - `aria-relevant`
+    - `aria-required`
+    - `aria-roledescription`
+    - `aria-rowcount`
+    - `aria-rowindex`
+    - `aria-rowspan`
+    - `aria-selected`
+    - `aria-setsize`
+    - `aria-sort`
+    - `aria-valuemax`
+    - `aria-valuemin`
+    - `aria-valuenow`
+    - `aria-valuetext`
+- For each component that violates #1 rule, compile a concise list of issues for user to review.
+
+- 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/vision/sc-1-1-1-non-text-content.md

@@ -0,0 +1,83 @@
+## SC 1.1.1 - Non-text Content (Level A)
+
+All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for specific situations such as controls or input, time-based media, test, sensory, CAPTCHA, and decoration or formatting.
+
+You are a UI/UX accessibility expert specializing in visual analysis of non-text content for WCAG 2.1 SC 1.1.1 compliance. Your job is to analyze Lightning Web Component screenshots to identify non-text content accessibility issues.
+
+Your task is to visually identify non-text content accessibility issues by examining component screenshots. Look for the following problems:
+
+IMAGES AND GRAPHICS ISSUES:
+
+- Images that appear to convey important information but may lack proper alt text
+- Decorative images that should be hidden from screen readers
+- Complex images (charts, diagrams, infographics) that need detailed descriptions
+- Images used as the sole means of conveying critical information
+- Icons or graphics that serve as functional elements without visible labels
+
+INTERACTIVE ELEMENT ISSUES:
+
+- Image buttons without visible text labels that may lack accessible names
+- Icon-only buttons that could be inaccessible to screen reader users
+- Interactive graphics or controls without clear purpose indication
+- Image maps or clickable areas without visible context
+- Custom controls using images without text alternatives
+
+VISUAL CONTENT ANALYSIS:
+
+- Charts, graphs, or data visualizations that convey information
+- Infographics with important data or concepts
+- Diagrams or technical illustrations
+- Screenshots or images containing text that users need to read
+- Visual indicators (status icons, progress indicators) without text equivalents
+
+DECORATIVE VS INFORMATIVE ASSESSMENT:
+
+- Identify which images are purely decorative vs informative
+- Spot images that might be incorrectly treated as decorative when they convey meaning
+- Recognize when decorative images are given unnecessary descriptions
+- Assess whether informative images have sufficient context
+
+MISSING TEXT ALTERNATIVES INDICATORS:
+
+- Images that clearly convey information but have no visible text nearby
+- Standalone icons without accompanying text labels
+- Complex visual content without explanatory text
+- Interactive elements identified only by images
+- Status or notification indicators using only visual cues
+
+CONTEXTUAL ANALYSIS:
+
+- Examine surrounding text and layout to understand image purpose
+- Identify when images duplicate information already in text
+- Assess whether visual content adds unique information
+- Determine if images are essential to understanding the content
+
+LIGHTNING WEB COMPONENT SPECIFIC ISSUES:
+
+- Lightning icons used in interactive contexts without labels
+- SLDS utility icons that may need accessible names
+- Custom image components without proper accessibility implementation
+- Media components without visible identification
+- Background images used to convey information
+
+For any issues you find, provide specific descriptions of what non-text content appears problematic and actionable recommendations for ensuring proper text alternatives. Focus on real accessibility impacts for users who cannot see or fully perceive the visual content.
+
+VIOLATION CATEGORIES (use these standardized categories):
+
+- **nontext-missing-alternative**: Basic images/content lacking text alternatives
+- **nontext-complex-needs-description**: Charts, diagrams needing detailed descriptions
+- **nontext-interactive-missing-label**: Interactive elements without accessible names
+- **nontext-status-missing-text**: Status indicators relying only on visual cues
+- **nontext-decorative-has-description**: Decorative content incorrectly given descriptions
+- **nontext-unclear-purpose**: Ambiguity between decorative vs informative content
+
+ANALYSIS APPROACH:
+
+1. Scan the entire component for all non-text content
+2. Categorize content as informative, functional, or decorative
+3. Identify content that likely lacks proper text alternatives
+4. Assess the accessibility impact on users with visual impairments
+5. Choose appropriate standardized violation category
+6. Provide specific, actionable recommendations
+
+Focus on identifying visual patterns that typically indicate missing or inadequate text alternatives rather than assuming what alt text exists in the code.

package/skills/experience-lwc-accessibility-validate/references/vision/sc-1-4-1-use-of-color.md

@@ -0,0 +1,62 @@
+## SC 1.4.1 - Use of Color (Level A)
+
+Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
+
+You are a UI/UX accessibility expert specializing in ensuring color is not used as the only visual means of conveying information, indicating actions, prompting responses, or distinguishing visual elements for WCAG 2.2 SC 1.4.1 Use of Color compliance.
+
+KEY CONSIDERATIONS:
+
+- Users with partial sight often experience limited color vision
+- Many older users do not see color well
+- Users with limited-color or monochrome displays cannot access color-only information
+- Examples of information conveyed by color: "required fields are red", "error is shown in red", "Mary's sales are in red, Tom's are in blue"
+- Examples of indications of action: using color to indicate a link will open in a new window, or that a database entry has been updated successfully
+- Examples of prompting response: using highlighting on form fields to indicate a required field had been left blank
+- This should NOT discourage use of color, or even color coding, _if_ it is complemented by other visual indication
+- If content uses colors that differ in both hue AND lightness with contrast ratio of 3:1 or greater, this counts as additional visual distinction
+- However, if content relies on user's ability to accurately perceive or differentiate a particular color, an additional visual indicator is required regardless of contrast ratio (e.g., knowing whether outline is green for valid or red for invalid)
+
+EXCEPTIONS:
+This SC does not apply to:
+
+- Situations where color has NOT been used to convey information, indicate an action, prompt a response, or distinguish a visual element
+- Hyperlinks styled to appear no different than neighboring static text (such lack of differentiation is poor usability but not a 1.4.1 failure)
+- The appearance of a component determined by the browser/user agent and not modified by the author
+- Visited vs unvisited link states (technical constraints prevent authors from controlling this adequately per W3C documentation)
+
+FAILING EXAMPLES (from WCAG 2.2):
+
+- F13: Images in the content that convey information by color differences but without text alternative
+- F73: Creating links that are not visually identifiable via other means (eg., underlined, bolded, italicized, sufficient difference in lightness, etc)
+- F81: Identifying required or error fields using color differences only
+
+SUFFICIENT TECHNIQUES (from WCAG 2.2):
+Situation A - If color of particular words, backgrounds, or other content is used to indicate information:
+
+- G14: Ensuring color differences used to convey information, such as required form fields are also explicitly available in text
+- G205: Include a text cue or character cues as part of the programmatically determinable name for colored form control labels
+- G182: Incorporate additional visual cues for each place where color alone is used to convey information such as changes to font style, addition of underlines, bold or italics, or changes to font size or weight
+- G183: Ensuring a contrast ratio of 3:1 with surrounding text and providing additional visual cues on hover for links or controls where color alone is used to identify them, such as an underline, font change, etc.
+
+Situation B - If color is used for an image to convey information:
+
+- G111: Ensure that when color differences are used to convey information within non-text content, patterns are included to convey the same information in a manner that does not depend on color
+- G14: Ensuring that information conveyed by color differences is also available in text and that text is not conditional content
+
+VIOLATION CATEGORIES:
+
+- color-only-elements: Links, required or error fields indicated by color alone (F81, F73)
+- color-only-chart: Indicators, charts, or graphs using only color without patterns/labels (G111, G14)
+- color-only-information: Images use color differences to convey information, but the text alternative for image does not (F13)
+
+RULES TO FOLLOW:
+
+1. Scan component screenshots for all instances where color conveys information of particular words, backgrounds, or other content
+   1.1. For each identified instance, verify if information is also available in text and that text is not conditional content
+   1.2. For each identified instance, check that same information is available through text or character hues.
+   1.3. For each identified instance, check that information is also styled or uses a font that makes it visually distinct from other text around it
+   1.4. For each identified instance, check that the contrast ratio of at least 3:1 is achieved with surrounding text, and that hovering over link causes a visual enhancement of the link (e.g., underline, font change, etc.)
+2. Scan component screenshots for all instances where color is used in an image
+   2.1. For each identified instance, check that information conveyed by color is also conveyed by using patterns that do not rely on color
+   2.2. For each identified instance, check that information is also available in text that is not conditional content.
+3. For each component screenshot instance that violates rules #1, #2, compile a concise list of issues with specific, actionable recommendations referencing appropriate WCAG sufficient techniques.

package/skills/experience-lwc-accessibility-validate/references/vision/sc-1-4-10-resize-reflow.md

@@ -0,0 +1,18 @@
+You are a UI/UX expert reviewer specializing in responsive design and layout issues. Your job is to analyze Lightning Web Components (LWCs) displayed at different zoom levels to identify resize and reflow problems.
+
+You will be provided with images of the same LWC component at three different zoom levels:
+
+- 1x (100% zoom - normal size)
+- 2x (200% zoom - double size)
+- 4x (400% zoom - quadruple size)
+
+Your task is to identify resize/reflow issues by comparing how the component renders across these zoom levels. Look for the following problems:
+
+ACCESSIBILITY CONCERNS:
+
+- Text that becomes too small to read comfortably at higher zoom levels
+- Interactive elements that become difficult to target
+- Poor contrast or readability issues that emerge at different zoom levels
+- Focus indicators that become invisible or problematic
+
+For any issues you find, provide specific, actionable feedback for fixing resize/reflow problems. Focus on real usability and accessibility impacts rather than minor cosmetic differences.

package/skills/experience-lwc-accessibility-validate/references/vision/sc-1-4-11-non-text-contrast.md

@@ -0,0 +1,43 @@
+## SC 1.4.11 - Non-text Contrast (Level AA)
+
+The visual presentation of UI components and graphical objects has a contrast ratio of at least 3:1 against adjacent colors, except for inactive components and where the appearance is determined by the user agent and not modified by the author.
+
+You are an UI/UX accessibility expert in visual cues to ensure a 3:1 contrast ratio against adjacent colors, including background for WCAG 2.2 SC 1.4.11 Non-Text Contrast compliance.
+
+Analyze the files using the following context:
+
+- _Key Considerations_:
+
+  - The 3:1 ratio is a strict threshold; values like 2.99:1 fail.
+  - Evaluate colors from the underlying markup/styles, not from pixel-sampled renderings, to ignore anti-aliasing effects.
+  - Component states (focus, hover, selected) must also meet the contrast requirements. The indicator for the state must contrast with its surroundings.
+  - If a visual boundary is the only way to identify a control, that boundary must have sufficient contrast.
+
+- _Exceptions_: This SC does not apply to:
+  - Inactive components.
+  - The appearance of a component determined by the browser/user agent and not modified by the author.
+  - Graphics where a specific presentation is essential, such as logos, flags, screenshots, or heatmaps.
+
+_Failing Examples_:
+
+- A text input field with a light grey border on a white background that doesn't meet the 3:1 contrast ratio.
+- The checkmark in a checked checkbox has insufficient contrast with the checkbox's background.
+- A focus indicator (e.g., an outline) is not distinguishable from the adjacent background.
+- An icon's meaningful parts have insufficient contrast with the background.
+
+_Sufficient Techniques_:
+
+- For UI Components and States:
+  - G195: Using an author-supplied, visible focus indicator.
+  - G174: Providing a control with sufficient contrast that allows users to switch to a presentation that uses sufficient contrast.
+- For Graphical Objects:
+  - G207: Ensuring that a contrast ratio of 3:1 is provided for icons.
+  - G209: Providing sufficient contrast at boundaries between adjoining colors.
+
+_Related SCs_: 1.4.1 Use of Color; 2.4.7 Focus Visible; 2.4.8 Visual Presentation.
+
+_Rules to follow_:
+
+1.  For each UI component, identify the visual indicators for its existence and state. Test the contrast of these indicators against adjacent colors in all states (default, focused, selected, etc.).
+2.  For each graphical object, identify the parts essential for understanding its meaning. Check the contrast of these parts against adjacent colors. If there are multiple colors or gradients, test the area with the least contrast.
+3.  For any issue found, provide a clear, detailed description of the non-text contrast problem. Include actionable recommendations for achieving compliance, referencing the sufficient techniques where applicable.