@a11yfred/neighbor 0.2.0 → 1.0.1

package/CHANGELOG.md

@@ -1,6 +1,83 @@
 # Changelog
 
-## 0.2.0 — 2026-05-12
+## 1.0.0  -  2026-05-12
+
+### Breaking change
+
+CSS rules renamed from `ulam/` to `neighbor/` namespace:
+
+| Old | New |
+| --- | --- |
+| `ulam/user-preferences` | `neighbor/user-preferences` |
+| `ulam/no-outline-none` | `neighbor/no-outline-none` |
+| `ulam/no-forced-colors-none` | `neighbor/no-forced-colors-none` |
+
+Update your `.stylelintrc.json` to use the new names.
+
+---
+
+## 0.4.0  -  2026-05-12
+
+### New entry point
+
+`@a11yfred/neighbor/content`  -  an ESLint plugin for accessibility and inclusion problems in web and app copy. Lints string literals and JSX text in JS/TS/JSX/TSX files.
+
+### New content rules (all `warn`)
+
+| Rule | What it flags |
+| --- | --- |
+| `no-ableist-language` | Slurs, suffering-framing, and condescending euphemisms when writing about disability ("wheelchair-bound", "suffers from", "special needs", "differently abled") |
+| `no-disability-metaphor` | Figurative uses of disability language ("blind spot", "tone deaf", "paralyzed by", "crippling debt") |
+| `no-english-idiom` | English idioms and sports metaphors opaque to ESL and international readers ("slam dunk", "boil the ocean", "circle back", "touch base") |
+| `no-vague-cta` | Vague link and button text ("click here", "read more", "here", "learn more") |
+| `no-directional-language` | Layout-dependent position instructions ("see above", "in the right sidebar", "as shown below") |
+| `no-unexplained-abbreviation` | Acronyms used without a prior expansion in the same file |
+| `no-all-caps-prose` | ALL CAPS words that screen readers may spell out letter-by-letter |
+| `no-vague-error-message` | Error messages that don't explain what went wrong ("An error occurred", "Something went wrong") |
+| `no-ampersand-in-prose` | `&` in place of "and" in prose  -  announced inconsistently across AT vendors |
+
+Rules are synthesised from 17 sources spanning W3C WAI, government plain language guides (US, UK, Australia, Canada), and disability language authorities (NCDJ, AP Stylebook, ADA National Network, APA Style, SIGACCESS). See [RULES-CONTENT.md](RULES-CONTENT.md) for full methodology and source citations.
+
+### New rule reference pages
+
+RULES.md is now an index. Full references split into:
+
+- [RULES-MARKUP.md](RULES-MARKUP.md)  -  ESLint markup rules
+- [RULES-CSS.md](RULES-CSS.md)  -  Stylelint CSS rules
+- [RULES-CONTENT.md](RULES-CONTENT.md)  -  content rules with sources and methodology
+
+### Entry point table update
+
+`@a11yfred/neighbor/stylelint` added as an explicit stylelint alias alongside the default export.
+
+---
+
+## 0.3.0  -  2026-05-12
+
+### New rule
+
+| Rule | What it catches |
+| --- | --- |
+| `neighbor/no-forced-colors-none` | `forced-color-adjust: none` inside `@media (forced-colors)`  -  actively opts out of Windows High Contrast Mode |
+
+### Severity changes
+
+10 rules moved from `warn` to `off` in the recommended config  -  they flag real problems but are too noisy for most codebases by default. All remain available to opt in individually:
+
+`no-application-role`, `no-grid-role`, `no-aria-roledescription`, `no-aria-readonly`, `no-tab-without-controls`, `no-href-hash`, `warn-role-alert`, `prefer-aria-disabled`, `no-target-blank-without-label`, `no-dialog-without-close`
+
+`no-tooltip-role-misuse` and `no-menu-role-on-nav` remain on as warns.
+
+### Docs
+
+- WCAG SC and HTML spec links added throughout README and RULES.md
+- CONTRIBUTING.md, PR template, and issue templates added
+- README table of contents added
+- @ulam described as a JavaScript framework (not React-based)
+
+---
+
+## 0.2.0  -  2026-05-12
 
 ### New rules
 
