@a11yfred/neighbor 1.0.4 → 2.0.0

package/CHANGELOG.md

@@ -1,15 +1,74 @@
 # Changelog
 
-## 1.0.4  -  2026-05-13
+<!-- markdownlint-disable MD024 -->
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] - 2026-05-24
+
+### Added
+
+- **Native iOS Linting (SwiftUI)**: 9 custom SwiftLint rules for SwiftUI accessibility, distributed via `.swiftlint.yml`. Checks for disabled focus effects, hardcoded font sizes, redundant accessibility labels, small touch targets, restrictive orientation locks, and more. See [apps/ios-app/README.md](apps/ios-app/README.md).
+- **Native Android Linting (Jetpack Compose)**: 8 custom Android Lint detector rules for Jetpack Compose, distributed as a standard Gradle lint module. Checks for missing `contentDescription`, hardcoded `sp` text, small touch targets, missing `stateDescription`, `pointerInput` without semantics, disabled traversal groups, restrictive orientation, and forced light mode. See [apps/android-app/README.md](apps/android-app/README.md).
+- **Microsoft Word Add-in**: An Office.js add-in that checks Word documents for exclusionary and ableist language while you type. Built with React, Fluent UI, and Vite. See [apps/word-addin/README.md](apps/word-addin/README.md).
+- **New Stylelint Rules**:
+  - `neighbor/no-text-justify` (error): Disallows `text-align: justify` which creates uneven word spacing that is hard for dyslexic users to read (SC 1.4.8).
+  - `neighbor/no-absolute-viewport-text` (warn): Warns on pure viewport units (`vw`, `vh`) for text sizing which block browser zoom (SC 1.4.4).
+  - `neighbor/no-user-select-all-none` (warn): Warns on `user-select: none` which prevents text selection and translation (SC 1.4.4).
+- **New Content Rules**:
+  - `no-exclusive-language`: Tech jargon and culturally appropriated terms (blacklist, master/slave, sanity check, spirit animal).
+  - `no-colonial-and-violent-language`: Words rooted in colonialism or violence applied to people (stakeholder, target population, tackle).
+  - `no-deficit-language`: Words that reduce people to their circumstances (the homeless, inmate, addict, at-risk youth).
+  - `no-gendered-language`: Gendered pronouns when gender is unknown (he/she, his or her, mum and dad).
+  - `no-anti-lgbtq-language`: Outdated or pathologizing terms about sexual orientation and gender identity.
+  - `no-device-specific-action`: Device-specific input actions (click, tap, swipe).
+- **New Markup Rules**:
+  - `vue-router-focus-management` (off): Warns if a Vue Router view transition happens without managing focus.
+  - `react-spa-focus-management` (warn): Warns if a React Router or Remix transition happens without managing focus.
+- **Remix 3 Support**: Added a dedicated ESLint configuration (`@a11yfred/neighbor/remix3`) for file-based routing.
+- **Web Components / Vanilla HTML Support**: Added a dedicated ESLint configuration (`@a11yfred/neighbor/webcomponents`) using `@html-eslint/parser`.
+- **App Stubs**: Scaffolded workspace directories for `webapp`, `chrome-extension`, `firefox-extension`, and `electron-app`.
+- **Vale Dictionary**: Compiled Vale-compatible dictionary containing textlint content vocabulary for standalone Markdown checking.
+
+### Changed
+
+- **Rule Severities**: All recommended framework ARIA rules and Vale content rules are now set to `warn` by default to reduce friction on initial adoption.
+- **Rule Severities**: The `prefer-aria-disabled` rule is explicitly set to `error`, as previously documented.
+- **Linter Dependencies**: Dropped `eslint-plugin-jsx-a11y` as a direct dependency. It is now an optional `peerDependency`, meaning teams using only Web Components or text linting are not forced to install React accessibility rules. `eslint-plugin-vuejs-accessibility` and `@angular-eslint/eslint-plugin-template` have also been properly registered as optional.
+- **Vale Configs**: Automatically generated and packaged the latest content rules for `@a11yfred/vale-config-neighbor`.
+- **CI/CD**: Fixed publish workflow to publish from `packages/neighbor/` and `packages/textlint-rule-neighbor/` instead of the monorepo root. Fixed Vale zip path.
+
+### Documentation
+
+- Comprehensive 6-pass documentation audit for markdownlint compliance, accuracy, plain language, and ESL friendliness.
+- All rule tables sorted by severity (most severe first) then alphabetically.
+- Contractions replaced with full forms across all authored documentation.
+- All ecosystem tools (ESLint, Stylelint, textlint, Vale, SwiftLint, Android Lint, Word Add-in) documented in README.
+- Grammatical em dashes and en dashes replaced with hyphens across the entire codebase.
+- AI-assisted development disclaimer added to README.
+
+## 1.1.0 - 2026-05-23
+
+- **New rule:** `no-disabled-and-aria-disabled`: Elements with both `disabled` and `aria-disabled` attributes cause conflicting states in assistive tech
+- **Severity change:** `prefer-aria-disabled` moved from `off` to `error` by default to enforce discoverable form controls in tab order.
 
