@a11yfred/neighbor 1.0.1 → 1.0.3

package/README.md

@@ -9,7 +9,8 @@ Some rules are specific to **@ulam**  -  an upcoming JavaScript framework by the
 - [Install](#install)
 - [Entry points](#entry-points)
 - [Setup](#setup)
-  - [React / JSX](#react--jsx)
+  - [Vanilla JS / plain HTML (no framework)](#vanilla-js--plain-html-no-framework)
+  - [React / JSX](#react-jsx)
   - [Remix 2](#remix-2)
   - [Remix 3](#remix-3)
   - [Vue](#vue)
@@ -18,11 +19,11 @@ Some rules are specific to **@ulam**  -  an upcoming JavaScript framework by the
   - [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)
+  - [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)
@@ -48,6 +49,99 @@ npm install --save-dev @a11yfred/neighbor
 
 ## Setup
 
+### Vanilla JS / plain HTML (no framework)
+
+If you write plain JavaScript with no JSX, React, Vue, or Angular, only the **Stylelint CSS rules** and the **content linter** apply. The ESLint markup rules require a component framework — they lint JSX or template syntax that plain JS does not have.
+
+**What you get:**
+
+| Plugin | What it checks |
+| --- | --- |
+| Stylelint (`@a11yfred/neighbor`) | CSS: bare `outline: none`, forced-colors opt-out, motion/transparency without `prefers-*` fallbacks |
+| Content linter (`@a11yfred/neighbor/content`) | JS strings: ableist language, vague CTAs, unexplained abbreviations, idioms, all-caps prose |
+
+**Stylelint setup** (CSS only, no framework needed):
+
+```bash
+npm install --save-dev stylelint stylelint-config-standard @a11yfred/neighbor
+```
+
+```json
+// .stylelintrc.json
+{
+  "extends": ["stylelint-config-standard"],
+  "plugins": ["@a11yfred/neighbor"],
+  "rules": {
+    "neighbor/no-outline-none": true,
+    "neighbor/no-forced-colors-none": true,
+    "neighbor/user-preferences": true
+  }
+}
+```
+
+Run it:
+
+```bash
+npx stylelint "**/*.css"
+```
+
+**Content linter setup** (plain JS string literals, no framework needed):
+
+```bash
+npm install --save-dev eslint @a11yfred/neighbor
+```
+
+```js
+// eslint.config.js  (ESLint flat config, ESLint >= 8)
+import neighborContent from '@a11yfred/neighbor/content'
+
+export default [
+  {
+    files: ['**/*.js'],
+    plugins: { ...neighborContent.configs.recommended.plugins },
+    rules:   { ...neighborContent.configs.recommended.rules },
+  },
+]
+```
+
+Run it:
+
+```bash
+npx eslint src/
+```
+
+**Both together:**
+
+```js
+// eslint.config.js
+import neighborContent from '@a11yfred/neighbor/content'
+
+export default [
+  {
+    files: ['**/*.js'],
+    plugins: { ...neighborContent.configs.recommended.plugins },
+    rules:   { ...neighborContent.configs.recommended.rules },
+  },
+]
+```
+
+```json
+// .stylelintrc.json
+{
+  "extends": ["stylelint-config-standard"],
+  "plugins": ["@a11yfred/neighbor"],
+  "rules": {
+    "neighbor/no-outline-none": true,
+    "neighbor/no-forced-colors-none": true,
+    "neighbor/user-preferences": true
+  }
+}
+```
+
+The ESLint markup rules (`@a11yfred/neighbor/eslint` and variants) require JSX or a component template syntax. They will not produce useful output on plain HTML or vanilla JS files and should be skipped.
+
+---
+
 ### React / JSX
 
 Neighbor works alongside `eslint-plugin-jsx-a11y`. Install both.

package/neighbor-stylelint.mjs

@@ -13,6 +13,9 @@
  *   double-great/stylelint-a11y  github.com/double-great/stylelint-a11y
  */
 
+import stylelint from 'stylelint';
+const { utils: { report } } = stylelint;
+
 const defined = (x) => x !== undefined && x !== null;
 
 /** True if the node or any ancestor is a prefers-* / forced-colors media block */
@@ -117,7 +120,7 @@ function rule(primaryOption) {
 
       // opacity  -  warn on non-structural values (i.e. dims like 0.5, 0.75)
       if (prop === 'opacity' && !isStructuralOpacity(value)) {
-        decl.warn(result, messages.opacity(value), { rule: ruleName });
+        report(decl, messages.opacity(value));
         return;
       }
 
@@ -125,7 +128,7 @@ function rule(primaryOption) {
       if (prop === 'animation' || prop === 'transition' || prop === 'animation-name') {
         // Skip "none" values  -  they're already the reduced state
         if (/^none\b/i.test(value.trim())) return;
-        decl.warn(result, messages.animation(prop, value), { rule: ruleName });
+        report(decl, messages.animation(prop, value));
         return;
       }
 
@@ -136,7 +139,7 @@ function rule(primaryOption) {
         'outline-color', 'box-shadow', 'text-shadow', 'fill', 'stroke',
       ]);
       if (visualProps.has(prop) && hasAlphaChannel(value)) {
-        decl.warn(result, messages.alpha(value), { rule: ruleName });
+        report(decl, messages.alpha(value));
       }
     });
   };
@@ -169,6 +172,30 @@ function isFocusSelector(selector) {
   return /:focus(?:-visible|-within)?/i.test(selector);
 }
 
+/** Returns true if the node is inside a @media (pointer: fine/coarse) block — keyboard users are unaffected. */
+function insidePointerMedia(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'atrule' &&
+      current.name === 'media' &&
+      /pointer\s*:\s*(fine|coarse)/.test(current.params)
+    ) return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+/** Returns true if the decl or any ancestor rule node targets a focus state. */
+function insideFocusSelector(decl) {
+  let current = decl.parent;
+  while (current) {
+    if (current.type === 'rule' && isFocusSelector(current.selector ?? '')) return true;
+    current = current.parent;
+  }
+  return false;
+}
+
 /** @type {import('stylelint').Rule} */
 function noOutlineNoneRule(_primaryOption) {
   return (root, result) => {
@@ -176,14 +203,12 @@ function noOutlineNoneRule(_primaryOption) {
       const value = decl.value.trim().toLowerCase();
       if (value !== 'none' && value !== '0') return;
 
-      // If this declaration is already inside a :focus / :focus-visible rule, it's fine  - 
-      // the author is intentionally restyling focus, which is acceptable as long as they
-      // provide an alternative (we can't verify the alternative statically, so we allow it).
-      const parent = decl.parent;
-      if (parent?.type === 'rule' && isFocusSelector(parent.selector ?? '')) return;
+      // Allow inside :focus / :focus-visible (author is intentionally restyling focus)
+      if (insideFocusSelector(decl)) return;
+      // Allow inside @media (pointer: fine/coarse) — keyboard users are unaffected
+      if (insidePointerMedia(decl)) return;
 
-      // Flag it
-      decl.warn(result, noOutlineNoneMessages.removed(decl.value), { rule: noOutlineNoneRuleName });
+      report({ message: noOutlineNoneMessages.removed(decl.value), node: decl, result, ruleName: noOutlineNoneRuleName });
     });
   };
 }
@@ -243,7 +268,7 @@ function noForcedColorsNoneRule(_primaryOption) {
       if (decl.value.trim().toLowerCase() !== 'none') return;
       if (!insideForcedColorsMedia(decl)) return;
       const selector = decl.parent?.selector ?? decl.parent?.name ?? '(unknown)';
-      decl.warn(result, noForcedColorsNoneMessages.none(selector), { rule: noForcedColorsNoneRuleName });
+      report({ message: noForcedColorsNoneMessages.none(selector), node: decl, result, ruleName: noForcedColorsNoneRuleName });
     });
   };
 }

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "@a11yfred/neighbor",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Accessibility linting for a11yfred  -  ESLint (markup + content), Stylelint (CSS). Won't you be my neighbor?",
   "type": "module",
   "license": "MIT",
-  "files": ["lib", "*.mjs", "LICENSE", "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "RULES.md", "RULES-MARKUP.md", "RULES-CSS.md", "RULES-CONTENT.md"],
+  "files": [
+    "lib",
+    "*.mjs",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "RULES.md",
+    "RULES-MARKUP.md",
+    "RULES-CSS.md",
+    "RULES-CONTENT.md"
+  ],
   "main": "./neighbor-stylelint.mjs",
   "repository": {
     "type": "git",
@@ -67,6 +78,7 @@
     }
   },
   "devDependencies": {
+    "@a11yfred/neighbor": "^1.0.1",
     "eslint": "^9.39.4",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "stylelint": "^17.11.0"