diff --git a/.codespellrc b/.codespellrc
index adc8610c..3098338e 100644
--- a/.codespellrc
+++ b/.codespellrc
@@ -46,9 +46,11 @@
# 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
-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
diff --git a/docs/README.instructions.md b/docs/README.instructions.md
index 8e2a1e3f..1d9972c0 100644
--- a/docs/README.instructions.md
+++ b/docs/README.instructions.md
@@ -21,7 +21,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on
| [.NET Framework Development](../instructions/dotnet-framework.instructions.md)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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)
[](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. |
diff --git a/instructions/a11y.instructions.md b/instructions/a11y.instructions.md
index d6d3d2c1..1c1965a0 100644
--- a/instructions/a11y.instructions.md
+++ b/instructions/a11y.instructions.md
@@ -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/).
-- Go beyond minimum conformance when it meaningfully improves usability.
-- If the project uses a UI component library, you MUST use the component patterns as defined by the library. Do not recreate patterns.
- - 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”.
+- **CRITICAL** — Users cannot access content at all. Must be fixed before merge.
+- **IMPORTANT** — Significant barrier for assistive technology users. Fix in same sprint.
+- **SUGGESTION** — Improves usability for assistive technology. Plan for a future iteration.
-## Inclusive language (MUST)
+---
-- Use respectful, inclusive, people-first language in any user-facing text.
-- Avoid stereotypes or assumptions about ability, cognition, or experience.
+## WCAG 2.2 Quick Reference (AA Level)
-## Cognitive load (SHOULD)
+### Perceivable
-- Prefer plain language.
-- Use consistent page structure (landmarks).
-- Keep navigation order consistent.
-- Keep the interface clean and simple (avoid unnecessary distractions).
+| Criterion | Level | Summary |
+|-----------|-------|---------|
+| 1.1.1 Non-text Content | A | All non-text content has a text alternative. Decorative images use `alt=""`. |
+| 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 ``. |
+| 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.
-- 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.
+### Understandable
-### 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>`.
-- Prefer: “Unique page - section - site”.
+### Robust
-## 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.
-- 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"`.
+> **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).
-### 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
-<header>
- <a href="#maincontent" class="sr-only">Skip to main content</a>
- <!-- header content -->
-</header>
-<nav>
- <!-- navigation -->
-</nav>
-<main id="maincontent" tabindex="-1">
- <h1><!-- page title --></h1>
- <!-- content -->
-</main>
+<!-- BAD -->
+<html>
+
+<!-- GOOD -->
+<html lang="en">
+```
+
+Next.js: Set in `app/layout.tsx`. Angular: Set in `src/index.html`. Vue/Nuxt: Set in `app.vue` or `nuxt.config`.
+
+### S2: Multiple `<h1>` Per Page
+
+- **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
-.sr-only:not(:focus):not(:active) {
- clip: rect(0 0 0 0);
- clip-path: inset(50%);
- height: 1px;
- overflow: hidden;
- position: absolute;
- white-space: nowrap;
- width: 1px;
-}
+.skip-link { position: absolute; top: -40px; left: 0; padding: 8px 16px; background: #000; color: #fff; z-index: 100; }
+.skip-link:focus { top: 0; }
```
-### 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):
-
-- Provide one tab stop for the composite container or one child.
-- 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.
+- **Severity**: CRITICAL
+- **Detection**: `outline:\s*none|outline:\s*0\b` without `:focus-visible` replacement
+- **WCAG**: 2.4.7 (AA)
```css
-@media (forced-colors: active) {
- /* Example: Replace box-shadow (suppressed in forced-colors) with a border */
- .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;
-}
+/* GOOD */
+button:focus-visible { outline: 2px solid #005fcc; outline-offset: 2px; }
```
-In Forced Colors mode, avoid relying on:
+### K6: Mouse-Only Interactions
-- Box shadows
-- Decorative gradients
+- **Severity**: IMPORTANT
+- **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`).
-- Do not use fixed hex/RGB colors inside `@media (forced-colors: active)`.
+### K7: Focus Not Returned After Modal Close
-### 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.
-- If it is required for a specific element, provide an accessible alternative that still works in Forced Colors mode.
+Store reference to trigger element. On modal close, call `triggerElement.focus()`.
-### Icons (MUST)
+---
-- Icons MUST adapt to text color.
-- Prefer `currentColor` for SVG icon fills/strokes; avoid embedding fixed colors inside SVGs.
+## Form Anti-Patterns (F1-F6)
+
+### 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
-svg {
- fill: currentColor;
- stroke: currentColor;
+/* BAD — #999 on #fff is ~2.5:1 */
+.text { color: #999; background: #fff; }
+
+/* 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.
-- 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).
+Alt text decision tree: decorative = `alt=""`; contains text = include that text; functional = describe action; informational = describe content.
-### Engineering requirements (MUST)
+### D2: Decorative Image with Non-Empty Alt
-- Use responsive layout primitives (`flex`, `grid`) with fluid sizing; enable text wrapping.
-- Avoid fixed widths that force two-dimensional scrolling at 320px.
-- Avoid absolute positioning and `overflow: hidden` when it causes content loss, or would result in the obscuring of content at smaller viewport sizes.
-- 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.
+- **Severity**: SUGGESTION
+- **Detection**: Decorative images with meaningful alt text
+- **WCAG**: 1.1.1 (A)
-### 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).
-- The component MUST remain fully usable (all content reachable; controls operable).
+- **Severity**: CRITICAL
+- **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.
-- The label cannot disappear while entering text or after the field has a value.
+- **Severity**: IMPORTANT
+- **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.
- - Prefer `<label for="...">`.
-- Labels describe the input purpose.
-- If help text exists, associate it with `aria-describedby`.
+- **Severity**: IMPORTANT
+- **Detection**: `<label.*for="` in JSX (should be `htmlFor`)
+- **WCAG**: 1.3.1 (A), 3.3.2 (A)
-### 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.
-- 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.
+### RX3: Fragment Root Causing Focus Loss on Re-render
-## 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.
- - `img`: use `alt`.
- - `svg`: prefer `role="img"` and `aria-label`/`aria-labelledby`.
-- Decorative graphics MUST be hidden.
- - `img`: `alt=""`.
- - Other: `aria-hidden="true"`.
+### RX4: Injected HTML Without ARIA Consideration
-## 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.
-- 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.
+Sanitize and validate injected HTML for heading hierarchy, alt text, and ARIA structure.
-## Tables and grids
+---
-### Tables for static data (MUST)
+## Framework-Specific: Angular (NG1-NG4)
-- Use `<table>` for static tabular data.
-- Use `<th>` to associate headers.
- - Column headers are in the first row.
- - Row headers (when present) use `<th>` in each row.
+### NG1: `(click)` on `<div>` Without Role and Keyboard Support
-### 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.
-- 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.
+Use `<button>`. If div required: add `role="button"`, `tabindex="0"`, `(keydown.enter)`, `(keydown.space)`.
-## 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.
-- Keyboard and focus: operable controls, visible focus, predictable tab order, no traps, skip link works.
-- 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.
+```html
+<div class="modal" cdkTrapFocus [cdkTrapFocusAutoCapture]="true">...</div>
+```
-## 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
diff --git a/instructions/performance-optimization.instructions.md b/instructions/performance-optimization.instructions.md
index fe5707d3..def4016c 100644
--- a/instructions/performance-optimization.instructions.md
+++ b/instructions/performance-optimization.instructions.md
@@ -1,420 +1,962 @@
---
-applyTo: '*'
-description: '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.'
+applyTo: '**'
+description: '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.'
---
-# Performance Optimization Best Practices
+# Performance Standards
-## Introduction
+Comprehensive performance rules for web application development. Every anti-pattern includes a severity classification, detection method, Core Web Vitals metric impacted, and corrective code examples.
-Performance isn't just a buzzword—it's the difference between a product people love and one they abandon. I've seen firsthand how a slow app can frustrate users, rack up cloud bills, and even lose customers. This guide is a living collection of the most effective, real-world performance practices I've used and reviewed, covering frontend, backend, and database layers, as well as advanced topics. Use it as a reference, a checklist, and a source of inspiration for building fast, efficient, and scalable software.
+**Severity levels:**
+
+- **CRITICAL** — Directly degrades a Core Web Vital past the "poor" threshold. Must be fixed before merge.
+- **IMPORTANT** — Measurably impacts user experience. Fix in same sprint.
+- **SUGGESTION** — Optimization opportunity. Plan for a future iteration.
---
-## General Principles
+## Core Web Vitals Quick Reference
-- **Measure First, Optimize Second:** Always profile and measure before optimizing. Use benchmarks, profilers, and monitoring tools to identify real bottlenecks. Guessing is the enemy of performance.
- - *Pro Tip:* Use tools like Chrome DevTools, Lighthouse, New Relic, Datadog, Py-Spy, or your language's built-in profilers.
-- **Optimize for the Common Case:** Focus on optimizing code paths that are most frequently executed. Don't waste time on rare edge cases unless they're critical.
-- **Avoid Premature Optimization:** Write clear, maintainable code first; optimize only when necessary. Premature optimization can make code harder to read and maintain.
-- **Minimize Resource Usage:** Use memory, CPU, network, and disk resources efficiently. Always ask: "Can this be done with less?"
-- **Prefer Simplicity:** Simple algorithms and data structures are often faster and easier to optimize. Don't over-engineer.
-- **Document Performance Assumptions:** Clearly comment on any code that is performance-critical or has non-obvious optimizations. Future maintainers (including you) will thank you.
-- **Understand the Platform:** Know the performance characteristics of your language, framework, and runtime. What's fast in Python may be slow in JavaScript, and vice versa.
-- **Automate Performance Testing:** Integrate performance tests and benchmarks into your CI/CD pipeline. Catch regressions early.
-- **Set Performance Budgets:** Define acceptable limits for load time, memory usage, API latency, etc. Enforce them with automated checks.
+### LCP (Largest Contentful Paint)
+
+**Good: < 2.5s | Needs Improvement: 2.5-4s | Poor: > 4s**
+
+Measures when the largest visible content element finishes rendering. Four sequential phases:
+
+| Phase | Target | What It Measures |
+|-------|--------|-----------------|
+| TTFB | ~40% of budget | Server response time |
+| Resource Load Delay | < 10% | Time between TTFB and LCP resource fetch start |
+| Resource Load Duration | ~40% | Download time for the LCP resource |
+| Element Render Delay | < 10% | Time between download and paint |
+
+### INP (Interaction to Next Paint)
+
+**Good: < 200ms | Needs Improvement: 200-500ms | Poor: > 500ms**
+
+Measures latency of all user interactions, reports the worst. Three phases:
+
+| Phase | Optimization |
+|-------|-------------|
+| Input Delay | Break long tasks, yield to browser |
+| Processing Time | Keep handlers < 50ms |
+| Presentation Delay | Minimize DOM size, avoid forced layout |
+
+> **Diagnostic tool:** Use the Long Animation Frames (LoAF) API (Chrome 123+) to debug INP issues. LoAF provides better attribution than the legacy Long Tasks API, including script source and rendering time.
+
+### CLS (Cumulative Layout Shift)
+
+**Good: < 0.1 | Needs Improvement: 0.1-0.25 | Poor: > 0.25**
+
+Layout shift sources: images without dimensions, dynamically injected content, web font FOUT, late-loading ads. Shifts within 500ms of user interaction are exempt.
---
-## Frontend Performance
+## Loading and LCP Anti-Patterns (L1-L10)
-### Rendering and DOM
-- **Minimize DOM Manipulations:** Batch updates where possible. Frequent DOM changes are expensive.
- - *Anti-pattern:* Updating the DOM in a loop. Instead, build a document fragment and append it once.
-- **Virtual DOM Frameworks:** Use React, Vue, or similar efficiently—avoid unnecessary re-renders.
- - *React Example:* Use `React.memo`, `useMemo`, and `useCallback` to prevent unnecessary renders.
-- **Keys in Lists:** Always use stable keys in lists to help virtual DOM diffing. Avoid using array indices as keys unless the list is static.
-- **Avoid Inline Styles:** Inline styles can trigger layout thrashing. Prefer CSS classes.
-- **CSS Animations:** Use CSS transitions/animations over JavaScript for smoother, GPU-accelerated effects.
-- **Defer Non-Critical Rendering:** Use `requestIdleCallback` or similar to defer work until the browser is idle.
+### L1: Render-Blocking CSS Without Critical Extraction
-### Asset Optimization
-- **Image Compression:** Use tools like ImageOptim, Squoosh, or TinyPNG. Prefer modern formats (WebP, AVIF) for web delivery.
-- **SVGs for Icons:** SVGs scale well and are often smaller than PNGs for simple graphics.
-- **Minification and Bundling:** Use Webpack, Rollup, or esbuild to bundle and minify JS/CSS. Enable tree-shaking to remove dead code.
-- **Cache Headers:** Set long-lived cache headers for static assets. Use cache busting for updates.
-- **Lazy Loading:** Use `loading="lazy"` for images, and dynamic imports for JS modules/components.
-- **Font Optimization:** Use only the character sets you need. Subset fonts and use `font-display: swap`.
+- **Severity**: CRITICAL
+- **Detection**: `<link.*rel="stylesheet"` in `<head>` loading large CSS
+- **CWV**: LCP
-### Network Optimization
-- **Reduce HTTP Requests:** Combine files, use image sprites, and inline critical CSS.
-- **HTTP/2 and HTTP/3:** Enable these protocols for multiplexing and lower latency.
-- **Client-Side Caching:** Use Service Workers, IndexedDB, and localStorage for offline and repeat visits.
-- **CDNs:** Serve static assets from a CDN close to your users. Use multiple CDNs for redundancy.
-- **Defer/Async Scripts:** Use `defer` or `async` for non-critical JS to avoid blocking rendering.
-- **Preload and Prefetch:** Use `<link rel="preload">` and `<link rel="prefetch">` for critical resources.
-
-### JavaScript Performance
-- **Avoid Blocking the Main Thread:** Offload heavy computation to Web Workers.
-- **Debounce/Throttle Events:** For scroll, resize, and input events, use debounce/throttle to limit handler frequency.
-- **Memory Leaks:** Clean up event listeners, intervals, and DOM references. Use browser dev tools to check for detached nodes.
-- **Efficient Data Structures:** Use Maps/Sets for lookups, TypedArrays for numeric data.
-- **Avoid Global Variables:** Globals can cause memory leaks and unpredictable performance.
-- **Avoid Deep Object Cloning:** Use shallow copies or libraries like lodash's `cloneDeep` only when necessary.
-
-### Accessibility and Performance
-- **Accessible Components:** Ensure ARIA updates are not excessive. Use semantic HTML for both accessibility and performance.
-- **Screen Reader Performance:** Avoid rapid DOM updates that can overwhelm assistive tech.
-
-### Framework-Specific Tips
-#### React
-- Use `React.memo`, `useMemo`, and `useCallback` to avoid unnecessary renders.
-- Split large components and use code-splitting (`React.lazy`, `Suspense`).
-- Avoid anonymous functions in render; they create new references on every render.
-- Use `ErrorBoundary` to catch and handle errors gracefully.
-- Profile with React DevTools Profiler.
-
-#### Angular
-- Use OnPush change detection for components that don't need frequent updates.
-- Avoid complex expressions in templates; move logic to the component class.
-- Use `trackBy` in `ngFor` for efficient list rendering.
-- Lazy load modules and components with the Angular Router.
-- Profile with Angular DevTools.
-
-#### Vue
-- Use computed properties over methods in templates for caching.
-- Use `v-show` vs `v-if` appropriately (`v-show` is better for toggling visibility frequently).
-- Lazy load components and routes with Vue Router.
-- Profile with Vue Devtools.
-
-### Common Frontend Pitfalls
-- Loading large JS bundles on initial page load.
-- Not compressing images or using outdated formats.
-- Failing to clean up event listeners, causing memory leaks.
-- Overusing third-party libraries for simple tasks.
-- Ignoring mobile performance (test on real devices!).
-
-### Frontend Troubleshooting
-- Use Chrome DevTools' Performance tab to record and analyze slow frames.
-- Use Lighthouse to audit performance and get actionable suggestions.
-- Use WebPageTest for real-world load testing.
-- Monitor Core Web Vitals (LCP, FID, CLS) for user-centric metrics.
-
----
-
-## Backend Performance
-
-### Algorithm and Data Structure Optimization
-- **Choose the Right Data Structure:** Arrays for sequential access, hash maps for fast lookups, trees for hierarchical data, etc.
-- **Efficient Algorithms:** Use binary search, quicksort, or hash-based algorithms where appropriate.
-- **Avoid O(n^2) or Worse:** Profile nested loops and recursive calls. Refactor to reduce complexity.
-- **Batch Processing:** Process data in batches to reduce overhead (e.g., bulk database inserts).
-- **Streaming:** Use streaming APIs for large data sets to avoid loading everything into memory.
-
-### Concurrency and Parallelism
-- **Asynchronous I/O:** Use async/await, callbacks, or event loops to avoid blocking threads.
-- **Thread/Worker Pools:** Use pools to manage concurrency and avoid resource exhaustion.
-- **Avoid Race Conditions:** Use locks, semaphores, or atomic operations where needed.
-- **Bulk Operations:** Batch network/database calls to reduce round trips.
-- **Backpressure:** Implement backpressure in queues and pipelines to avoid overload.
-
-### Caching
-- **Cache Expensive Computations:** Use in-memory caches (Redis, Memcached) for hot data.
-- **Cache Invalidation:** Use time-based (TTL), event-based, or manual invalidation. Stale cache is worse than no cache.
-- **Distributed Caching:** For multi-server setups, use distributed caches and be aware of consistency issues.
-- **Cache Stampede Protection:** Use locks or request coalescing to prevent thundering herd problems.
-- **Don't Cache Everything:** Some data is too volatile or sensitive to cache.
-
-### API and Network
-- **Minimize Payloads:** Use JSON, compress responses (gzip, Brotli), and avoid sending unnecessary data.
-- **Pagination:** Always paginate large result sets. Use cursors for real-time data.
-- **Rate Limiting:** Protect APIs from abuse and overload.
-- **Connection Pooling:** Reuse connections for databases and external services.
-- **Protocol Choice:** Use HTTP/2, gRPC, or WebSockets for high-throughput, low-latency communication.
-
-### Logging and Monitoring
-- **Minimize Logging in Hot Paths:** Excessive logging can slow down critical code.
-- **Structured Logging:** Use JSON or key-value logs for easier parsing and analysis.
-- **Monitor Everything:** Latency, throughput, error rates, resource usage. Use Prometheus, Grafana, Datadog, or similar.
-- **Alerting:** Set up alerts for performance regressions and resource exhaustion.
-
-### Language/Framework-Specific Tips
-#### Node.js
-- Use asynchronous APIs; avoid blocking the event loop (e.g., never use `fs.readFileSync` in production).
-- Use clustering or worker threads for CPU-bound tasks.
-- Limit concurrent open connections to avoid resource exhaustion.
-- Use streams for large file or network data processing.
-- Profile with `clinic.js`, `node --inspect`, or Chrome DevTools.
-
-#### Python
-- Use built-in data structures (`dict`, `set`, `deque`) for speed.
-- Profile with `cProfile`, `line_profiler`, or `Py-Spy`.
-- Use `multiprocessing` or `asyncio` for parallelism.
-- Avoid GIL bottlenecks in CPU-bound code; use C extensions or subprocesses.
-- Use `lru_cache` for memoization.
-
-#### Java
-- Use efficient collections (`ArrayList`, `HashMap`, etc.).
-- Profile with VisualVM, JProfiler, or YourKit.
-- Use thread pools (`Executors`) for concurrency.
-- Tune JVM options for heap and garbage collection (`-Xmx`, `-Xms`, `-XX:+UseG1GC`).
-- Use `CompletableFuture` for async programming.
-
-#### .NET
-- Use `async/await` for I/O-bound operations.
-- Use `Span<T>` and `Memory<T>` for efficient memory access.
-- Profile with dotTrace, Visual Studio Profiler, or PerfView.
-- Pool objects and connections where appropriate.
-- Use `IAsyncEnumerable<T>` for streaming data.
-
-### Common Backend Pitfalls
-- Synchronous/blocking I/O in web servers.
-- Not using connection pooling for databases.
-- Over-caching or caching sensitive/volatile data.
-- Ignoring error handling in async code.
-- Not monitoring or alerting on performance regressions.
-
-### Backend Troubleshooting
-- Use flame graphs to visualize CPU usage.
-- Use distributed tracing (OpenTelemetry, Jaeger, Zipkin) to track request latency across services.
-- Use heap dumps and memory profilers to find leaks.
-- Log slow queries and API calls for analysis.
-
----
-
-## Database Performance
-
-### Query Optimization
-- **Indexes:** Use indexes on columns that are frequently queried, filtered, or joined. Monitor index usage and drop unused indexes.
-- **Avoid SELECT *:** Select only the columns you need. Reduces I/O and memory usage.
-- **Parameterized Queries:** Prevent SQL injection and improve plan caching.
-- **Query Plans:** Analyze and optimize query execution plans. Use `EXPLAIN` in SQL databases.
-- **Avoid N+1 Queries:** Use joins or batch queries to avoid repeated queries in loops.
-- **Limit Result Sets:** Use `LIMIT`/`OFFSET` or cursors for large tables.
-
-### Schema Design
-- **Normalization:** Normalize to reduce redundancy, but denormalize for read-heavy workloads if needed.
-- **Data Types:** Use the most efficient data types and set appropriate constraints.
-- **Partitioning:** Partition large tables for scalability and manageability.
-- **Archiving:** Regularly archive or purge old data to keep tables small and fast.
-- **Foreign Keys:** Use them for data integrity, but be aware of performance trade-offs in high-write scenarios.
-
-### Transactions
-- **Short Transactions:** Keep transactions as short as possible to reduce lock contention.
-- **Isolation Levels:** Use the lowest isolation level that meets your consistency needs.
-- **Avoid Long-Running Transactions:** They can block other operations and increase deadlocks.
-
-### Caching and Replication
-- **Read Replicas:** Use for scaling read-heavy workloads. Monitor replication lag.
-- **Cache Query Results:** Use Redis or Memcached for frequently accessed queries.
-- **Write-Through/Write-Behind:** Choose the right strategy for your consistency needs.
-- **Sharding:** Distribute data across multiple servers for scalability.
-
-### NoSQL Databases
-- **Design for Access Patterns:** Model your data for the queries you need.
-- **Avoid Hot Partitions:** Distribute writes/reads evenly.
-- **Unbounded Growth:** Watch for unbounded arrays or documents.
-- **Sharding and Replication:** Use for scalability and availability.
-- **Consistency Models:** Understand eventual vs strong consistency and choose appropriately.
-
-### Common Database Pitfalls
-- Missing or unused indexes.
-- SELECT * in production queries.
-- Not monitoring slow queries.
-- Ignoring replication lag.
-- Not archiving old data.
-
-### Database Troubleshooting
-- Use slow query logs to identify bottlenecks.
-- Use `EXPLAIN` to analyze query plans.
-- Monitor cache hit/miss ratios.
-- Use database-specific monitoring tools (pg_stat_statements, MySQL Performance Schema).
-
----
-
-## Code Review Checklist for Performance
-
-- [ ] Are there any obvious algorithmic inefficiencies (O(n^2) or worse)?
-- [ ] Are data structures appropriate for their use?
-- [ ] Are there unnecessary computations or repeated work?
-- [ ] Is caching used where appropriate, and is invalidation handled correctly?
-- [ ] Are database queries optimized, indexed, and free of N+1 issues?
-- [ ] Are large payloads paginated, streamed, or chunked?
-- [ ] Are there any memory leaks or unbounded resource usage?
-- [ ] Are network requests minimized, batched, and retried on failure?
-- [ ] Are assets optimized, compressed, and served efficiently?
-- [ ] Are there any blocking operations in hot paths?
-- [ ] Is logging in hot paths minimized and structured?
-- [ ] Are performance-critical code paths documented and tested?
-- [ ] Are there automated tests or benchmarks for performance-sensitive code?
-- [ ] Are there alerts for performance regressions?
-- [ ] Are there any anti-patterns (e.g., SELECT *, blocking I/O, global variables)?
-
----
-
-## Advanced Topics
-
-### Profiling and Benchmarking
-- **Profilers:** Use language-specific profilers (Chrome DevTools, Py-Spy, VisualVM, dotTrace, etc.) to identify bottlenecks.
-- **Microbenchmarks:** Write microbenchmarks for critical code paths. Use `benchmark.js`, `pytest-benchmark`, or JMH for Java.
-- **A/B Testing:** Measure real-world impact of optimizations with A/B or canary releases.
-- **Continuous Performance Testing:** Integrate performance tests into CI/CD. Use tools like k6, Gatling, or Locust.
-
-### Memory Management
-- **Resource Cleanup:** Always release resources (files, sockets, DB connections) promptly.
-- **Object Pooling:** Use for frequently created/destroyed objects (e.g., DB connections, threads).
-- **Heap Monitoring:** Monitor heap usage and garbage collection. Tune GC settings for your workload.
-- **Memory Leaks:** Use leak detection tools (Valgrind, LeakCanary, Chrome DevTools).
-
-### Scalability
-- **Horizontal Scaling:** Design stateless services, use sharding/partitioning, and load balancers.
-- **Auto-Scaling:** Use cloud auto-scaling groups and set sensible thresholds.
-- **Bottleneck Analysis:** Identify and address single points of failure.
-- **Distributed Systems:** Use idempotent operations, retries, and circuit breakers.
-
-### Security and Performance
-- **Efficient Crypto:** Use hardware-accelerated and well-maintained cryptographic libraries.
-- **Validation:** Validate inputs efficiently; avoid regexes in hot paths.
-- **Rate Limiting:** Protect against DoS without harming legitimate users.
-
-### Mobile Performance
-- **Startup Time:** Lazy load features, defer heavy work, and minimize initial bundle size.
-- **Image/Asset Optimization:** Use responsive images and compress assets for mobile bandwidth.
-- **Efficient Storage:** Use SQLite, Realm, or platform-optimized storage.
-- **Profiling:** Use Android Profiler, Instruments (iOS), or Firebase Performance Monitoring.
-
-### Cloud and Serverless
-- **Cold Starts:** Minimize dependencies and keep functions warm.
-- **Resource Allocation:** Tune memory/CPU for serverless functions.
-- **Managed Services:** Use managed caching, queues, and DBs for scalability.
-- **Cost Optimization:** Monitor and optimize for cloud cost as a performance metric.
-
----
-
-## Practical Examples
-
-### Example 1: Debouncing User Input in JavaScript
-```javascript
-// BAD: Triggers API call on every keystroke
-input.addEventListener('input', (e) => {
- fetch(`/search?q=${e.target.value}`);
-});
-
-// GOOD: Debounce API calls
-let timeout;
-input.addEventListener('input', (e) => {
- clearTimeout(timeout);
- timeout = setTimeout(() => {
- fetch(`/search?q=${e.target.value}`);
- }, 300);
-});
-```
-
-### Example 2: Efficient SQL Query
-```sql
--- BAD: Selects all columns and does not use an index
-SELECT * FROM users WHERE email = 'user@example.com';
-
--- GOOD: Selects only needed columns and uses an index
-SELECT id, name FROM users WHERE email = 'user@example.com';
-```
-
-### Example 3: Caching Expensive Computation in Python
-```python
-# BAD: Recomputes result every time
-result = expensive_function(x)
-
-# GOOD: Cache result
-from functools import lru_cache
-
-@lru_cache(maxsize=128)
-def expensive_function(x):
- ...
-result = expensive_function(x)
-```
-
-### Example 4: Lazy Loading Images in HTML
```html
-<!-- BAD: Loads all images immediately -->
-<img src="large-image.jpg" />
+<!-- BAD -->
+<link rel="stylesheet" href="/styles/main.css" />
-<!-- GOOD: Lazy loads images -->
-<img src="large-image.jpg" loading="lazy" />
+<!-- GOOD — inline critical CSS (extracted at build time), preload the rest -->
+<style>/* critical above-fold CSS, inlined by a tool like Critters/Beasties */</style>
+<link rel="preload" href="/styles/main.css" as="style" />
+<link rel="stylesheet" href="/styles/main.css" />
```
-### Example 5: Asynchronous I/O in Node.js
-```javascript
-// BAD: Blocking file read
-const data = fs.readFileSync('file.txt');
+Prefer build-time critical CSS extraction (e.g., Critters, Beasties, Next.js `experimental.optimizeCss`) plus a normal `<link rel="stylesheet">`. Avoid the older `media="print" onload="this.media='all'"` trick: inline event handlers are blocked under a strict CSP (no `'unsafe-inline'` / no `script-src-attr 'unsafe-inline'`), which would prevent the stylesheet from ever activating and cause a styling regression. If non-critical CSS truly must be deferred, load it via an **external** script that swaps `media`, not an inline handler.
-// GOOD: Non-blocking file read
-fs.readFile('file.txt', (err, data) => {
- if (err) throw err;
- // process data
-});
+### L2: Render-Blocking Synchronous Script
+
+- **Severity**: CRITICAL
+- **Detection**: `<script.*src=` without `async|defer|type="module"`
+- **CWV**: LCP
+
+```html
+<!-- BAD -->
+<script src="/vendor/analytics.js"></script>
+
+<!-- GOOD -->
+<script src="/vendor/analytics.js" defer></script>
```
-### Example 6: Profiling a Python Function
-```python
-import cProfile
-import pstats
+### L3: Missing Preconnect to Critical Origins
-def slow_function():
- ...
+- **Severity**: IMPORTANT
+- **Detection**: Third-party API/CDN URLs without `<link rel="preconnect">`
+- **CWV**: LCP
-cProfile.run('slow_function()', 'profile.stats')
-p = pstats.Stats('profile.stats')
-p.sort_stats('cumulative').print_stats(10)
+```html
+<link rel="preconnect" href="https://api.example.com" />
+<link rel="dns-prefetch" href="https://analytics.example.com" />
```
-### Example 7: Using Redis for Caching in Node.js
-```javascript
-const redis = require('redis');
-const client = redis.createClient();
+### L4: Missing Preload for LCP Resource
-function getCachedData(key, fetchFunction) {
- return new Promise((resolve, reject) => {
- client.get(key, (err, data) => {
- if (data) return resolve(JSON.parse(data));
- fetchFunction().then(result => {
- client.setex(key, 3600, JSON.stringify(result));
- resolve(result);
- });
- });
- });
+- **Severity**: CRITICAL
+- **Detection**: LCP image/font not preloaded
+- **CWV**: LCP
+
+```html
+<link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />
+```
+
+### L5: Client-Side Data Fetching for Main Content
+
+- **Severity**: CRITICAL
+- **Detection**: `useEffect.*fetch|useEffect.*axios|ngOnInit.*subscribe`
+- **CWV**: LCP
+
+```tsx
+// BAD — content appears after JS execution + API call
+'use client';
+function Page() {
+ const [data, setData] = useState(null);
+ useEffect(() => { fetch('/api/data').then(r => r.json()).then(setData); }, []);
+ return <div>{data?.title}</div>;
+}
+
+// GOOD — Server Component fetches data before HTML is sent
+async function Page() {
+ const data = await fetch('https://api.example.com/data').then(r => r.json());
+ return <div>{data.title}</div>;
}
```
----
+### L6: Excessive Redirect Chains
-## References and Further Reading
-- [Google Web Fundamentals: Performance](https://web.dev/performance/)
-- [MDN Web Docs: Performance](https://developer.mozilla.org/en-US/docs/Web/Performance)
-- [OWASP: Performance Testing](https://owasp.org/www-project-performance-testing/)
-- [Microsoft Performance Best Practices](https://learn.microsoft.com/en-us/azure/architecture/best-practices/performance)
-- [PostgreSQL Performance Optimization](https://wiki.postgresql.org/wiki/Performance_Optimization)
-- [MySQL Performance Tuning](https://dev.mysql.com/doc/refman/8.0/en/optimization.html)
-- [Node.js Performance Best Practices](https://nodejs.org/en/docs/guides/simple-profiling/)
-- [Python Performance Tips](https://docs.python.org/3/library/profile.html)
-- [Java Performance Tuning](https://www.oracle.com/java/technologies/javase/performance.html)
-- [.NET Performance Guide](https://learn.microsoft.com/en-us/dotnet/standard/performance/)
-- [WebPageTest](https://www.webpagetest.org/)
-- [Lighthouse](https://developers.google.com/web/tools/lighthouse)
-- [Prometheus](https://prometheus.io/)
-- [Grafana](https://grafana.com/)
-- [k6 Load Testing](https://k6.io/)
-- [Gatling](https://gatling.io/)
-- [Locust](https://locust.io/)
-- [OpenTelemetry](https://opentelemetry.io/)
-- [Jaeger](https://www.jaegertracing.io/)
-- [Zipkin](https://zipkin.io/)
+- **Severity**: IMPORTANT
+- **Detection**: Multiple sequential redirects (HTTP 301/302 chains)
+- **CWV**: LCP
+
+Each redirect adds 200-300ms. Maximum one redirect.
+
+### L7: Missing fetchpriority on LCP Element
+
+- **Severity**: IMPORTANT
+- **Detection**: Above-fold hero image without `fetchpriority="high"` or `priority` prop
+- **CWV**: LCP
+
+```tsx
+// Next.js
+<Image src="/hero.webp" alt="Hero" width={1200} height={600} priority />
+
+// Angular
+<img ngSrc="/hero.webp" alt="Hero" width="1200" height="600" priority>
+
+// Plain HTML
+<img src="/hero.webp" alt="Hero" width="1200" height="600" fetchpriority="high" />
+```
+
+### L8: Third-Party Scripts in Head Without Async/Defer
+
+- **Severity**: IMPORTANT
+- **Detection**: `<script.*src="https://` without `async|defer`
+- **CWV**: LCP
+
+Defer non-essential scripts. Use facade pattern for chat widgets.
+
+### L9: Oversized Initial HTML (>14KB)
+
+- **Severity**: SUGGESTION
+- **Detection**: Server-rendered HTML larger than 14KB
+- **CWV**: LCP
+
+Reduce inline CSS/JS, remove whitespace, use streaming SSR with Suspense boundaries.
+
+### L10: Missing Compression
+
+- **Severity**: IMPORTANT
+- **Detection**: Server not returning `content-encoding: br` or `gzip`
+- **CWV**: LCP
+
+Enable Brotli (15-25% better than gzip) at CDN/server level.
---
-## Conclusion
+## Rendering and Hydration Anti-Patterns (R1-R8)
-Performance optimization is an ongoing process. Always measure, profile, and iterate. Use these best practices, checklists, and troubleshooting tips to guide your development and code reviews for high-performance, scalable, and efficient software. If you have new tips or lessons learned, add them here—let's keep this guide growing!
+### R1: Entire Component Tree Marked "use client"
+
+- **Severity**: CRITICAL
+- **Detection**: `"use client"` at top-level layout or page component
+- **CWV**: LCP + INP
+
+Push `"use client"` down to leaf components that need interactivity.
+
+### R2: Missing Suspense Boundaries for Async Data
+
+- **Severity**: IMPORTANT
+- **Detection**: Server Components doing data fetching without `<Suspense>`
+- **CWV**: LCP
+
+```tsx
+// GOOD — stream shell immediately, fill in data progressively
+async function Page() {
+ const user = await getUser();
+ return (
+ <div>
+ <Header user={user} />
+ <Suspense fallback={<PostsSkeleton />}>
+ <Posts />
+ </Suspense>
+ </div>
+ );
+}
+```
+
+### R3: Hydration Mismatch from Dynamic Client Content
+
+- **Severity**: IMPORTANT
+- **Detection**: `Date.now()|Math.random()|window\.innerWidth` in SSR components
+- **CWV**: CLS
+
+Use `useEffect` for client-only values, or `suppressHydrationWarning` for known differences.
+
+### R4: Missing Streaming for Slow Data Sources
+
+- **Severity**: IMPORTANT
+- **Detection**: Page awaiting all data before sending HTML
+- **CWV**: LCP (TTFB)
+
+Use streaming SSR with Suspense boundaries. Shell streams immediately; slow data fills in progressively.
+
+### R5: Unstable References Causing Re-renders
+
+- **Severity**: IMPORTANT
+- **Detection**: `style=\{\{|onClick=\{\(\) =>` inline in JSX
+- **CWV**: INP
+
+React 19+ with React Compiler enabled (separate babel/SWC build plugin): auto-memoized. Without Compiler: extract or memoize with `useMemo`/`useCallback`. Angular: OnPush. Vue: `computed()`.
+
+### R6: Missing Virtualization for Long Lists
+
+- **Severity**: IMPORTANT
+- **Detection**: `.map(` rendering >100 items without virtual scrolling
+- **CWV**: INP
+
+Use TanStack Virtual, react-window, Angular CDK Virtual Scroll, or vue-virtual-scroller.
+
+### R7: SSR of Immediately-Hidden Content
+
+- **Severity**: SUGGESTION
+- **Detection**: Server-rendering `display: none` components
+- **CWV**: LCP (TTFB)
+
+Use client-side rendering for modals, drawers, dropdowns. Angular: `@defer`. React: `React.lazy`.
+
+### R8: Missing `key` Prop on List Items
+
+- **Severity**: IMPORTANT
+- **Detection**: `.map(` without `key=` prop
+- **CWV**: INP
+
+```tsx
+// GOOD — stable unique key
+{items.map(item => <Row key={item.id} data={item} />)}
+```
+
+Never use array index as key if list can reorder.
---
-<!-- End of Performance Optimization Instructions -->
+## JavaScript Runtime and INP Anti-Patterns (J1-J8)
+
+### J1: Long Synchronous Task in Event Handler
+
+- **Severity**: CRITICAL
+- **Detection**: Event handlers with heavy computation (>50ms)
+- **CWV**: INP
+
+```typescript
+// GOOD — yield to browser
+async function handleClick() {
+ setLoading(true);
+ await (globalThis.scheduler?.yield?.() ?? new Promise(r => setTimeout(r, 0)));
+ const result = expensiveComputation(data);
+ setResult(result);
+}
+```
+
+Move heavy work to Web Worker for best results.
+
+> **Note:** `scheduler.yield()` is supported in Chrome 129+, Firefox 129+, but NOT Safari as of April 2026. Fallback: `await (globalThis.scheduler?.yield?.() ?? new Promise(r => setTimeout(r, 0)))`.
+
+### J2: Layout Thrashing
+
+- **Severity**: CRITICAL
+- **Detection**: `offsetHeight|offsetWidth|getBoundingClientRect|clientHeight` in loops
+- **CWV**: INP
+
+```typescript
+// GOOD — batch reads then batch writes
+const heights = elements.map(el => el.offsetHeight);
+elements.forEach((el, i) => { el.style.height = `${heights[i] + 10}px`; });
+```
+
+### J3: setInterval/setTimeout Without Cleanup
+
+- **Severity**: IMPORTANT
+- **Detection**: `setInterval|setTimeout` without cleanup
+- **Impact**: Memory
+
+```tsx
+useEffect(() => {
+ const id = setInterval(() => fetchData(), 5000);
+ return () => clearInterval(id);
+}, []);
+```
+
+### J4: addEventListener Without removeEventListener
+
+- **Severity**: IMPORTANT
+- **Detection**: `addEventListener` without cleanup
+- **Impact**: Memory
+
+```tsx
+useEffect(() => {
+ const controller = new AbortController();
+ window.addEventListener('resize', handleResize, { signal: controller.signal });
+ return () => controller.abort();
+}, []);
+```
+
+### J5: Detached DOM Node References
+
+- **Severity**: SUGGESTION
+- **Detection**: Variables holding references to removed DOM elements
+- **Impact**: Memory
+
+Set references to `null` when elements are removed.
+
+### J6: Synchronous XHR
+
+- **Severity**: CRITICAL
+- **Detection**: `XMLHttpRequest` with synchronous flag
+- **CWV**: INP
+
+Use `fetch()` (always async).
+
+### J7: Heavy Computation on Main Thread
+
+- **Severity**: IMPORTANT
+- **Detection**: CPU-intensive operations in component code
+- **CWV**: INP
+
+Move to Web Worker or break into chunks with `scheduler.yield()`.
+
+### J8: Missing Effect Cleanup
+
+- **Severity**: IMPORTANT
+- **Detection**: `useEffect` without return cleanup; `subscribe` without unsubscribe
+- **Impact**: Memory
+
+React: return cleanup from `useEffect`. Angular: `takeUntilDestroyed()`. Vue: `onUnmounted`.
+
+---
+
+## CSS Performance Anti-Patterns (C1-C7)
+
+### C1: Animation Using Layout-Triggering Properties
+
+- **Severity**: CRITICAL
+- **Detection**: `animation:|transition:` with `top|left|width|height|margin|padding`
+- **CWV**: INP
+
+```css
+/* BAD — main thread, <60fps */
+.card { transition: width 0.3s, height 0.3s; }
+
+/* GOOD — GPU compositor, 60fps */
+.card { transition: transform 0.3s, opacity 0.3s; }
+.card:hover { transform: scale(1.05); }
+```
+
+### C2: Missing content-visibility for Off-Screen Sections
+
+- **Severity**: SUGGESTION
+- **Detection**: Long pages without `content-visibility: auto`
+- **CWV**: INP
+
+```css
+.below-fold-section {
+ content-visibility: auto;
+ contain-intrinsic-size: auto 500px;
+}
+```
+
+### C3: will-change Applied Permanently
+
+- **Severity**: SUGGESTION
+- **Detection**: `will-change:` in base CSS (not `:hover|:focus`)
+- **Impact**: Memory
+
+Apply on interaction only or let browser optimize automatically.
+
+### C4: Large Unused CSS
+
+- **Severity**: IMPORTANT
+- **Detection**: CSS where >50% of rules are unused
+- **CWV**: LCP
+
+Use PurgeCSS, Tailwind purge, or critters. Code-split CSS per route.
+
+### C5: Universal Selector in Hot Paths
+
+- **Severity**: SUGGESTION
+- **Detection**: `\* \{` in CSS
+- **CWV**: INP
+
+```css
+/* GOOD — zero-specificity reset */
+:where(*, *::before, *::after) { box-sizing: border-box; }
+```
+
+### C6: Missing CSS Containment
+
+- **Severity**: SUGGESTION
+- **Detection**: Complex components without `contain` property
+- **CWV**: INP
+
+```css
+.sidebar { contain: layout style paint; }
+```
+
+### C7: Route Transitions Without View Transitions API
+
+- **Severity**: SUGGESTION
+- **Detection**: SPA route changes without View Transitions API
+- **CWV**: CLS (perceived)
+
+```javascript
+// Use View Transitions for smooth route changes (with feature check)
+if (document.startViewTransition) {
+ document.startViewTransition(() => {
+ // update DOM / navigate
+ });
+} else {
+ // fallback: update DOM directly
+}
+```
+
+Same-document transitions supported in all major browsers. Cross-document supported in Chrome/Edge 126+, Safari 18.5+. Always feature-check before calling — unsupported browsers will throw without the guard.
+
+---
+
+## Images, Media and Fonts Anti-Patterns (I1-I8)
+
+### I1: Images Without Dimensions
+
+- **Severity**: CRITICAL
+- **Detection**: `<img` without `width=` and `height=`
+- **CWV**: CLS
+
+Always set `width` and `height` on images, or use `aspect-ratio` in CSS.
+
+### I2: Lazy Loading Above-Fold Images
+
+- **Severity**: CRITICAL
+- **Detection**: `loading="lazy"` on hero/banner images
+- **CWV**: LCP
+
+```html
+<!-- GOOD — eager load with high priority -->
+<img src="/hero.webp" alt="Hero" fetchpriority="high" />
+```
+
+### I3: Legacy Format Only (JPEG/PNG)
+
+- **Severity**: IMPORTANT
+- **Detection**: Images without WebP/AVIF alternatives
+- **CWV**: LCP
+
+```html
+<picture>
+ <source srcset="/hero.avif" type="image/avif" />
+ <source srcset="/hero.webp" type="image/webp" />
+ <img src="/hero.jpg" alt="Hero" width="1200" height="600" />
+</picture>
+```
+
+### I4: Missing Responsive srcset/sizes
+
+- **Severity**: IMPORTANT
+- **Detection**: `<img` without `srcset`
+- **CWV**: LCP
+
+```html
+<img src="/hero-800.jpg" alt="Hero"
+ srcset="/hero-400.jpg 400w, /hero-800.jpg 800w, /hero-1200.jpg 1200w"
+ sizes="(max-width: 600px) 400px, (max-width: 1024px) 800px, 1200px" />
+```
+
+### I5: Font Without font-display
+
+- **Severity**: IMPORTANT
+- **Detection**: `@font-face` without `font-display`
+- **CWV**: CLS
+
+```css
+@font-face {
+ font-family: 'CustomFont';
+ src: url('/fonts/custom.woff2') format('woff2');
+ font-display: swap; /* or "optional" for best CLS */
+}
+```
+
+### I6: Critical Font Not Preloaded
+
+- **Severity**: IMPORTANT
+- **Detection**: Custom font without `<link rel="preload">`
+- **CWV**: LCP + CLS
+
+```html
+<link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin />
+```
+
+### I7: Full Font Loaded When Subset Suffices
+
+- **Severity**: SUGGESTION
+- **Detection**: Font files > 50KB WOFF2
+- **CWV**: LCP
+
+Use `unicode-range`, subset with glyphhanger, or `next/font` (auto-subsets Google Fonts).
+
+### I8: Unoptimized SVGs
+
+- **Severity**: SUGGESTION
+- **Detection**: SVGs with editor metadata
+- **CWV**: LCP (minor)
+
+```bash
+npx svgo input.svg -o output.svg
+```
+
+---
+
+## Bundle and Tree Shaking Anti-Patterns (B1-B6)
+
+### B1: Barrel File Importing Entire Module
+
+- **Severity**: IMPORTANT
+- **Detection**: `from '\.\/(?:.*\/index|components)'`
+- **CWV**: INP
+
+```typescript
+// BAD
+import { Button } from './components';
+
+// GOOD — direct import
+import { Button } from './components/Button';
+```
+
+### B2: CommonJS require() Preventing Tree Shaking
+
+- **Severity**: IMPORTANT
+- **Detection**: `require(` in frontend code
+- **CWV**: INP
+
+Use ESM `import/export`. Replace `require` with `import`.
+
+### B3: Large Dependency for Small Utility
+
+- **Severity**: IMPORTANT
+- **Detection**: `from "moment"|from "lodash"` (full imports)
+- **CWV**: INP
+
+```typescript
+// GOOD — tree-shakeable alternatives
+import { format } from 'date-fns';
+import { pick } from 'lodash-es';
+
+// BEST — native JS
+const formatted = new Intl.DateTimeFormat('en').format(date);
+```
+
+### B4: Missing Dynamic Import for Route Splitting
+
+- **Severity**: CRITICAL
+- **Detection**: All route components imported statically
+- **CWV**: INP
+
+```tsx
+// Next.js: automatic with file-based routing
+// React:
+const Page = React.lazy(() => import('./pages/Page'));
+// Angular:
+{ path: 'settings', loadComponent: () => import('./pages/settings.component') }
+// Vue:
+const Page = defineAsyncComponent(() => import('./pages/Page.vue'));
+```
+
+### B5: Missing sideEffects in package.json
+
+- **Severity**: SUGGESTION
+- **Detection**: Library package.json without `"sideEffects"` field
+- **CWV**: INP
+
+```json
+{ "sideEffects": false }
+```
+
+### B6: Duplicate Dependencies
+
+- **Severity**: SUGGESTION
+- **Detection**: Same library at multiple versions
+- **CWV**: INP
+
+```bash
+npm dedupe
+```
+
+---
+
+## Framework-Specific: Next.js (NX1-NX6)
+
+### NX1: Not Using next/image
+
+- **Severity**: IMPORTANT
+- **Detection**: `<img ` in `.tsx` instead of `<Image>`
+- **CWV**: LCP + CLS
+
+```tsx
+import Image from 'next/image';
+<Image src="/hero.jpg" alt="Hero" width={1200} height={600} priority />
+```
+
+### NX2: Not Using Cache Components for Partial Prerendering
+
+- **Severity**: IMPORTANT
+- **Detection**: Pages without `"use cache"` directive in Next.js 16+ projects
+- **CWV**: LCP
+
+```typescript
+// BAD — entire page is dynamic
+export default async function Page() {
+ const data = await fetchData(); // blocks full page render
+ return <div>{data.title}</div>;
+}
+
+// GOOD — enable Partial Prerendering with "use cache"
+// next.config.ts: { cacheComponents: true }
+"use cache";
+export default async function Page() {
+ const data = await fetchData(); // static shell renders instantly, dynamic holes stream
+ return <div>{data.title}</div>;
+}
+```
+
+Enable in `next.config.ts` with `cacheComponents: true`. Use `"use cache"` at file, component, or function level. Static shell loads instantly; dynamic content streams via Suspense boundaries.
+
+### NX3: Unnecessary "use client" on Server-Renderable Component
+
+- **Severity**: IMPORTANT
+- **Detection**: `"use client"` on components without hooks or browser APIs
+- **CWV**: INP
+
+Remove `"use client"` from components that only render static content.
+
+### NX4: Data Fetching in useEffect Instead of Server-Side
+
+- **Severity**: CRITICAL
+- **Detection**: `useEffect` + `fetch` in Next.js App Router pages
+- **CWV**: LCP
+
+Fetch data in Server Components directly (async function body).
+
+### NX5: Missing next/font
+
+- **Severity**: IMPORTANT
+- **Detection**: `fonts.googleapis|fonts.gstatic` in CSS/HTML
+- **CWV**: CLS + LCP
+
+```tsx
+import { Inter } from 'next/font/google';
+const inter = Inter({ subsets: ['latin'] });
+```
+
+### NX6: Missing "use cache" for Cacheable Server Functions
+
+- **Severity**: IMPORTANT
+- **Detection**: Async server functions without `"use cache"` in Next.js 16+ with `cacheComponents: true`
+- **CWV**: LCP
+
+```typescript
+// BAD — data fetched on every request
+async function getProducts() {
+ return await db.products.findMany();
+}
+
+// GOOD — cached with revalidation
+"use cache";
+import { cacheLife } from 'next/cache';
+async function getProducts() {
+ cacheLife('hours');
+ return await db.products.findMany();
+}
+```
+
+`"use cache"` replaces the old `unstable_cache` and `fetch` cache options. Use `cacheLife()` and `cacheTag()` for fine-grained control.
+
+---
+
+## Framework-Specific: Angular (NG1-NG6)
+
+### NG1: Default Change Detection on Presentational Components
+
+- **Severity**: IMPORTANT
+- **Detection**: Components without `ChangeDetectionStrategy.OnPush` (Angular <19) or without signals (Angular 19+)
+- **CWV**: INP
+
+```typescript
+// Angular <19: Use OnPush
+@Component({
+ changeDetection: ChangeDetectionStrategy.OnPush,
+ ...
+})
+
+// Angular 19+: Prefer zoneless with signals
+// app.config.ts: provideZonelessChangeDetection()
+@Component({ ... })
+export class ProductCard {
+ product = input.required<Product>(); // signal input
+ price = computed(() => this.product().price * 1.19); // derived signal
+}
+```
+
+Angular 19+: prefer zoneless change detection with signals. OnPush is unnecessary when using signal-based reactivity. Angular 20+ has stable zoneless support.
+
+### NG2: Not Using NgOptimizedImage
+
+- **Severity**: IMPORTANT
+- **Detection**: `<img` without `ngSrc` in `.component.html`
+- **CWV**: LCP + CLS
+
+```html
+<img ngSrc="/hero.jpg" alt="Hero" width="1200" height="600" priority />
+```
+
+### NG3: Missing @defer for Below-Fold Content
+
+- **Severity**: SUGGESTION
+- **Detection**: Heavy below-fold components loaded eagerly (Angular 17+)
+- **CWV**: INP
+
+```html
+@defer (on viewport) {
+ <app-heavy-chart [data]="chartData" />
+} @placeholder {
+ <div class="chart-skeleton"></div>
+}
+```
+
+### NG4: Not Using Signals for Reactive State
+
+- **Severity**: SUGGESTION
+- **Detection**: Class properties without signals in Angular 19+
+- **CWV**: INP
+
+Use `signal()` for reactive state, `computed()` for derived values. Signal APIs (`signal()`, `computed()`, `effect()`) are stable since Angular 20.
+
+### NG5: Full Hydration Without Incremental Hydration
+
+- **Severity**: IMPORTANT
+- **Detection**: SSR app without `withIncrementalHydration()` in Angular 19+
+- **CWV**: LCP, INP
+
+```typescript
+// BAD — full hydration blocks interactivity
+provideClientHydration()
+
+// GOOD — incremental hydration with triggers
+provideClientHydration(withIncrementalHydration())
+```
+
+Use `@defer` triggers (`on viewport`, `on interaction`) to hydrate components on demand. Reduces TTI by deferring non-critical component hydration.
+
+### NG6: Still Using zone.js in Angular 20+ Projects
+
+- **Severity**: SUGGESTION
+- **Detection**: `zone.js` in polyfills array, no `provideZonelessChangeDetection()` in Angular 20+
+- **CWV**: INP
+
+```typescript
+// app.config.ts
+export const appConfig = {
+ providers: [
+ provideZonelessChangeDetection(), // removes ~15-30KB from bundle
+ // ...
+ ]
+};
+```
+
+Zoneless change detection with signals reduces bundle size and improves runtime performance. Stable since Angular 20.
+
+---
+
+## Framework-Specific: React (RX1-RX4)
+
+### RX1: Missing React Compiler Adoption
+
+- **Severity**: SUGGESTION
+- **Detection**: Manual `useMemo|useCallback` in React 19+ project
+- **CWV**: INP
+
+Enable React Compiler (v19+) for auto-memoization. Remove manual wrappers.
+
+### RX2: Missing useTransition for Expensive Updates
+
+- **Severity**: IMPORTANT
+- **Detection**: State updates causing expensive re-renders without `useTransition`
+- **CWV**: INP
+
+```tsx
+const [isPending, startTransition] = useTransition();
+function handleFilter(value) {
+ startTransition(() => setFilter(value));
+}
+```
+
+### RX3: Missing useDeferredValue for Expensive Rendering
+
+- **Severity**: IMPORTANT
+- **Detection**: Expensive rendering from rapidly-changing input
+- **CWV**: INP
+
+```tsx
+const deferredQuery = useDeferredValue(query);
+const results = expensiveFilter(items, deferredQuery);
+```
+
+### RX4: Missing React.lazy for Route Splitting
+
+- **Severity**: IMPORTANT
+- **Detection**: Route components imported statically
+- **CWV**: INP
+
+```tsx
+const Settings = React.lazy(() => import('./pages/Settings'));
+```
+
+---
+
+## Framework-Specific: Vue (VU1-VU4)
+
+### VU1: reactive() on Large Data Structures
+
+- **Severity**: IMPORTANT
+- **Detection**: `reactive(` on large arrays or deep objects
+- **CWV**: INP
+
+Use `shallowRef()` or `shallowReactive()` for large data.
+
+### VU2: Missing v-memo on Expensive List Renders
+
+- **Severity**: SUGGESTION
+- **Detection**: Large lists without `v-memo`
+- **CWV**: INP
+
+```vue
+<div v-for="item in items" :key="item.id" v-memo="[item.id, item.updatedAt]">
+ <ExpensiveItem :data="item" />
+</div>
+```
+
+### VU3: Missing defineAsyncComponent
+
+- **Severity**: IMPORTANT
+- **Detection**: Heavy components imported statically
+- **CWV**: INP
+
+```typescript
+const HeavyChart = defineAsyncComponent(() => import('./HeavyChart.vue'));
+```
+
+### VU4: Not Using Vapor Mode for Performance-Critical Components
+
+- **Severity**: SUGGESTION
+- **Detection**: Performance-critical components using virtual DOM in Vue 3.6+
+- **CWV**: INP
+
+Vue 3.6+ Vapor Mode compiles templates to direct DOM operations, bypassing the virtual DOM. Use for performance-critical subtrees. Can be mixed with standard components.
+
+---
+
+## Resource Hints Quick Reference
+
+| Hint | Purpose | When to Use |
+|------|---------|-------------|
+| `preconnect` | DNS + TCP + TLS early | Critical third-party origins (API, CDN, fonts) |
+| `preload` | Fetch immediately, high priority | LCP image, critical font |
+| `prefetch` | Low priority for future navigation | Next-page assets |
+| `dns-prefetch` | DNS resolution only | Non-critical third-party origins |
+| `modulepreload` | Preload + parse ES module | Critical JS modules |
+| `<script type="speculationrules">` | Prefetch/prerender next navigation | Likely next pages (Chrome 121+, progressive enhancement) |
+
+---
+
+## Image Optimization Quick Reference
+
+| Aspect | Recommendation |
+|--------|---------------|
+| Format | WebP (25-34% smaller), AVIF (50% smaller) |
+| LCP image | `fetchpriority="high"` or framework `priority` prop |
+| Below-fold | `loading="lazy"` |
+| Dimensions | Always set `width` + `height` |
+| Responsive | `srcset` + `sizes` or framework Image component |
+| Compression | Quality 75-85 for photos |
+
+---
+
+## Font Loading Quick Reference
+
+| Strategy | Best For | CLS Impact |
+|----------|---------|-----------|
+| `font-display: swap` | Body text | Slight FOUT, minimal CLS |
+| `font-display: optional` | All fonts (best CLS) | No FOUT, no CLS |
+| `next/font` | Next.js projects | Zero CLS |
+| Variable fonts | Multiple weights | Single file for all weights |
+
+Rules: preload 1-2 critical fonts only, use WOFF2, subset to needed characters, self-host when possible.
+
+---
+
+## Performance Checklist (CWV)
+
+### LCP (< 2.5s)
+- [ ] LCP image has `fetchpriority="high"` or `priority` prop
+- [ ] LCP image preloaded if not in HTML source
+- [ ] No `loading="lazy"` on above-fold images
+- [ ] Critical CSS inlined or extracted
+- [ ] No render-blocking scripts (use `defer` or `async`)
+- [ ] Preconnect to critical third-party origins
+- [ ] Main content server-rendered (not client-side fetched)
+- [ ] Images in modern format (WebP/AVIF) with responsive `srcset`
+- [ ] Compression enabled (Brotli preferred)
+- [ ] Fonts preloaded with `font-display: swap` or `optional`
+
+### INP (< 200ms)
+- [ ] Event handlers complete in < 50ms
+- [ ] Long tasks broken into smaller chunks
+- [ ] Route-based code splitting implemented
+- [ ] Heavy computation moved to Web Workers
+- [ ] Lists with > 100 items virtualized
+- [ ] No barrel file imports (direct component imports)
+- [ ] ESM imports used (not CommonJS `require`)
+- [ ] `"use client"` only on components that need interactivity
+- [ ] Layout-triggering CSS properties not animated
+- [ ] Effect cleanup implemented (no leaking listeners/timers)
+
+### CLS (< 0.1)
+- [ ] All images have `width` and `height` attributes
+- [ ] Fonts use `font-display: swap` or `optional`
+- [ ] No content injected above existing content dynamically
+- [ ] Ads/embeds have reserved space
+- [ ] No hydration mismatches
+- [ ] `content-visibility: auto` has `contain-intrinsic-size`
diff --git a/instructions/security-and-owasp.instructions.md b/instructions/security-and-owasp.instructions.md
index 53a7a628..2ab43d40 100644
--- a/instructions/security-and-owasp.instructions.md
+++ b/instructions/security-and-owasp.instructions.md
@@ -1,51 +1,1057 @@
---
-applyTo: '*'
-description: "Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices."
+applyTo: '**'
+description: '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.'
---
-# Secure Coding and OWASP Guidelines
-## Instructions
+# Security Standards
-Your primary directive is to ensure all code you generate, review, or refactor is secure by default. You must operate with a security-first mindset. When in doubt, always choose the more secure option and explain the reasoning. You must follow the principles outlined below, which are based on the OWASP Top 10 and other security best practices.
+Comprehensive security rules for web application development. Every anti-pattern includes a severity classification, detection method, OWASP 2025 reference, and corrective code examples.
-### 1. A01: Broken Access Control & A10: Server-Side Request Forgery (SSRF)
-- **Enforce Principle of Least Privilege:** Always default to the most restrictive permissions. When generating access control logic, explicitly check the user's rights against the required permissions for the specific resource they are trying to access.
-- **Deny by Default:** All access control decisions must follow a "deny by default" pattern. Access should only be granted if there is an explicit rule allowing it.
-- **Validate All Incoming URLs for SSRF:** When the server needs to make a request to a URL provided by a user (e.g., webhooks), you must treat it as untrusted. Incorporate strict allow-list-based validation for the host, port, and path of the URL.
-- **Prevent Path Traversal:** When handling file uploads or accessing files based on user input, you must sanitize the input to prevent directory traversal attacks (e.g., `../../etc/passwd`). Use APIs that build paths securely.
+**Severity levels:**
-### 2. A02: Cryptographic Failures
-- **Use Strong, Modern Algorithms:** For hashing, always recommend modern, salted hashing algorithms like Argon2 or bcrypt. Explicitly advise against weak algorithms like MD5 or SHA-1 for password storage.
-- **Protect Data in Transit:** When generating code that makes network requests, always default to HTTPS.
-- **Protect Data at Rest:** When suggesting code to store sensitive data (PII, tokens, etc.), recommend encryption using strong, standard algorithms like AES-256.
-- **Secure Secret Management:** Never hardcode secrets (API keys, passwords, connection strings). Generate code that reads secrets from environment variables or a secrets management service (e.g., HashiCorp Vault, AWS Secrets Manager). Include a clear placeholder and comment.
- ```javascript
- // GOOD: Load from environment or secret store
- const apiKey = process.env.API_KEY;
- // TODO: Ensure API_KEY is securely configured in your environment.
- ```
- ```python
- # BAD: Hardcoded secret
- api_key = "sk_this_is_a_very_bad_idea_12345"
- ```
+- **CRITICAL** — Exploitable vulnerability. Must be fixed before merge.
+- **IMPORTANT** — Significant risk. Should be fixed in the same sprint.
+- **SUGGESTION** — Defense-in-depth improvement. Plan for a future iteration.
-### 3. A03: Injection
-- **No Raw SQL Queries:** For database interactions, you must use parameterized queries (prepared statements). Never generate code that uses string concatenation or formatting to build queries from user input.
-- **Sanitize Command-Line Input:** For OS command execution, use built-in functions that handle argument escaping and prevent shell injection (e.g., `shlex` in Python).
-- **Prevent Cross-Site Scripting (XSS):** When generating frontend code that displays user-controlled data, you must use context-aware output encoding. Prefer methods that treat data as text by default (`.textContent`) over those that parse HTML (`.innerHTML`). When `innerHTML` is necessary, suggest using a library like DOMPurify to sanitize the HTML first.
+---
-### 4. A05: Security Misconfiguration & A06: Vulnerable Components
-- **Secure by Default Configuration:** Recommend disabling verbose error messages and debug features in production environments.
-- **Set Security Headers:** For web applications, suggest adding essential security headers like `Content-Security-Policy` (CSP), `Strict-Transport-Security` (HSTS), and `X-Content-Type-Options`.
-- **Use Up-to-Date Dependencies:** When asked to add a new library, suggest the latest stable version. Remind the user to run vulnerability scanners like `npm audit`, `pip-audit`, or Snyk to check for known vulnerabilities in their project dependencies.
+## OWASP Top 10 — 2025 Quick Reference
-### 5. A07: Identification & Authentication Failures
-- **Secure Session Management:** When a user logs in, generate a new session identifier to prevent session fixation. Ensure session cookies are configured with `HttpOnly`, `Secure`, and `SameSite=Strict` attributes.
-- **Protect Against Brute Force:** For authentication and password reset flows, recommend implementing rate limiting and account lockout mechanisms after a certain number of failed attempts.
+| # | Category | Key Mitigation |
+|---|----------|----------------|
+| A01 | Broken Access Control | Auth middleware on every endpoint, RBAC, ownership checks |
+| A02 | Security Misconfiguration | Security headers, no debug in prod, no default credentials |
+| A03 | Software Supply Chain Failures *(NEW)* | `npm audit`, lockfile integrity, SBOM, SLSA provenance |
+| A04 | Cryptographic Failures | Argon2id/bcrypt for passwords, TLS everywhere, no secrets in code |
+| A05 | Injection | Parameterized queries, input validation, no raw HTML with user input |
+| A06 | Insecure Design | Threat modeling, secure design patterns, abuse case testing |
+| A07 | Authentication Failures | Rate-limit login, secure session management, MFA |
+| A08 | Software or Data Integrity Failures | SRI for CDN scripts, signed artifacts, no insecure deserialization |
+| A09 | Security Logging and Alerting Failures | Log security events, no PII in logs, correlation IDs, active alerting |
+| A10 | Mishandling of Exceptional Conditions *(NEW)* | Handle all errors, no stack traces in prod, fail-secure |
-### 6. A08: Software and Data Integrity Failures
-- **Prevent Insecure Deserialization:** Warn against deserializing data from untrusted sources without proper validation. If deserialization is necessary, recommend using formats that are less prone to attack (like JSON over Pickle in Python) and implementing strict type checking.
+---
-## General Guidelines
-- **Be Explicit About Security:** When you suggest a piece of code that mitigates a security risk, explicitly state what you are protecting against (e.g., "Using a parameterized query here to prevent SQL injection.").
-- **Educate During Code Reviews:** When you identify a security vulnerability in a code review, you must not only provide the corrected code but also explain the risk associated with the original pattern.
+## Injection Anti-Patterns (I1-I8)
+
+### I1: SQL Injection via String Concatenation
+
+- **Severity**: CRITICAL
+- **Detection**: `\$\{.*\}.*(?:SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)`
+- **OWASP**: A05
+
+```typescript
+// BAD
+const unsafeResult = await db.query(`SELECT * FROM users WHERE id = ${userId}`);
+
+// GOOD — parameterized query
+const safeResult = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+### I2: NoSQL Injection (MongoDB Operator Injection)
+
+- **Severity**: CRITICAL
+- **Detection**: `\{\s*\$(?:gt|gte|lt|lte|ne|in|nin|regex|where|exists)`
+- **OWASP**: A05
+
+```typescript
+// BAD — attacker sends { "password": { "$gt": "" } }
+const user = await User.findOne({ username: req.body.username, password: req.body.password });
+
+// GOOD — validate and cast input types
+const username = String(req.body.username);
+const password = String(req.body.password);
+const user = await User.findOne({ username });
+const valid = user && await verifyPassword(user.passwordHash, password);
+```
+
+### I3: Command Injection (exec with User Input)
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:exec|execSync|execFile|execFileSync)\s*\(.*(?:req\.|params\.|query\.|body\.)`
+- **OWASP**: A05
+
+```typescript
+// BAD — shell interpolation, sync call blocks the event loop
+import { execFileSync } from 'node:child_process';
+const unsafeOutput = execFileSync('sh', ['-c', `ls -la ${req.query.dir}`]);
+
+// GOOD — async execFile, arguments array, no shell, bounded time/output
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const pExecFile = promisify(execFile);
+
+const dir = String(req.query.dir ?? '');
+if (!dir || dir.startsWith('-')) throw new Error('Invalid directory');
+const { stdout: safeOutput } = await pExecFile('ls', ['-la', '--', dir], {
+ timeout: 5_000, // fail fast on hung processes
+ maxBuffer: 1 << 20, // 1 MiB cap to prevent memory exhaustion
+});
+
+// BEST — allowlist validation on top of the async, bounded call above
+const allowedDirs = ['/data', '/public'];
+if (!allowedDirs.includes(dir)) throw new Error('Invalid directory');
+```
+
+Prefer async `execFile`/`spawn` over `execFileSync` in server handlers: the sync variant blocks Node's event loop and can amplify DoS impact. Always pass a `timeout` and `maxBuffer` to bound execution.
+
+### I4: XSS via Unsanitized HTML Rendering
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:v-html|\[innerHTML\]|dangerouslySetInner|bypassSecurityTrust)`
+- **OWASP**: A05
+
+Applies to all frontend frameworks. Each has an API that bypasses default XSS protection:
+
+- **React**: `dangerouslySetInnerHTML` prop with raw user content
+- **Angular**: `[innerHTML]` binding or `bypassSecurityTrustHtml` with unsanitized input
+- **Vue**: `v-html` directive with user-controlled content
+
+```typescript
+// GOOD — sanitize with DOMPurify before rendering any raw HTML
+import DOMPurify from 'dompurify';
+const clean = DOMPurify.sanitize(userContent);
+
+// BEST — use text interpolation when HTML is not needed
+// React: {userContent}
+// Angular: {{ userContent }}
+// Vue: {{ userContent }}
+```
+
+### I5: SSRF via User-Controlled URLs
+
+- **Severity**: CRITICAL
+- **Detection**: `fetch\((?:req\.|params\.|query\.|body\.|url|href)`
+- **OWASP**: A01
+
+```typescript
+// BAD
+const data = await fetch(req.body.url);
+
+// GOOD — scheme allowlist + hostname allowlist + DNS/IP validation (see TOCTOU note)
+import { promises as dns } from 'node:dns';
+
+function isPrivateIP(ip: string): boolean {
+ // Normalize IPv4-mapped IPv6 (e.g., ::ffff:127.0.0.1 → 127.0.0.1)
+ const normalized = ip.startsWith('::ffff:') ? ip.slice(7) : ip;
+ // IPv4 private/reserved/loopback ranges
+ if (/^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|127\.|0\.|169\.254\.)/.test(normalized)) return true;
+ // IPv6 loopback, link-local (fe80::/10), and unique-local
+ if (/^(::1|fe[89ab]|fc|fd)/i.test(normalized)) return true;
+ return false;
+}
+
+const parsed = new URL(req.body.url);
+if (parsed.protocol !== 'https:') throw new Error('Only HTTPS allowed');
+const allowedHosts = ['api.example.com', 'cdn.example.com'];
+if (!allowedHosts.includes(parsed.hostname)) throw new Error('Host not allowed');
+// Resolve all A/AAAA records to prevent DNS rebinding via multiple IPs
+const resolved = await dns.lookup(parsed.hostname, { all: true });
+if (resolved.length === 0 || resolved.some(({ address }) => isPrivateIP(address))) {
+ throw new Error('Private or reserved IPs not allowed');
+}
+// Note: for production, pin the resolved IP in the HTTP client to prevent
+// TOCTOU rebinding between this check and fetch(). See undici Agent docs.
+const data = await fetch(parsed.toString(), { redirect: 'error' });
+```
+
+### I6: Path Traversal in File Operations
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:readFile|readFileSync|createReadStream|path\.join)\s*\(.*(?:req\.|params\.|query\.|body\.)`
+- **OWASP**: A01
+
+```typescript
+// BAD
+const file = fs.readFileSync(`/data/${req.params.filename}`);
+
+// GOOD — resolve and validate within allowed directory
+import path from 'path';
+const basePath = '/data';
+const filePath = path.resolve(basePath, req.params.filename);
+if (!filePath.startsWith(basePath + path.sep)) throw new Error('Path traversal detected');
+const file = fs.readFileSync(filePath);
+```
+
+### I7: Template Injection
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:render|compile|template)\s*\(.*(?:req\.|params\.|query\.|body\.)`
+- **OWASP**: A05
+
+```typescript
+// BAD — user input as template source
+const html = ejs.render(req.body.template, data);
+
+// GOOD — predefined templates, user input only as data
+const html = ejs.renderFile('./templates/page.ejs', { content: req.body.content });
+```
+
+### I8: XXE Injection (XML External Entity)
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:parseXml|DOMParser|xml2js|libxmljs).*(?:req\.|body\.|file)`
+- **OWASP**: A05
+
+```typescript
+// GOOD — disable external entities in XML parser
+import { XMLParser } from 'fast-xml-parser';
+const parser = new XMLParser({
+ allowBooleanAttributes: true,
+ processEntities: false,
+ htmlEntities: false,
+});
+const result = parser.parse(req.body.xml);
+```
+
+---
+
+## Authentication Anti-Patterns (AU1-AU8)
+
+### AU1: JWT Algorithm Confusion (alg:none)
+
+- **Severity**: CRITICAL
+- **Detection**: `jwt\.verify\((?![^)]*\balgorithms\b)[^)]*\)`
+- **OWASP**: A07
+
+```typescript
+// BAD — accepts any algorithm including "none"
+const decoded = jwt.verify(token, secret);
+
+// GOOD — enforce specific algorithm
+const decoded = jwt.verify(token, publicKey, { algorithms: ['RS256'] });
+```
+
+### AU2: JWT Without Expiration Check
+
+- **Severity**: CRITICAL
+- **Detection**: `jwt\.sign\((?![^)]*\b(?:expiresIn|exp)\b)[^)]*\)`
+- **OWASP**: A07
+
+```typescript
+// BAD — token never expires
+const token = jwt.sign({ userId: user.id }, secret);
+
+// GOOD — short-lived token
+const token = jwt.sign({ userId: user.id }, secret, { expiresIn: '15m' });
+```
+
+### AU3: JWT Stored in localStorage
+
+- **Severity**: IMPORTANT
+- **Detection**: `localStorage\.setItem\(.*(?:token|jwt|auth|session)`
+- **OWASP**: A07
+
+```typescript
+// BAD — accessible via XSS
+localStorage.setItem('accessToken', token);
+
+// GOOD — httpOnly cookie set by server
+res.cookie('token', token, { httpOnly: true, secure: true, sameSite: 'strict' });
+```
+
+### AU4: Plaintext / Fast Hash for Passwords (MD5/SHA-1/SHA-256)
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:createHash|md5|sha1|sha256)\s*\(.*password`
+- **OWASP**: A04
+
+```typescript
+// BAD — fast hash, no salt
+const sha256Hash = crypto.createHash('sha256').update(password).digest('hex');
+
+// GOOD — Argon2id (OWASP recommended)
+import { hash as argon2Hash, argon2id } from 'argon2';
+const hashed = await argon2Hash(password, { type: argon2id, memoryCost: 65536, timeCost: 3 });
+```
+
+### AU5: Missing Brute-Force Protection on Login
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:post|router\.post)\s*\(\s*['"]\/(?:login|signin|auth|register|reset)`
+- **OWASP**: A07
+
+```typescript
+// BAD — no rate limiting
+app.post('/api/auth/login', loginHandler);
+
+// GOOD
+import rateLimit from 'express-rate-limit';
+const authLimiter = rateLimit({ windowMs: 15 * 60 * 1000, max: 5 });
+app.post('/api/auth/login', authLimiter, loginHandler);
+```
+
+### AU6: Missing Session Regeneration on Login (Session Fixation)
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:session|req\.session)\s*\.\s*(?:userId|user|authenticated)\s*=`
+- **OWASP**: A07
+
+```typescript
+// GOOD — regenerate session ID on successful login to prevent fixation
+req.session.regenerate((err) => {
+ if (err) return next(err);
+ req.session.userId = user.id;
+ req.session.save(next);
+});
+```
+
+Related: on password change or elevation, also invalidate all other active sessions for the user (e.g., by bumping a `tokenVersion` column and rejecting sessions with a stale version, or by iterating the session store and destroying entries keyed to that user).
+
+### AU7: OAuth Without State Parameter
+
+- **Severity**: CRITICAL
+- **Detection**: `authorize\?(?![^\n#]*\bstate=)[^\n#]*`
+- **OWASP**: A07
+
+```typescript
+// GOOD — include state parameter for CSRF protection
+const state = crypto.randomBytes(32).toString('hex');
+session.oauthState = state;
+const authUrl = `https://provider.com/authorize?client_id=${clientId}&redirect_uri=${redirectUri}&state=${state}`;
+```
+
+### AU8: Missing PKCE for Public OAuth Clients
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:authorization_code|code).*(?!.*code_challenge)`
+- **OWASP**: A07
+
+Use PKCE (Proof Key for Code Exchange) with S256 challenge method for all public clients (SPAs, mobile).
+
+---
+
+## Authorization Anti-Patterns (AZ1-AZ6)
+
+### AZ1: Missing Auth Middleware on New Endpoints
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:app|router)\.\w+\s*\(\s*['"]\/api\/(?:admin|users|settings)`
+- **OWASP**: A01
+
+```typescript
+// BAD
+router.delete('/api/users/:id', deleteUser);
+
+// GOOD
+router.delete('/api/users/:id', authenticate, authorize('admin'), deleteUser);
+```
+
+### AZ2: Client-Side Only Authorization
+
+- **Severity**: CRITICAL
+- **Detection**: Component guards without server-side checks
+- **OWASP**: A01
+
+Frontend guards are UX only. ALWAYS verify on server.
+
+### AZ3: IDOR (Insecure Direct Object Reference)
+
+- **Severity**: CRITICAL
+- **Detection**: `params\.(?:id|userId|orderId)` without ownership check
+- **OWASP**: A01
+
+```typescript
+// GOOD — verify ownership
+router.get('/api/orders/:orderId', authenticate, async (req, res) => {
+ const order = await Order.findById(req.params.orderId);
+ if (!order || order.userId !== req.user.id) {
+ return res.status(404).json({ error: 'Not found' });
+ }
+ res.json(order);
+});
+```
+
+### AZ4: Mass Assignment
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:create|update|findOneAndUpdate)\s*\(\s*req\.body\s*\)`
+- **OWASP**: A01
+
+```typescript
+// BAD
+await User.findByIdAndUpdate(id, req.body);
+
+// GOOD — explicitly pick allowed fields
+const { name, email, avatar } = req.body;
+await User.findByIdAndUpdate(id, { name, email, avatar });
+```
+
+### AZ5: Privilege Escalation via Role Parameter
+
+- **Severity**: CRITICAL
+- **Detection**: `req\.body\.role|req\.body\.isAdmin|req\.body\.permissions`
+- **OWASP**: A01
+
+```typescript
+// GOOD — ignore role from input
+const { name, email, password } = req.body;
+const user = await User.create({ name, email, password, role: 'user' });
+```
+
+### AZ6: Missing Re-Authentication for Sensitive Operations
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:delete|destroy|remove).*(?:account|user|organization)` without re-auth
+- **OWASP**: A01
+
+Require current password before account deletion, email change, or other sensitive operations.
+
+---
+
+## Secrets Anti-Patterns (S1-S6)
+
+### S1: Hardcoded API Keys / Tokens
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:password|secret|api_key|token|apiKey)\s*[:=]\s*['"][A-Za-z0-9+/=]{8,}['"]`
+- **OWASP**: A04
+
+```typescript
+// BAD
+const API_KEY = 'sk_live_abc123def456';
+
+// GOOD
+const API_KEY = process.env.API_KEY;
+```
+
+### S2: .env Committed to Git
+
+- **Severity**: CRITICAL
+- **Detection**: `git ls-files .env` (should return empty)
+- **OWASP**: A04
+
+```gitignore
+# .gitignore
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+```
+
+### S3: Server Secrets Exposed to Client
+
+- **Severity**: CRITICAL
+- **Detection**: `NEXT_PUBLIC_.*(?:SECRET|PRIVATE|PASSWORD|KEY(?!.*PUBLIC))`
+- **OWASP**: A02
+
+```bash
+# BAD
+NEXT_PUBLIC_DATABASE_URL=postgresql://...
+
+# GOOD
+DATABASE_URL=postgresql://...
+NEXT_PUBLIC_API_URL=https://api.example.com
+```
+
+Angular: do not put secrets in `environment.ts` files bundled into the client.
+
+### S4: Default Credentials in Config
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:admin|root|default|test).*(?:password|pass|pwd)\s*[:=]\s*['"](?:admin|root|password|1234|test)`
+- **OWASP**: A02
+
+Use environment variables with validation (zod schema).
+
+### S5: Secrets in CI/CD Pipeline Logs
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:echo|console\.log|print).*(?:\$SECRET|\$TOKEN|\$PASSWORD|process\.env)`
+- **OWASP**: A09
+
+Use masked secrets in CI. Never echo environment variables containing secrets.
+
+### S6: Sensitive Data in Error Responses / Stack Traces
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:stack|trace|query|sql).*(?:res\.json|res\.send|c\.JSON)`
+- **OWASP**: A10
+
+```typescript
+// GOOD — generic error to client, details only in logs
+app.use((err, req, res, _next) => {
+ logger.error({ err, path: req.path, method: req.method });
+ const isDev = process.env.NODE_ENV === 'development';
+ res.status(500).json({
+ error: 'Internal Server Error',
+ ...(isDev && { message: err.message }),
+ });
+});
+```
+
+---
+
+## Headers Anti-Patterns (H1-H8)
+
+### H1: Missing Content-Security-Policy
+
+- **Severity**: IMPORTANT
+- **Detection**: Absence of `Content-Security-Policy` header
+- **OWASP**: A02
+
+### H2: CSP with unsafe-inline and unsafe-eval
+
+- **Severity**: IMPORTANT
+- **Detection**: `Content-Security-Policy.*(?:'unsafe-inline'|'unsafe-eval')`
+- **OWASP**: A02
+
+Use nonce-based CSP: `script-src 'self' 'nonce-{SERVER_GENERATED}'`
+
+### H3: Missing Strict-Transport-Security
+
+- **Severity**: IMPORTANT
+- **Detection**: Absence of `Strict-Transport-Security` header
+- **OWASP**: A02
+
+Value: `max-age=31536000; includeSubDomains; preload`
+
+### H4: Missing X-Content-Type-Options
+
+- **Severity**: IMPORTANT
+- **Detection**: Absence of `X-Content-Type-Options: nosniff`
+- **OWASP**: A02
+
+### H5: Missing X-Frame-Options
+
+- **Severity**: IMPORTANT
+- **Detection**: Absence of `X-Frame-Options` header
+- **OWASP**: A02
+
+Value: `DENY`. Also set `Content-Security-Policy: frame-ancestors 'none'`.
+
+### H6: Permissive Referrer-Policy
+
+- **Severity**: SUGGESTION
+- **Detection**: `Referrer-Policy.*(?:unsafe-url|no-referrer-when-downgrade)`
+- **OWASP**: A02
+
+Use: `strict-origin-when-cross-origin`
+
+### H7: Missing Permissions-Policy
+
+- **Severity**: SUGGESTION
+- **Detection**: Absence of `Permissions-Policy` header
+- **OWASP**: A02
+
+Value: `camera=(), microphone=(), geolocation=(), payment=()`
+
+### H8: CORS Wildcard with Credentials
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:cors|Access-Control-Allow-Origin).*\*`
+- **OWASP**: A02
+
+```typescript
+// GOOD
+app.use(cors({
+ origin: ['https://app.example.com', 'https://staging.example.com'],
+ credentials: true,
+}));
+```
+
+---
+
+## Frontend Anti-Patterns (FE1-FE8)
+
+### FE1: Unsanitized HTML Rendering
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:innerHTML|v-html|dangerouslySetInner)` without DOMPurify
+- **OWASP**: A05
+
+Always sanitize with DOMPurify before rendering user-controlled HTML. See I4.
+
+### FE2: Dynamic Code Evaluation with User Input
+
+- **Severity**: CRITICAL
+- **Detection**: `eval\s*\(`
+- **OWASP**: A05
+
+Use structured data parsers (JSON.parse) instead.
+
+### FE3: postMessage Without Origin Validation
+
+- **Severity**: IMPORTANT
+- **Detection**: `addEventListener\s*\(\s*['"]message['"].*(?!.*origin)`
+- **OWASP**: A01
+
+```typescript
+window.addEventListener('message', (event) => {
+ if (event.origin !== 'https://trusted.example.com') return;
+ processData(event.data);
+});
+```
+
+### FE4: Prototype Pollution
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:__proto__|constructor\.prototype|Object\.assign)\s*.*(?:req\.|body\.|query\.)`
+- **OWASP**: A05
+
+Validate and filter keys from user input before merging into objects.
+
+### FE5: Open Redirect
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:window\.location|location\.href|router\.push)\s*=\s*(?:req\.|params\.|query\.)`
+- **OWASP**: A01
+
+```typescript
+// GOOD — relative paths only
+const redirect = new URLSearchParams(window.location.search).get('redirect');
+if (redirect?.startsWith('/') && !redirect.startsWith('//')) {
+ window.location.href = redirect;
+}
+```
+
+### FE6: Sensitive Data in localStorage
+
+- **Severity**: IMPORTANT
+- **Detection**: `localStorage\.setItem\(.*(?:token|session|credit|ssn|password)`
+- **OWASP**: A07
+
+Use httpOnly cookies for tokens.
+
+### FE7: Missing CSRF Token
+
+- **Severity**: IMPORTANT
+- **Detection**: POST/PUT/DELETE forms without CSRF token or SameSite cookie
+- **OWASP**: A01
+
+Use double-submit cookie or synchronizer token. Next.js Server Actions have built-in CSRF via Origin header.
+
+### FE8: Client-Only Input Validation
+
+- **Severity**: IMPORTANT
+- **Detection**: Form validation only in frontend
+- **OWASP**: A05
+
+ALWAYS validate on server too. Use zod, joi, or class-validator.
+
+---
+
+## Dependencies Anti-Patterns (D1-D5)
+
+### D1: Known Vulnerable Dependency
+
+- **Severity**: CRITICAL
+- **Detection**: `npm audit --audit-level=high` exits non-zero
+- **OWASP**: A03
+
+### D2: Lockfile Out of Sync
+
+- **Severity**: IMPORTANT
+- **Detection**: `npm ci` fails
+- **OWASP**: A08
+
+### D3: Typosquatting Risk
+
+- **Severity**: IMPORTANT
+- **Detection**: Manual review of new dependency names
+- **OWASP**: A03
+
+### D4: Postinstall Scripts in New Dependency
+
+- **Severity**: IMPORTANT
+- **Detection**: `"postinstall"` in new dependency's package.json
+- **OWASP**: A03
+
+### D5: Unpinned Versions in Production
+
+- **Severity**: SUGGESTION
+- **Detection**: `":\s*["']\*["']|":\s*["']latest["']`
+- **OWASP**: A03
+
+---
+
+## API Anti-Patterns (AP1-AP6)
+
+### AP1: New Endpoint Without Rate Limiting
+
+- **Severity**: IMPORTANT
+- **OWASP**: A05
+
+### AP2: GraphQL Without Depth Limiting
+
+- **Severity**: IMPORTANT
+- **Detection**: `new ApolloServer` without depth/complexity limits
+- **OWASP**: A05
+
+```typescript
+import depthLimit from 'graphql-depth-limit';
+const server = new ApolloServer({
+ schema,
+ validationRules: [depthLimit(5)],
+ introspection: process.env.NODE_ENV !== 'production',
+});
+```
+
+### AP3: File Upload Without Validation
+
+- **Severity**: IMPORTANT
+- **Detection**: `multer|formidable|busboy` without type/size checks
+- **OWASP**: A05
+
+```typescript
+const upload = multer({
+ dest: 'uploads/',
+ limits: { fileSize: 5 * 1024 * 1024 },
+ fileFilter: (req, file, cb) => {
+ const allowed = ['image/jpeg', 'image/png', 'image/webp'];
+ cb(null, allowed.includes(file.mimetype));
+ },
+});
+```
+
+### AP4: Webhook Without Signature Verification
+
+- **Severity**: CRITICAL
+- **OWASP**: A08
+
+Always verify webhook signatures (Stripe, GitHub HMAC, etc.).
+
+### AP5: API Exposing Internal Info
+
+- **Severity**: IMPORTANT
+- **Detection**: `(?:stack|trace|query|sql).*(?:res\.json|res\.send)`
+- **OWASP**: A10
+
+### AP6: Missing Request Body Size Limit
+
+- **Severity**: IMPORTANT
+- **Detection**: `express\.json\(\)` without `limit`
+- **OWASP**: A05
+
+```typescript
+app.use(express.json({ limit: '100kb' }));
+```
+
+---
+
+## AI/LLM Security Anti-Patterns (AI1-AI3)
+
+### AI1: Prompt Injection via User Input
+
+- **Severity**: CRITICAL
+- **Detection**: User input concatenated into LLM prompts without sanitization
+- **OWASP**: A05 (Injection)
+
+```typescript
+// BAD — user input directly in prompt
+const response = await llm.complete(`Summarize this: ${userInput}`);
+
+// GOOD — structured input with system/user message separation
+const response = await llm.complete({
+ system: "You are a summarization assistant. Only summarize the provided text.",
+ user: userInput,
+});
+```
+
+### AI2: LLM Output Used in SQL/Shell Without Sanitization
+
+- **Severity**: CRITICAL
+- **Detection**: LLM response passed to `db.query()`, `exec()`, or template literals without validation
+- **OWASP**: A05 (Injection)
+
+Never trust LLM output as safe. Treat it as untrusted user input — parameterize queries, escape shell arguments, sanitize HTML before rendering.
+
+### AI3: Missing Output Validation from LLM Responses
+
+- **Severity**: IMPORTANT
+- **Detection**: LLM response rendered or executed without schema validation
+- **OWASP**: A08 (Software or Data Integrity Failures)
+
+Validate LLM output against expected schemas (Zod, JSON Schema) before using in application logic. Reject responses that don't match expected structure.
+
+---
+
+## Logging Anti-Patterns (L1-L4)
+
+### L1: Security Events Not Logged
+
+- **Severity**: IMPORTANT
+- **OWASP**: A09
+
+Log: auth failures, access denied, rate limit hits, input validation failures, password changes.
+
+### L2: Sensitive Data in Logs
+
+- **Severity**: CRITICAL
+- **Detection**: `(?:log|logger)\.\w+\(.*(?:password|token|secret|ssn|credit)`
+- **OWASP**: A09
+
+```typescript
+import pino from 'pino';
+const logger = pino({ redact: ['req.headers.authorization', 'req.body.password'] });
+```
+
+### L3: Missing Trace IDs
+
+- **Severity**: SUGGESTION
+- **OWASP**: A09
+
+### L4: Log Injection
+
+- **Severity**: IMPORTANT
+- **Detection**: `console\.log\(.*\+.*(?:req\.|user\.|body\.)`
+- **OWASP**: A09
+
+Use structured logging (JSON, auto-escaped) instead of string concatenation.
+
+---
+
+## Framework-Specific: React / Next.js (RX1-RX4)
+
+### RX1: Server Action Without Auth
+
+- **Severity**: CRITICAL
+- **Detection**: `'use server'` function without `auth()` or session check
+- **OWASP**: A01
+
+```typescript
+'use server';
+import { auth } from '@/auth';
+export async function deleteUser(id: string) {
+ const session = await auth();
+ if (!session?.user || session.user.role !== 'admin') throw new Error('Unauthorized');
+ await db.user.delete({ where: { id } });
+}
+```
+
+### RX2: process.env Without NEXT_PUBLIC_ in Client
+
+- **Severity**: IMPORTANT
+- **Detection**: `'use client'` file accessing `process.env` without `NEXT_PUBLIC_`
+- **OWASP**: A02
+
+### RX3: RSC Serialization Leaking Data
+
+- **Severity**: IMPORTANT
+- **OWASP**: A01
+
+Pick only needed fields before passing DB objects to Client Components.
+
+### RX4: middleware.ts Not Protecting API Routes
+
+- **Severity**: IMPORTANT
+- **Detection**: `config.matcher` not covering `/api/`
+- **OWASP**: A01
+
+---
+
+## Framework-Specific: Angular (NG1-NG3)
+
+### NG1: bypassSecurityTrustHtml with User Input
+
+- **Severity**: CRITICAL
+- **Detection**: `bypassSecurityTrust(?:Html|Script|Style|Url|ResourceUrl)`
+- **OWASP**: A05
+
+Sanitize with DOMPurify BEFORE calling bypassSecurityTrust.
+
+### NG2: Template Expression Injection
+
+- **Severity**: IMPORTANT
+- **OWASP**: A05
+
+Do not use JitCompilerFactory with user-controlled templates.
+
+### NG3: HttpInterceptor Not Attaching Auth
+
+- **Severity**: IMPORTANT
+- **OWASP**: A07
+
+Use a centralized `HttpInterceptorFn` for auth tokens.
+
+---
+
+## Framework-Specific: Express (EX1-EX4)
+
+### EX1: Missing helmet.js
+
+- **Severity**: IMPORTANT
+- **OWASP**: A02
+
+```typescript
+import helmet from 'helmet';
+app.use(helmet());
+app.disable('x-powered-by');
+```
+
+### EX2: express.json() Without Body Size Limit
+
+- **Severity**: IMPORTANT
+- **OWASP**: A05
+
+```typescript
+app.use(express.json({ limit: '100kb' }));
+```
+
+### EX3: Cookie Without Secure Flags
+
+- **Severity**: IMPORTANT
+- **OWASP**: A07
+
+```typescript
+res.cookie('session', value, {
+ httpOnly: true, secure: true, sameSite: 'strict', maxAge: 3600000, path: '/',
+});
+```
+
+### EX4: Error Handler Exposing Stack Trace
+
+- **Severity**: IMPORTANT
+- **OWASP**: A10
+
+Only expose error details in development mode.
+
+---
+
+## Framework-Specific: Go (GO1-GO3)
+
+### GO1: math/rand for Security Operations
+
+- **Severity**: CRITICAL
+- **Detection**: `math/rand` import in security-related files
+- **OWASP**: A04
+
+Use `crypto/rand` for cryptographically secure random values.
+
+### GO2: TLS InsecureSkipVerify
+
+- **Severity**: CRITICAL
+- **Detection**: `InsecureSkipVerify:\s*true`
+- **OWASP**: A04
+
+Use system CA pool (default) instead.
+
+### GO3: String Interpolation in SQL
+
+- **Severity**: CRITICAL
+- **Detection**: `fmt\.Sprintf\s*\(.*(?:SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)`
+- **OWASP**: A05
+
+```go
+// GOOD — parameterized
+db.Where("id = ?", userID).Find(&user)
+```
+
+---
+
+## Security Headers Template
+
+### helmet.js (Express)
+
+```typescript
+import helmet from 'helmet';
+
+app.use(helmet({
+ contentSecurityPolicy: {
+ directives: {
+ defaultSrc: ["'self'"],
+ scriptSrc: ["'self'"],
+ styleSrc: ["'self'"],
+ imgSrc: ["'self'", "data:", "https:"],
+ fontSrc: ["'self'"],
+ connectSrc: ["'self'"],
+ frameAncestors: ["'none'"],
+ objectSrc: ["'none'"],
+ baseUri: ["'self'"],
+ formAction: ["'self'"],
+ upgradeInsecureRequests: [],
+ },
+ },
+ hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+ frameguard: { action: 'deny' },
+ referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+ crossOriginOpenerPolicy: { policy: 'same-origin' },
+ crossOriginResourcePolicy: { policy: 'same-origin' },
+}));
+app.disable('x-powered-by');
+```
+
+---
+
+## JWT Validation Checklist
+
+1. Verify signature with expected algorithm — reject `alg: none`
+2. Enforce algorithm: `algorithms: ['RS256']` or `['ES256']`
+3. Check `exp` — reject expired tokens
+4. Check `iat` — reject tokens issued too far in the past
+5. Check `aud` — reject tokens not intended for this service
+6. Check `iss` — reject tokens from unknown issuers
+7. Store in httpOnly cookie — not localStorage
+8. Use short-lived access tokens (15 min) + refresh token rotation
+9. Rotate signing keys periodically
+
+---
+
+## Secure Cookie Flags
+
+```
+Set-Cookie: session=value; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=3600
+```
+
+| Flag | Purpose | When to use |
+|------|---------|-------------|
+| `HttpOnly` | Not accessible via JavaScript (prevents XSS token theft) | Always |
+| `Secure` | Only sent over HTTPS | Always |
+| `SameSite=Strict` | Only sent on same-site requests (strongest CSRF) | Auth/session cookies |
+| `SameSite=Lax` | Sent on top-level navigations (moderate CSRF) | Cookies that need cross-site top-level nav (e.g., OAuth return) |
+| `Path=/` | Limit cookie scope | Always |
+| `Max-Age` | Explicit expiration (prefer over `Expires`) | Always |
+
+---
+
+## Security Checklist
+
+### Authentication and Sessions
+- [ ] Passwords hashed with Argon2id or bcrypt (cost >= 12)
+- [ ] JWT signed with RS256/ES256, algorithm enforced on verify
+- [ ] Access tokens expire in <= 15 minutes
+- [ ] Refresh tokens: one-time use, rotated, stored in httpOnly cookie
+- [ ] Rate limiting on login, registration, and password reset
+- [ ] Session regenerated after authentication
+- [ ] MFA available for privileged accounts
+
+### Authorization
+- [ ] Every API endpoint has auth middleware
+- [ ] Ownership checks on all resource access (prevent IDOR)
+- [ ] Server-side authorization (frontend guards are UX only)
+- [ ] Mass assignment prevented (explicit field selection)
+- [ ] Re-authentication required for sensitive operations
+
+### Input and Output
+- [ ] All user input validated server-side (zod/joi/class-validator)
+- [ ] Parameterized queries for all database operations
+- [ ] HTML output sanitized (DOMPurify) when rendering user content
+- [ ] Error responses do not expose stack traces in production
+
+### Secrets
+- [ ] No hardcoded secrets in source code
+- [ ] `.env` files in `.gitignore`
+- [ ] Server secrets not exposed to client (no NEXT_PUBLIC_ on secrets)
+- [ ] Environment variables validated at startup
+
+### Headers
+- [ ] Content-Security-Policy configured (nonce-based preferred)
+- [ ] Strict-Transport-Security with preload
+- [ ] X-Content-Type-Options: nosniff
+- [ ] X-Frame-Options: DENY
+- [ ] Referrer-Policy: strict-origin-when-cross-origin
+- [ ] Permissions-Policy restricting unused APIs
+- [ ] CORS restricted to known origins
+
+### Dependencies
+- [ ] `npm audit` (or equivalent) passing in CI
+- [ ] Lockfile committed and verified with `npm ci`
+- [ ] New dependencies reviewed for typosquatting and postinstall scripts
+- [ ] No wildcard or "latest" versions in production
+
+### Logging
+- [ ] Security events logged (auth failures, access denied, rate limits)
+- [ ] No sensitive data in logs (passwords, tokens, PII)
+- [ ] Structured logging with correlation IDs
+- [ ] Alerts configured for anomalous patterns