mirror of
https://github.com/github/awesome-copilot.git
synced 2026-04-11 02:35:55 +00:00
feat(instructions): update security, a11y, and performance to 2025-2026 standards (#1270)
* feat(instructions): update security, a11y, and performance to 2025-2026 standards Security: OWASP 2025 (55 anti-patterns, AI/LLM section, 6 frameworks) Accessibility: WCAG 2.2 AA (38 anti-patterns, legal context EAA/ADA, 4 frameworks) Performance: CWV (50 anti-patterns, Next.js 16, Angular 20, modern APIs) * fix(instructions): use globalThis.scheduler to prevent ReferenceError Access scheduler via globalThis to safely handle environments where the Scheduling API is not declared as a global variable. * fix(instructions): correct regex patterns and harden SSRF example - AU1: anchor jwt.verify lookahead inside parentheses - AU2: anchor jwt.sign lookahead, add expiresIn alternative - AU7: fix greedy .* before negative lookahead in OAuth state check - I5: resolve all DNS records, add TOCTOU production note - K2: add closing delimiters and multi-digit support to tabindex regex * fix(instructions): enhance SSRF IP validation with IPv4-mapped IPv6 Normalize IPv4-mapped IPv6 addresses (::ffff:127.0.0.1) before checking private ranges, preventing bypass via mapped addresses. * fix(instructions): add noscript fallback for deferred CSS pattern Without JS, the media="print" + onload pattern leaves the stylesheet inactive. The noscript tag loads it normally when JS is disabled. * fix(instructions): add execFileSync to I3 command injection detection The BAD example uses execFileSync but the regex only matched exec, execSync, and execFile — missing the sync variant. * fix(instructions): cover full IPv6 link-local range in SSRF check fe80::/10 spans fe80-febf (fe8*, fe9*, fea*, feb*). Previous regex only matched fe80::. Also use normalized variable for consistency. * fix(instructions): adjust SSRF wording and downgrade reduced-motion severity - SSRF: replace "full DNS/IP validation" with accurate wording that acknowledges TOCTOU limitation - V5: downgrade prefers-reduced-motion from IMPORTANT to SUGGESTION, remove 2.2.2 (A) reference since it's an AAA enhancement * fix(instructions): rename AU4 heading to include SHA-256 The heading said "Weak Password Hash (MD5/SHA1)" but the detection regex and BAD example both use SHA-256. Renamed to "Fast Hash for Passwords" which better describes the actual anti-pattern. * fix(instructions): clarify WCAG 2.2 SC 4.1.1 status as obsolete SC 4.1.1 Parsing is still present in the WCAG 2.2 spec but marked as obsolete (always satisfied). Changed wording from "removed" to "obsolete" for accuracy. * fix(instructions): rename I1 example vars to avoid TS redeclaration Copy-pasting the I1 SQL injection example as a single block failed with a TypeScript redeclaration error because both BAD and GOOD snippets used `const result`. Rename to `unsafeResult`/`safeResult` so the block remains copy-pasteable into a single scope. * fix(instructions): migrate I3 example to async execFile with bounds The I3 command injection example used `execFileSync` in both BAD and GOOD paths, which (a) redeclared `const output` in the same block and (b) blocks the Node event loop in server handlers, amplifying DoS impact. Switch the GOOD/BEST paths to a promisified `execFile` call with explicit `timeout` and `maxBuffer` bounds, and rename variables to `unsafeOutput`/`safeOutput` so the snippet stays copy-pasteable. Add a trailing note recommending async child_process APIs for server code. * fix(instructions): align AU6 heading with session fixation example The AU6 heading claimed "Session Not Invalidated on Password Change" but the mitigation example showed `req.session.regenerate`, which is the canonical defense against session fixation on login rather than bulk invalidation after a credential change. Rename the anti-pattern to "Missing Session Regeneration on Login (Session Fixation)" so it matches the example, and add a trailing note pointing to the complementary practice of invalidating other active sessions for the user on password change (e.g., via a `tokenVersion` counter). * fix(instructions): make L1 critical CSS pattern CSP-compatible The L1 "GOOD" snippet relied on an inline `onload="this.media='all'"` handler on a `<link>` tag. Under a strict CSP that disallows `'unsafe-inline'` / `script-src-attr 'unsafe-inline'`, inline event handlers are blocked, so the stylesheet would never activate and users would hit a styling regression. Replace the pattern with build-time critical CSS extraction (Critters/Beasties/Next.js `optimizeCss`) plus a normal `<link rel="preload" as="style">` and standard `<link rel="stylesheet">`. Add a trailing note explaining why the older inline-onload trick breaks under strict CSP and how to defer non-critical CSS with an external script when deferral is truly needed.
This commit is contained in:
Gonzalo Fleming
GitHub
@@ -46,9 +46,11 @@
|
|||||||
|
|
||||||
# queston - intentional misspelling example in skills/arize-dataset/SKILL.md demonstrating typo detection in field names
|
# queston - intentional misspelling example in skills/arize-dataset/SKILL.md demonstrating typo detection in field names
|
||||||
|
|
||||||
|
# nin - MongoDB $nin operator in security instructions NoSQL injection detection regex
|
||||||
|
|
||||||
# Vertexes - FreeCAD shape sub-elements used as property of obj.Shape
|
# Vertexes - FreeCAD shape sub-elements used as property of obj.Shape
|
||||||
|
|
||||||
ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes
|
ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE,FillIn,alle,vai,LOD,InOut,pixelX,aNULL,Wee,Sherif,queston,Vertexes,nin
|
||||||
|
|
||||||
# Skip certain files and directories
|
# Skip certain files and directories
|
||||||
|
|
||||||
|
|||||||
@@ -21,7 +21,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on
|
|||||||
| [.NET Framework Development](../instructions/dotnet-framework.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md) | Guidance for working with .NET Framework projects. Includes project structure, C# language version, NuGet management, and best practices. |
|
| [.NET Framework Development](../instructions/dotnet-framework.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-framework.instructions.md) | Guidance for working with .NET Framework projects. Includes project structure, C# language version, NuGet management, and best practices. |
|
||||||
| [.NET Framework Upgrade Specialist](../instructions/dotnet-upgrade.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md) | Specialized agent for comprehensive .NET framework upgrades with progressive tracking and validation |
|
| [.NET Framework Upgrade Specialist](../instructions/dotnet-upgrade.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-upgrade.instructions.md) | Specialized agent for comprehensive .NET framework upgrades with progressive tracking and validation |
|
||||||
| [.NET MAUI](../instructions/dotnet-maui.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md) | .NET MAUI component and application patterns |
|
| [.NET MAUI](../instructions/dotnet-maui.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-maui.instructions.md) | .NET MAUI component and application patterns |
|
||||||
| [Accessibility instructions](../instructions/a11y.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md) | Guidance for creating more accessible code |
|
| [Accessibility Standards](../instructions/a11y.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fa11y.instructions.md) | Comprehensive web accessibility standards based on WCAG 2.2 AA, with 38+ anti-patterns, legal enforcement context (EAA, ADA Title II), WAI-ARIA patterns, and framework-specific fixes for modern web frameworks and libraries. |
|
||||||
| [Agent Safety & Governance](../instructions/agent-safety.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-safety.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-safety.instructions.md) | Guidelines for building safe, governed AI agent systems. Apply when writing code that uses agent frameworks, tool-calling LLMs, or multi-agent orchestration to ensure proper safety boundaries, policy enforcement, and auditability. |
|
| [Agent Safety & Governance](../instructions/agent-safety.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-safety.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-safety.instructions.md) | Guidelines for building safe, governed AI agent systems. Apply when writing code that uses agent frameworks, tool-calling LLMs, or multi-agent orchestration to ensure proper safety boundaries, policy enforcement, and auditability. |
|
||||||
| [Agent Skills File Guidelines](../instructions/agent-skills.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md) | Guidelines for creating high-quality Agent Skills for GitHub Copilot |
|
| [Agent Skills File Guidelines](../instructions/agent-skills.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fagent-skills.instructions.md) | Guidelines for creating high-quality Agent Skills for GitHub Copilot |
|
||||||
| [AI Prompt Engineering & Safety Best Practices](../instructions/ai-prompt-engineering-safety-best-practices.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md) | Comprehensive best practices for AI prompt engineering, safety frameworks, bias mitigation, and responsible AI usage for Copilot and LLMs. |
|
| [AI Prompt Engineering & Safety Best Practices](../instructions/ai-prompt-engineering-safety-best-practices.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fai-prompt-engineering-safety-best-practices.instructions.md) | Comprehensive best practices for AI prompt engineering, safety frameworks, bias mitigation, and responsible AI usage for Copilot and LLMs. |
|
||||||
@@ -135,7 +135,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on
|
|||||||
| [Object Calisthenics Rules](../instructions/object-calisthenics.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fobject-calisthenics.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fobject-calisthenics.instructions.md) | Enforces Object Calisthenics principles for business domain code to ensure clean, maintainable, and robust code |
|
| [Object Calisthenics Rules](../instructions/object-calisthenics.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fobject-calisthenics.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fobject-calisthenics.instructions.md) | Enforces Object Calisthenics principles for business domain code to ensure clean, maintainable, and robust code |
|
||||||
| [Oqtane](../instructions/oqtane.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foqtane.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foqtane.instructions.md) | Oqtane Module patterns |
|
| [Oqtane](../instructions/oqtane.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foqtane.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Foqtane.instructions.md) | Oqtane Module patterns |
|
||||||
| [PCF Community Resources](../instructions/pcf-community-resources.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-community-resources.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-community-resources.instructions.md) | PCF community resources including gallery, videos, blogs, and development tools |
|
| [PCF Community Resources](../instructions/pcf-community-resources.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-community-resources.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-community-resources.instructions.md) | PCF community resources including gallery, videos, blogs, and development tools |
|
||||||
| [Performance Optimization Best Practices](../instructions/performance-optimization.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md) | The most comprehensive, practical, and engineer-authored performance optimization instructions for all languages, frameworks, and stacks. Covers frontend, backend, and database best practices with actionable guidance, scenario-based checklists, troubleshooting, and pro tips. |
|
| [Performance Standards](../instructions/performance-optimization.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md) | Comprehensive web performance standards based on Core Web Vitals (LCP, INP, CLS), with 50+ anti-patterns, detection regex, framework-specific fixes for modern web frameworks, and modern API guidance. |
|
||||||
| [PHP MCP Server Development Best Practices](../instructions/php-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fphp-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fphp-mcp-server.instructions.md) | Best practices for building Model Context Protocol servers in PHP using the official PHP SDK with attribute-based discovery and multiple transport options |
|
| [PHP MCP Server Development Best Practices](../instructions/php-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fphp-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fphp-mcp-server.instructions.md) | Best practices for building Model Context Protocol servers in PHP using the official PHP SDK with attribute-based discovery and multiple transport options |
|
||||||
| [Playwright .NET Test Generation Instructions](../instructions/playwright-dotnet.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-dotnet.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-dotnet.instructions.md) | Playwright .NET test generation instructions |
|
| [Playwright .NET Test Generation Instructions](../instructions/playwright-dotnet.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-dotnet.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-dotnet.instructions.md) | Playwright .NET test generation instructions |
|
||||||
| [Playwright Python Test Generation Instructions](../instructions/playwright-python.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-python.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-python.instructions.md) | Playwright Python AI test generation instructions based on official documentation. |
|
| [Playwright Python Test Generation Instructions](../instructions/playwright-python.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-python.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-python.instructions.md) | Playwright Python AI test generation instructions based on official documentation. |
|
||||||
@@ -165,7 +165,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on
|
|||||||
| [Rust Coding Conventions and Best Practices](../instructions/rust.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust.instructions.md) | Rust programming language coding conventions and best practices |
|
| [Rust Coding Conventions and Best Practices](../instructions/rust.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust.instructions.md) | Rust programming language coding conventions and best practices |
|
||||||
| [Rust MCP Server Development Best Practices](../instructions/rust-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust-mcp-server.instructions.md) | Best practices for building Model Context Protocol servers in Rust using the official rmcp SDK with async/await patterns |
|
| [Rust MCP Server Development Best Practices](../instructions/rust-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust-mcp-server.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Frust-mcp-server.instructions.md) | Best practices for building Model Context Protocol servers in Rust using the official rmcp SDK with async/await patterns |
|
||||||
| [Scala Best Practices](../instructions/scala2.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fscala2.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fscala2.instructions.md) | Scala 2.12/2.13 programming language coding conventions and best practices following Databricks style guide for functional programming, type safety, and production code quality. |
|
| [Scala Best Practices](../instructions/scala2.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fscala2.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fscala2.instructions.md) | Scala 2.12/2.13 programming language coding conventions and best practices following Databricks style guide for functional programming, type safety, and production code quality. |
|
||||||
| [Secure Coding and OWASP Guidelines](../instructions/security-and-owasp.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md) | Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices. |
|
| [Security Standards](../instructions/security-and-owasp.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md) | Comprehensive secure coding standards based on OWASP Top 10 2025, with 55+ anti-patterns, detection regex, framework-specific fixes for modern web and backend frameworks, and AI/LLM security guidance. |
|
||||||
| [Self-explanatory Code Commenting Instructions](../instructions/self-explanatory-code-commenting.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fself-explanatory-code-commenting.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fself-explanatory-code-commenting.instructions.md) | Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments. |
|
| [Self-explanatory Code Commenting Instructions](../instructions/self-explanatory-code-commenting.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fself-explanatory-code-commenting.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fself-explanatory-code-commenting.instructions.md) | Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments. |
|
||||||
| [Shell Scripting Guidelines](../instructions/shell.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshell.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshell.instructions.md) | Shell scripting best practices and conventions for bash, sh, zsh, and other shells |
|
| [Shell Scripting Guidelines](../instructions/shell.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshell.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fshell.instructions.md) | Shell scripting best practices and conventions for bash, sh, zsh, and other shells |
|
||||||
| [Spec Driven Workflow v1](../instructions/spec-driven-workflow-v1.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspec-driven-workflow-v1.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspec-driven-workflow-v1.instructions.md) | Specification-Driven Workflow v1 provides a structured approach to software development, ensuring that requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented and validated. |
|
| [Spec Driven Workflow v1](../instructions/spec-driven-workflow-v1.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspec-driven-workflow-v1.instructions.md)<br />[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fspec-driven-workflow-v1.instructions.md) | Specification-Driven Workflow v1 provides a structured approach to software development, ensuring that requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented and validated. |
|
||||||
|
|||||||
@@ -1,307 +1,729 @@
|
|||||||
---
|
---
|
||||||
description: "Guidance for creating more accessible code"
|
applyTo: '**'
|
||||||
applyTo: "**"
|
description: 'Comprehensive web accessibility standards based on WCAG 2.2 AA, with 38+ anti-patterns, legal enforcement context (EAA, ADA Title II), WAI-ARIA patterns, and framework-specific fixes for modern web frameworks and libraries.'
|
||||||
---
|
---
|
||||||
|
|
||||||
# Accessibility instructions
|
# Accessibility Standards
|
||||||
|
|
||||||
You are an expert in accessibility with deep software engineering expertise.
|
Comprehensive accessibility rules for web application development. Every anti-pattern includes a severity classification, detection method, WCAG 2.2 reference, and corrective code examples.
|
||||||
|
|
||||||
## Non-negotiables (MUST)
|
**Severity levels:**
|
||||||
|
|
||||||
- Conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
|
- **CRITICAL** — Users cannot access content at all. Must be fixed before merge.
|
||||||
- Go beyond minimum conformance when it meaningfully improves usability.
|
- **IMPORTANT** — Significant barrier for assistive technology users. Fix in same sprint.
|
||||||
- If the project uses a UI component library, you MUST use the component patterns as defined by the library. Do not recreate patterns.
|
- **SUGGESTION** — Improves usability for assistive technology. Plan for a future iteration.
|
||||||
- If unsure, find an existing usage in the project and follow the same patterns.
|
|
||||||
- Ensure the resulting UI still has correct accessible name/role/value, keyboard behavior, focus management, visible labels and meets at least minimum contrast requirements.
|
|
||||||
- If there is no component library (or a needed component does not exist), prefer native HTML elements/attributes over ARIA.
|
|
||||||
- Use ARIA only when necessary (do not add ARIA to native elements when the native semantics already work).
|
|
||||||
- Ensure correct accessible **name, role, value, states, and properties**.
|
|
||||||
- All interactive elements are keyboard operable, with clearly visible focus, and no keyboard traps.
|
|
||||||
- Do not claim the output is “fully accessible”.
|
|
||||||
|
|
||||||
## Inclusive language (MUST)
|
---
|
||||||
|
|
||||||
- Use respectful, inclusive, people-first language in any user-facing text.
|
## WCAG 2.2 Quick Reference (AA Level)
|
||||||
- Avoid stereotypes or assumptions about ability, cognition, or experience.
|
|
||||||
|
|
||||||
## Cognitive load (SHOULD)
|
### Perceivable
|
||||||
|
|
||||||
- Prefer plain language.
|
| Criterion | Level | Summary |
|
||||||
- Use consistent page structure (landmarks).
|
|-----------|-------|---------|
|
||||||
- Keep navigation order consistent.
|
| 1.1.1 Non-text Content | A | All non-text content has a text alternative. Decorative images use `alt=""`. |
|
||||||
- Keep the interface clean and simple (avoid unnecessary distractions).
|
| 1.2.1 Audio/Video-only | A | Provide transcript (audio) or text alternative (video). |
|
||||||
|
| 1.2.2 Captions (Prerecorded) | A | All prerecorded video has synchronized captions. |
|
||||||
|
| 1.3.1 Info and Relationships | A | Structure (headings, lists, tables, labels, landmarks) programmatically conveyed. |
|
||||||
|
| 1.3.2 Meaningful Sequence | A | DOM reading order matches visual order. |
|
||||||
|
| 1.3.3 Sensory Characteristics | A | Instructions don't rely solely on shape, size, position, or sound. |
|
||||||
|
| 1.3.4 Orientation | AA | Content not restricted to single orientation unless essential. |
|
||||||
|
| 1.3.5 Identify Input Purpose | AA | Input fields have `autocomplete` attributes for user data (name, email, tel). |
|
||||||
|
| 1.4.1 Use of Color | A | Color is not the only means of conveying info. |
|
||||||
|
| 1.4.3 Contrast (Minimum) | AA | Text: 4.5:1 normal, 3:1 large (18pt / 14pt bold). |
|
||||||
|
| 1.4.4 Resize Text | AA | Text resizable to 200% without loss of content. |
|
||||||
|
| 1.4.10 Reflow | AA | Content reflows at 320px CSS width (no horizontal scroll). |
|
||||||
|
| 1.4.11 Non-text Contrast | AA | UI components and graphics: 3:1 against adjacent colors. |
|
||||||
|
| 1.4.12 Text Spacing | AA | No loss of content with overridden line-height (1.5x), spacing. |
|
||||||
|
| 1.4.13 Content on Hover/Focus | AA | Tooltips: dismissible, hoverable, persistent. |
|
||||||
|
|
||||||
## Structure and semantics
|
### Operable
|
||||||
|
|
||||||
### Page structure (MUST)
|
| Criterion | Level | Summary |
|
||||||
|
|-----------|-------|---------|
|
||||||
|
| 2.1.1 Keyboard | A | All functionality operable via keyboard. |
|
||||||
|
| 2.1.2 No Keyboard Trap | A | User can navigate away from any component using keyboard. |
|
||||||
|
| 2.2.1 Timing Adjustable | A | Time limits can be extended or disabled. |
|
||||||
|
| 2.2.2 Pause, Stop, Hide | A | Auto-updating content can be paused. |
|
||||||
|
| 2.3.1 Three Flashes | A | No content flashes more than 3 times per second. |
|
||||||
|
| 2.4.1 Bypass Blocks | A | Skip link to bypass repeated navigation. |
|
||||||
|
| 2.4.2 Page Titled | A | Pages have descriptive `<title>`. |
|
||||||
|
| 2.4.3 Focus Order | A | Focus order preserves meaning and operability. |
|
||||||
|
| 2.4.4 Link Purpose | A | Link purpose determinable from text or context. |
|
||||||
|
| 2.4.6 Headings and Labels | AA | Headings and labels describe topic or purpose. |
|
||||||
|
| 2.4.7 Focus Visible | AA | Keyboard focus indicator is visible. |
|
||||||
|
| 2.4.11 Focus Not Obscured | AA | Focused element not entirely hidden by sticky headers/footers. *(New in 2.2)* |
|
||||||
|
| 2.5.1 Pointer Gestures | A | Multi-point gestures have single-pointer alternative. |
|
||||||
|
| 2.5.2 Pointer Cancellation | A | Activation on up-event, not down-event. |
|
||||||
|
| 2.5.3 Label in Name | A | Accessible name contains the visible label text. |
|
||||||
|
| 2.5.4 Motion Actuation | A | Device motion has UI alternative and can be disabled. |
|
||||||
|
| 2.5.7 Dragging Movements | AA | Drag-and-drop has click/tap alternative. *(New in 2.2)* |
|
||||||
|
| 2.5.8 Target Size (Minimum) | AA | Touch targets at least 24x24 CSS px. *(New in 2.2)* |
|
||||||
|
|
||||||
- Use landmarks (`header`, `nav`, `main`, `footer`) appropriately.
|
### Understandable
|
||||||
- Use headings to introduce new sections of content; avoid skipping heading levels.
|
|
||||||
- Prefer one `h1` for the page topic. Generally, the first heading within the `main` element / landmark.
|
|
||||||
|
|
||||||
### Page title (SHOULD)
|
| Criterion | Level | Summary |
|
||||||
|
|-----------|-------|---------|
|
||||||
|
| 3.1.1 Language of Page | A | `<html lang="...">` set correctly. |
|
||||||
|
| 3.1.2 Language of Parts | AA | Content in different language marked with `lang` attribute. |
|
||||||
|
| 3.2.1 On Focus | A | Focus doesn't trigger unexpected context change. |
|
||||||
|
| 3.2.2 On Input | A | Changing input doesn't auto-trigger unexpected context change. |
|
||||||
|
| 3.2.6 Consistent Help | A | Help mechanisms in same relative order across pages. *(New in 2.2)* |
|
||||||
|
| 3.3.1 Error Identification | A | Errors described to user in text. |
|
||||||
|
| 3.3.2 Labels or Instructions | A | Labels or instructions provided for user input. |
|
||||||
|
| 3.3.3 Error Suggestion | AA | Suggest corrections for detected errors. |
|
||||||
|
| 3.3.4 Error Prevention | AA | Submissions are reversible, checked, or confirmed. |
|
||||||
|
| 3.3.7 Redundant Entry | A | Don't re-ask for info already provided in same process. *(New in 2.2)* |
|
||||||
|
| 3.3.8 Accessible Authentication (Minimum) | AA | No cognitive function test (puzzle CAPTCHA). Allow paste and autofill. *(New in 2.2)* |
|
||||||
|
|
||||||
- Set a descriptive `<title>`.
|
### Robust
|
||||||
- Prefer: “Unique page - section - site”.
|
|
||||||
|
|
||||||
## Keyboard and focus
|
| Criterion | Level | Summary |
|
||||||
|
|-----------|-------|---------|
|
||||||
|
| 4.1.2 Name, Role, Value | A | All UI components have accessible name, role, and state. |
|
||||||
|
| 4.1.3 Status Messages | AA | Status messages announced by screen readers without receiving focus. |
|
||||||
|
|
||||||
### Core rules (MUST)
|
> **Note:** 4.1.1 Parsing is obsolete in WCAG 2.2 (always satisfied). Issues it covered are now addressed by 1.3.1 and 4.1.2.
|
||||||
|
|
||||||
- All interactive elements are keyboard operable.
|
> **New AAA criteria in 2.2** (not required for AA, but recommended): 2.4.12 Focus Not Obscured (Enhanced), 2.4.13 Focus Appearance, 3.3.9 Accessible Authentication (Enhanced).
|
||||||
- Tab order follows reading order and is predictable.
|
|
||||||
- Focus is always visible.
|
|
||||||
- Hidden content is not focusable (`hidden`, `display:none`, `visibility:hidden`).
|
|
||||||
- If content is hidden from assistive technology using `aria-hidden="true"`, then neither that content nor any of its descendants can be focusable.
|
|
||||||
- Static content MUST NOT be tabbable.
|
|
||||||
- Exception: if an element needs programmatic focus, use `tabindex="-1"`.
|
|
||||||
|
|
||||||
### Skip link / bypass blocks (MUST)
|
> **Looking ahead:** WCAG 3.0 (W3C Accessibility Guidelines) is in Working Draft (March 2026). It replaces pass/fail with Bronze/Silver/Gold conformance and "Outcomes" instead of "Success Criteria." It is NOT yet a standard — continue targeting WCAG 2.2 AA.
|
||||||
|
|
||||||
Provide a skip link as the first focusable element.
|
## Legal Enforcement Context (2026)
|
||||||
|
|
||||||
|
- **European Accessibility Act (EAA)**: Enforced since June 2025 across all 27 EU member states. Applies to digital products and services. Fines up to EUR 3 million. References EN 301 549 (maps to WCAG 2.1 AA).
|
||||||
|
- **ADA Title II (US)**: Digital accessibility rule effective April 2026 for state/local governments serving 50,000+ people (April 2027 for smaller entities). Requires WCAG 2.1 AA.
|
||||||
|
- **Section 508 (US Federal)**: References WCAG 2.0 AA (refresh to 2.1/2.2 expected).
|
||||||
|
|
||||||
|
**Target**: WCAG 2.2 AA covers all current legal requirements (superset of 2.1 AA and 2.0 AA).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Five Rules of ARIA
|
||||||
|
|
||||||
|
1. **Prefer native HTML** — Use `<button>` not `<div role="button">`. Native elements have built-in keyboard, focus, and semantics.
|
||||||
|
2. **Don't change native semantics** — Don't add `role="heading"` to a `<button>`. Use the correct element.
|
||||||
|
3. **All ARIA controls must be keyboard operable** — If `role="button"`, handle Enter and Space key events.
|
||||||
|
4. **Don't use `aria-hidden="true"` on focusable elements** — Hidden from assistive tech but still focusable creates a "ghost" element.
|
||||||
|
5. **All interactive elements need an accessible name** — Via label, `aria-label`, `aria-labelledby`, or visible text content.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Semantic HTML Anti-Patterns (S1-S8)
|
||||||
|
|
||||||
|
### S1: Missing `lang` Attribute on `<html>`
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `<html` without `lang=`
|
||||||
|
- **WCAG**: 3.1.1 (A)
|
||||||
|
|
||||||
```html
|
```html
|
||||||
<header>
|
<!-- BAD -->
|
||||||
<a href="#maincontent" class="sr-only">Skip to main content</a>
|
<html>
|
||||||
<!-- header content -->
|
|
||||||
</header>
|
<!-- GOOD -->
|
||||||
<nav>
|
<html lang="en">
|
||||||
<!-- navigation -->
|
```
|
||||||
</nav>
|
|
||||||
<main id="maincontent" tabindex="-1">
|
Next.js: Set in `app/layout.tsx`. Angular: Set in `src/index.html`. Vue/Nuxt: Set in `app.vue` or `nuxt.config`.
|
||||||
<h1><!-- page title --></h1>
|
|
||||||
<!-- content -->
|
### S2: Multiple `<h1>` Per Page
|
||||||
</main>
|
|
||||||
|
- **Severity**: SUGGESTION
|
||||||
|
- **Detection**: Multiple `<h1>` elements that make the page heading structure unclear
|
||||||
|
- **WCAG**: Best practice (supports 1.3.1)
|
||||||
|
|
||||||
|
Prefer one `<h1>` per page representing the main topic. Use `<h2>` for sections. Multiple `<h1>` elements are not a strict WCAG violation but can confuse screen reader navigation.
|
||||||
|
|
||||||
|
### S3: Heading Level Gaps
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `<h1>` followed by `<h3>` (skipping `<h2>`)
|
||||||
|
- **WCAG**: 1.3.1 (A)
|
||||||
|
|
||||||
|
Maintain logical nesting: `h1 > h2 > h3 > h4`. Style headings with CSS, not by choosing a different heading level.
|
||||||
|
|
||||||
|
### S4: Div Soup — No Landmark Elements
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Pages using only `<div>` without `<nav>`, `<main>`, `<header>`, `<footer>`
|
||||||
|
- **WCAG**: 1.3.1 (A), 2.4.1 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- GOOD -->
|
||||||
|
<header>...</header>
|
||||||
|
<nav aria-label="Main">...</nav>
|
||||||
|
<main>...</main>
|
||||||
|
<footer>...</footer>
|
||||||
|
```
|
||||||
|
|
||||||
|
### S5: Layout Tables Without `role="presentation"`
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `<table>` without `<th>`, `<caption>`, or `role="presentation"`
|
||||||
|
- **WCAG**: 1.3.1 (A)
|
||||||
|
|
||||||
|
Use CSS Grid/Flexbox for layout. If table must be used for layout, add `role="presentation"`.
|
||||||
|
|
||||||
|
### S6: Data Tables Without Headers
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `<table>` with data rows but no `<th>` elements
|
||||||
|
- **WCAG**: 1.3.1 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- GOOD -->
|
||||||
|
<table>
|
||||||
|
<caption>User list</caption>
|
||||||
|
<thead>
|
||||||
|
<tr><th scope="col">Name</th><th scope="col">Email</th></tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr><td>Alice</td><td>alice@example.com</td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
```
|
||||||
|
|
||||||
|
### S7: Non-Descriptive Link Text
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `>click here<|>read more<|>learn more<|>here<|>more<|>link<`
|
||||||
|
- **WCAG**: 2.4.4 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- BAD -->
|
||||||
|
<a href="/pricing">Click here</a>
|
||||||
|
|
||||||
|
<!-- GOOD -->
|
||||||
|
<a href="/pricing">View pricing plans</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
### S8: Interactive Elements Without Semantic HTML
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `<div.*(?:onClick|@click|\(click\))`
|
||||||
|
- **WCAG**: 4.1.2 (A)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// BAD — not focusable, no role, no keyboard support
|
||||||
|
<div onClick={handleClick}>Submit</div>
|
||||||
|
|
||||||
|
// GOOD
|
||||||
|
<button onClick={handleClick}>Submit</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ARIA Anti-Patterns (A1-A8)
|
||||||
|
|
||||||
|
### A1: Redundant ARIA on Native Elements
|
||||||
|
|
||||||
|
- **Severity**: SUGGESTION
|
||||||
|
- **Detection**: `<button.*role="button"|<nav.*role="navigation"|<a.*role="link"`
|
||||||
|
- **WCAG**: ARIA Rule 2
|
||||||
|
|
||||||
|
Remove redundant ARIA. `<button>` already has `role="button"`.
|
||||||
|
|
||||||
|
### A2: `aria-hidden="true"` on Focusable Element
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `aria-hidden="true"` on focusable elements (button, input, a, [tabindex])
|
||||||
|
- **WCAG**: ARIA Rule 4
|
||||||
|
|
||||||
|
Use `inert` attribute or remove from tab order entirely.
|
||||||
|
|
||||||
|
### A3: Missing Required ARIA Properties
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `role="tab"` without `aria-selected`, `role="checkbox"` without `aria-checked`
|
||||||
|
- **WCAG**: 4.1.2 (A)
|
||||||
|
|
||||||
|
Required per role: `tab` needs `aria-selected`/`aria-controls`; `combobox` needs `aria-expanded`/`aria-controls`; `slider` needs `aria-valuemin`/`aria-valuemax`/`aria-valuenow`; `checkbox` needs `aria-checked`.
|
||||||
|
|
||||||
|
### A4: Invalid ARIA Role Values
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `role="[^"]*"` with non-existent values
|
||||||
|
- **WCAG**: 4.1.2 (A)
|
||||||
|
|
||||||
|
Invalid roles are ignored by assistive technology. Common mistakes: `role="input"`, `role="text"`, misspellings.
|
||||||
|
|
||||||
|
### A5: ARIA Where Native HTML Works
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `role="button"` on `<div>`, `role="checkbox"` on `<div>`
|
||||||
|
- **WCAG**: ARIA Rule 1
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- BAD — requires manual keyboard, focus, and state management -->
|
||||||
|
<div role="checkbox" aria-checked="false" tabindex="0">Accept terms</div>
|
||||||
|
|
||||||
|
<!-- GOOD — all behavior built-in -->
|
||||||
|
<label><input type="checkbox" /> Accept terms</label>
|
||||||
|
```
|
||||||
|
|
||||||
|
### A6: Missing `aria-label` on Icon-Only Buttons
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `<button` with SVG/icon child and no text or `aria-label`
|
||||||
|
- **WCAG**: 4.1.2 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- GOOD -->
|
||||||
|
<button aria-label="Close dialog"><svg aria-hidden="true">...</svg></button>
|
||||||
|
```
|
||||||
|
|
||||||
|
### A7: `role="presentation"` on Focusable Elements
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `role="presentation"` on interactive elements
|
||||||
|
- **WCAG**: ARIA Rule 4
|
||||||
|
|
||||||
|
### A8: Missing Live Region for Dynamic Content
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Toast/notification components without `role="alert"`, `role="status"`, or `aria-live`
|
||||||
|
- **WCAG**: 4.1.3 (AA)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- GOOD — content announced when injected -->
|
||||||
|
<div role="status" aria-live="polite">Item saved successfully</div>
|
||||||
|
<!-- Use role="alert" (assertive) for errors -->
|
||||||
|
<div role="alert">Failed to save. Please try again.</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Keyboard and Focus Anti-Patterns (K1-K7)
|
||||||
|
|
||||||
|
### K1: `onClick` Without `onKeyDown` on Non-Native Elements
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `(?:onClick|@click|\(click\))` on `<div>` or `<span>` without keyboard handler
|
||||||
|
- **WCAG**: 2.1.1 (A)
|
||||||
|
|
||||||
|
Use `<button>` instead. If div is required: add `role="button"`, `tabIndex={0}`, and handle Enter/Space.
|
||||||
|
|
||||||
|
### K2: Positive `tabindex` Values
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `(?:tabindex="[1-9]\d*"|tabIndex=\{[1-9]\d*\})`
|
||||||
|
- **WCAG**: 2.4.3 (A)
|
||||||
|
|
||||||
|
Only use `tabindex="0"` (add to tab order) and `tabindex="-1"` (programmatic focus only).
|
||||||
|
|
||||||
|
### K3: Focus Trap Without Escape
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: Modal/overlay without Escape key handler or focus trapping
|
||||||
|
- **WCAG**: 2.1.2 (A)
|
||||||
|
|
||||||
|
Use native `<dialog>` with `showModal()` — it provides focus trapping, Escape-to-close, and focus return automatically. Use `inert` attribute on background content to prevent interaction outside the dialog (96%+ browser support). If custom implementation is needed: trap Tab within the dialog, close on Escape, return focus to the trigger element on close.
|
||||||
|
|
||||||
|
### K4: Missing Skip Link
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: No skip link as first focusable element
|
||||||
|
- **WCAG**: 2.4.1 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<a href="#main-content" class="skip-link">Skip to main content</a>
|
||||||
|
<nav>...</nav>
|
||||||
|
<main id="main-content" tabindex="-1">...</main>
|
||||||
```
|
```
|
||||||
|
|
||||||
```css
|
```css
|
||||||
.sr-only:not(:focus):not(:active) {
|
.skip-link { position: absolute; top: -40px; left: 0; padding: 8px 16px; background: #000; color: #fff; z-index: 100; }
|
||||||
clip: rect(0 0 0 0);
|
.skip-link:focus { top: 0; }
|
||||||
clip-path: inset(50%);
|
|
||||||
height: 1px;
|
|
||||||
overflow: hidden;
|
|
||||||
position: absolute;
|
|
||||||
white-space: nowrap;
|
|
||||||
width: 1px;
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Composite widgets (SHOULD)
|
### K5: `outline: none` Without Replacement
|
||||||
|
|
||||||
If a component uses arrow-key navigation within itself (tabs, listbox, menu-like UI, grid/date picker):
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `outline:\s*none|outline:\s*0\b` without `:focus-visible` replacement
|
||||||
- Provide one tab stop for the composite container or one child.
|
- **WCAG**: 2.4.7 (AA)
|
||||||
- Manage internal focus with either roving tabindex or `aria-activedescendant`.
|
|
||||||
|
|
||||||
Roving tabindex (SHOULD):
|
|
||||||
|
|
||||||
- Exactly one focusable item has `tabindex="0"`; all others are `-1`.
|
|
||||||
- Arrow keys move focus by swapping tabindex and calling `.focus()`.
|
|
||||||
|
|
||||||
`aria-activedescendant` (SHOULD):
|
|
||||||
|
|
||||||
- Container is implicitly focusable or has `tabindex="0"` and `aria-activedescendant="IDREF"`.
|
|
||||||
- Arrow keys update `aria-activedescendant`.
|
|
||||||
|
|
||||||
## Low vision and contrast (MUST)
|
|
||||||
|
|
||||||
### Contrast requirements (MUST)
|
|
||||||
|
|
||||||
- Text contrast: at least 4.5:1 (large text: 3:1).
|
|
||||||
- Large text is at least 24px regular or 18.66px bold.
|
|
||||||
- Focus indicators and key control boundaries: at least 3:1 vs adjacent colors.
|
|
||||||
- Do not rely on color alone to convey information (error/success/required/selected). Provide text and/or icons with accessible names.
|
|
||||||
|
|
||||||
### Color generation rules (MUST)
|
|
||||||
|
|
||||||
- Do not invent arbitrary colors.
|
|
||||||
- Use project-approved design tokens (CSS variables).
|
|
||||||
- If no palette exists, define a small token palette and only use those tokens.
|
|
||||||
- Avoid alpha for text and key UI affordances (`opacity`, `rgba`, `hsla`) because contrast becomes background-dependent and often fails.
|
|
||||||
- Ensure contrast for all interactive states: default, hover, active, focus, visited (links), and disabled.
|
|
||||||
|
|
||||||
### Safe defaults when unsure (SHOULD)
|
|
||||||
|
|
||||||
- Prefer very dark text on very light backgrounds, or the reverse.
|
|
||||||
- Avoid mid-gray text on white; muted text should still meet 4.5:1.
|
|
||||||
|
|
||||||
### Tokenized palette contract (SHOULD)
|
|
||||||
|
|
||||||
- Define and use tokens like: `--color-bg`, `--color-text`, `--color-muted-text`, `--color-link`, `--color-border`, `--color-focus`, `--color-danger`, `--color-success`.
|
|
||||||
- Only assign UI colors via these tokens (avoid scattered inline hex values).
|
|
||||||
|
|
||||||
### Verification (MUST)
|
|
||||||
|
|
||||||
Contrast verification is covered by the Final verification checklist.
|
|
||||||
|
|
||||||
## High contrast / forced colors mode (MUST)
|
|
||||||
|
|
||||||
### Support OS-level accessibility features (MUST)
|
|
||||||
|
|
||||||
- Never override or disrupt OS accessibility settings.
|
|
||||||
- The UI MUST adapt to High Contrast / Forced Colors mode automatically.
|
|
||||||
- Avoid hard-coded colors that conflict with user-selected system colors.
|
|
||||||
|
|
||||||
### Use the `forced-colors` media query when needed (SHOULD)
|
|
||||||
|
|
||||||
Use `@media (forced-colors: active)` only when system defaults are not sufficient.
|
|
||||||
|
|
||||||
```css
|
```css
|
||||||
@media (forced-colors: active) {
|
/* GOOD */
|
||||||
/* Example: Replace box-shadow (suppressed in forced-colors) with a border */
|
button:focus-visible { outline: 2px solid #005fcc; outline-offset: 2px; }
|
||||||
.button {
|
|
||||||
border: 2px solid ButtonBorder;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/* if using box-shadow for a focus style, also use a transparent outline
|
|
||||||
so that the outline will render when the high contrast setting is enabled */
|
|
||||||
.button:focus {
|
|
||||||
box-shadow: 0 0 4px 3px rgba(90, 50, 200, .7);
|
|
||||||
outline: 2px solid transparent;
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
In Forced Colors mode, avoid relying on:
|
### K6: Mouse-Only Interactions
|
||||||
|
|
||||||
- Box shadows
|
- **Severity**: IMPORTANT
|
||||||
- Decorative gradients
|
- **Detection**: `onMouseOver|onMouseEnter|@mouseenter` without keyboard equivalent
|
||||||
|
- **WCAG**: 2.1.1 (A)
|
||||||
|
|
||||||
### Respect user color schemes in forced colors (MUST)
|
Pair hover with focus events. Use `onFocus`/`onBlur` alongside `onMouseEnter`/`onMouseLeave`.
|
||||||
|
|
||||||
- Use system color keywords (e.g., `ButtonText`, `ButtonBorder`, `CanvasText`, `Canvas`).
|
### K7: Focus Not Returned After Modal Close
|
||||||
- Do not use fixed hex/RGB colors inside `@media (forced-colors: active)`.
|
|
||||||
|
|
||||||
### Do not disable forced colors (MUST)
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Dialog close without restoring focus to trigger
|
||||||
|
- **WCAG**: 2.4.3 (A)
|
||||||
|
|
||||||
- Do not use `forced-color-adjust: none` unless absolutely necessary and explicitly justified.
|
Store reference to trigger element. On modal close, call `triggerElement.focus()`.
|
||||||
- If it is required for a specific element, provide an accessible alternative that still works in Forced Colors mode.
|
|
||||||
|
|
||||||
### Icons (MUST)
|
---
|
||||||
|
|
||||||
- Icons MUST adapt to text color.
|
## Form Anti-Patterns (F1-F6)
|
||||||
- Prefer `currentColor` for SVG icon fills/strokes; avoid embedding fixed colors inside SVGs.
|
|
||||||
|
### F1: Input Without Associated Label
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `<input|<select|<textarea` without `<label>`, `aria-label`, or `aria-labelledby`
|
||||||
|
- **WCAG**: 1.3.1 (A), 3.3.2 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- GOOD -->
|
||||||
|
<label for="email">Email address</label>
|
||||||
|
<input id="email" type="email" placeholder="you@example.com" />
|
||||||
|
```
|
||||||
|
|
||||||
|
### F2: Error Messages Not Linked to Input
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: Error elements near inputs without `aria-describedby`
|
||||||
|
- **WCAG**: 3.3.1 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<input id="email" type="email" aria-describedby="email-error" aria-invalid="true" />
|
||||||
|
<span id="email-error" class="error">Invalid email format</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
### F3: Required Field Indicated Only by Color or `*`
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `required` or `*` without `aria-required="true"` or HTML `required`
|
||||||
|
- **WCAG**: 3.3.2 (A), 1.4.1 (A)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<label for="name">Name <span aria-hidden="true">*</span></label>
|
||||||
|
<input id="name" type="text" required />
|
||||||
|
<p class="form-note">Fields marked * are required</p>
|
||||||
|
```
|
||||||
|
|
||||||
|
### F4: No Error Summary or Focus on First Error
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Form submit handler without focus management on validation failure
|
||||||
|
- **WCAG**: 3.3.1 (A)
|
||||||
|
|
||||||
|
On submit failure, focus the first invalid field or show and focus an error summary.
|
||||||
|
|
||||||
|
### F5: CAPTCHA Without Accessible Alternative
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Puzzle/image CAPTCHAs without fallback; password fields with `autocomplete='off'` or paste-blocking JavaScript
|
||||||
|
- **WCAG**: 3.3.8 (AA)
|
||||||
|
|
||||||
|
Use reCAPTCHA v3 (invisible), hCaptcha accessibility mode, or alternative authentication. Never block paste or autofill on password fields — this violates WCAG 3.3.8.
|
||||||
|
|
||||||
|
### F6: Placeholder as Label
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `placeholder=` without accompanying `<label>`, `aria-label`, or `aria-labelledby`
|
||||||
|
- **WCAG**: 3.3.2 (A)
|
||||||
|
|
||||||
|
Always pair placeholder with a visible `<label>`. Placeholder is a hint, not a label.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Visual and Color Anti-Patterns (V1-V5)
|
||||||
|
|
||||||
|
### V1: Insufficient Text Contrast
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: Text color combinations below 4.5:1 (normal) or 3:1 (large)
|
||||||
|
- **WCAG**: 1.4.3 (AA)
|
||||||
|
|
||||||
```css
|
```css
|
||||||
svg {
|
/* BAD — #999 on #fff is ~2.5:1 */
|
||||||
fill: currentColor;
|
.text { color: #999; background: #fff; }
|
||||||
stroke: currentColor;
|
|
||||||
|
/* GOOD — #595959 on #fff is 7.0:1 */
|
||||||
|
.text { color: #595959; background: #fff; }
|
||||||
|
```
|
||||||
|
|
||||||
|
### V2: Information Conveyed by Color Alone
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: Error/success states distinguished only by color
|
||||||
|
- **WCAG**: 1.4.1 (A)
|
||||||
|
|
||||||
|
Add a secondary indicator: icon, text, pattern, underline, or border.
|
||||||
|
|
||||||
|
### V3: Fixed Font Sizes Preventing Resize
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `font-size:\s*[0-9]*px` (excluding root/base)
|
||||||
|
- **WCAG**: 1.4.4 (AA)
|
||||||
|
|
||||||
|
Use `rem` or `em` for font sizes. Base font can be `px`, but content fonts should be relative.
|
||||||
|
|
||||||
|
### V4: Content Not Reflowing at 320px
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Fixed-width containers, horizontal scroll at narrow widths
|
||||||
|
- **WCAG**: 1.4.10 (AA)
|
||||||
|
|
||||||
|
Use responsive layouts (Grid, Flexbox). Test at 320px CSS width. Avoid fixed-width containers.
|
||||||
|
|
||||||
|
### V5: Animation Without `prefers-reduced-motion`
|
||||||
|
|
||||||
|
- **Severity**: SUGGESTION
|
||||||
|
- **Detection**: `animation:|transition:` without `prefers-reduced-motion` media query
|
||||||
|
- **WCAG**: 2.3.3 (AAA)
|
||||||
|
|
||||||
|
Best practice and AAA enhancement. Gate non-essential animations behind `prefers-reduced-motion` so users who request less motion are not forced to experience interaction-triggered effects.
|
||||||
|
|
||||||
|
```css
|
||||||
|
@media (prefers-reduced-motion: no-preference) {
|
||||||
|
.card { transition: transform 0.3s ease; }
|
||||||
|
.card:hover { transform: scale(1.05); }
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Reflow (WCAG 2.2 SC 1.4.10) (MUST)
|
---
|
||||||
|
|
||||||
### Goal (MUST)
|
## Media Anti-Patterns (D1-D4)
|
||||||
|
|
||||||
Multi-line text must be able to fit within 320px wide containers or viewports, so that users do not need to scroll in two-dimensions to read sections of content.
|
### D1: Informational Image Without Alt Text
|
||||||
|
|
||||||
### Core principles (MUST)
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `<img|<Image` without `alt=` attribute
|
||||||
|
- **WCAG**: 1.1.1 (A)
|
||||||
|
|
||||||
- Preserve information and function: nothing essential is removed, obscured, or truncated.
|
Alt text decision tree: decorative = `alt=""`; contains text = include that text; functional = describe action; informational = describe content.
|
||||||
- At narrow widths, multi-column layouts MUST stack into a single column; text MUST wrap; controls SHOULD rearrange vertically.
|
|
||||||
- Users MUST NOT need to scroll left/right to read multi-line text.
|
|
||||||
- If content is collapsed in the narrow layout, the full content/function MUST be available within 1 click (e.g., overflow menu, dialog, tooltip).
|
|
||||||
|
|
||||||
### Engineering requirements (MUST)
|
### D2: Decorative Image with Non-Empty Alt
|
||||||
|
|
||||||
- Use responsive layout primitives (`flex`, `grid`) with fluid sizing; enable text wrapping.
|
- **Severity**: SUGGESTION
|
||||||
- Avoid fixed widths that force two-dimensional scrolling at 320px.
|
- **Detection**: Decorative images with meaningful alt text
|
||||||
- Avoid absolute positioning and `overflow: hidden` when it causes content loss, or would result in the obscuring of content at smaller viewport sizes.
|
- **WCAG**: 1.1.1 (A)
|
||||||
- Media and containers SHOULD NOT overflow the viewport at 320px (for example, prefer `max-width: 100%` for images/video/canvas/iframes).
|
|
||||||
- In flex/grid layouts, ensure children can shrink/wrap (common fix: `min-width: 0` on flex/grid children).
|
|
||||||
- Handle long strings (URLs, tokens) without forcing overflow (common fix: `overflow-wrap: anywhere` or equivalent).
|
|
||||||
- Ensure all interactive elements remain visible, reachable, and operable at 320px.
|
|
||||||
|
|
||||||
### Exceptions (SHOULD)
|
Use `alt=""` for decorative images. Add `aria-hidden="true"` for decorative SVGs.
|
||||||
|
|
||||||
If a component truly requires a two-dimensional layout for meaning/usage (e.g., large data tables, maps, diagrams, charts, games, presentations), allow horizontal scrolling only at the component level.
|
### D3: Video Without Captions
|
||||||
|
|
||||||
- The page as a whole MUST still reflow (unless the page layout truly requires two-dimensional layout for usage).
|
- **Severity**: CRITICAL
|
||||||
- The component MUST remain fully usable (all content reachable; controls operable).
|
- **Detection**: `<video` without `<track kind="captions">`
|
||||||
|
- **WCAG**: 1.2.2 (A)
|
||||||
|
|
||||||
## Controls and labels
|
```html
|
||||||
|
<video src="/tutorial.mp4" controls>
|
||||||
|
<track kind="captions" src="/tutorial-en.vtt" srclang="en" label="English" default />
|
||||||
|
</video>
|
||||||
|
```
|
||||||
|
|
||||||
### Visible labels (MUST)
|
### D4: Audio/Video Autoplay
|
||||||
|
|
||||||
- Every interactive element has a visible label.
|
- **Severity**: IMPORTANT
|
||||||
- The label cannot disappear while entering text or after the field has a value.
|
- **Detection**: `autoplay` attribute without `muted`
|
||||||
|
- **WCAG**: 1.4.2 (A)
|
||||||
|
|
||||||
### Voice access (MUST)
|
Never autoplay audio. If video autoplays, start muted with controls.
|
||||||
|
|
||||||
- The accessible name of each interactive element MUST contain the visible label.
|
---
|
||||||
- If using `aria-label`, include the visual label text.
|
|
||||||
- If multiple controls share the same visible label (e.g., many “Remove” buttons), use an `aria-label` that keeps the visible label text and adds context (e.g., “Remove item: Socks”).
|
|
||||||
|
|
||||||
## Forms
|
## Framework-Specific: React / Next.js (RX1-RX4)
|
||||||
|
|
||||||
### Labels and help text (MUST)
|
### RX1: Missing `htmlFor` on `<label>`
|
||||||
|
|
||||||
- Every form control has a programmatic label.
|
- **Severity**: IMPORTANT
|
||||||
- Prefer `<label for="...">`.
|
- **Detection**: `<label.*for="` in JSX (should be `htmlFor`)
|
||||||
- Labels describe the input purpose.
|
- **WCAG**: 1.3.1 (A), 3.3.2 (A)
|
||||||
- If help text exists, associate it with `aria-describedby`.
|
|
||||||
|
|
||||||
### Required fields (MUST)
|
### RX2: SPA Route Change Without Focus Management
|
||||||
|
|
||||||
- Indicate required fields visually (often `*`) and programmatically (`aria-required="true"`).
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Navigation without focus management or live region
|
||||||
|
- **WCAG**: 4.1.3 (AA)
|
||||||
|
|
||||||
### Errors and validation (MUST)
|
After route change, focus the main heading or announce the new page title via a live region. Next.js includes a built-in route announcer (since v13) that reads `document.title`, then `<h1>`, then pathname. Ensure every page has a unique `<title>`.
|
||||||
|
|
||||||
- Provide error messages that explain how to fix the issue.
|
### RX3: Fragment Root Causing Focus Loss on Re-render
|
||||||
- Use `aria-invalid="true"` for invalid fields; remove it when valid.
|
|
||||||
- Associate inline errors with the field via `aria-describedby`.
|
|
||||||
- Submit buttons SHOULD NOT be disabled solely to prevent submission.
|
|
||||||
- On submit with invalid input, focus the first invalid control.
|
|
||||||
|
|
||||||
## Graphics and images
|
- **Severity**: SUGGESTION
|
||||||
|
- **Detection**: `<>...</>` root with conditional rendering causing DOM restructuring
|
||||||
|
- **WCAG**: 2.4.3 (A)
|
||||||
|
|
||||||
All graphics include `img`, `svg`, icon fonts, and emojis.
|
Use `key` prop to preserve DOM identity, or manually restore focus with `useRef` + `useEffect`.
|
||||||
|
|
||||||
- Informative graphics MUST have meaningful alternatives.
|
### RX4: Injected HTML Without ARIA Consideration
|
||||||
- `img`: use `alt`.
|
|
||||||
- `svg`: prefer `role="img"` and `aria-label`/`aria-labelledby`.
|
|
||||||
- Decorative graphics MUST be hidden.
|
|
||||||
- `img`: `alt=""`.
|
|
||||||
- Other: `aria-hidden="true"`.
|
|
||||||
|
|
||||||
## Navigation and menus
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Rich text rendering without accessibility validation
|
||||||
|
- **WCAG**: 1.3.1 (A)
|
||||||
|
|
||||||
- Use semantic navigation: `<nav>` with lists and links.
|
Sanitize and validate injected HTML for heading hierarchy, alt text, and ARIA structure.
|
||||||
- Do not use `role="menu"` / `role="menubar"` for site navigation.
|
|
||||||
- For expandable navigation:
|
|
||||||
- Include button elements to toggle navigation and/or sub-navigations. Use `aria-expanded` on the button to indicate state.
|
|
||||||
- `Escape` MAY close open sub-navigations.
|
|
||||||
|
|
||||||
## Tables and grids
|
---
|
||||||
|
|
||||||
### Tables for static data (MUST)
|
## Framework-Specific: Angular (NG1-NG4)
|
||||||
|
|
||||||
- Use `<table>` for static tabular data.
|
### NG1: `(click)` on `<div>` Without Role and Keyboard Support
|
||||||
- Use `<th>` to associate headers.
|
|
||||||
- Column headers are in the first row.
|
|
||||||
- Row headers (when present) use `<th>` in each row.
|
|
||||||
|
|
||||||
### Grids for dynamic UIs (SHOULD)
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `(click)` on `<div>` or `<span>` without `role=`, `tabindex`, `(keydown)`
|
||||||
|
- **WCAG**: 2.1.1 (A), 4.1.2 (A)
|
||||||
|
|
||||||
- Use grid roles only for truly interactive/dynamic experiences.
|
Use `<button>`. If div required: add `role="button"`, `tabindex="0"`, `(keydown.enter)`, `(keydown.space)`.
|
||||||
- If using `role="grid"`, grid cells MUST be nested in rows so header/cell relationships are determinable.
|
|
||||||
- Use arrow navigation to navigate within the grid.
|
|
||||||
|
|
||||||
## Final verification checklist (MUST)
|
### NG2: Missing `cdkTrapFocus` in Modal Components
|
||||||
|
|
||||||
Before finalizing output, explicitly verify:
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Modal components without `cdkTrapFocus`
|
||||||
|
- **WCAG**: 2.1.2 (A)
|
||||||
|
|
||||||
- Structure and semantics: landmarks, headings, and one `h1` for the page topic.
|
```html
|
||||||
- Keyboard and focus: operable controls, visible focus, predictable tab order, no traps, skip link works.
|
<div class="modal" cdkTrapFocus [cdkTrapFocusAutoCapture]="true">...</div>
|
||||||
- Controls and labels: visible labels present and included in accessible names.
|
```
|
||||||
- Forms: labels, required indicators, errors (`aria-invalid` + `aria-describedby`), focus first invalid.
|
|
||||||
- Contrast: meets 4.5:1 / 3:1 thresholds, focus/boundaries meet 3:1, color not the only cue.
|
|
||||||
- Forced colors: does not break OS High Contrast / Forced Colors; uses system colors in `forced-colors: active`.
|
|
||||||
- Reflow: sections of content should be able to adjust to 320px width without the need for two-dimensional scrolling to read multi-line text; no content loss; controls remain operable.
|
|
||||||
- Graphics: informative alternatives; decorative graphics hidden.
|
|
||||||
- Tables/grids: tables use `<th>`; grids (when needed) are structured with rows and cells.
|
|
||||||
|
|
||||||
## Final note
|
Angular CDK's `Dialog` service handles focus trapping and restoration automatically.
|
||||||
|
|
||||||
Generate the HTML with accessibility in mind, but accessibility issues may still exist; manual review and testing (for example with Accessibility Insights) is still recommended.
|
### NG3: Route Change Without LiveAnnouncer
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Angular Router navigation without `LiveAnnouncer`
|
||||||
|
- **WCAG**: 4.1.3 (AA)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
router.events.pipe(filter(e => e instanceof NavigationEnd)).subscribe(() => {
|
||||||
|
liveAnnouncer.announce(titleService.getTitle(), 'polite');
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### NG4: Template-Driven Forms Without Accessible Validation
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: Forms showing errors without `[attr.aria-invalid]` or `[attr.aria-describedby]`
|
||||||
|
- **WCAG**: 3.3.1 (A), 3.3.3 (AA)
|
||||||
|
|
||||||
|
Bind `[attr.aria-invalid]` and `[attr.aria-describedby]` to form control state.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Framework-Specific: Vue (VU1-VU3)
|
||||||
|
|
||||||
|
### VU1: `@click` on Non-Interactive Element Without Role and Keyboard
|
||||||
|
|
||||||
|
- **Severity**: CRITICAL
|
||||||
|
- **Detection**: `@click` on `<div>` or `<span>` without `role=`, `tabindex`, `@keydown`
|
||||||
|
- **WCAG**: 2.1.1 (A), 4.1.2 (A)
|
||||||
|
|
||||||
|
Use `<button>`. Or add `role="button"`, `tabindex="0"`, `@keydown.enter`, `@keydown.space.prevent`.
|
||||||
|
|
||||||
|
### VU2: `v-if` Toggle Without Focus Management
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `v-if` toggling without managing focus via `nextTick`
|
||||||
|
- **WCAG**: 2.4.3 (A)
|
||||||
|
|
||||||
|
```vue
|
||||||
|
<script setup>
|
||||||
|
import { ref, watch, nextTick } from 'vue';
|
||||||
|
const showPanel = ref(false);
|
||||||
|
const panel = ref(null);
|
||||||
|
watch(showPanel, async (val) => {
|
||||||
|
if (val) { await nextTick(); panel.value?.focus(); }
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### VU3: `v-html` Injecting Content Without Accessible Structure
|
||||||
|
|
||||||
|
- **Severity**: IMPORTANT
|
||||||
|
- **Detection**: `v-html` rendering user or CMS content
|
||||||
|
- **WCAG**: 1.3.1 (A)
|
||||||
|
|
||||||
|
Sanitize and validate HTML for heading hierarchy, alt text, and ARIA structure before injection.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Keyboard Interaction Reference
|
||||||
|
|
||||||
|
| Key | Expected Behavior |
|
||||||
|
|-----|-------------------|
|
||||||
|
| `Tab` | Move focus to next focusable element in DOM order |
|
||||||
|
| `Shift+Tab` | Move focus to previous focusable element |
|
||||||
|
| `Enter` | Activate buttons and links |
|
||||||
|
| `Space` | Activate buttons, toggle checkboxes, select radio buttons |
|
||||||
|
| `Escape` | Close modals, dialogs, popovers, dropdowns |
|
||||||
|
| `Arrow Up/Down` | Navigate within menus, listboxes, radio groups, tabs |
|
||||||
|
| `Arrow Left/Right` | Navigate within tab bars, sliders, radio groups |
|
||||||
|
| `Home` | Move to first item in list, menu, or tab bar |
|
||||||
|
| `End` | Move to last item in list, menu, or tab bar |
|
||||||
|
|
||||||
|
### Widget-Specific Patterns
|
||||||
|
|
||||||
|
| Widget | Tab enters | Internal nav | Activate | Exit |
|
||||||
|
|--------|-----------|-------------|----------|------|
|
||||||
|
| Tab bar | Focus active tab | Arrow Left/Right | automatic or Enter | Tab out |
|
||||||
|
| Menu | Focus first item | Arrow Up/Down | Enter | Escape |
|
||||||
|
| Dialog | Focus first element | Tab cycles within | Enter on buttons | Escape |
|
||||||
|
| Combobox | Focus input | Arrow Up/Down | Enter selects | Escape closes |
|
||||||
|
| Tree view | Focus first node | Arrow keys | Enter/Space | Tab out |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Color Contrast Quick Reference
|
||||||
|
|
||||||
|
### Text Contrast (WCAG 1.4.3 AA)
|
||||||
|
|
||||||
|
| Text Type | Minimum Ratio |
|
||||||
|
|-----------|--------------|
|
||||||
|
| Normal text (< 18pt / < 14pt bold) | 4.5:1 |
|
||||||
|
| Large text (>= 18pt / >= 14pt bold) | 3:1 |
|
||||||
|
| Incidental (disabled, decorative) | No requirement |
|
||||||
|
|
||||||
|
### Non-Text Contrast (WCAG 1.4.11 AA)
|
||||||
|
|
||||||
|
| Element | Minimum Ratio |
|
||||||
|
|---------|--------------|
|
||||||
|
| UI components (borders, icons) | 3:1 against adjacent |
|
||||||
|
| Graphical objects | 3:1 against adjacent |
|
||||||
|
| Focus indicators | 3:1 against background |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Accessibility Checklist (POUR)
|
||||||
|
|
||||||
|
### Perceivable
|
||||||
|
- [ ] All images have appropriate alt text (descriptive or empty for decorative)
|
||||||
|
- [ ] Videos have synchronized captions
|
||||||
|
- [ ] Page uses semantic landmarks: `<header>`, `<nav>`, `<main>`, `<footer>`
|
||||||
|
- [ ] Headings follow logical hierarchy (h1 > h2 > h3, no gaps)
|
||||||
|
- [ ] Text contrast meets 4.5:1 (normal) / 3:1 (large)
|
||||||
|
- [ ] UI component contrast meets 3:1
|
||||||
|
- [ ] Information not conveyed by color alone
|
||||||
|
- [ ] Content reflows at 320px without horizontal scroll
|
||||||
|
- [ ] `<html lang="...">` is set correctly
|
||||||
|
- [ ] Text resizable to 200% without loss of content
|
||||||
|
|
||||||
|
### Operable
|
||||||
|
- [ ] All functionality accessible via keyboard
|
||||||
|
- [ ] No keyboard traps (Escape closes overlays)
|
||||||
|
- [ ] Skip link provided as first focusable element
|
||||||
|
- [ ] Focus indicator visible on all interactive elements
|
||||||
|
- [ ] Focus order matches visual order
|
||||||
|
- [ ] Focus not obscured by sticky headers/footers
|
||||||
|
- [ ] Focus returned to trigger after modal close
|
||||||
|
- [ ] Touch targets at least 24x24 CSS px
|
||||||
|
- [ ] Animations respect `prefers-reduced-motion`
|
||||||
|
- [ ] No content flashes more than 3 times per second
|
||||||
|
|
||||||
|
### Understandable
|
||||||
|
- [ ] All form inputs have associated `<label>` or `aria-label`
|
||||||
|
- [ ] Error messages linked to inputs via `aria-describedby`
|
||||||
|
- [ ] Required fields indicated with `required` or `aria-required`
|
||||||
|
- [ ] Error summary or focus-on-first-error on submit failure
|
||||||
|
- [ ] No unexpected context changes on focus or input
|
||||||
|
|
||||||
|
### Robust
|
||||||
|
- [ ] All interactive elements have accessible name, role, and state
|
||||||
|
- [ ] ARIA roles have required properties
|
||||||
|
- [ ] No `aria-hidden="true"` on focusable elements
|
||||||
|
- [ ] Dynamic content announced via live regions
|
||||||
|
- [ ] SPA route changes announced to screen readers
|
||||||
|
- [ ] No redundant ARIA on native HTML elements
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user