Files
skills/public/frontend-web-accessibility.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

733 lines
34 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>frontend-web-accessibility</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/frontend-web-accessibility.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/frontend-web-accessibility">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/frontend-web-accessibility.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>frontend-web-accessibility</h1><p class="lede">Building accessible web applications</p><h1>Web Accessibility</h1>
<p><strong>Scope</strong>: WCAG 2.1 AA, ARIA, keyboard navigation, screen readers, color contrast <strong>Lines</strong>: ~300 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Building accessible web applications</li><li>Implementing WCAG compliance</li><li>Supporting keyboard navigation</li><li>Designing for screen readers</li><li>Testing accessibility</li><li>Fixing accessibility issues</li></ul>
<h2>Core Concepts</h2>
<h3>WCAG Principles (POUR)</h3>
<p><strong>Perceivable</strong> - Information must be presentable to users <strong>Operable</strong> - UI must be operable by all users <strong>Understandable</strong> - Information must be understandable <strong>Robust</strong> - Content must work across technologies</p>
<h3>Conformance Levels</h3>
<p><strong>Level A</strong> - Minimum (basic accessibility) <strong>Level AA</strong> - Recommended (target for most sites) <strong>Level AAA</strong> - Enhanced (not always achievable)</p>
<p><strong>Target: WCAG 2.1 AA</strong> for production applications.</p>
<hr>
<h2>Semantic HTML</h2>
<h3>Use Correct Elements</h3>
<pre><code class="lang-tsx">// ❌ Bad: Divs for everything
&lt;div onClick={handleClick}&gt;Click me&lt;/div&gt;
&lt;div&gt;Important message&lt;/div&gt;
// ✅ Good: Semantic elements
&lt;button onClick={handleClick}&gt;Click me&lt;/button&gt;
&lt;main&gt;Important message&lt;/main&gt;</code></pre>
<h3>Document Structure</h3>
<pre><code class="lang-tsx">&lt;body&gt;
&lt;header&gt;
&lt;nav&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/&quot;&gt;Home&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/about&quot;&gt;About&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/nav&gt;
&lt;/header&gt;
&lt;main&gt;
&lt;article&gt;
&lt;h1&gt;Page Title&lt;/h1&gt;
&lt;section&gt;
&lt;h2&gt;Section Title&lt;/h2&gt;
&lt;p&gt;Content...&lt;/p&gt;
&lt;/section&gt;
&lt;/article&gt;
&lt;aside&gt;
&lt;h2&gt;Related Links&lt;/h2&gt;
&lt;ul&gt;...&lt;/ul&gt;
&lt;/aside&gt;
&lt;/main&gt;
&lt;footer&gt;
&lt;p&gt;&amp;copy; 2025 Company&lt;/p&gt;
&lt;/footer&gt;
&lt;/body&gt;</code></pre>
<h3>Heading Hierarchy</h3>
<pre><code class="lang-tsx">// ❌ Bad: Skipping levels
&lt;h1&gt;Page Title&lt;/h1&gt;
&lt;h3&gt;Subsection&lt;/h3&gt;
&lt;h5&gt;Detail&lt;/h5&gt;
// ✅ Good: Proper hierarchy
&lt;h1&gt;Page Title&lt;/h1&gt;
&lt;h2&gt;Section&lt;/h2&gt;
&lt;h3&gt;Subsection&lt;/h3&gt;</code></pre>
<p><strong>Rules</strong>:</p>
<ul><li>One <code>&lt;h1&gt;</code> per page</li><li>Don&#x27;t skip levels (h1 → h3)</li><li>Headings describe content</li></ul>
<hr>
<h2>ARIA (Accessible Rich Internet Applications)</h2>
<h3>When to Use ARIA</h3>
<p><strong>First Rule of ARIA</strong>: Don&#x27;t use ARIA if you can use native HTML.</p>
<pre><code class="lang-tsx">// ❌ Bad: ARIA on native element
&lt;div role=&quot;button&quot; tabIndex={0} onClick={...}&gt;Click&lt;/div&gt;
// ✅ Good: Native element
&lt;button onClick={...}&gt;Click&lt;/button&gt;</code></pre>
<h3>Common ARIA Attributes</h3>
<p><strong>aria-label</strong> - Accessible name</p>
<pre><code class="lang-tsx">&lt;button aria-label=&quot;Close dialog&quot;&gt;
&lt;XIcon /&gt;
&lt;/button&gt;</code></pre>
<p><strong>aria-labelledby</strong> - Reference to label</p>
<pre><code class="lang-tsx">&lt;div role=&quot;dialog&quot; aria-labelledby=&quot;dialog-title&quot;&gt;
&lt;h2 id=&quot;dialog-title&quot;&gt;Confirm Delete&lt;/h2&gt;
...
&lt;/div&gt;</code></pre>
<p><strong>aria-describedby</strong> - Additional description</p>
<pre><code class="lang-tsx">&lt;input
type=&quot;password&quot;
aria-describedby=&quot;password-hint&quot;
/&gt;
&lt;p id=&quot;password-hint&quot;&gt;Must be at least 8 characters&lt;/p&gt;</code></pre>
<p><strong>aria-live</strong> - Announce dynamic content</p>
<pre><code class="lang-tsx">&lt;div aria-live=&quot;polite&quot; aria-atomic=&quot;true&quot;&gt;
{status}
&lt;/div&gt;</code></pre>
<p><strong>aria-expanded</strong> - Disclosure state</p>
<pre><code class="lang-tsx">&lt;button
aria-expanded={isOpen}
aria-controls=&quot;dropdown-menu&quot;
onClick={() =&gt; setIsOpen(!isOpen)}
&gt;
Menu
&lt;/button&gt;
&lt;ul id=&quot;dropdown-menu&quot; hidden={!isOpen}&gt;
&lt;li&gt;Item 1&lt;/li&gt;
&lt;li&gt;Item 2&lt;/li&gt;
&lt;/ul&gt;</code></pre>
<p><strong>aria-hidden</strong> - Hide from screen readers</p>
<pre><code class="lang-tsx">&lt;span aria-hidden=&quot;true&quot;&gt;★&lt;/span&gt;
&lt;span className=&quot;sr-only&quot;&gt;5 stars&lt;/span&gt;</code></pre>
<h3>ARIA Roles</h3>
<pre><code class="lang-tsx">// Navigation landmark
&lt;nav role=&quot;navigation&quot;&gt;...&lt;/nav&gt;
// Search landmark
&lt;form role=&quot;search&quot;&gt;...&lt;/form&gt;
// Alert (announces to screen reader)
&lt;div role=&quot;alert&quot;&gt;Error: Form submission failed&lt;/div&gt;
// Tab interface
&lt;div role=&quot;tablist&quot;&gt;
&lt;button role=&quot;tab&quot; aria-selected={true}&gt;Tab 1&lt;/button&gt;
&lt;button role=&quot;tab&quot; aria-selected={false}&gt;Tab 2&lt;/button&gt;
&lt;/div&gt;
&lt;div role=&quot;tabpanel&quot;&gt;Content&lt;/div&gt;</code></pre>
<hr>
<h2>Keyboard Navigation</h2>
<h3>Focus Management</h3>
<p><strong>Tab Order</strong> - Follow DOM order</p>
<pre><code class="lang-tsx">// ❌ Bad: Breaking tab order with CSS
&lt;div style={{ display: &#x27;flex&#x27;, flexDirection: &#x27;column-reverse&#x27; }}&gt;
&lt;button&gt;Second (visually first)&lt;/button&gt;
&lt;button&gt;First (visually second)&lt;/button&gt;
&lt;/div&gt;
// ✅ Good: DOM order matches visual order
&lt;div style={{ display: &#x27;flex&#x27;, flexDirection: &#x27;column&#x27; }}&gt;
&lt;button&gt;First&lt;/button&gt;
&lt;button&gt;Second&lt;/button&gt;
&lt;/div&gt;</code></pre>
<p><strong>tabIndex</strong></p>
<pre><code class="lang-tsx">// 0 = Natural tab order
&lt;div tabIndex={0}&gt;Focusable&lt;/div&gt;
// -1 = Programmatically focusable (not in tab order)
&lt;div tabIndex={-1}&gt;Not in tab order&lt;/div&gt;
// Positive numbers = Custom tab order (avoid!)</code></pre>
<h3>Keyboard Event Handlers</h3>
<pre><code class="lang-tsx">function KeyboardAccessibleButton({ onClick, children }: {
onClick: () =&gt; void;
children: React.ReactNode;
}) {
const handleKeyDown = (e: React.KeyboardEvent) =&gt; {
if (e.key === &#x27;Enter&#x27; || e.key === &#x27; &#x27;) {
e.preventDefault();
onClick();
}
};
return (
&lt;div
role=&quot;button&quot;
tabIndex={0}
onClick={onClick}
onKeyDown={handleKeyDown}
&gt;
{children}
&lt;/div&gt;
);
}
// ✅ Better: Just use &lt;button&gt;
&lt;button onClick={onClick}&gt;{children}&lt;/button&gt;</code></pre>
<h3>Focus Trap (Modals)</h3>
<pre><code class="lang-tsx">import { useEffect, useRef } from &#x27;react&#x27;;
function Modal({ isOpen, onClose, children }: {
isOpen: boolean;
onClose: () =&gt; void;
children: React.ReactNode;
}) {
const dialogRef = useRef&lt;HTMLDivElement&gt;(null);
useEffect(() =&gt; {
if (!isOpen) return;
const dialog = dialogRef.current;
if (!dialog) return;
// Focus first focusable element
const focusableElements = dialog.querySelectorAll(
&#x27;button, [href], input, select, textarea, [tabindex]:not([tabindex=&quot;-1&quot;])&#x27;
);
const firstElement = focusableElements[0] as HTMLElement;
const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
firstElement?.focus();
// Trap focus inside modal
const handleTabKey = (e: KeyboardEvent) =&gt; {
if (e.key !== &#x27;Tab&#x27;) return;
if (e.shiftKey) {
if (document.activeElement === firstElement) {
e.preventDefault();
lastElement?.focus();
}
} else {
if (document.activeElement === lastElement) {
e.preventDefault();
firstElement?.focus();
}
}
};
// Close on Escape
const handleEscape = (e: KeyboardEvent) =&gt; {
if (e.key === &#x27;Escape&#x27;) onClose();
};
dialog.addEventListener(&#x27;keydown&#x27;, handleTabKey);
dialog.addEventListener(&#x27;keydown&#x27;, handleEscape);
return () =&gt; {
dialog.removeEventListener(&#x27;keydown&#x27;, handleTabKey);
dialog.removeEventListener(&#x27;keydown&#x27;, handleEscape);
};
}, [isOpen, onClose]);
if (!isOpen) return null;
return (
&lt;div
ref={dialogRef}
role=&quot;dialog&quot;
aria-modal=&quot;true&quot;
aria-labelledby=&quot;dialog-title&quot;
&gt;
&lt;h2 id=&quot;dialog-title&quot;&gt;Dialog Title&lt;/h2&gt;
{children}
&lt;/div&gt;
);
}</code></pre>
<hr>
<h2>Screen Reader Support</h2>
<h3>Hidden Text for Screen Readers</h3>
<pre><code class="lang-tsx">// CSS approach
&lt;style&gt;
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border-width: 0;
}
&lt;/style&gt;
&lt;button&gt;
&lt;XIcon aria-hidden=&quot;true&quot; /&gt;
&lt;span className=&quot;sr-only&quot;&gt;Close&lt;/span&gt;
&lt;/button&gt;</code></pre>
<h3>Live Regions</h3>
<pre><code class="lang-tsx">function Toast({ message }: { message: string }) {
return (
&lt;div
role=&quot;status&quot;
aria-live=&quot;polite&quot;
aria-atomic=&quot;true&quot;
&gt;
{message}
&lt;/div&gt;
);
}
function ErrorAlert({ error }: { error: string }) {
return (
&lt;div
role=&quot;alert&quot;
aria-live=&quot;assertive&quot;
aria-atomic=&quot;true&quot;
&gt;
{error}
&lt;/div&gt;
);
}</code></pre>
<p><strong>aria-live values</strong>:</p>
<ul><li><code>off</code> - No announcements</li><li><code>polite</code> - Announce when idle (default)</li><li><code>assertive</code> - Interrupt and announce immediately</li></ul>
<h3>Form Labels</h3>
<pre><code class="lang-tsx">// ❌ Bad: No label
&lt;input type=&quot;text&quot; placeholder=&quot;Email&quot; /&gt;
// ✅ Good: Explicit label
&lt;label htmlFor=&quot;email&quot;&gt;Email&lt;/label&gt;
&lt;input id=&quot;email&quot; type=&quot;email&quot; /&gt;
// ✅ Good: Implicit label
&lt;label&gt;
Email
&lt;input type=&quot;email&quot; /&gt;
&lt;/label&gt;
// ✅ Good: aria-label (when visual label not desired)
&lt;input type=&quot;search&quot; aria-label=&quot;Search products&quot; /&gt;</code></pre>
<hr>
<h2>Color and Contrast</h2>
<h3>Contrast Ratios (WCAG AA)</h3>
<p><strong>Normal text</strong> (&lt; 18pt): 4.5:1 minimum <strong>Large text</strong> (≥ 18pt or 14pt bold): 3:1 minimum</p>
<pre><code class="lang-tsx">// ❌ Bad: Insufficient contrast
&lt;div style={{ color: &#x27;#999&#x27;, backgroundColor: &#x27;#fff&#x27; }}&gt;
Text (2.8:1 - fails AA)
&lt;/div&gt;
// ✅ Good: Sufficient contrast
&lt;div style={{ color: &#x27;#767676&#x27;, backgroundColor: &#x27;#fff&#x27; }}&gt;
Text (4.5:1 - passes AA)
&lt;/div&gt;</code></pre>
<p><strong>Tools</strong>:</p>
<ul><li>Chrome DevTools (Lighthouse)</li><li>WebAIM Contrast Checker</li><li>Stark (Figma plugin)</li></ul>
<h3>Don&#x27;t Rely on Color Alone</h3>
<pre><code class="lang-tsx">// ❌ Bad: Color only
&lt;span style={{ color: &#x27;red&#x27; }}&gt;Error&lt;/span&gt;
// ✅ Good: Color + icon + text
&lt;span style={{ color: &#x27;red&#x27; }}&gt;
&lt;ErrorIcon aria-hidden=&quot;true&quot; /&gt;
Error: Field is required
&lt;/span&gt;</code></pre>
<hr>
<h2>Images and Media</h2>
<h3>Alt Text</h3>
<pre><code class="lang-tsx">// ❌ Bad: Missing alt
&lt;img src=&quot;logo.png&quot; /&gt;
// ❌ Bad: Redundant alt
&lt;img src=&quot;photo.jpg&quot; alt=&quot;Image of a photo&quot; /&gt;
// ✅ Good: Descriptive alt
&lt;img src=&quot;logo.png&quot; alt=&quot;Company Logo&quot; /&gt;
// ✅ Good: Decorative image
&lt;img src=&quot;decoration.png&quot; alt=&quot;&quot; /&gt;</code></pre>
<p><strong>Alt text guidelines</strong>:</p>
<ul><li>Describe content and function</li><li>Keep under 125 characters</li><li>Don&#x27;t start with &quot;Image of&quot;</li><li>Empty alt (<code>alt=&quot;&quot;</code>) for decorative images</li></ul>
<h3>Video Captions</h3>
<pre><code class="lang-tsx">&lt;video controls&gt;
&lt;source src=&quot;video.mp4&quot; type=&quot;video/mp4&quot; /&gt;
&lt;track
kind=&quot;captions&quot;
src=&quot;captions.vtt&quot;
srcLang=&quot;en&quot;
label=&quot;English&quot;
default
/&gt;
&lt;/video&gt;</code></pre>
<hr>
<h2>Common Accessible Components</h2>
<h3>Accessible Button</h3>
<pre><code class="lang-tsx">&lt;button
type=&quot;button&quot;
onClick={handleClick}
disabled={isDisabled}
aria-label=&quot;Close dialog&quot;
&gt;
&lt;XIcon aria-hidden=&quot;true&quot; /&gt;
&lt;/button&gt;</code></pre>
<h3>Accessible Link</h3>
<pre><code class="lang-tsx">// ❌ Bad: Non-descriptive link
&lt;a href=&quot;/report.pdf&quot;&gt;Click here&lt;/a&gt;
// ✅ Good: Descriptive link
&lt;a href=&quot;/report.pdf&quot;&gt;Download 2025 Annual Report (PDF, 2MB)&lt;/a&gt;
// ✅ Good: External link
&lt;a href=&quot;https://example.com&quot; target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;
Visit Example
&lt;span className=&quot;sr-only&quot;&gt;(opens in new tab)&lt;/span&gt;
&lt;/a&gt;</code></pre>
<h3>Accessible Dropdown</h3>
<pre><code class="lang-tsx">import { useState } from &#x27;react&#x27;;
function Dropdown({ label, items }: {
label: string;
items: Array&lt;{ id: string; label: string; onClick: () =&gt; void }&gt;;
}) {
const [isOpen, setIsOpen] = useState(false);
return (
&lt;div&gt;
&lt;button
aria-haspopup=&quot;true&quot;
aria-expanded={isOpen}
onClick={() =&gt; setIsOpen(!isOpen)}
&gt;
{label}
&lt;/button&gt;
{isOpen &amp;&amp; (
&lt;ul role=&quot;menu&quot;&gt;
{items.map(item =&gt; (
&lt;li key={item.id} role=&quot;none&quot;&gt;
&lt;button
role=&quot;menuitem&quot;
onClick={() =&gt; {
item.onClick();
setIsOpen(false);
}}
&gt;
{item.label}
&lt;/button&gt;
&lt;/li&gt;
))}
&lt;/ul&gt;
)}
&lt;/div&gt;
);
}</code></pre>
<hr>
<h2>Testing Accessibility</h2>
<h3>Automated Testing</h3>
<pre><code class="lang-tsx">// Jest + Testing Library
import { render } from &#x27;@testing-library/react&#x27;;
import { axe, toHaveNoViolations } from &#x27;jest-axe&#x27;;
expect.extend(toHaveNoViolations);
test(&#x27;should have no accessibility violations&#x27;, async () =&gt; {
const { container } = render(&lt;MyComponent /&gt;);
const results = await axe(container);
expect(results).toHaveNoViolations();
});</code></pre>
<h3>Manual Testing</h3>
<p><strong>Keyboard navigation</strong>:</p>
<ol><li>Tab through all interactive elements</li><li>Shift+Tab to go backward</li><li>Enter/Space to activate</li><li>Arrow keys for custom widgets</li></ol>
<p><strong>Screen reader testing</strong>:</p>
<ul><li>NVDA (Windows, free)</li><li>JAWS (Windows, paid)</li><li>VoiceOver (macOS, built-in)</li></ul>
<p><strong>Browser DevTools</strong>:</p>
<ul><li>Lighthouse accessibility audit</li><li>Accessibility tree inspector</li><li>Color contrast checker</li></ul>
<hr>
<h2>Quick Reference</h2>
<h3>Accessibility Checklist</h3>
<pre><code>[ ] Semantic HTML (header, nav, main, footer)
[ ] Heading hierarchy (h1 → h6, no skipping)
[ ] Alt text for images
[ ] Labels for form inputs
[ ] Keyboard navigation (Tab, Enter, Space, Esc)
[ ] Focus indicators (visible outline)
[ ] Color contrast (4.5:1 for text)
[ ] ARIA labels for icon buttons
[ ] aria-live for dynamic content
[ ] Focus trap in modals
[ ] Skip navigation link
[ ] No reliance on color alone
[ ] Descriptive link text
[ ] Captions for video</code></pre>
<h3>Common ARIA Patterns</h3>
<pre><code class="lang-tsx">// Button
&lt;button aria-label=&quot;Close&quot;&gt;×&lt;/button&gt;
// Toggle
&lt;button aria-pressed={isActive}&gt;Toggle&lt;/button&gt;
// Expandable
&lt;button aria-expanded={isOpen} aria-controls=&quot;content&quot;&gt;Expand&lt;/button&gt;
// Live region
&lt;div aria-live=&quot;polite&quot; role=&quot;status&quot;&gt;{message}&lt;/div&gt;
// Dialog
&lt;div role=&quot;dialog&quot; aria-modal=&quot;true&quot; aria-labelledby=&quot;title&quot;&gt;
// Tab
&lt;div role=&quot;tablist&quot;&gt;
&lt;button role=&quot;tab&quot; aria-selected={true}&gt;Tab 1&lt;/button&gt;
&lt;/div&gt;
&lt;div role=&quot;tabpanel&quot;&gt;Content&lt;/div&gt;</code></pre>
<hr>
<h2>Common Anti-Patterns</h2>
<p>❌ <strong>Div/span as button</strong>: Use <code>&lt;button&gt;</code> ✅ Native semantics</p>
<p>❌ <strong>No focus indicators</strong>: Users can&#x27;t see where they are ✅ Visible focus styles</p>
<p>❌ <strong>Positive tabIndex</strong>: Breaks natural tab order ✅ Use 0 or -1 only</p>
<p>❌ <strong>Color-only indicators</strong>: Not accessible to colorblind ✅ Use color + icon/text</p>
<p>❌ <strong>Missing alt text</strong>: Screen readers can&#x27;t describe images ✅ Descriptive alt text</p>
<p>❌ <strong>Auto-playing media</strong>: Disorienting, annoying ✅ User-controlled playback</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>react-component-patterns.md</code> - Custom hook patterns</li><li><code>react-form-handling.md</code> - Accessible form patterns</li><li><code>nextjs-app-router.md</code> - Metadata, SEO</li><li><code>frontend-performance.md</code> - Performance affects accessibility</li></ul>
<hr>
<h2>Level 3: Resources</h2>
<p><strong>Location</strong>: <code>skills/frontend/web-accessibility/resources/</code></p>
<h3>REFERENCE.md</h3>
<p>Comprehensive 1,900+ line reference covering:</p>
<ul><li><strong>WCAG Guidelines</strong>: Complete Level A, AA, AAA criteria with code examples</li><li><strong>ARIA Reference</strong>: All roles, states, and properties with usage patterns</li><li><strong>Semantic HTML</strong>: Document structure, heading hierarchy, lists, tables, forms</li><li><strong>Keyboard Navigation</strong>: Tab order, focus management, roving tabindex</li><li><strong>Screen Reader Support</strong>: Hidden text, live regions, form labels, announcements</li><li><strong>Focus Management</strong>: Focus traps, restoration, programmatic focus</li><li><strong>Color and Contrast</strong>: WCAG ratios, color blindness, testing tools</li><li><strong>Forms and Validation</strong>: Labels, error messages, aria-invalid, error summaries</li><li><strong>Dynamic Content</strong>: Loading states, live announcements, progress indicators</li><li><strong>Testing Tools</strong>: axe-core, Lighthouse, manual testing workflows</li><li><strong>Common Patterns</strong>: Modals, accordions, tabs, dropdowns, comboboxes</li><li><strong>Mobile Accessibility</strong>: Touch targets, gestures, viewport, screen readers</li><li><strong>Anti-Patterns</strong>: Common mistakes with fixes</li></ul>
<h3>Scripts</h3>
<p><strong>check_accessibility.py</strong> (Python, executable)</p>
<ul><li>Automated accessibility auditing with axe-core via Selenium</li><li>Scans web pages for WCAG violations</li><li>Multiple standards: WCAG 2.1/2.2 Level A/AA/AAA</li><li>Output: text, JSON, or HTML reports</li><li>Batch URL processing</li><li>Usage: <code>./check_accessibility.py &lt;url&gt; [--standard wcag2aa] [--json]</code></li></ul>
<p><strong>analyze_aria.py</strong> (Python, executable)</p>
<ul><li>Analyzes ARIA usage in HTML/JSX files</li><li>Detects invalid roles, attributes, and values</li><li>Checks for common mistakes (redundant roles, hidden focusable elements)</li><li>Validates ARIA patterns and requirements</li><li>Usage: <code>./analyze_aria.py &lt;path&gt; [--recursive] [--json]</code></li></ul>
<p><strong>test_keyboard_nav.js</strong> (Node.js/Puppeteer, executable)</p>
<ul><li>Tests keyboard navigation patterns with Puppeteer</li><li>Verifies tab order, focus indicators, keyboard traps</li><li>Checks skip links, interactive elements, modals, menus</li><li>Reports: text or JSON</li><li>Usage: <code>./test_keyboard_nav.js &lt;url&gt; [--json]</code></li></ul>
<h3>Examples</h3>
<p><strong>react/accessible-modal.tsx</strong></p>
<ul><li>Complete accessible modal dialog component</li><li>Focus trap (Tab/Shift+Tab cycle)</li><li>Escape key to close</li><li>Focus restoration</li><li>ARIA attributes (role=&quot;dialog&quot;, aria-modal, aria-labelledby)</li><li>Backdrop click to close</li></ul>
<p><strong>react/accessible-form.tsx</strong></p>
<ul><li>Accessible form with validation</li><li>Proper labels and aria-describedby</li><li>Error messages with aria-invalid</li><li>Error summary with focus management</li><li>Client-side validation</li><li>Required field indicators</li></ul>
<p><strong>react/accessible-dropdown.tsx</strong></p>
<ul><li>ARIA combobox pattern</li><li>Keyboard navigation (Arrow keys, Enter, Escape)</li><li>aria-activedescendant for active option</li><li>Search/filter functionality</li><li>Proper focus management</li></ul>
<p><strong>html/semantic-examples.html</strong></p>
<ul><li>Complete semantic HTML document</li><li>Proper heading hierarchy</li><li>Skip links</li><li>Semantic landmarks (header, nav, main, aside, footer)</li><li>Accessible forms, tables, lists</li><li>Figure with caption</li></ul>
<p><strong>css/focus-visible.css</strong></p>
<ul><li>Modern focus indicator patterns</li><li>:focus-visible for keyboard-only focus</li><li>High contrast mode support</li><li>Dark mode support</li><li>Custom focus styles for buttons, inputs, cards</li><li>Skip link styles</li><li>Animated focus (respecting prefers-reduced-motion)</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/frontend-web-accessibility.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>