docs/testing-framework.md

@@ -352,13 +352,26 @@ npx playwright show-report
 
 ### Framework
 
-- **Unit Level**: jest-axe with Vitest
-- **E2E Level**: Playwright accessibility tests
+- **Unit Level**: jest-axe with Vitest (`tests/accessibility/unit/`)
+- **E2E Level**: Playwright accessibility tests (`tests/accessibility/e2e/`)
 - **Standards**: WCAG 2.1 AA compliance
 
-### Automated Testing
+### Test Organization
+
+Accessibility tests are organized in a dedicated `tests/accessibility/` folder:
+
+```
+tests/accessibility/
+├── unit/                          # Unit-level accessibility tests
+│   └── components.test.jsx        # Component accessibility (jest-axe)
+└── e2e/                          # E2E accessibility tests
+    └── wcag-compliance.spec.ts    # WCAG compliance (Playwright)
+```
+
+### Unit-Level Accessibility Testing
 
 ```jsx
+// tests/accessibility/unit/components.test.jsx
 import { axe, toHaveNoViolations } from "jest-axe";
 
 test("component has no accessibility violations", async () => {
@@ -368,6 +381,42 @@ test("component has no accessibility violations", async () => {
 });
 ```
 
+### E2E Accessibility Testing
+
+```typescript
+// tests/accessibility/e2e/wcag-compliance.spec.ts
+import { test, expect } from "@playwright/test";
+
+test("WCAG 2.1 AA compliance - homepage", async ({ page }) => {
+  await page.goto("/");
+
+  // Check for proper HTML structure
+  const html = page.locator("html");
+  const lang = await html.getAttribute("lang");
+  expect(lang).toBeTruthy();
+
+  // Check for main heading
+  const h1 = page.locator("h1").first();
+  await expect(h1).toBeVisible();
+});
+```
+
+### Running Accessibility Tests
+
+```bash
+# Run all accessibility tests
+npm test tests/accessibility/
+
+# Run unit accessibility tests only
+npm test tests/accessibility/unit/
+
+# Run E2E accessibility tests only
+npx playwright test tests/accessibility/e2e/
+
+# Run specific accessibility test
+npx playwright test tests/accessibility/e2e/wcag-compliance.spec.ts
+```
+
 ### Manual Testing Checklist
 
 - [ ] Screen reader compatibility

docs/testing-quick-reference.md

@@ -109,6 +109,22 @@ npm run lhci:desktop
 npm run performance:budget
 ```
 
+### Accessibility Testing
+
+```bash
+# Run all accessibility tests
+npm test tests/accessibility/
+
+# Run unit accessibility tests only
+npm test tests/accessibility/unit/
+
+# Run E2E accessibility tests only
+npx playwright test tests/accessibility/e2e/
+
+# Run specific accessibility test
+npx playwright test tests/accessibility/e2e/wcag-compliance.spec.ts
+```
+
 ## 📱 Browser Support
 
 | Browser     | Project Name | Status          |
@@ -257,20 +273,25 @@ tests/
 │   ├── RuleCard.test.jsx         # 18 tests
 │   ├── SectionHeader.test.jsx    # 17 tests
 │   ├── NumberedCard.test.jsx     # 18 tests
-│   └── accessibility.test.jsx    # 18 tests
+│   └── ...                       # Other component tests
 ├── integration/                   # Integration tests
 │   ├── component-interactions.integration.test.jsx
 │   ├── page-flow.integration.test.jsx
 │   ├── user-journey.integration.test.jsx
 │   ├── layout.integration.test.jsx
 │   └── ContentLockup.integration.test.jsx
-└── e2e/                          # E2E tests
+├── accessibility/                 # Accessibility-focused tests
+│   ├── unit/                     # Unit-level accessibility (jest-axe)
+│   │   └── components.test.jsx   # Component accessibility tests
+│   └── e2e/                      # E2E accessibility (Playwright + axe-core)
+│       └── wcag-compliance.spec.ts # WCAG compliance tests
+└── e2e/                          # General E2E tests
     ├── homepage.spec.ts          # Homepage functionality
     ├── user-journeys.spec.ts     # User workflows
     ├── header.responsive.spec.js # Responsive header
     ├── footer.responsive.spec.js # Responsive footer
     ├── visual-regression.spec.ts # Visual consistency
-    ├── accessibility.spec.ts     # Accessibility compliance
+    ├── accessibility.spec.ts     # General accessibility tests
     └── performance.spec.ts       # Performance metrics
 ```
 

playwright.config.ts

@@ -1,7 +1,11 @@
 import { defineConfig, devices } from "@playwright/test";
 
 export default defineConfig({
-  testDir: "tests/e2e",
+  testDir: "tests",
+  testMatch: [
+    "tests/e2e/**/*.spec.{js,ts}",
+    "tests/accessibility/**/*.spec.{js,ts}",
+  ],
   timeout: 60_000,
   expect: {
     timeout: 10_000,

tests/accessibility/unit/components.test.jsx

@@ -1,8 +1,8 @@
 import { describe, test, expect, beforeEach } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { axe, toHaveNoViolations } from "jest-axe";
-import Header from "../../app/components/Header.js";
-import Footer from "../../app/components/Footer.js";
+import Header from "../../../app/components/Header.js";
+import Footer from "../../../app/components/Footer.js";
 
 // Extend expect to include accessibility matchers
 expect.extend(toHaveNoViolations);
@@ -155,7 +155,7 @@ describe("Accessibility - Component Level", () => {
     }
 
     const headingLevels = headings.map((heading) =>
-      parseInt(heading.tagName.charAt(1)),
+      parseInt(heading.tagName.charAt(1))
     );
 
     // Check that heading levels are sequential (no skipping levels)

vitest.config.mjs

@@ -15,6 +15,7 @@ export default defineConfig({
     include: [
       "tests/unit/**/*.test.{js,jsx,ts,tsx}",
       "tests/integration/**/*.test.{js,jsx,ts,tsx}",
+      "tests/accessibility/**/*.test.{js,jsx,ts,tsx}",
     ],
     css: true,
     coverage: {