-### Bug fixes
+---
+
+## 1.0.6 - 2026-05-13
+
+**Changed:**
 
-- **`no-placeholder-only`** — no longer false-positives on `<input>` elements inside a `role="search"` landmark with an accessible name. The input is correctly labeled at the group level in that pattern.
-- **`no-dialog-without-close`** — no longer false-positives on `role="dialog"` elements whose children are passed dynamically (`{children}`). When a close button cannot be statically detected, the rule skips rather than reporting.
+- **Documentation:** Add severity column to all rule tables in README
+- **Docs cleanup:** Remove em dashes, fix MD036/MD040 markdownlint issues across all docs
+
+**Fixed:**
+
+- **`no-placeholder-only`**: no longer false-positives on `<input>` elements inside a `role="search"` landmark with an accessible name. The input is correctly labeled at the group level in that pattern.
+- **`no-dialog-without-close`**: no longer false-positives on `role="dialog"` elements whose children are passed dynamically (`{children}`). When a close button cannot be statically detected, the rule skips rather than reporting.
 
 ---
 
-## 1.0.0  -  2026-05-12
+## 1.0.0 - 2026-05-12
 
 ### Breaking change
 
@@ -17,98 +76,56 @@ 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` |
+| `ulam/no-outline-none` | `neighbor/no-outline-none` |
+| `ulam/user-preferences` | `neighbor/user-preferences` |
 
 Update your `.stylelintrc.json` to use the new names.
 
----
-
-## 0.4.0  -  2026-05-12
+### Added
 
-### 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`)
+- **New rule:** `neighbor/no-forced-colors-none`: `forced-color-adjust: none` inside `@media (forced-colors)` actively opts out of Windows High Contrast Mode
+- **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-all-caps-prose` | ALL CAPS words that screen readers may spell out letter-by-letter |
+| `no-ampersand-in-prose` | `&` in place of "and" in prose - announced inconsistently across AT vendors |
+| `no-directional-language` | Layout-dependent position instructions ("see above", "in the right sidebar", "as shown below") |
 | `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-cta` | Vague link and button text ("click here", "read more", "here", "learn more") |
 | `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
+- **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
+- **New entry point alias:** `@a11yfred/neighbor/stylelint` added as an explicit stylelint alias alongside the default export.
+- **Additional rules:** `no-labelledby-missing-target`, `no-dynamic-content-without-live`, `form-field-multiple-labels`, `no-empty-table-header` added to core markup rules (all run on React, Vue, and Angular).
 
-RULES.md is now an index. Full references split into:
+### Changed
 
