From 0e376b5031c5297cd05141ec91d8fb7e8fc6654b Mon Sep 17 00:00:00 2001 From: Taarik <147209483+taarikashenafi@users.noreply.github.com> Date: Fri, 24 Jul 2026 13:52:30 -0500 Subject: [PATCH] Prepare v1.1.0 release Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 420c7633-4b5c-4b35-a1bd-5cb6e438a8e4 --- README.md | 24 +++++++++++++----------- package-lock.json | 4 ++-- package.json | 2 +- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 23e1607..a862a37 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The Alt-Text Plugin is a [plugin](https://github.com/github/accessibility-scanner/blob/main/PLUGINS.md) for the [AI-powered Accessibility Scanner](https://github.com/github/accessibility-scanner) that flags low-quality `alt` text on images. It complements axe-core's built-in `image-alt` rule, helping teams ship images with descriptive, screen-reader-friendly alternative text. -The plugin helps teams: +Five deterministic rules run by default and help teams: - 🖼️ Catch vague, generic, or filler `alt` text (`"image"`, `"photo"`, `"icon"`) - 📛 Catch raw filenames used as `alt` text (`"IMG_1234.png"`) @@ -10,6 +10,8 @@ The plugin helps teams: - 🚧 Catch boilerplate placeholder `alt` text (`"todo"`, `"tbd"`, `"fixme"`) - ♿ Catch images missing an `alt` attribute entirely (without flagging intentional decorative `alt=""`) +An additional opt-in, model-backed `alt-text-quality` rule evaluates whether alt text accurately describes its image and flags SEO keyword stuffing. It is disabled by default and requires a GitHub Models token. + > ⚠️ **Note:** This plugin is in active development alongside the a11y scanner's public preview. New rules are still being added and end-to-end integration with the scanner's issue-filing workflow is still maturing. Always review filed issues before acting on them. --- @@ -66,7 +68,7 @@ jobs: token: ${{ secrets.GH_TOKEN }} cache_key: REPLACE_THIS scans: | - ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.0.0"}] + ["axe", {"name": "alt-text-scan", "package": "@github/accessibility-scanner-alt-text-plugin", "version": "1.1.0"}] ``` > 👉 Update all `REPLACE_THIS` placeholders with your actual values. See the [scanner's Action inputs](https://github.com/github/accessibility-scanner#action-inputs) for the full list, and the scanner's [PLUGINS.md](https://github.com/github/accessibility-scanner/blob/main/PLUGINS.md) for how NPM plugins are loaded. @@ -94,14 +96,14 @@ Trigger your scanner workflow manually or on its configured schedule. The plugin The plugin runs every extracted image through an append-only registry of rules. Each rule returns a finding when an image fails its criteria, and the scanner turns each finding into an issue. -| Rule | ID | Fires when | Example (flagged) | -| ------------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| **Missing alt** | `missing-alt-text` | The `alt` attribute is absent (`null`) or whitespace-only (`" "`). `alt=""` is treated as intentional decorative use and is **not** flagged. | ``
` ` | -| **Vague alt** | `vague-alt-text` | The alt text is one of a curated set of generic single words (`image`, `photo`, `icon`, `logo`, `screenshot`, `chart`, `untitled`, etc.) or short filler phrases (`an image of`, `a photo of`). Normalization is applied before matching: case-insensitive, whitespace-collapsed, surrounding punctuation stripped. | `image`
`An image of`
`PHOTO.` | -| **Filename as alt** | `filename-alt-text` | The alt text ends in a common image file extension (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.bmp`, `.ico`). | `IMG_1234.png`
`Screenshot 2024-04-28.jpg` | -| **Repeated alt** | `repeated-alt-text` | Two or more adjacent images on the rendered page share the same normalized alt text. Useful for patterns like five star icons all labeled `"3/5 stars"`. | Five consecutive `3/5 stars` elements | -| **Placeholder alt** | `placeholder-alt-text` | The alt text matches a known boilerplate string that signals it was never written (`todo`, `tbd`, `fixme`, `placeholder`, `alt text`, `insert alt text`, `image alt`). Normalization is applied before matching. | `TODO`
`insert alt text` | -| **Alt quality** (opt-in) | `alt-text-quality` | A vision model judges the alt text against the image itself and flags it when the text is inaccurate, incomplete, or otherwise low-quality — plausible-looking alt that the deterministic rules can't catch. **Disabled by default**; requires a GitHub Models token (optionally Azure AI Vision). See [Alt-text quality](#alt-text-quality-model-backed-opt-in). | `a person` | +| Rule | ID | Fires when | Example (flagged) | +| ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| **Missing alt** | `missing-alt-text` | The `alt` attribute is absent (`null`) or whitespace-only (`" "`). `alt=""` is treated as intentional decorative use and is **not** flagged. | ``
` ` | +| **Vague alt** | `vague-alt-text` | The alt text is one of a curated set of generic single words (`image`, `photo`, `icon`, `logo`, `screenshot`, `chart`, `untitled`, etc.) or short filler phrases (`an image of`, `a photo of`). Normalization is applied before matching: case-insensitive, whitespace-collapsed, surrounding punctuation stripped. | `image`
`An image of`
`PHOTO.` | +| **Filename as alt** | `filename-alt-text` | The alt text ends in a common image file extension (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.bmp`, `.ico`). | `IMG_1234.png`
`Screenshot 2024-04-28.jpg` | +| **Repeated alt** | `repeated-alt-text` | Two or more adjacent images on the rendered page share the same normalized alt text. Useful for patterns like five star icons all labeled `"3/5 stars"`. | Five consecutive `3/5 stars` elements | +| **Placeholder alt** | `placeholder-alt-text` | The alt text matches a known boilerplate string that signals it was never written (`todo`, `tbd`, `fixme`, `placeholder`, `alt text`, `insert alt text`, `image alt`). Normalization is applied before matching. | `TODO`
`insert alt text` | +| **Alt quality** (opt-in) | `alt-text-quality` | A vision model judges the alt text against the image itself and flags inaccurate, incomplete, or keyword-stuffed text that the deterministic rules cannot catch. **Disabled by default**; requires a GitHub Models token (optionally Azure AI Vision). See [Alt-text quality](#alt-text-quality-model-backed-opt-in). | `a person` | ### Image extraction @@ -118,7 +120,7 @@ The scanner's built-in Axe scan includes a rule called [`image-alt`](https://deq ### Alt-text quality (model-backed, opt-in) -The five rules above are deterministic pattern matches. `alt-text-quality` goes further: it sends each image, its alt text, and surrounding context in the DOM to a vision model, which judges whether the alt text actually and sufficiently describes the image. This catches plausible-looking but wrong or incomplete alt text — for example `alt="a person"` on a photo of an individual named in surrounding text. +The five default rules are deterministic pattern matches and never call a model. `alt-text-quality` is a separate opt-in rule: it sends each image, its alt text, and surrounding DOM context to a vision model, which judges whether the alt text actually and sufficiently describes the image. This catches plausible-looking but wrong or incomplete alt text — for example `alt="a person"` on a photo of an individual named in surrounding text — as well as SEO keyword stuffing that lists search terms instead of describing the image. Because it makes a per-image model call (cost and latency), it is **disabled by default**. To turn it on: diff --git a/package-lock.json b/package-lock.json index 0767fda..3142ded 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@github/accessibility-scanner-alt-text-plugin", - "version": "1.0.0", + "version": "1.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@github/accessibility-scanner-alt-text-plugin", - "version": "1.0.0", + "version": "1.1.0", "license": "MIT", "devDependencies": { "@github/prettier-config": "^0.0.6", diff --git a/package.json b/package.json index 05cd30d..96f4953 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@github/accessibility-scanner-alt-text-plugin", - "version": "1.0.0", + "version": "1.1.0", "description": "Alt-text validation plugin for github/accessibility-scanner", "license": "MIT", "repository": {