lwc-accessibility

Use this skill when a Lightning Web Component looks correct visually but may fail for keyboard users or assistive technology. The highest-value move in LWC accessibility work is usually to remove custom interaction code and return to accessible base components, then handle the few remaining focus and labeling gaps deliberately.

---

## Before Starting

Gather this context before working on anything in this domain:

- Which parts of the UI are interactive: buttons, menus, tabs, dialogs, inline actions, or custom pickers?
- Is the component built mostly from `lightning-*` base components, SLDS blueprint markup, or custom HTML?
- Where should focus move after the user opens a modal, triggers validation errors, saves, or cancels?

---

## Core Concepts

Accessibility in LWC is easiest when the component stays close to platform primitives. The farther a team moves toward clickable `div` elements, custom focus logic, and manual ARIA, the more likely it is to recreate a solved problem badly.

| Principle | Default | Anti-pattern | Why it matters |
|---|---|---|---|
| Base components first | Use `lightning-*` base components or SLDS blueprints | Custom menu/button/toggle in raw HTML | Base components ship tested keyboard, label, and AT support |
| Accessible name | Real button text, label on inputs, `alternative-text` on meaningful icons | ARIA-patching a clickable `span` or `div` | ARIA cannot repair structurally wrong markup |
| Focus contract | Land on first actionable element, trap inside modals, return to launcher on close | Letting focus stay wherever the browser last placed it after rerender/save | Lost focus = component is broken for keyboard users |
| Programmatic validation | Use base-component validation; programmatic error association on custom inputs | Error state shown only in color or layout text | Color-only errors fail screen readers and color-blind users |

---

## Common Patterns

### Base-Component Replacement For Custom Click Targets

**When to use:** The component currently uses custom HTML such as a clickable `div`, icon-only action, or hand-rolled toggle.

**How it works:** Replace the interactive surface with `lightning-button`, `lightning-button-icon`, `lightning-input`, or another standard base component. Keep any remaining custom markup decorative, not interactive.

**Why not the alternative:** Adding `tabindex`, `role`, and key handlers to arbitrary markup usually creates incomplete keyboard behavior and inconsistent screen-reader output.

### Deliberate Focus Management Around Dialogs

**When to use:** The component opens a modal, quick action surface, or blocking overlay.

**How it works:** Use `LightningModal` or another supported dialog surface, set focus on meaningful content or the first actionable control, and return focus to the launch element when the interaction closes.

**Why not the alternative:** Leaving focus wherever the browser last had it makes the overlay hard to use and easy to lose.

### Accessible Composite Widget Boundary

**When to use:** A real business need requires a custom picker, listbox, or multi-step composite component.

**How it works:** Choose a known WAI-ARIA interaction pattern, document the keyboard contract, and test it with both tab order and screen-reader announcements before shipping.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Standard action, toggle, or input | Use a `lightning-*` base component | Accessible behavior is already implemented and maintained by the platform |
| Need branded layout but normal semantics | Use an SLDS blueprint with minimal custom behavior | Keeps semantics closer to supported interaction models |
| Need a modal or blocking overlay | Use `LightningModal` with an explicit focus plan | Modal semantics and dismissal behavior are easier to keep correct |
| Considering ARIA on a clickable `div` | Replace it with semantic HTML or a base component | ARIA does not fully repair incorrect structure |
| Custom composite widget is unavoidable | Implement and test a formal keyboard model | Composite controls need a documented accessibility contract |

---


## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. Document — record any deviations from standard patterns and update the template if needed

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] Every interactive surface is semantic HTML or a supported base component.
- [ ] Inputs, buttons, and meaningful icons have a clear accessible name.
- [ ] Focus order matches the visible reading order and business flow.
- [ ] Modal or overlay interactions trap and restore focus intentionally.
- [ ] Validation feedback is programmatic and not color-only.
- [ ] Keyboard-only testing covers open, close, save, cancel, and error states.

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **`lightning-icon` needs deliberate text when it carries meaning** - icon-only affordances look obvious visually but become vague or silent to assistive technology without `alternative-text`.
2. **Custom HTML can regress below the platform baseline quickly** - moving away from `lightning-*` components often removes built-in keyboard and label behavior teams assumed they still had.
3. **Focus can get lost after rerender** - conditional templates, async state changes, and modal open or close transitions can strand keyboard users unless focus is restored deliberately.
4. **ARIA does not replace semantic structure** - adding roles to the wrong element can still produce confusing navigation and announcement behavior.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Accessibility review | Findings on semantic markup, labels, keyboard interaction, and focus behavior |
| Remediation plan | Concrete changes to base components, ARIA usage, and focus handling |
| Test checklist | Keyboard and screen-reader scenarios that should pass before release |

---

## Related Skills

- `lwc/lwc-modal-and-overlay` - use when the main problem is dialog choice and overlay lifecycle rather than general accessibility posture.
- `lwc/lwc-forms-and-validation` - use when the accessibility issue is mainly inside form validation and record-edit UX.
- `lwc/lwc-testing` - use alongside this skill to turn accessibility expectations into repeatable component tests.