@diegovelasquezweb/a11y-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 diegovelasquezweb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @diegovelasquezweb/a11y-engine
+
+WCAG 2.2 AA accessibility audit engine. Scanner, analyzer, and report builders.
+
+## Install
+
+```bash
+npm i @diegovelasquezweb/a11y-engine
+npx playwright install chromium
+```
+
+## Usage
+
+```bash
+npx a11y-audit --base-url https://example.com --max-routes 5
+```
+
+## Options
+
+See `a11y-audit --help` for full CLI reference.

package/assets/discovery/crawler-config.json

@@ -0,0 +1,11 @@
+{
+  "blockedExtensions": [
+    "pdf", "jpg", "jpeg", "png", "gif", "svg", "webp", "ico",
+    "css", "js", "mjs", "json", "xml", "zip", "tar", "gz",
+    "mp4", "mp3", "webm", "wav", "woff", "woff2", "ttf", "otf", "eot",
+    "avif", "csv", "txt", "map", "wasm"
+  ],
+  "paginationParams": [
+    "page", "paged", "p", "pg", "offset", "cursor", "start", "from", "skip", "limit", "per_page"
+  ]
+}

package/assets/discovery/stack-detection.json

@@ -0,0 +1,33 @@
+{
+  "platformStructureDetectors": [
+    ["wordpress", ["wp-content/themes"]],
+    ["drupal", ["web/themes", "themes"]],
+    ["shopify", ["sections", "snippets", "layout", "templates"]]
+  ],
+  "uiLibraryPackageDetectors": [
+    ["@radix-ui", "radix"],
+    ["@headlessui", "headless-ui"],
+    ["@chakra-ui", "chakra"],
+    ["@mantine", "mantine"],
+    ["@mui", "material-ui"],
+    ["antd", "ant-design"],
+    ["@shopify/polaris", "polaris"],
+    ["@react-aria", "react-aria"],
+    ["ariakit", "ariakit"],
+    ["primevue", "primevue"],
+    ["vuetify", "vuetify"],
+    ["swiper", "swiper"]
+  ],
+  "frameworkPackageDetectors": [
+    ["next", "nextjs"],
+    ["gatsby", "gatsby"],
+    ["nuxt", "nuxt"],
+    ["@nuxt/core", "nuxt"],
+    ["@angular/core", "angular"],
+    ["astro", "astro"],
+    ["@sveltejs/kit", "svelte"],
+    ["svelte", "svelte"],
+    ["vue", "vue"],
+    ["react", "react"]
+  ]
+}

package/assets/remediation/axe-check-maps.json

@@ -0,0 +1,31 @@
+{
+  "failureModes": {
+    "button-has-visible-text": "missing_visible_text",
+    "has-visible-text": "missing_visible_text",
+    "aria-label": "missing_aria_label",
+    "aria-labelledby": "missing_or_invalid_aria_labelledby",
+    "explicit-label": "missing_accessible_label",
+    "implicit-label": "missing_accessible_label",
+    "color-contrast-enhanced": "insufficient_color_contrast",
+    "color-contrast": "insufficient_color_contrast",
+    "form-field-multiple-labels": "conflicting_label_association",
+    "label": "missing_accessible_label",
+    "select-name": "missing_select_name",
+    "presentational-role": "missing_accessible_name",
+    "only-listitems": "invalid_list_structure",
+    "listitem": "orphaned_list_item",
+    "heading-order": "invalid_heading_order",
+    "meta-viewport": "zoom_disabled",
+    "region": "content_outside_landmarks"
+  },
+  "relationshipHints": {
+    "aria-labelledby": "aria_labelledby_references_missing_or_invalid_target",
+    "explicit-label": "label_not_associated_with_control",
+    "implicit-label": "control_has_no_wrapped_label",
+    "form-field-multiple-labels": "multiple_labels_reference_same_control",
+    "label": "control_has_no_accessible_label_source",
+    "select-name": "select_has_no_accessible_label_source",
+    "aria-label": "control_has_no_accessible_name_source",
+    "presentational-role": "presentational_role_removed_name_source"
+  }
+}

package/assets/remediation/code-patterns.json