-- [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
+- **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.
+- **Extended rules:** `no-announce-in-render` now runs in Vue and Angular plugins (not just React). Safe contexts are tuned per framework: Vue recognizes `onMounted`, `watch`, `watchEffect`, `nextTick`; Angular recognizes `ngOnInit`, `ngAfterViewInit`, `ngOnChanges`, and class method event handlers.
 
-### 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
+### Documentation
 
 - 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
+- README now includes correct parser snippets for Vue and Angular, and separate setup sections for Remix 2 and Remix 3
 - @ulam described as a JavaScript framework (not React-based)
 
 ---
 
-## 0.2.0  -  2026-05-12
-
-### New rules
-
-| Rule | What it catches |
-|---|---|
-| `no-labelledby-missing-target` | `aria-labelledby`/`describedby`/`controls`/`owns`/`activedescendant` referencing an `id` that doesn't exist in the file |
-| `no-dynamic-content-without-live` | `dangerouslySetInnerHTML` / `v-html` / `[innerHTML]` on an element outside a live region |
-| `form-field-multiple-labels` | Multiple `<label for="…">` elements targeting the same input |
-| `no-empty-table-header` | `<th>` or `role="columnheader"/"rowheader"` with no accessible text |
-
-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.
-
-### Setup improvements
-
-README now includes correct parser snippets for Vue and Angular, and separate setup sections for Remix 2 and Remix 3.
-
----
-
-## 0.1.0  -  2026-04-30
+## 0.1.0 - 2026-04-30
 
 Initial release.

package/CONTRIBUTING.md

@@ -1,23 +1,23 @@
 # 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.
+Neighbor is maintained by [@a11yfred](https://github.com/a11yfred). We welcome help from the accessibility community: experts, screen reader users, spec readers, and anyone who sees something missing in other tools.
 
 ## What belongs here
 
-A rule belongs in neighbor if it meets all three criteria:
+A rule belongs in neighbor if it meets all three checks:
 
-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.).
+1. **Easy to find in code**: The linter can find the problem just by looking at the code, without needing a browser. Things like color contrast belong in `axe-core`.
+2. **Not in other tools**: Plugins like `jsx-a11y` or `vuejs-accessibility` do not already check it.
+3. **Expert-backed**: A rule must come from WCAG, ARIA specs, or accessibility experts.
 
-If you're unsure, open an issue before writing a rule. A brief description and a source is enough to start a conversation.
+If you are not sure, open an issue before writing the rule. Just describe the idea and where it comes from to start a conversation.
 
-## What doesn't belong here
+## What does not 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))
+- Rules that need a browser to run (like checking CSS layout).
+- Rules already in the standard accessibility linter for your framework (e.g., `jsx-a11y`, `vuejs-accessibility`, `@angular-eslint/template`, or `lit-a11y`). Neighbor works with them, it does not replace them.
+- Code style rules that do not affect accessibility.
+- Rules that give too many false warnings on real projects (see rejected rules in [RULES.md](RULES.md)).
 
 ## Setup
 
@@ -27,7 +27,7 @@ cd neighbor
 npm install
 ```
 
-No build step. Rules are plain ES modules  -  edit and run ESLint directly.
+There is no build step. Rules are simple JavaScript files. You can edit them and run ESLint directly.
 
 ## How rules are structured
 
@@ -53,63 +53,63 @@ export function makeMyNewRule(h) {
 }
 ```
 
-The `h` adapter gives you a uniform interface across all three frameworks:
+The `h` helper gives you a single way to check code across React, Vue, and Angular:
 
 | Helper | Returns |
-|---|---|
+| --- | --- |
+| `h.elementVisitor` | AST node type string for `create()` visitor key |
+| `h.elementWithChildrenVisitor` | visitor key for rules that need child access |
+| `h.getAncestors(node)` | iterable of ancestor element nodes, root-ward |
 | `h.getAttr(node, name)` | attribute node or `null` |
 | `h.getAttrStringValue(attr)` | string or `null` (null for dynamic expressions) |
+| `h.getChildOpeningElements(node)` | iterable of direct child element nodes |
 | `h.getElementName(node)` | lowercase tag name, or `null` for custom components |
-| `h.hasAttr(node, name)` | boolean |
+| `h.getInnerHtmlAttr(node)` | `dangerouslySetInnerHTML` / `v-html` / `[innerHTML]` node or `null` |
+| `h.getParent(node)` | parent element node or `null` |
 | `h.getRoleValue(node)` | role string or `null` |
-| `h.hasAccessibleName(node)` | boolean  -  checks `aria-label` / `aria-labelledby` |
+| `h.hasAccessibleName(node)` | boolean: checks `aria-label` / `aria-labelledby` |
+| `h.hasAttr(node, name)` | boolean |
 | `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).
+**Angular warning:** `getParent()` and `getAncestors()` return `null` in Angular. The parser does not link child nodes to parent nodes. If your rule needs to look at parent nodes, it should fail quietly (skip the check, do not throw an error).
 
-After writing your factory:
+After writing your rule function:
 
-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
+1. Add it to `RULE_FACTORIES` at the bottom of `lib/rules.js`.
+2. Add it to `buildRecommendedRules()` and set the severity (`'error'`, `'warn'`, or `'off'`).
+3. If the rule is only for Vue or Angular, 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.
+Stylelint rules live in [`neighbor-stylelint.mjs`](neighbor-stylelint.mjs). They use PostCSS. Look at the existing rules to see how they work.
 
 ## 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. |
+| --- | --- |
+| `error` | This breaks screen readers or violates HTML rules. There is no good reason to do this. |
+| `warn` | This is usually bad, but sometimes there is a good reason to do it. |
+| `off` | This rule gives too many warnings on normal code to be turned on by default. Users can turn it on if they want. |
 
-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.
+If you are not sure, start with `warn`. It is easier to change a `warn` to an `error` later.
 
 ## Commit style
 
-```
+```text
 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.
+You do not need to include issue ticket numbers in your commit messages.
 
 ## Opening a PR
 
-Use the PR template. The key things:
+Please use the PR template. Here are the most important 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.)
+- **What problem does this find?** Link to WCAG, ARIA specs, or an expert guide.
+- **Why can axe-core not catch this?** If `axe-core` can catch it, the rule probably belongs there.
+- **When will this give false warnings?** Be honest. We prefer to set a rule to `off` instead of rejecting your PR.
+- **Does it fail quietly in Angular?** Remember that parent-walking does not work in Angular.
 
 ## 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.
+Open an issue or talk to us in the [Web A11y Slack](https://web-a11y.slack.com). The `#tools` channel is a great place to talk about rule ideas before you start writing code.