`, `

`, ``, `

`, headings. `.sr-only` exposes supplemental info. | | 1.4.3 Contrast (Minimum) | All default colors meet 4.5:1. `btn-primary` = 4.56:1. Dark mode maintains AA. | | 1.4.6 Contrast (Enhanced) | `prefers-contrast: more` strengthens colors beyond AA. | | 1.4.11 Non-Text Contrast | Focus indicators, button borders, input borders all meet 3:1. | | 2.1.1 Keyboard | All interactive elements keyboard-operable via native HTML. | | 2.3.3 Animation | `prefers-reduced-motion: reduce` disables all animations. | | 2.4.1 Bypass Blocks | `.skip-link` for keyboard bypass navigation. | | 2.4.7 Focus Visible | `:focus-visible` on every interactive element. | | 4.1.2 Name, Role, Value | Zero JS = no ARIA state failures. Native HTML exposes correct roles. | ### What needs application-level work - **Alt text** — Add `alt` to every ``; `alt=""` for decorative. (1.1.1) - **Heading hierarchy** — One `

` per page, then h2-h6 in sequence. (1.3.1) - Custom widget ARIA — JS-powered dropdowns, modals, tabs need `aria-expanded`, `aria-controls`, `role`. (4.1.2) - Custom color contrast — If you override `--ply-` variables, verify 4.5:1 for text, 3:1 for large text/UI. (1.4.3) - Keyboard for custom widgets — Custom JS components must be keyboard-operable. (2.1.1) - Page title — Every page needs ``. (2.4.2) - Language — Set `<html lang="en">`. (3.1.1) - Form labels — Use `<label>` for all inputs. (3.3.2) - Error identification — Identify errors in text, not just color. (3.3.1) ### AI agent guidance for accessible markup When generating ply markup, always: 1. Use semantic elements for landmarks — `<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>` 2. Add `aria-label` to custom widgets without visible text labels 3. Use `<form role="search">` for search forms 4. Include `.skip-link` as the first focusable element 5. Add `alt` text to all `<img>` elements 6. Maintain heading hierarchy (h1 > h2 > h3, no skipping) 7. Label all form inputs with `<label>` 8. Set `lang` on `<html>` 9. Pair color with text for status indicators 10. Prefer native elements over ARIA — `<button>` over `<div role="button">`, `<dialog>` over `<div role="dialog">` --- ## Focus Management & Keyboard Patterns ply provides `:focus-visible` outlines on all native interactive elements. For custom widgets, manage focus yourself. ### Focus Order Strategy 1. Use semantic HTML first — `<button>`, `<a>`, `<input>`, `<select>`, `<details>`, `<dialog>` are already in tab order. 2. `tabindex="0"` — Add to custom interactive elements to include in tab order. ply's `:focus-visible` applies automatically. 3. `tabindex="-1"` — For programmatic focus targets (modal containers, error summaries). NOT in tab order. 4. Never use `tabindex` > 0 — Overrides natural DOM order. ```html  <button class="btn">Save</button> <a href="/settings">Settings</a>  <div role="button" tabindex="0" onclick="doAction()" onkeydown="if(event.key==='Enter'||event.key===' ')doAction()"> Custom Action </div>  <div id="error-summary" tabindex="-1" role="alert"> Please fix the errors below. </div> <script> document.getElementById('error-summary').focus(); </script>  <span class="sr-only">3 notifications</span> ``` ### Arrow Key Navigation (Roving Tabindex) For grouped controls (tabs, toolbars, menu items): one item has `tabindex="0"` (active), the rest have `tabindex="-1"`. Arrow keys move focus within the group. ```html <div role="tablist" aria-label="Settings"> <button role="tab" aria-selected="true" tabindex="0" aria-controls="panel-general">General</button> <button role="tab" aria-selected="false" tabindex="-1" aria-controls="panel-security">Security</button> <button role="tab" aria-selected="false" tabindex="-1" aria-controls="panel-notifications">Notifications</button> </div> <div role="tabpanel" id="panel-general" aria-labelledby="tab-general"> General settings content. </div> ``` ```js tablist.addEventListener('keydown', (e) => { const tabs = [...tablist.querySelectorAll('[role="tab"]')]; const current = tabs.indexOf(document.activeElement); let next; if (e.key === 'ArrowRight') next = (current + 1) % tabs.length; else if (e.key === 'ArrowLeft') next = (current - 1 + tabs.length) % tabs.length; else if (e.key === 'Home') next = 0; else if (e.key === 'End') next = tabs.length - 1; else return; e.preventDefault(); tabs[current].setAttribute('tabindex', '-1'); tabs[current].setAttribute('aria-selected', 'false'); tabs[next].setAttribute('tabindex', '0'); tabs[next].setAttribute('aria-selected', 'true'); tabs[next].focus(); tabs.forEach((tab, i) => { document.getElementById(tab.getAttribute('aria-controls')).hidden = (i !== next); }); }); ``` ### ARIA Attributes Reference | Attribute | When to use | Example | |---|---|---| | `aria-expanded` | Toggleable content (dropdowns, accordions, menus) | `<button aria-expanded="false" aria-controls="menu">Menu</button>` | | `aria-controls` | Links trigger to controlled element | `<button aria-controls="dropdown-1">Options</button>` | | `aria-selected` | Active item in tabs, listboxes | `<button role="tab" aria-selected="true">Tab 1</button>` | | `aria-current="page"` | Current page in navigation | `<a href="/" aria-current="page">Home</a>` | | `aria-live="polite"` | Dynamic content updates | `<div aria-live="polite">3 results found.</div>` | | `aria-live="assertive"` | Urgent announcements | `<div aria-live="assertive" role="alert">Session expired.</div>` | | `aria-label` | Elements without visible text | `<button aria-label="Close">×</button>` | | `aria-labelledby` | Points to another element for label | `<div role="tabpanel" aria-labelledby="tab-1">` | | `aria-describedby` | Additional description | `<input aria-describedby="password-hint">` | ### Live Regions for Dynamic Content ```html  <div aria-live="polite" role="status" class="sr-only" id="search-status"></div> <script> document.getElementById('search-status').textContent = '12 results found.'; </script>  <div aria-live="assertive" role="alert"> Your session has expired. Please log in again. </div> ``` --- ## Custom Widget Accessibility Patterns When building custom interactive widgets beyond ply's built-in components, follow these patterns for WCAG 2.1 AA compliance. ### Drag-and-Drop with Full Keyboard Support Drag-and-drop interfaces must be fully keyboard operable (WCAG 2.1.1). Use a listbox pattern with grab/move/drop states and an `aria-live` region for screen reader announcements. ```html  <div class="sr-only" aria-live="assertive" id="dnd-status"></div>  <p class="text-secondary text-sm"> Keyboard: Tab to list, Space to grab, Up/Down to move, Enter to drop, Escape to cancel. </p>  <ul role="listbox" aria-label="Sortable tasks" id="sortable-list"> <li role="option" tabindex="0" aria-grabbed="false">Review pull request</li> <li role="option" tabindex="-1" aria-grabbed="false">Update documentation</li> <li role="option" tabindex="-1" aria-grabbed="false">Fix navigation bug</li> </ul> ``` ```js const list = document.getElementById('sortable-list'); const status = document.getElementById('dnd-status'); let grabbed = null; list.addEventListener('keydown', (e) => { const item = e.target; if (item.getAttribute('role') !== 'option') return; switch (e.key) { case ' ': e.preventDefault(); if (!grabbed) { grabbed = item; item.setAttribute('aria-grabbed', 'true'); status.textContent = `Grabbed ${item.textContent}. Use arrow keys to move, Enter to drop, Escape to cancel.`; } break; case 'ArrowDown': e.preventDefault(); if (grabbed) { const next = grabbed.nextElementSibling; if (next) { list.insertBefore(next, grabbed); status.textContent = `Moved down to position ${[...list.children].indexOf(grabbed) + 1}.`; } } break; case 'ArrowUp': e.preventDefault(); if (grabbed) { const prev = grabbed.previousElementSibling; if (prev) { list.insertBefore(grabbed, prev); status.textContent = `Moved up to position ${[...list.children].indexOf(grabbed) + 1}.`; } } break; case 'Enter': if (grabbed) { e.preventDefault(); grabbed.setAttribute('aria-grabbed', 'false'); status.textContent = `Dropped ${grabbed.textContent} at position ${[...list.children].indexOf(grabbed) + 1}.`; grabbed = null; } break; case 'Escape': if (grabbed) { e.preventDefault(); grabbed.setAttribute('aria-grabbed', 'false'); status.textContent = 'Reorder cancelled.'; grabbed = null; } break; } }); ``` Accessibility features in this pattern: - `aria-grabbed` toggles between "true" (grabbed) and "false" (released) — announced by screen readers (WCAG 4.1.2) - `aria-live="assertive"` region announces every move to screen readers - Roving tabindex — only the focused item has `tabindex="0"` - `role="listbox"` + `role="option"` — correct semantics for screen readers - Visible keyboard instructions for sighted users - `prefers-reduced-motion: reduce` — disable drag animations in CSS - Full keyboard alternative: Space=grab, Arrows=move, Enter=drop, Escape=cancel (WCAG 2.1.1) ### Focus Trap for Modals Prefer native `<dialog>` — ply styles it automatically and browsers handle focus trapping. For custom modals: ```js function trapFocus(modal) { const focusable = modal.querySelectorAll( 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])' ); const first = focusable[0], last = focusable[focusable.length - 1]; modal.addEventListener('keydown', (e) => { if (e.key !== 'Tab') return; if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); } else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); } }); first?.focus(); } ``` ### Focus Return After Close Always restore focus to the element that triggered the widget: ```js const trigger = document.activeElement; modal.showModal(); modal.addEventListener('close', () => trigger.focus(), { once: true }); ``` ### Custom Widget Accessibility Checklist | Requirement | WCAG Criterion | How to verify | |---|---|---| | Keyboard operable (no mouse required) | 2.1.1 Keyboard | Tab, Enter, Space, arrow keys all work | | Focus indicator visible | 2.4.7 Focus Visible | ply provides `:focus-visible` — don't override `outline: none` | | States announced to screen readers | 4.1.2 Name, Role, Value | `aria-grabbed`, `aria-expanded`, `aria-selected` update on interaction | | Focus trapped in modals | 2.4.3 Focus Order | Tab does not leave an open dialog | | Focus restored on close | 2.4.3 Focus Order | Closing returns focus to the trigger element | | Touch targets >= 44x44px | 2.5.5 Target Size | Measure interactive elements | | Alternative input available | 2.1.1 Keyboard | Drag-and-drop has keyboard fallback | | Screen reader tested | 4.1.2 Name, Role, Value | Verify with VoiceOver (macOS) or NVDA (Windows) | ### Screen Reader Testing (VoiceOver on macOS) | Action | Shortcut | |---|---| | Turn on/off VoiceOver | Cmd + F5 | | Navigate next element | VO + Right Arrow (VO = Ctrl + Option) | | Navigate previous | VO + Left Arrow | | Activate element | VO + Space | | Read current element | VO + F3 | | Open rotor (landmarks, headings) | VO + U | Verify: Every interactive element reachable by Tab/arrows. Buttons announce label + role. Expanded/collapsed state announced. Dynamic content announced via `aria-live`. Form inputs announce label + required + errors. Heading hierarchy logical. --- ## AI-Friendly Design ply is built for AI code generation: 1. Single-dash class names read like English — `units-row`, `equal-height`, `padding`, `border-radius` 2. No abbreviation guessing — `padding-lg` not `pl-6`, `margin-top` not `mt-4` 3. 458 documented classes in `ply-classes.json` — machine-readable reference 4. Semantic HTML first — auto-styled elements reduce class clutter 5. AI-friendly aliases — `btn-lg`/`btn-big`, `btn-sm`/`btn-small`, `alert`/`tools-alert` all work ### Alias Table | Short | Long | |---|---| | `alert` | `tools-alert` | | `alert-blue` | `tools-alert-blue` | | `message` | `tools-message` | | `btn-lg` | `btn-big` | | `btn-sm` | `btn-small` | | `btn-xs` | `btn-smaller` | | `input-lg` | `input-big` | | `input-sm` | `input-small` | | `input-xs` | `input-smaller` | | `li.active` | `li.on` (navbar) | | `bg-black` | `background-black` | | `bg-white` | `background-white` | --- ## Anti-Patterns - DON'T use Tailwind, Bootstrap, or other frameworks with ply - DON'T skip semantic HTML — use `<nav>`, `<code>`, `<table>`, `<details>`, `<dialog>` before `<div>` - DON'T invent class names — only use classes from `ply-classes.json` - DON'T use `role="button"` on links — use `<button>` - DON'T put `unit-` outside `units-row` - DON'T hard-code colors — use `var(--ply-*)` custom properties - DON'T forget the `.form` wrapper on forms - DON'T override `outline: none` on interactive elements — it breaks focus visibility

Main Content

Dashboard

Card Title