@@ -0,0 +1,109 @@
+{
+  "patterns": [
+    {
+      "id": "placeholder-only-label",
+      "title": "Input uses placeholder as its only label",
+      "severity": "Critical",
+      "wcag": "WCAG 1.3.1 / 4.1.2 A",
+      "wcag_criterion": "1.3.1",
+      "wcag_level": "A",
+      "type": "structural",
+      "fix_description": "Placeholder text is not a label — it disappears on input and is not reliably announced by screen readers. Fix using one of these approaches:\n\n**Option A — Visually hidden label (preferred when no visible label exists):**\n```jsx\n<label htmlFor=\"field-id\" className=\"sr-only\">Field name</label>\n<input id=\"field-id\" placeholder=\"...\" />\n```\n\n**Option B — aria-label (acceptable for icon-only inputs like search):**\n```jsx\n<input aria-label=\"Search\" placeholder=\"Search\" />\n```\n\n**Option C — Visible label already exists nearby (wire it up):**\n```jsx\n<label htmlFor=\"field-id\">Field name</label>\n<input id=\"field-id\" placeholder=\"...\" />\n```\n\nNever rely on `placeholder` alone as the accessible name. Always verify the label is announced correctly with a screen reader.",
+      "requires_manual_verification": true,
+      "regex": "\\bplaceholder=[\"']",
+      "globs": ["**/*.tsx", "**/*.jsx", "**/*.html", "**/*.vue", "**/*.svelte", "**/*.astro"],
+      "context_reject_regex": "aria-label|aria-labelledby|for=|htmlFor=|<label",
+      "context_window": 6
+    },
+    {
+      "id": "mouseover-without-focus",
+      "title": "Hover handler has no keyboard focus equivalent",
+      "severity": "Serious",
+      "wcag": "WCAG 2.1.1 A",
+      "wcag_criterion": "2.1.1",
+      "wcag_level": "A",
+      "type": "structural",
+      "fix_description": "Add `onFocus`/`onBlur` (or `onFocusIn`/`onFocusOut`) handlers alongside every `onMouseOver`/`onMouseEnter` handler so keyboard users receive the same interaction.",
+      "requires_manual_verification": true,
+      "regex": "onMouseOver=|onMouseEnter=",
+      "globs": ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.html"],
+      "context_reject_regex": "onFocus[^I]|onFocusIn",
+      "context_window": 10
+    },
+    {
+      "id": "new-window-no-warning",
+      "title": "Link opens in new tab without warning",
+      "severity": "Serious",
+      "wcag": "WCAG 3.2.2 A",
+      "wcag_criterion": "3.2.2",
+      "wcag_level": "A",
+      "type": "structural",
+      "fix_description": "Add visible text such as `(opens in new tab)` or an `aria-label` containing that warning. Always pair `target=\"_blank\"` with `rel=\"noopener noreferrer\"`.",
+      "requires_manual_verification": true,
+      "regex": "target=[\"']_blank[\"']",
+      "globs": ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.html", "**/*.astro"],
+      "context_reject_regex": "new.tab|new.window|opens.in|sr-only",
+      "context_window": 5
+    },
+    {
+      "id": "spa-route-title",
+      "title": "SPA navigation does not update document.title",
+      "severity": "Serious",
+      "wcag": "WCAG 2.4.2 A",
+      "wcag_criterion": "2.4.2",
+      "wcag_level": "A",
+      "type": "structural",
+      "fix_description": "Set `document.title` after every router navigation call to reflect the new route's page title. Screen reader users rely on the title to know when the page has changed.",
+      "requires_manual_verification": true,
+      "regex": "router\\.push\\(|router\\.replace\\(|navigate\\(|useNavigate\\(",
+      "globs": ["**/*.tsx", "**/*.jsx", "**/*.ts", "**/*.js", "**/*.vue"],
+      "context_reject_regex": "document\\.title",
+      "context_window": 20
+    },
+    {
+      "id": "focus-outline-suppressed",
+      "title": "Focus outline suppressed without replacement",
+      "severity": "Serious",
+      "wcag": "WCAG 2.4.7 AA",
+      "wcag_criterion": "2.4.7",
+      "wcag_level": "AA",
+      "type": "style",
+      "fix_description": "Replace `outline: none` / `outline: 0` with a `:focus-visible` rule that renders a clearly visible custom focus indicator (e.g., a 2px solid high-contrast outline). Never suppress focus outlines globally.",
+      "requires_manual_verification": true,
+      "regex": "outline:\\s*none|outline:\\s*0|focus:outline-none",
+      "globs": ["**/*.css", "**/*.scss", "**/*.sass", "**/*.tsx", "**/*.jsx"],
+      "context_reject_regex": ":focus-visible",
+      "context_window": 5
+    },
+    {
+      "id": "orientation-lock",
+      "title": "Screen orientation locked programmatically",
+      "severity": "Moderate",
+      "wcag": "WCAG 1.3.4 AA",
+      "wcag_criterion": "1.3.4",
+      "wcag_level": "AA",
+      "type": "structural",
+      "fix_description": "Remove the programmatic orientation lock. If a specific orientation is essential for the content, provide an accessible alternative layout for the other orientation.",
+      "requires_manual_verification": false,
+      "regex": "screen\\.orientation\\.lock\\(|lockOrientation\\(",
+      "globs": ["**/*.ts", "**/*.js", "**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte"],
+      "context_reject_regex": null,
+      "context_window": 0
+    },
+    {
+      "id": "character-key-shortcut",
+      "title": "Single-character accesskey shortcut with no override mechanism",
+      "severity": "Moderate",
+      "wcag": "WCAG 2.1.4 A",
+      "wcag_criterion": "2.1.4",
+      "wcag_level": "A",
+      "type": "structural",
+      "fix_description": "Remove the `accesskey` attribute or provide a user-facing mechanism to remap or disable it. Single-character shortcuts conflict with screen reader and speech-input keystroke commands.",
+      "requires_manual_verification": false,
+      "regex": "\\baccesskey=",
+      "globs": ["**/*.html", "**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro"],
+      "context_reject_regex": null,
+      "context_window": 0
+    }
+  ]
+}