@@ -15,7 +92,7 @@ All four rules run on React, Vue, and Angular.
 
 ### Extended rules
 
-**`no-announce-in-render`** now runs in the Vue and Angular plugins, not just React. Safe contexts are tuned per framework — Vue recognises `onMounted`, `watch`, `watchEffect`, `nextTick`; Angular recognises `ngOnInit`, `ngAfterViewInit`, `ngOnChanges`, and class method event handlers.
+**`no-announce-in-render`** now runs in the Vue and Angular plugins, not just React. Safe contexts are tuned per framework  -  Vue recognises `onMounted`, `watch`, `watchEffect`, `nextTick`; Angular recognises `ngOnInit`, `ngAfterViewInit`, `ngOnChanges`, and class method event handlers.
 
 ### Setup improvements
 
@@ -23,6 +100,6 @@ README now includes correct parser snippets for Vue and Angular, and separate se
 
 ---
 
-## 0.1.0 — 2026-04-30
+## 0.1.0  -  2026-04-30
 
 Initial release.

package/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to @a11yfred/neighbor
+
+Neighbor is maintained by [@a11yfred](https://github.com/a11yfred). Contributions are welcome from the accessibility community  -  practitioners, AT users, spec readers, and people who have found a gap in existing tooling.
+
+## What belongs here
+
+A rule belongs in neighbor if it meets all three criteria:
+
+1. **Statically detectable**  -  the violation can be identified from markup/code alone, without a browser or AT. Runtime-only failures (color contrast, focus order in the DOM) belong in axe-core.
+2. **Not already covered**  -  jsx-a11y, vuejs-accessibility, @angular-eslint/template, or axe-core doesn't already flag it in a recommended config.
+3. **Expert-backed**  -  there's a WCAG SC, ARIA spec citation, or clear consensus from accessibility practitioners (Roselli, O'Hara, Lauke, Sutton, Pickering, Groves, Eggert, etc.).
+
+If you're unsure, open an issue before writing a rule. A brief description and a source is enough to start a conversation.
+
+## What doesn't belong here
+
+- Rules that require runtime information (computed styles, DOM layout, AT output)
+- Rules already in jsx-a11y recommended  -  neighbor extends it, not replaces it
+- Opinionated style rules without a clear accessibility impact
+- Rules with very high false-positive rates on real codebases (see the rejected rules list in [RULES.md](RULES.md))
+
+## Setup
+
+```bash
+git clone https://github.com/a11yfred/neighbor.git
+cd neighbor
+npm install
+```
+
+No build step. Rules are plain ES modules  -  edit and run ESLint directly.
+
+## How rules are structured
+
+All ESLint rules live in [`lib/rules.js`](lib/rules.js) as factory functions:
+
+```js
+export function makeMyNewRule(h) {
+  return {
+    meta: {
+      type: 'problem',             // 'problem' | 'suggestion'
+      docs: { description: '...' },
+      messages: { myMessage: '...' },
+      schema: [],
+    },
+    create(context) {
+      return {
+        [h.elementVisitor](node) {
+          // h adapts the rule to React/Vue/Angular ASTs
+        },
+      }
+    },
+  }
+}
+```
+
+The `h` adapter gives you a uniform interface across all three frameworks:
+
+| Helper | Returns |
+|---|---|
+| `h.getAttr(node, name)` | attribute node or `null` |
+| `h.getAttrStringValue(attr)` | string or `null` (null for dynamic expressions) |
+| `h.getElementName(node)` | lowercase tag name, or `null` for custom components |
+| `h.hasAttr(node, name)` | boolean |
+| `h.getRoleValue(node)` | role string or `null` |
+| `h.hasAccessibleName(node)` | boolean  -  checks `aria-label` / `aria-labelledby` |
+| `h.isInteractiveElement(node)` | boolean |
+| `h.getParent(node)` | parent element node or `null` |
+| `h.getAncestors(node)` | iterable of ancestor element nodes, root-ward |
+| `h.getChildOpeningElements(node)` | iterable of direct child element nodes |
+| `h.getInnerHtmlAttr(node)` | `dangerouslySetInnerHTML` / `v-html` / `[innerHTML]` node or `null` |
+| `h.elementVisitor` | AST node type string for `create()` visitor key |
+| `h.elementWithChildrenVisitor` | visitor key for rules that need child access |
+
+**Angular caveat:** `getParent()` and `getAncestors()` return `null`/nothing for Angular  -  the template parser doesn't attach parent pointers. Rules that require ancestor walking should degrade gracefully (skip the check, don't throw).
+
+After writing your factory:
+
+1. Add it to `RULE_FACTORIES` at the bottom of `lib/rules.js`
+2. Add it to `buildRecommendedRules()` at the appropriate severity (`'error'` / `'warn'` / `'off'`)
+3. If it's Vue/Angular-only (porting a jsx-a11y gap), add it to `buildPortabilityRules()` instead
+
+Stylelint rules live in [`neighbor-stylelint.mjs`](neighbor-stylelint.mjs) and use the PostCSS AST directly. See the existing rules for the pattern.
+
+## Severity guidance
+
+| Severity | When to use |
+|---|---|
+| `error` | Unambiguous AT breakage  -  a phantom control, broken name computation, HTML spec violation. No legitimate override. |
+| `warn` | Strong guidance with a clear accessibility basis, but real codebases occasionally have justified exceptions. |
+| `off` | Real problem, but fires too often on legitimate patterns to be on by default. Make it available; let teams opt in. |
+
+When in doubt, start at `warn`. It's easier to promote a rule to `error` than to demote it after people have already configured it.
+
+## Commit style
+
+```
+feat: add no-my-new-rule (short description)
+fix: correct false positive in no-existing-rule
+docs: update RULES.md for no-my-new-rule
+```
+
+No ticket numbers required.
+
+## Opening a PR
+
+Use the PR template. The key things:
+
+- **What problem does this flag?** Link a WCAG SC, ARIA spec section, or expert source.
+- **Why can't axe-core catch it at runtime instead?** (If it can, it probably belongs there.)
+- **What are the false-positive cases?** Be honest  -  we'd rather move a rule to `off` than reject it.
+- **Does it degrade gracefully for Angular?** (Parent walking unavailable.)
+
+## Questions
+
+Open an issue or reach out in the [Web A11y Slack](https://web-a11y.slack.com). The `#tools` channel is a good place to discuss rule ideas before writing code.

package/README.md

@@ -2,6 +2,33 @@
 
 Neighbor is an accessibility linting plugin for ESLint and Stylelint that builds on jsx-a11y. It looks to cover gaps: bad ARIA patterns, live region misuse, missing names on roles, and CSS that removes focus indicators. It also brings that coverage to Vue and Angular, where jsx-a11y does not apply.
 
+Some rules are specific to **@ulam**  -  an upcoming JavaScript framework by the same author. Those rules are prefixed `no-announce-in-render`, `no-hash-router-in-remix`, and `no-use-page-title-in-remix`. They activate only when @ulam-related imports are detected and are harmless in non-@ulam projects.
+
+## Contents
+
+- [Install](#install)
+- [Entry points](#entry-points)
+- [Setup](#setup)
+  - [React / JSX](#react--jsx)
+  - [Remix 2](#remix-2)
+  - [Remix 3](#remix-3)
+  - [Vue](#vue)
+  - [Angular](#angular)
+  - [Stylelint](#stylelint)
+  - [Content linting](#content-linting)
+- [Peer dependencies](#peer-dependencies)
+- [What neighbor adds](#what-neighbor-adds)
+  - [ESLint  -  React / JSX](#eslint--react--jsx)
+  - [ESLint  -  Remix 2](#eslint--remix-2)
+  - [ESLint  -  Vue SFCs](#eslint--vue-sfcs)
+  - [ESLint  -  Angular templates](#eslint--angular-templates)
+  - [Stylelint  -  CSS](#stylelint--css)
+  - [Content linter](#content-linter)
+- [Rule severity](#rule-severity)
+- [Contributing](CONTRIBUTING.md)
+- [See also](#see-also)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -12,10 +39,12 @@ npm install --save-dev @a11yfred/neighbor
 
 | Import | Use for |
 | --- | --- |
-| `@a11yfred/neighbor/eslint` | React / JSX, Remix 2 |
-| `@a11yfred/neighbor/eslint-vue` | Vue SFCs |
-| `@a11yfred/neighbor/eslint-angular` | Angular templates |
-| `@a11yfred/neighbor` | Stylelint — CSS user-preference fallbacks |
+| `@a11yfred/neighbor/eslint` | React / JSX, Remix 2  -  markup rules |
+| `@a11yfred/neighbor/eslint-vue` | Vue SFCs  -  markup rules |
+| `@a11yfred/neighbor/eslint-angular` | Angular templates  -  markup rules |
+| `@a11yfred/neighbor/content` | Any JS/TS/JSX/TSX  -  content and prose rules |
+| `@a11yfred/neighbor` | Stylelint  -  CSS rules (default export) |
+| `@a11yfred/neighbor/stylelint` | Stylelint  -  CSS rules (explicit) |
 
 ## Setup
 
@@ -62,7 +91,7 @@ export default [
 
 ### Remix 3
 
-Remix 3 is framework-agnostic and does not require React. Neighbor does not have a dedicated Remix 3 entry point — use the entry point that matches your renderer.
+Remix 3 is framework-agnostic and does not require React. Neighbor does not have a dedicated Remix 3 entry point  -  use the entry point that matches your renderer.
 
 If you are using React with Remix 3:
 
@@ -134,23 +163,67 @@ export default [
 
 ### Stylelint
 
-```js
+```json
 // .stylelintrc.json
 {
   "plugins": ["@a11yfred/neighbor"],
   "rules": {
-    "ulam/user-preferences": true,
-    "ulam/no-outline-none": true
+    "neighbor/user-preferences": true,
+    "neighbor/no-outline-none": true,
+    "neighbor/no-forced-colors-none": true
   }
 }
 ```
 
+### Content linting
+
+The content plugin lints string literals and JSX text in JavaScript, TypeScript, JSX, and TSX files. It is separate from the markup plugins and can be used alongside any of them.
+
+```bash
+npm install --save-dev @a11yfred/neighbor
+```
+
+```js
+// eslint.config.js
+import neighborContent from '@a11yfred/neighbor/content'
+
+export default [
+  {
+    files: ['**/*.{js,jsx,ts,tsx}'],
+    plugins: { ...neighborContent.configs.recommended.plugins },
+    rules:   { ...neighborContent.configs.recommended.rules },
+  },
+]
+```
+
+To use alongside the React markup plugin:
+
+```js
+// eslint.config.js
+import neighbor from '@a11yfred/neighbor/eslint'
+import neighborContent from '@a11yfred/neighbor/content'
+
+export default [
+  {
+    files: ['**/*.{js,jsx,ts,tsx}'],
+    plugins: {
+      ...neighbor.configs.recommended.plugins,
+      ...neighborContent.configs.recommended.plugins,
+    },
+    rules: {
+      ...neighbor.configs.recommended.rules,
+      ...neighborContent.configs.recommended.rules,
+    },
+  },
+]
+```
+
 ## Peer dependencies
 
 | Peer | Required for |
 | --- | --- |
 | `eslint >= 8` | Any ESLint entry point |
-| `eslint-plugin-jsx-a11y >= 6` | React config — neighbor extends it, not replaces it |
+| `eslint-plugin-jsx-a11y >= 6` | React config  -  neighbor extends it, not replaces it |
 | `eslint-plugin-vuejs-accessibility >= 2` | Vue config |
 | `@angular-eslint/eslint-plugin-template >= 17` | Angular config |
 | `stylelint >= 14` | Stylelint config |
@@ -159,61 +232,61 @@ All peers are optional. Install only what your project uses.
 
 ## What neighbor adds
 
-### ESLint — React / JSX
+### ESLint  -  React / JSX
 
 Base: `eslint-plugin-jsx-a11y`
 
 | What it checks | Rule | WCAG SC |
 | --- | --- | --- |
-| `aria-disabled` keeps element reachable | `prefer-aria-disabled` | 2.1.1 |
-| `aria-disabled` must block click handler | `no-unblocked-aria-disabled` | 2.1.1 |
-| `aria-label` on a generic element with no role | `no-aria-label-on-generic` | 1.3.1 |
-| `role="alert"` overuse | `warn-role-alert` | 4.1.3 |
-| `aria-live="assertive"` outside `role="alert"` | `no-assertive-live-overuse` | 4.1.3 |
-| `role="dialog"` requires accessible name | `no-roles-without-name` | 4.1.2 |
-| `role="group"` with form controls requires name | `no-group-without-name` | 1.3.1 |
-| `role="tooltip"` requires `id` on the tooltip | `no-tooltip-role-misuse` | 4.1.2 |
-| `role="application"` disables AT browse mode | `no-application-role` | — |
-| `role="grid"` almost always wrong | `no-grid-role` | — |
-| `role="menu"` on nav triggers wrong AT mode | `no-menu-role-on-nav` | 2.1.1 |
-| `role="presentation"` on a focusable element | `no-presentation-on-focusable` | 2.1.1 |
-| `role="log"` must not contain interactive children | `no-log-with-interactive-children` | 4.1.2 |
-| `role="img"` requires accessible name | `no-image-role-without-name` | 4.1.2 |
-| `role="tab"` requires `aria-selected` | `no-tabs-without-structure` | 4.1.2 |
-| `role="tab"` should declare `aria-controls` | `no-tab-without-controls` | 4.1.2 |
-| `role="combobox"` requires `aria-expanded` | `no-combobox-without-expanded` | 4.1.2 |
-| `role="slider"` requires value range attributes | `no-slider-without-range` | 4.1.2 |
-| `role="spinbutton"` requires value range attributes | `no-spinbutton-without-range` | 4.1.2 |
-| `role="listbox"` requires `role="option"` children | `no-listbox-without-option` | 4.1.2 |
-| `role="tree"` requires `role="treeitem"` children | `no-tree-without-treeitem` | 4.1.2 |
-| `role="feed"` requires `role="article"` children | `no-feed-without-article` | 4.1.2 |
-| `aria-hidden="true"` + `role="none"` is redundant | `no-redundant-aria-hidden-with-presentation` | — |
-| `aria-roledescription` does not translate | `no-aria-roledescription` | — |
-| `aria-readonly` has poor AT support | `no-aria-readonly` | — |
-| `aria-owns` on a void element | `no-aria-owns-on-void` | 4.1.2 |
-| `aria-activedescendant` requires a non-empty static ID | `no-aria-activedescendant-without-id` | 4.1.2 |
-| `aria-required` only valid on form-control roles | `no-aria-required-on-non-form` | 4.1.2 |
-| `<a>` with only aria-hidden children | `no-aria-hidden-in-link` | 4.1.2 |
-| `<button>` with only aria-hidden children | `no-empty-button` | 4.1.2 |
-| `<input>` placeholder used as sole label | `no-placeholder-only` | 1.3.1 |
-| `<input>` with invalid type value | `no-input-type-invalid` | 1.3.5 |
-| `<button>` in a form missing explicit type | `no-button-type-missing` | HTML spec |
-| `<summary>` outside `<details>` | `no-summary-without-details` | 2.1.1 |
-| `<a href="#">` used as a button | `no-href-hash` | 2.1.1 |
-| `target="_blank"` without new-tab disclosure | `no-target-blank-without-label` | 3.2.2 |
-| Duplicate `id` breaks ARIA relationships | `no-duplicate-id` | 1.3.1 |
-| Positive `tabIndex` breaks tab order | `no-positive-tabindex` | 2.4.3 |
-| Heading inside an interactive element | `no-heading-inside-interactive` | 4.1.2 |
-| `title` attribute as the only accessible name | `no-title-as-label` | 2.4.6 |
-| `<video>` or `<audio autoplay>` without controls | `no-autoplay-without-controls` | 1.4.2 |
-| Mouse-only events without keyboard equivalents | `no-mouse-only-events` | 2.1.1 |
-| `aria-labelledby`/`describedby` references missing `id` | `no-labelledby-missing-target` | 4.1.2 |
-| `dangerouslySetInnerHTML` outside a live region | `no-dynamic-content-without-live` | 4.1.3 |
-| Multiple `<label>` elements for the same control | `form-field-multiple-labels` | 1.3.1 |
-| `<th>` or header role with no accessible text | `no-empty-table-header` | 1.3.1 |
-| `announce()` called in component render body | `no-announce-in-render` | 4.1.3 |
-
-### ESLint — Remix 2
+| `aria-disabled` keeps element reachable | `prefer-aria-disabled` | [2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) |
+| `aria-disabled` must block click handler | `no-unblocked-aria-disabled` | [2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) |
+| `aria-label` on a generic element with no role | `no-aria-label-on-generic` | [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) |
+| `role="alert"` overuse | `warn-role-alert` | [4.1.3](https://www.w3.org/WAI/WCAG21/Understanding/status-messages) |
+| `aria-live="assertive"` outside `role="alert"` | `no-assertive-live-overuse` | [4.1.3](https://www.w3.org/WAI/WCAG21/Understanding/status-messages) |
+| `role="dialog"` requires accessible name | `no-roles-without-name` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="group"` with form controls requires name | `no-group-without-name` | [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) |
+| `role="tooltip"` requires `id` on the tooltip | `no-tooltip-role-misuse` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="application"` disables AT browse mode | `no-application-role` | - |
+| `role="grid"` almost always wrong | `no-grid-role` | - |
+| `role="menu"` on nav triggers wrong AT mode | `no-menu-role-on-nav` | [2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) |
+| `role="presentation"` on a focusable element | `no-presentation-on-focusable` | [2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) |
+| `role="log"` must not contain interactive children | `no-log-with-interactive-children` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="img"` requires accessible name | `no-image-role-without-name` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="tab"` requires `aria-selected` | `no-tabs-without-structure` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="tab"` should declare `aria-controls` | `no-tab-without-controls` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="combobox"` requires `aria-expanded` | `no-combobox-without-expanded` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="slider"` requires value range attributes | `no-slider-without-range` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="spinbutton"` requires value range attributes | `no-spinbutton-without-range` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="listbox"` requires `role="option"` children | `no-listbox-without-option` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="tree"` requires `role="treeitem"` children | `no-tree-without-treeitem` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `role="feed"` requires `role="article"` children | `no-feed-without-article` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `aria-hidden="true"` + `role="none"` is redundant | `no-redundant-aria-hidden-with-presentation` | - |
+| `aria-roledescription` does not translate | `no-aria-roledescription` | - |
+| `aria-readonly` has poor AT support | `no-aria-readonly` | - |
+| `aria-owns` on a void element | `no-aria-owns-on-void` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `aria-activedescendant` requires a non-empty static ID | `no-aria-activedescendant-without-id` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `aria-required` only valid on form-control roles | `no-aria-required-on-non-form` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `<a>` with only aria-hidden children | `no-aria-hidden-in-link` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `<button>` with only aria-hidden children | `no-empty-button` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `<input>` placeholder used as sole label | `no-placeholder-only` | [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) |
+| `<input>` with invalid type value | `no-input-type-invalid` | [1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose) |
+| `<button>` in a form missing explicit type | `no-button-type-missing` | [HTML spec](https://html.spec.whatwg.org/multipage/form-elements.html#the-button-element) |
+| `<summary>` outside `<details>` | `no-summary-without-details` | [2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) |
+| `<a href="#">` used as a button | `no-href-hash` | [2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) |
+| `target="_blank"` without new-tab disclosure | `no-target-blank-without-label` | [3.2.2](https://www.w3.org/WAI/WCAG21/Understanding/on-input) |
+| Duplicate `id` breaks ARIA relationships | `no-duplicate-id` | [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) |
+| Positive `tabIndex` breaks tab order | `no-positive-tabindex` | [2.4.3](https://www.w3.org/WAI/WCAG21/Understanding/focus-order) |
+| Heading inside an interactive element | `no-heading-inside-interactive` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `title` attribute as the only accessible name | `no-title-as-label` | [2.4.6](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels) |
+| `<video>` or `<audio autoplay>` without controls | `no-autoplay-without-controls` | [1.4.2](https://www.w3.org/WAI/WCAG21/Understanding/audio-control) |
+| Mouse-only events without keyboard equivalents | `no-mouse-only-events` | [2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard) |
+| `aria-labelledby`/`describedby` references missing `id` | `no-labelledby-missing-target` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| `dangerouslySetInnerHTML` outside a live region | `no-dynamic-content-without-live` | [4.1.3](https://www.w3.org/WAI/WCAG21/Understanding/status-messages) |
+| Multiple `<label>` elements for the same control | `form-field-multiple-labels` | [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) |
+| `<th>` or header role with no accessible text | `no-empty-table-header` | [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) |
+| `announce()` called in component render body | `no-announce-in-render` | [4.1.3](https://www.w3.org/WAI/WCAG21/Understanding/status-messages) |
+
+### ESLint  -  Remix 2
 
 Same as React / JSX. Additional rules activate when Remix imports are detected in the file being linted:
 
@@ -222,7 +295,7 @@ Same as React / JSX. Additional rules activate when Remix imports are detected i
 | `@ulam` hash router alongside `react-router` | `no-hash-router-in-remix` | warn |
 | `usePageTitle()` alongside `react-router` | `no-use-page-title-in-remix` | warn |
 
-### ESLint — Vue SFCs
+### ESLint  -  Vue SFCs
 
 Base: `eslint-plugin-vuejs-accessibility`
 
@@ -230,31 +303,50 @@ Neighbor adds everything in the React table above, adapted for Vue's AST (`v-htm
 
 | What it checks | Rule | WCAG SC |
 | --- | --- | --- |
-| Ambiguous link text ("click here", "read more") | `no-anchor-ambiguous-text` | 2.4.4 |
-| `<a>` with no content and no accessible name | `no-anchor-no-content` | 4.1.2 |
-| Invalid ARIA attribute values | `no-invalid-aria-prop-value` | 4.1.2 |
-| Invalid `autocomplete` token | `no-autocomplete-invalid` | 1.3.5 |
-| Heading with no content | `no-heading-no-content` | 2.4.6 |
-| `<iframe>` without `title` | `no-iframe-no-title` | 4.1.2 |
-| Alt text contains "image", "photo" | `no-img-redundant-alt` | 1.1.1 |
-| `accessKey` attribute | `no-access-key` | 2.1.4 |
-| `scope` on `<td>` (only valid on `<th>`) | `no-scope-on-td` | 1.3.1 |
-| `announce()` called outside `onMounted`/`watch`/handler | `no-announce-in-render` | 4.1.3 |
-
-### ESLint — Angular templates
+| Ambiguous link text ("click here", "read more") | `no-anchor-ambiguous-text` | [2.4.4](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context) |
+| `<a>` with no content and no accessible name | `no-anchor-no-content` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| Invalid ARIA attribute values | `no-invalid-aria-prop-value` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| Invalid `autocomplete` token | `no-autocomplete-invalid` | [1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose) |
+| Heading with no content | `no-heading-no-content` | [2.4.6](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels) |
+| `<iframe>` without `title` | `no-iframe-no-title` | [4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value) |
+| Alt text contains "image", "photo" | `no-img-redundant-alt` | [1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content) |
+| `accessKey` attribute | `no-access-key` | [2.1.4](https://www.w3.org/WAI/WCAG21/Understanding/character-key-shortcuts) |
+| `scope` on `<td>` (only valid on `<th>`) | `no-scope-on-td` | [1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) |
+| `announce()` called outside `onMounted`/`watch`/handler | `no-announce-in-render` | [4.1.3](https://www.w3.org/WAI/WCAG21/Understanding/status-messages) |
+
+### ESLint  -  Angular templates
 
 Base: `@angular-eslint/eslint-plugin-template`
 
-Neighbor adds the same rule set as Vue, adapted for Angular's template AST (`[innerHTML]` instead of `dangerouslySetInnerHTML`). The `no-announce-in-render` rule also lints Angular component TypeScript files — see the setup instructions for how to configure it for `.ts` files alongside `.html` templates.
+Neighbor adds the same rule set as Vue, adapted for Angular's template AST (`[innerHTML]` instead of `dangerouslySetInnerHTML`). The `no-announce-in-render` rule also lints Angular component TypeScript files  -  see the setup instructions for how to configure it for `.ts` files alongside `.html` templates.
 
 **Known limitation:** Angular's template parser does not attach parent pointers to AST nodes. Rules that need to walk up the tree (`no-summary-without-details`, `no-button-type-missing`, `no-log-with-interactive-children`, `no-menu-role-on-nav`, `no-heading-inside-interactive`) will silently pass in Angular templates. The `no-dynamic-content-without-live` rule only checks the element itself for Angular (no ancestor walk).
 
-### Stylelint — CSS
+### Stylelint  -  CSS
 
 | Rule | What it checks |
 | --- | --- |
-| `ulam/user-preferences` | Warns when motion, transparency, or alpha colors are used without `@media (prefers-*)` fallbacks |
-| `ulam/no-outline-none` | Disallows bare `outline: none` or `outline: 0` outside `:focus` selectors |
+| `neighbor/user-preferences` | Warns when motion, transparency, or alpha colors are used without `@media (prefers-*)` fallbacks  -  [SC 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum) / [SC 2.3.3](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions) |
+| `neighbor/no-outline-none` | Disallows bare `outline: none` or `outline: 0` outside `:focus` selectors  -  [SC 2.4.7](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible) |
+| `neighbor/no-forced-colors-none` | Disallows `forced-color-adjust: none` inside `@media (forced-colors)`  -  opts out of Windows High Contrast Mode  -  [SC 1.4.11](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast) |
+
+### Content linter
+
+Rules that flag accessibility and inclusion problems in web and app copy. Works on string literals and JSX text in JS/TS/JSX/TSX files.
+
+| Rule | What it flags | Severity | WCAG SC |
+| --- | --- | --- | --- |
+| `no-ableist-language` | Slurs, condescending euphemisms, suffering-framing ("suffers from", "wheelchair-bound", "special needs") | warn | [3.1.1](https://www.w3.org/WAI/WCAG22/Understanding/language-of-page) |
+| `no-disability-metaphor` | Figurative use of disability language ("blind spot", "tone deaf", "paralyzed by") | warn | - |
+| `no-english-idiom` | Idioms and sports metaphors opaque to ESL readers ("ball park", "slam dunk", "boil the ocean") | warn | [3.1.5](https://www.w3.org/WAI/WCAG22/Understanding/reading-level) |
+| `no-vague-cta` | Vague link and button text ("click here", "read more", "here") | warn | [2.4.4](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context) |
+| `no-directional-language` | Layout-dependent position references ("see above", "in the right sidebar") | warn | [1.3.3](https://www.w3.org/WAI/WCAG22/Understanding/sensory-characteristics) |
+| `no-unexplained-abbreviation` | Acronyms used without a prior expansion in the same file | warn | [3.1.4](https://www.w3.org/WAI/WCAG22/Understanding/abbreviations) |
+| `no-all-caps-prose` | ALL CAPS words in prose that screen readers may spell out letter-by-letter | warn | - |
+| `no-vague-error-message` | Error messages that don't explain what went wrong ("An error occurred", "Something went wrong") | warn | [3.3.1](https://www.w3.org/WAI/WCAG22/Understanding/error-identification) |
+| `no-ampersand-in-prose` | `&` used in place of "and" in prose  -  announced inconsistently by screen readers | warn | - |
+
+See [RULES-CONTENT.md](RULES-CONTENT.md) for the full rule reference including sources, methodology, and the language-evolution note.
 
 ## Rule severity
 
@@ -262,12 +354,17 @@ Neighbor adds the same rule set as Vue, adapted for Angular's template AST (`[in
 | --- | --- |
 | `error` | Definite AT breakage or HTML spec violation |
 | `warn` | Strong guidance, occasional legitimate overrides exist |
+| `off` | Available but disabled  -  too noisy for most codebases, enable if it fits your project |
 
 All rules can be overridden in your config.
 
 ## See also
 
-- [RULES.md](RULES.md) — full rule list with descriptions
+- [RULES.md](RULES.md)  -  rule index across all domains
+- [RULES-MARKUP.md](RULES-MARKUP.md)  -  full ESLint rule reference (markup)
+- [RULES-CSS.md](RULES-CSS.md)  -  full Stylelint rule reference (CSS)
+- [RULES-CONTENT.md](RULES-CONTENT.md)  -  full content rule reference with sources
+- [neighbor-vale](https://github.com/a11yfred/neighbor-vale)  -  companion Vale package for prose linting in Markdown, MDX, and HTML
 
 ## License