chore: add CLAUDE.md and pull request checklist (#5035)

Adds a CLAUDE.md file for contributors

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jonathan Garbee <jonathan.garbee@deque.com>

Author: 3 people

CLAUDE.md

@@ -0,0 +1,102 @@
+# axe-core — Claude Code Context
+
+**Last updated:** 2026-03-19
+
+## 0. Fundamental Standards
+
+- **Formatting:** Run `npm run fmt` (Prettier) and `npm run eslint` before every commit. No exceptions.
+- **Zero-Exception Testing:** 100% coverage goal. Run `npm test` before completion. `feat`/`fix` and other behavior-changing PRs require unit + integration tests where applicable; see `doc/code-submission-guidelines.md` for exceptions (e.g., some `chore`/docs changes).
+- **Import Rule:** Directory-level import restrictions are strictly enforced. See `eslint.config.js`.
+- **Commits:** Angular commit convention is mandatory. PRs with non-conforming commits will be rejected. See `doc/code-submission-guidelines.md`.
+- **Issues:** All unresolved issues tracked in [GitHub Issues](https://github.com/dequelabs/axe-core/issues).
+
+## 1. Technical Guidelines
+
+### Code Structure
+
+- **Return Early:** Keep the happy path left-aligned. Handle errors/edge cases first with early returns — never nest when you can exit.
+- **Exports:** Default export at the top of the file, immediately after imports.
+- **JSDoc:** Add JSDoc/DocBlock comments where appropriate, especially for exported APIs and complex logic. Document parameters and return types. See `doc/code-submission-guidelines.md` (source of truth) and `doc/developer-guide.md` for additional guidance.
+- **Naming:** Files and rule/check IDs in kebab-case. Functions in camelCase. Booleans prefixed `is`/`has`/`should`. Constants in `UPPER_SNAKE_CASE`.
+- **Variables:** Declare at point of use, not at the top of the function.
+
+### Virtual Nodes vs. HTMLElement
+
+- **Prefer Virtual Nodes** for attribute access and property reads (`virtualNode.attr()`, `virtualNode.props`).
+- **Use real DOM** only when you need DOM APIs (e.g., `getBoundingClientRect`, `getRootNode`).
+- **`core/utils/` functions** should default to real DOM inputs/outputs, except utilities that are explicitly documented as operating on `VirtualNode` (for example, tree or selector helpers). Avoid introducing new `VirtualNode`-dependent utilities unless there is a clear performance or API benefit.
+- **Conversion:** Use `getNodeFromTree()` from `core/utils` when you receive an ambiguous input (such as a `VirtualNode`, selector, or mixed type) and need to resolve it to a real DOM `Node`.
+
+### Import Restrictions (Hard Rules)
+
+- `standards/` → nothing (pure data, no imports).
+- `core/utils/` → other `core/utils`, `core/base`, `standards` via **direct file paths only** (no index).
+- `core/imports/` → node modules **only** (the only place npm imports are allowed).
+- `commons/` → other `commons` (direct paths), `core/utils` (index OK).
+- `checks/` and `rules/` → any directory (index OK).
+- **Never** import `commons` from `core/utils`. This is the most commonly rejected violation.
+
+### Checks & Rules
+
+- **Check evaluate functions:** Return `true` (pass), `false` (fail), or `undefined` (incomplete). Use `this.data()` to pass values to message templates and to provide incomplete-result detail.
+- **Rule JSON:** Use `all`, `any`, `none` check arrays. `selector` + optional `matches` to scope candidates. Valid `impact` values: `"minor"`, `"moderate"`, `"serious"`, `"critical"`.
+- **Standards data:** Never hardcode ARIA/HTML lists in checks. Query from `standards/` via `commons/standards` functions.
+- **Messages:** All user-facing strings live in check/rule JSON `metadata.messages`. Use `${data.property}` templates. Support singular/plural variants. Update `locales/_template.json` whenever messages change (auto-synced on `npm run build`).
+
+### High-Risk Areas (Extra Scrutiny Required)
+
+- **Color contrast:** Handles all CSS color formats, opacity, blend modes, stacking contexts, text-shadow. Return `undefined` when background cannot be determined. See `doc/developer-guide.md`.
+- **ARIA validation:** Must stay current with spec. Query roles/attrs from `standards/aria-roles.js` and `standards/aria-attrs.js`. Handle implicit vs. explicit roles. See `doc/rule-development.md`.
+- **Hidden elements:** Use `isVisibleToScreenReaders()`, not CSS visibility alone. Account for `aria-hidden="true"` and Shadow DOM boundaries.
+- **i18n:** Update `locales/_template.json` on every message change and commit the generated file alongside source.
+
+## 2. Testing
+
+- **Structure:** Mirror `lib/` exactly under `test/`. File `lib/commons/text/sanitize.js` → `test/commons/text/sanitize.js`.
+- **Checks:** Use `axe.testUtils.MockCheckContext()`. Only reset `checkContext` in `afterEach` — `fixture` and `axe._tree` are auto-cleared.
+- **Integration tests:** All rule changes require an HTML + JSON pair. Use `test/integration/rules/<rule-name>/` for mocha-hosted tests or `test/integration/full/<rule-name>/` when the rule requires a full HTML page. JSON selectors must use axe array format (`["#id"]`; iframes: `["iframe", "#id"]`). Also update or create virtual-rules tests where appropriate.
+- **Shadow DOM:** Every relevant check/rule must include an open Shadow DOM test case using `queryShadowFixture`.
+- **Logging:** Do not commit `console.log` statements.
+
+## 3. Build & Commits
+
+- **Bundles (`axe.js`, `axe.min.js`)** are auto-generated for releases/publishing and are not committed to the repo (they are gitignored).
+- **Locales template (`locales/_template.json`)** is auto-generated. When message strings change, regenerate this file and commit it in the same commit as the source changes — never in a separate commit.
+- **One change per PR.** Do not mix refactoring with feature work.
+- **Commit format:** `<type>(<scope>): <subject>` — imperative, lowercase, no period, ≤100 chars total. Body explains motivation. Footer: `Closes issue #123` or full URL. See `doc/code-submission-guidelines.md` for the full type list.
+
+**Example:**
+
+```
+fix(aria-valid-attr-value): handle multiple aria-errormessage IDs
+
+When aria-errormessage contains multiple space-separated IDs, verify
+all IDs exist in aria-describedby instead of matching the full string.
+
+Closes issue #4957
+```
+
+## 4. Documentation & API Changes
+
+- **New rules:** Update `CHANGELOG.md`. `doc/rule-descriptions.md` is auto-generated by `npm run build`.
+- **API changes:** Update `doc/API.md` and `axe.d.ts` TypeScript definitions.
+- **Breaking changes:** Avoid breaking changes — prefer supporting both old and new formats simultaneously. If unavoidable, add `BREAKING CHANGE: description` to commit footer, include migration guide in `CHANGELOG.md`, and tag deprecated code with `@deprecated` JSDoc.
+
+## 5. Examples (Copy-Paste Reference)
+
+- **Code patterns:** `doc/examples/code-patterns.md` — return early, default export, imports, JSDoc, Virtual Node usage
+- **Test patterns:** `doc/examples/test-patterns.md` — unit tests, check tests, Shadow DOM tests, integration test HTML+JSON
+- **Rule & check templates:** `doc/examples/rule-check-templates.md` — JSON templates for rules and checks, evaluate function pattern
+- **PR review patterns:** `doc/examples/pr-review-patterns.md` — common reviewer feedback, anti-patterns, what reviewers look for
+
+## 6. Reference Docs & Help
+
+- **Contributing guide:** `CONTRIBUTING.md`
+- **Import rules detail:** `eslint.config.js`
+- **Code submission standards:** `doc/code-submission-guidelines.md`
+- **Developer guide:** `doc/developer-guide.md`
+- **Rule development:** `doc/rule-development.md`
+- **API reference:** `doc/API.md`
+- **Pull Request Checklist:** `doc/pull-request-checklist.md`
+- **Slack:** [axe-community](https://accessibility.deque.com/axe-community)
+- **Issues:** [GitHub Issues](https://github.com/dequelabs/axe-core/issues)

doc/examples/code-patterns.md

@@ -0,0 +1,152 @@
+# Code Pattern Examples
+
+Quick-reference examples for axe-core coding conventions.
+
+## Default Export at Top
+
+```javascript
+// GOOD: Default export right after imports
+import { getRole } from '../../commons/aria';
+import { isVisible } from '../../commons/dom';
+
+export default function myFunction(node, options) {
+  // function body
+}
+
+// BAD: Export buried at bottom of file
+import { getRole } from '../../commons/aria';
+
+function myFunction(node, options) {
+  // body
+}
+
+// ... more code ...
+
+export default myFunction; // Too far from top
+```
+
+## Return Early Pattern
+
+```javascript
+// GOOD: Main path left-aligned, edge cases exit early
+export default function processValue(value) {
+  if (!value) {
+    return null;
+  }
+
+  if (value.length < 3) {
+    throw new Error('Value too short');
+  }
+
+  const normalized = normalize(value);
+  const result = transform(normalized);
+  return result;
+}
+
+// BAD: Nested conditionals
+export default function processValue(value) {
+  let result;
+  if (value) {
+    if (value.length >= 3) {
+      const normalized = normalize(value);
+      result = transform(normalized);
+    } else {
+      throw new Error('Value too short');
+    }
+  } else {
+    result = null;
+  }
+  return result;
+}
+```
+
+## Import Restrictions
+
+```javascript
+// GOOD: commons importing from core/utils via index
+import { getNodeFromTree } from '../../core/utils';
+
+// GOOD: commons importing other commons directly
+import getExplicitRole from '../aria/get-explicit-role';
+
+// BAD: core/utils importing from commons — NEVER DO THIS
+import { isDisabled } from '../../commons/forms';
+
+// BAD: importing from index in core/utils — use direct path
+import { someUtil } from './index'; // Use: import someUtil from './some-util';
+```
+
+## JSDoc Comments
+
+### Standard function
+
+```javascript
+/**
+ * Determines if an element is a native select element
+ * @method isNativeSelect
+ * @memberof axe.commons.forms
+ * @param {VirtualNode|Element} node Node to determine if select
+ * @returns {Boolean}
+ */
+import nodeLookup from '../../core/utils/node-lookup';
+
+function isNativeSelect(node) {
+  const { vNode } = nodeLookup(node);
+  const nodeName = vNode.props.nodeName;
+  return nodeName === 'select';
+}
+```
+
+### Check evaluate function
+
+```javascript
+/**
+ * Check if an element's `role` attribute uses any abstract role values.
+ *
+ * Abstract roles are taken from the `ariaRoles` standards object from the roles `type` property.
+ *
+ * ##### Data:
+ * <table class="props">
+ *   <thead>
+ *     <tr>
+ *       <th>Type</th>
+ *       <th>Description</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <td><code>String[]</code></td>
+ *       <td>List of all abstract roles</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ *
+ * @memberof checks
+ * @return {Boolean} True if the element uses an `abstract` role. False otherwise.
+ */
+function abstractroleEvaluate(node, options, virtualNode) {
+  // implementation
+}
+```
+
+## Virtual Node vs HTMLElement
+
+```javascript
+// Use Virtual Node for attribute access and property reads
+function myCheck(node, options, virtualNode) {
+  const role = virtualNode.attr('role'); // Cached attribute access
+  const nodeName = virtualNode.props.nodeName;
+
+  // Only access real node when you need DOM APIs
+  const rect = node.getBoundingClientRect();
+  const rootNode = node.getRootNode();
+}
+
+// Convert ambiguous input using nodeLookup
+import nodeLookup from '../../core/utils/node-lookup';
+
+function myFunction(nodeOrVirtual) {
+  const { vNode, domNode } = nodeLookup(nodeOrVirtual);
+  // vNode = VirtualNode, domNode = real DOM node
+}
+```

doc/examples/pr-review-patterns.md

@@ -0,0 +1,69 @@
+# PR Review Patterns
+
+Common feedback and anti-patterns observed in axe-core code reviews.
+
+## What Gets Called Out
+
+### 1. Missing Tests
+
+- Every behavior-changing code change needs unit tests
+- Rule changes need integration tests (HTML + JSON pair)
+- Shadow DOM test coverage required for relevant checks/rules
+
+### 2. Commit Message Format
+
+- Wrong type/scope
+- Not imperative present tense
+- Subject too long or capitalized
+- Missing issue reference in footer
+
+### 3. Import Violations
+
+- `core/utils` importing from `commons` (forbidden)
+- Using index imports where direct file paths are required
+- Importing node modules outside `core/imports`
+
+### 4. Code Style Issues
+
+- Not using return early pattern
+- Default export not at top of file
+- Nested conditionals when early return would work
+- Missing JSDoc comments
+
+### 5. Performance Concerns
+
+- Unnecessary DOM queries in loops
+- Not caching Virtual Node properties
+- Computing same value repeatedly instead of storing it
+
+### 6. Incomplete Results
+
+- Not returning `undefined` when a check can't determine the result
+- Missing `incomplete` message variants in check JSON
+- Not setting appropriate `this.data()` for incomplete cases
+
+### 7. Accessibility Edge Cases
+
+- Not considering all ARIA states
+- Missing edge cases for hidden elements
+- Not handling Shadow DOM properly
+
+## What Reviewers Love
+
+1. Comprehensive test coverage including edge cases
+2. Clear, detailed commit messages with motivation
+3. JSDoc comments that explain "why" not just "what"
+4. Performance-conscious code that caches appropriately
+5. Following existing patterns in similar files
+6. Integration tests that cover both pass and fail cases
+
+## Common PR Mistakes
+
+1. Not running `npm test` locally before pushing
+2. Not committing auto-generated `locales/_template.json` in the same commit as message source changes
+3. Changing multiple unrelated things in one PR — split refactoring from feature work
+4. Not updating integration tests when changing rule behavior
+5. `console.log` statements should not be committed
+6. Not handling `null` or `undefined` gracefully
+7. Hardcoding strings that should come from `standards/` data
+8. Changing public APIs without `BREAKING CHANGE` in commit footer