PranavNagrecha 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:
- Gather context — confirm the org edition, relevant objects, and current configuration state
- Review official sources — check the references in this skill's well-architected.md before making changes
- Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
- Validate — run the skill's checker script and verify against the Review Checklist below
- 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:
lightning-iconneeds deliberate text when it carries meaning - icon-only affordances look obvious visually but become vague or silent to assistive technology withoutalternative-text.- 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. - 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.
- 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.