@shalii/galaxy-a11y 0.1.2 → 0.1.4

package/README.md

@@ -3,7 +3,7 @@
 Static **WCAG 2.2 / ADA accessibility scanner for Galaxy CMS themes** (html, scss, js).
 It understands Galaxy syntax (`#$variable|x$#`, `{if="…"}`, `[[id]]`, `__@@text@@__`), so every finding points to the real line in your real file and comes with the exact fix.
 
-> Static scanning finds roughly a third to a half of WCAG problems. See [Limits](#limits) and the manual checklist at the end of every report.
+> Static scanning finds roughly a third to a half of WCAG problems. See [Limits](#6-limits) and the manual checklist at the end of every report.
 
 ---
 
@@ -84,21 +84,181 @@ A non-zero exit code blocks the build or commit when errors exist.
 
 ---
 
-## 3. Rules
+## 3. What it checks
 
-HTML_LANG · LANG · TITLE · ZOOM · REFRESH · ALT (IMG) · MAP-AREA · SVG · MEDIA · AUDIO · AUDIO-CAPTIONS · ANIMATION · FLASH ·
-ERR-LINK · HREF · SKIP-LINK · NAV · HEADING · SEMANTIC · LABEL · LABEL-IN-NAME · INPUT-PURPOSE · AUTOFILL · AUTH · REDUNDANT-ENTRY · ERROR-SUGGESTION · STATUS-LIVE ·
-TABINDEX · KEYBOARD · FOCUS · FOCUS-ELEMENT · FOCUS-STRATEGY · TRAP · SHORTCUT · CHAR-KEYS · MODALITY · GESTURE · PTR-GESTURE ·
-ARIA · ARIA-ROLE · CONTRAST · COLOR · SIZE · SIZE-2.2 · ORIENTATION · SENSORY · CONSISTENT-HELP (manual).
+**48 rules** (46 automatic + 2 manual-only), made up of about **100 individual checks**, each mapped to a WCAG 2.2 success criterion. Every finding shows the rule name, the WCAG number, the line and column, and the fix.
+
+| Area | Rule | What it catches | WCAG |
+|---|---|---|---|
+| **Images and media** | `ALT` | `<img>` with no `alt`, or an `alt` that is only whitespace (suggests the Galaxy variable when the editor controls the alt) | 1.1.1 |
+| | `MAP-AREA` | `<area>` in an image map with no alt text | 1.1.1 / 2.4.4 |
+| | `SVG` | Inline `<svg>` exposed to screen readers without a name (decorative ones should be `aria-hidden`) | 1.1.1 / 4.1.2 |
+| | `MEDIA` | Embedded or `<video>` that autoplays with sound, has no controls, or has no text alternative | 1.4.2 / 2.2.2 |
+| | `AUDIO` | `<audio>` that autoplays | 1.4.2 |
+| | `AUDIO-CAPTIONS` | Embedded video: reminds you to confirm captions / transcript exist | 1.2.2 / 1.2.3 / 1.2.5 |
+| **Motion and timing** | `ANIMATION` | Infinite animations with no `prefers-reduced-motion` override; autoplay video with no pause | 2.2.2 / 2.3.3 |
+| | `FLASH` | Animations repeating faster than 3 times per second | 2.3.1 |
+| | `REFRESH` | Meta refresh and timed redirects | 2.2.1 / 2.2.4 / 3.2.5 |
+| **Page structure** | `HTML_LANG` / `LANG` | Missing or invalid `lang` attribute | 3.1.1 / 3.1.2 |
+| | `TITLE` | Empty or missing `<title>` | 2.4.2 |
+| | `PARSING` | Duplicate `id`s (breaks labels, ARIA and skip links) | 4.1.2 |
+| | `HEADING` | Empty headings, skipped levels (h2 → h4), more than one `<h1>`, and elements styled as headings but not real heading tags | 1.3.1 / 2.4.6 |
+| | `NAV` | No `<main>`, several unlabelled `<nav>` landmarks, links opening a new window without warning | 1.3.1 / 2.4.1 / 3.2.5 |
+| | `SKIP-LINK` | No skip-to-content link in the header, or a skip button with no JS handler | 2.4.1 |
+| | `SEMANTIC` | Interactive elements nested inside each other (`<a>` in `<button>`) | 4.1.2 |
+| **Links and buttons** | `HREF` | `<a>` with no `href` (not keyboard-focusable) | 2.1.1 / 4.1.2 |
+| | `ERR-LINK` | Dead links (`#`, `javascript:`), unclear link text ("click here"), and empty hidden links that screen readers still announce | 2.1.1 / 2.4.4 / 4.1.2 |
+| | `LABEL` | Buttons and inputs with no accessible name, empty `<label>`, `<fieldset>` with no `<legend>`, placeholder-only fields | 1.3.1 / 3.3.2 / 4.1.2 |
+| | `LABEL-IN-NAME` | `aria-label` that does not contain the visible text | 2.5.3 |
+| **Forms** | `INPUT-PURPOSE` | Personal-data fields (name, email, phone…) with no `autocomplete` | 1.3.5 |
+| | `AUTOFILL` | `autocomplete="off"` on personal-data fields | 1.3.5 / 3.3.7 |
+| | `AUTH` | Password fields that block password managers; paste blocked | 3.3.8 |
+| | `REDUNDANT-ENTRY` | "Confirm / repeat" fields that make users re-type information | 3.3.7 |
+| | `ERROR-SUGGESTION` | Error text that only says "required" without telling how to fix it | 3.3.1 / 3.3.3 |
+| | `STATUS-LIVE` | Error / success message containers screen readers will not announce | 4.1.3 |
+| **Keyboard and focus** | `TABINDEX` | Positive `tabindex`; `tabindex="-1"` on visible controls; `tabindex` on non-interactive elements | 2.4.3 |
+| | `KEYBOARD` | Click handlers on `<div>` / `<span>` that a keyboard cannot use | 2.1.1 |
+| | `FOCUS` | Focus outline removed with no replacement | 2.4.7 / 2.4.13 |
+| | `FOCUS-ELEMENT` | Overlays / menus opened without moving focus (`.focus()` never called) | 2.4.3 |
+| | `FOCUS-STRATEGY` | Sticky or fixed headers that can cover the focused element, no `scroll-padding-top` | 2.4.11 |
+| | `TRAP` | Dialogs without `aria-modal`, overlays with no Escape-key handling | 2.1.2 / 2.4.3 |
+| | `SHORTCUT` / `CHAR-KEYS` | `accesskey` and single-character keyboard shortcuts | 2.1.4 |
+| | `MODALITY` | Content shown on hover only, `onmouseover` without a keyboard equivalent | 2.1.1 / 1.4.13 |
+| **Touch and pointer** | `GESTURE` | Swipe / drag actions with no single-tap alternative | 2.5.1 / 2.5.7 |
+| | `PTR-GESTURE` | Actions that fire on press (`mousedown` / `touchstart`) instead of release | 2.5.2 |
+| **ARIA** | `ARIA` | Dialogs with no name, misspelled `aria-*` attributes, `aria-hidden` containers that hold focusable items | 4.1.2 |
+| | `ARIA-ROLE` | Unknown or redundant ARIA roles, and roles missing the attributes they require | 4.1.2 |
+| **Visual design (SCSS)** | `CONTRAST` | Text / background pairs under 4.5:1 (3:1 for large text); suggests the closest passing colour | 1.4.3 / 1.4.11 |
+| | `COLOR` | Links told apart from text by colour only (underline removed) | 1.4.1 |
+| | `SIZE` | Text smaller than 12px | 1.4.4 / 1.4.12 |
+| | `SIZE-2.2` | Click / tap targets smaller than 24×24 px | 2.5.8 / 2.5.5 |
+| | `ZOOM` | Text sized only in `vw`; viewport tag that blocks pinch-zoom | 1.4.4 |
+| | `ORIENTATION` | Content hidden or rotated by orientation media queries | 1.3.4 |
+| **Manual only** | `SENSORY` | Reminder to read content for "click the green button / on the right" instructions | 1.3.3 |
+| | `CONSISTENT-HELP` | Reminder: help / contact link must be in the same place on every page | 3.2.6 |
+
+The last two rules cannot be decided from source code, so they appear as reminders in the manual checklist at the end of every report.
 
 Notes
-- `HREF` = missing or empty href. `ERR-LINK` = dead links (`#`, `javascript:`) and unnamed or generic links.
-- `LABEL` also covers unnamed buttons and fieldsets.
-- CONTRAST only checks colours that appear together in one SCSS rule (literal values or `$variables`). Colours chosen in the CMS cannot be checked statically.
+- `HREF` = missing or empty href. `ERR-LINK` = dead links and unnamed or generic links.
+- `CONTRAST` only checks colours that appear together in one SCSS rule (literal values or `$variables`). Colours chosen in the CMS cannot be checked statically.
+- Some rules (for example `TRAP` and `FOCUS-ELEMENT`) report as a low-priority **note** when the code appears to use a known library that handles the problem. Use `--all` to see notes.
+
+---
+
+## 4. What to expect
+
+### Output
+This is a real run on two small files (`block/hero.html` and `sass/hero.scss`):
+
+```text
+block/hero.html
+     2:3   error   ALT             <img> has no alt attribute.  WCAG 1.1.1
+                                  fix: Add alt="Describe the image" — or alt="" if purely decorative.
+     3:20  error   KEYBOARD       <div> has a click handler but is not keyboard-operable.  WCAG 2.1.1
+                                  fix: Use <button type="button"> (best). If impossible: role="button" tabindex="0" + Enter/Space key handler.
+     4:6   warning ERR-LINK        Link points to "#" (dead link / script action).  WCAG 2.1.1 / 4.1.2
+                                  fix: If it navigates, use the real URL. If it runs JS, use <button type="button"> ...
+
+sass/hero.scss
+     1:1   error   CONTRAST        Contrast 2.85:1 for ".hero" (#999 on #fff); needs 4.5:1.  WCAG 1.4.3
+                                  fix: Change the text colour to #747474 (closest passing shade), or change the background.
+
+(manual checklist)
+     1:1   manual  KEYBOARD        Tab through every page type once: order, visible focus, no traps ...
+
+Scanned 2 files — 5 errors, 5 warnings, 7 manual checks
+
+By rule:
+  ALT                  1 err     0 warn   0 manual
+  ...
+```
+
+How to read a line: `line:column  severity  RULE  message  WCAG number`, then `fix:` underneath.
+
+### Severity levels
+| Level | Meaning | What to do |
+|---|---|---|
+| **error** | Definite failure of a WCAG criterion | Fix these first |
+| **warning** | Likely a problem, but depends on context | Check each one, fix or silence with `a11y-ignore` |
+| **manual** | The tool cannot decide | Do the check by hand (list at end of report) |
+| **note** | Low priority hint (shown only with `--all`) | Optional |
+
+### Things to know
+- **The first scan on an existing theme often shows many findings.** Many repeat the same cause (for example one SCSS rule used everywhere). Work through the "By rule" table from the top; fixing a shared template or mixin clears many lines at once.
+- **Expect some warnings that do not apply.** The scanner reads source code, so it sometimes cannot tell that a library or the CMS already handles something. Silence those with `a11y-ignore` or `--disable`.
+- **Line numbers point into your real files**, even when the line uses Galaxy syntax (`#$variable|x$#`, `{if="…"}`, `[[id]]`).
+- **Exit code:** `1` if any **error** is found (so CI and pre-commit hooks can block), otherwise `0`. Change with `--fail-on warning` or `--fail-on none`.
+- **`--html a11y-report.html`** writes a report you can filter by errors, warnings and manual checks and share with the team.
+- **Zero findings does not mean "100% accessible".** See [Limits](#6-limits).
+
+---
+
+## 5. What a fix looks like
+
+Every finding comes with the exact change to make. Typical examples:
+
+**Missing alt text** (`ALT`, WCAG 1.1.1)
+```html
+<!-- before -->  <img src="team.jpg">
+<!-- after  -->  <img src="team.jpg" alt="The support team at the 2026 summit">
+<!-- decorative image --> <img src="divider.svg" alt="">
+```
+
+**Clickable `<div>`** (`KEYBOARD`, WCAG 2.1.1)
+```html
+<!-- before -->  <div class="btn" onclick="openMenu()">Menu</div>
+<!-- after  -->  <button type="button" class="btn" onclick="openMenu()">Menu</button>
+```
+
+**Field with placeholder only** (`LABEL`, WCAG 1.3.1 / 3.3.2 / 4.1.2)
+```html
+<!-- before -->  <input type="email" name="email" placeholder="Email">
+<!-- after  -->  <label for="email">Email</label>
+                 <input id="email" type="email" name="email" autocomplete="email">
+```
+(`autocomplete="email"` also fixes `INPUT-PURPOSE`.)
+
+**Dead link used as a button** (`ERR-LINK`, WCAG 2.1.1 / 4.1.2)
+```html
+<!-- before -->  <a href="#" class="toggle">Open</a>
+<!-- after  -->  <button type="button" class="toggle" aria-expanded="false" aria-controls="panel">Open</button>
+                 <div id="panel" hidden>…</div>
+```
+
+**Low contrast** (`CONTRAST`, WCAG 1.4.3). The scanner calculates the closest passing colour:
+```scss
+// before
+.hero { color: #999; background: #fff; }      // 2.85:1, needs 4.5:1
+// after
+.hero { color: #747474; background: #fff; }   // passes
+```
+
+**Removed focus outline** (`FOCUS`, WCAG 2.4.7)
+```scss
+// before
+a:focus { outline: none; }
+// after
+a:focus-visible { outline: 2px solid $focus-color; outline-offset: 2px; }
+```
+
+**Tiny click target** (`SIZE-2.2`, WCAG 2.5.8)
+```scss
+// before
+.btn { width: 18px; height: 18px; }
+// after
+.btn { min-width: 24px; min-height: 24px; }   // ideally 44×44
+```
+
+**Silence a finding that does not apply**
+```html
+<!-- a11y-ignore: ALT -->
+<img src="logo.svg" alt="">
+```
 
 ---
 
-## 4. Limits
+## 6. Limits
 
 The scanner reads source code only. It cannot see:
 - colours and content that editors choose in the CMS,
@@ -113,7 +273,7 @@ No tool can promise "100% ADA". A realistic goal is: zero automated errors, warn
 
 ---
 
-## 5. VS Code extension
+## 7. VS Code extension
 
 Prefer to see the problems while you edit? Install the **Galaxy A11y** extension from the VS Code Marketplace (publisher `shalii`). It runs this same scanner and shows the findings as squiggles, with the fix in the hover. It is a separate project: `galaxy-a11y-vscode`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shalii/galaxy-a11y",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Static WCAG 2.2 / ADA accessibility scanner for Galaxy CMS themes (html, scss, js)",
   "keywords": [
     "accessibility",