package/assets/remediation/guardrails.json

@@ -0,0 +1,24 @@
+{
+  "shared": [
+    "**Element Verification**: Use the **Evidence from DOM** HTML to verify you are editing the correct element before applying any fix. Accessibility fixes are context-sensitive.",
+    "**Global Component Check**: If an issue repeats across multiple pages, it is likely inside a Global Component (e.g., `Header.tsx`, `Button.vue`). Fix it once at the source.",
+    "**Verification**: After applying a fix, explain *why* it resolves the WCAG criterion mentioned.",
+    "**No Placeholders**: Do not add \"todo\" comments. Provide the complete code fix.",
+    "**Backend Root Cause**: Some axe findings originate from server-side output (PHP warnings, WP_DEBUG stack traces rendering into the DOM) rather than frontend components. Identify by evidence containing server-generated debug output: PHP warnings, file paths like `wp-config.php` or `.env`, line numbers, or raw error messages in the DOM. For these findings: (1) explain the server-side root cause to the user in plain language, (2) do not attempt any frontend fix, (3) mark as 'Out of scope — backend root cause', (4) exclude from the fix queue and count as unresolved/unactionable in the Step 6 summary.",
+    "**Design Tokens (Tailwind)**: When fixing color contrast or visual issues, check `package.json` for the Tailwind version. v3: tokens in `tailwind.config.ts` or `tailwind.config.js`. v4: tokens in `@theme { … }` blocks inside CSS files (e.g. `app/globals.css`); a `tailwind.config.js` with `@config` may also exist — check both. Never report a missing config as an error in v4 projects."
+  ],
+  "stack": {
+    "react": "**React Project**: Edit `.tsx`/`.jsx` files in `src/`. **NEVER** edit `dist/`, `build/`, or `.cache/`. Source of Truth: fix at the component, not the compiled output.",
+    "nextjs": "**Next.js Project**: Edit `.tsx`/`.jsx` files in `app/`, `pages/`, or `components/`. **NEVER** edit `.next/` or `out/`. Source of Truth: fix at the component or page.",
+    "gatsby": "**Gatsby Project**: Edit `.tsx`/`.jsx` in `src/pages/` or `src/components/`. **NEVER** edit `public/` or `.cache/`. Source of Truth: fix at the component.",
+    "vue": "**Vue Project**: Edit `.vue` files in `src/`. **NEVER** edit `dist/` or `node_modules/`. Source of Truth: fix at the component.",
+    "nuxt": "**Nuxt Project**: Edit `.vue` files in `pages/`, `components/`, or `layouts/`. **NEVER** edit `.nuxt/` or `dist/`. Source of Truth: fix at the component.",
+    "angular": "**Angular Project**: Edit `.component.html` and `.component.ts` in `src/`. **NEVER** edit `dist/`. Source of Truth: fix at the component.",
+    "astro": "**Astro Project**: Edit `.astro` files in `src/`. **NEVER** edit `dist/` or `.astro/`. Source of Truth: fix at the component or page.",
+    "shopify": "**Shopify Project**: Edit `.liquid` files in `sections/`, `snippets/`, or `layout/`. **NEVER** edit compiled assets in `assets/*.min.js` or modify `config/settings_schema.json`. Source of Truth: fix at the template, not the rendered DOM.",
+    "wordpress": "**WordPress Project**: Work only in `wp-content/themes/`. **NEVER** edit `wp-content/plugins/`, `wp-admin/`, `wp-includes/`, `wp-config.php`, or any cached file. Source of Truth: fix at the theme template.",
+    "svelte": "**Svelte/SvelteKit Project**: Edit `.svelte` files in `src/`. **NEVER** edit `.svelte-kit/`, `build/`, or `dist/`. Source of Truth: fix at the component, not the compiled output.",
+    "drupal": "**Drupal Project**: Search for `.html.twig` in `web/themes/` or `themes/`. Clear cache with `drush cr` after changes. **NEVER** edit compiled or cached files.",
+    "generic": "**Framework & CMS Awareness**: This project may use React, Vue, Next.js, Astro, **Shopify** (.liquid), **WordPress** (.php), or **Drupal** (.twig).\n    - **NEVER** edit compiled, minified, or cached files (e.g., `dist/`, `.next/`, `build/`, `wp-content/cache/`, `assets/*.min.js`).\n    - **Source of Truth**: Traced DOM violations must be fixed at the **Source Component** or **Server-side Template**. Edit the origin, not the output."
+  }
+}