claude-code-mastery-project-starter-kit: Skill for Claude Code

Accessibility: Build It In, Don't Bolt It On

Accessibility is a current best practice, not a nice-to-have for later, and most of it costs nothing if you use the right elements from the start. Claude's defaults (clickable divs, missing labels, removed focus rings) are exactly what breaks screen readers and keyboards, and they're expensive to retrofit. Treat it as part of the build, like you would performance.

Semantic HTML first, ARIA last

The native element gives you keyboard support, focus, the correct role, and screen-reader semantics for free. The first rule of ARIA is don't use ARIA when a native element already does the job, and bad ARIA is worse than none. Reach for the real element before reaching for a role.

Use the real element, not a clickable div

<button> for actions (submit, toggle, open a menu), <a href> for navigation (it goes somewhere). A <div onclick> is none of these: it isn't focusable, doesn't fire on Enter or Space, and is announced as nothing. Recreating a button with role, tabindex, and keydown handlers is work you will get subtly wrong, the native <button> is already all of that. Same for <nav>, <ul>, <table>, <label>, <input>, use them.

Every interactive thing needs an accessible name

• Images: a descriptive alt, or alt="" for purely decorative ones so screen readers skip them. Never omit the attribute, that makes the reader announce the filename.
• Form fields: a real <label> tied to the input (for/id or wrapping). A placeholder is not a label, it vanishes on input, has poor contrast, and isn't reliably announced.
• Icon-only buttons (hamburger, close X, search): an aria-label. This is the single most common missing name, an icon button with no text is silent to a screen reader.

Keyboard and focus

Everything interactive must be reachable and operable by keyboard in a sensible order. Two things Claude breaks constantly:

• Never remove the focus ring (outline: none) without replacing it, a keyboard user then can't see where they are. Use :focus-visible to show a clear ring for keyboard users without it appearing on mouse clicks.
• Manage focus on modals and route changes. Prefer the native <dialog> with showModal(), it traps focus, closes on Escape, and restores focus to the trigger. If you build your own, replicate all of that. In a SPA, move focus to the new view's heading on navigation, or a screen-reader user never learns the page changed.