Build Accessibility Checker Rules That Return Pass, Fail, or Incomplete

## Treat Lint and Tests as Part of Every Change, Not Cleanup Treat formatting, linting, tests, documentation, and commit conventions as part of the change rather than cleanup after implementation. ### Required Checks - Run the repository's formatter and linter before committing. - Run the full test suite before completion, with unit and integration coverage for behavior changes. - Follow documented exceptions only for changes that cannot affect runtime behavior. - Keep unresolved work in the project's issue tracker instead of hiding it in unrelated changes. - Do not commit temporary logging or local debugging settings. ### Code Conventions - Handle errors and edge cases early so the successful path remains easy to follow. - Follow the established export placement, naming rules, and import style. - Name files and rule identifiers consistently; distinguish functions, booleans, and constants by project convention. - Declare variables near first use. - Document exported APIs, parameters, return values, and complex logic. - Keep refactoring separate from a focused feature or fix. ## Choose Virtual or Real DOM Nodes and Keep Dependencies One-Way Choose between a virtual tree abstraction and real DOM nodes deliberately. The abstraction is efficient for cached attributes and properties, while the real DOM is required for browser APIs and layout behavior. ### Node Selection - Prefer virtual nodes for attribute access, cached properties, tree traversal, and selector work. - Use real DOM nodes for layout, geometry, root lookup, computed browser behavior, and other native APIs. - Resolve ambiguous inputs through one documented conversion boundary. - Keep general utilities based on real DOM inputs and outputs unless a virtual-node dependency has a clear API or performance benefit. - Do not spread conversion logic across individual rules. ### Dependency Direction - Keep standards definitions as pure data with no runtime imports. - Allow low-level utilities to depend only on lower-level base code and standards data through explicit paths. - Centralize third-party module imports in a designated adapter layer. - Let shared domain helpers use low-level utilities, but never reverse that dependency. - Allow high-level checks and rules to compose lower layers without creating cycles. - Enforce these boundaries mechanically with lint or build rules. ## Return Pass, Fail, or Incomplete, and Keep Messages in Metadata Make the result contract explicit so consumers can distinguish compliance, failure, and insufficient evidence. ### Check Results - Return pass when the tested condition is satisfied. - Return fail when the tested condition is violated. - Return incomplete when the engine cannot determine the result reliably. - Attach structured data for message templates and for explaining incomplete results. - Do not force uncertainty into pass or fail merely to produce a binary answer. ### Rule Definitions - Compose checks with explicit all, any, and none groups. - Scope candidate elements with a selector and an optional additional matcher. - Restrict impact to the project's declared severity values. - Read HTML and ARIA definitions from centralized standards data instead of hardcoding lists inside checks. ### User-Facing Messages - Keep messages in rule or check metadata rather than implementation code. - Use named data placeholders whose values are supplied by the check result. - Provide singular and plural variants where grammar requires them. - Update the localization template whenever a source message changes. ## Review Color Contrast and Role Checks With Extra Care Some accessibility results depend on incomplete browser information or rapidly evolving standards. These areas require conservative outcomes and targeted review. ### Color and Visibility - Account for supported color formats, opacity, blending, stacking contexts, and text effects. - Return incomplete when the effective background or contrast cannot be determined. - Evaluate screen-reader visibility semantically rather than relying on CSS visibility alone. - Include hidden-state attributes, composed trees, and Shadow DOM boundaries. ### Semantic Standards - Keep role and attribute validation synchronized with the current accessibility specification. - Resolve implicit and explicit roles separately. - Query centralized role and attribute definitions so every rule uses the same source of truth. - Add regression cases for specification updates and previously misclassified markup. - Require focused review when a change can alter results across many rules. ## Test Each Rule on Real-Looking Pages, Including Shadow DOM Mirror source structure in the unit-test tree so implementation and test ownership remain obvious. ### Unit and Check Tests - Use the standard check context or harness provided by the project. - Reset only state owned by the test when shared fixtures and virtual trees are already cleared by the harness. - Test pass, fail, and incomplete outcomes, including attached message data. - Add focused cases for edge conditions before broad integration coverage. ### Integration Tests - Pair each rule fixture with structured expected results. - Use the engine's canonical selector representation, including nested selectors for frames. - Use a complete HTML page when document-level behavior cannot be represented by a fragment. - Add an open Shadow DOM case for every relevant rule or check. - Update virtual-rule coverage when a change affects virtual tree evaluation. - Run focused tests during iteration and the authoritative full suite before handoff. ## Regenerate Translation Templates in the Same Commit as Messages Distinguish generated release bundles from generated source artifacts that the repository intentionally tracks. ### Artifact Policy - Do not edit bundled or minified release output directly. - Regenerate tracked templates or source artifacts through the approved build. - Commit a generated localization template in the same change as the message source that produced it. - Do not split synchronized source and generated updates across separate commits. - Keep ignored publishing bundles out of ordinary feature commits. ### Verification - Inspect the generated diff for unexpected message, locale, or rule changes. - Confirm that every new placeholder exists in the producing check data. - Run localization and build validation after message changes. - Document which artifacts are generated, which are tracked, and which are release-only. ## Update the Changelog and API Docs, and Avoid Breaking Changes Keep each change focused and make its public consequences visible to reviewers and consumers. ### Change Documentation - Update the changelog when adding or materially changing a rule. - Update API documentation and type definitions together when a public interface changes. - Use the repository's required conventional commit form, with a concise subject and motivation in the body. - Link the resolved issue through the supported footer or pull request metadata. - Complete the project review checklist before handoff. ### Compatibility - Avoid breaking changes when old and new formats can be supported together. - Mark deprecated APIs clearly and provide a migration path. - When a break is unavoidable, identify it explicitly in release metadata and the changelog. - Include migration guidance, updated tests, synchronized generated files, and reviewer-visible evidence. - Do not claim readiness until formatting, linting, focused tests, integration tests, the full suite, and documentation checks have actual results.