# Lwc Accessibility > Guides designing or reviewing Lightning Web Components for keyboard access, semantic labeling, and focus management, prioritizing base components over custom ARIA. - Skill: `pranavnagrecha/lwc-accessibility` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds add pranavnagrecha/lwc-accessibility` - Raw SKILL.md: https://api.skillmd.com/api/skills/pranavnagrecha/lwc-accessibility/raw - Safety review: PASS (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend, Coding & Dev Tools, Accessibility, Frontend Frameworks - Tags: Accessibility, Aria, Focus Management, Keyboard Navigation, Lwc, Salesforce, Screen Reader - Author: PranavNagrecha (https://skillmd.com/u/pranavnagrecha) - Updated: 2026-08-22 - Page: https://skillmd.com/skills/pranavnagrecha/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.