accessibility-guide

Accessibility Guide for fundamental-styles

When to use this skill:

• Writing HTML examples for component documentation
• Creating new component demos
• Reviewing component accessibility
• Fixing accessibility issues in examples
• Questions about ARIA roles and attributes

Core Principles

1. Semantic HTML First

Always prefer native HTML elements over ARIA roles when possible.

✅ DO:

<button>Click me</button>
<nav>...</nav>
<header>...</header>
<input type="checkbox" />

❌ DON'T:

<div role="button">Click me</div>
<div role="navigation">...</div>
<div role="banner">...</div>
<div role="checkbox"></div>

Why: Native elements provide built-in keyboard support, focus management, and semantics without JavaScript.

2. Labels MUST Be Properly Connected

Every form control must have an accessible label.

✅ DO - Use for and id:

<label for="username">Username:</label> <input id="username" type="text" name="username" />

✅ DO - Nested label (alternative):

<label>
    Username:
    <input type="text" name="username" />
</label>

✅ DO - Using aria-labelledby for complex labels:

<span id="label-firstname">First Name</span>
<span id="label-required">(required)</span>
<input type="text" aria-labelledby="label-firstname label-required" />

❌ DON'T - Missing connection:

<label>Username</label>
<input type="text" />
<!-- No for/id connection -->

❌ DON'T - Non-existent ID reference:

<label for="nonexistent">Username</label>
<input id="username" type="text" />
<!-- Mismatched IDs -->

3. ID References Must Be Valid

When using aria-labelledby, aria-describedby, or for attributes, the referenced IDs must exist in the DOM.

✅ DO:

<h2 id="dialog-title">Confirm Action</h2>
<div role="dialog" aria-labelledby="dialog-title" aria-describedby="dialog-desc">
    <p id="dialog-desc">Are you sure you want to proceed?</p>
    <button>Confirm</button>
</div>