Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (57 loc) · 2.8 KB

CONTRIBUTING.md

File metadata and controls

73 lines (57 loc) · 2.8 KB
Raw

Contributing

Thanks for considering a contribution. This project is small and deliberately dependency-light; the guidelines below exist to keep it that way.

Getting set up

git clone https://github.com/css-scroll-driven/scroll-a11y-audit.git
cd scroll-a11y-audit
npm install
npm test

You need Node 20 or newer and a local Chrome or Chromium if you want to run the CLI. npm test needs neither Chrome nor a network connection.

Ground rules

  • puppeteer-core is the only runtime dependency. Please do not add another one. There is no test framework (node --test), no bundler (a hand-written concat script) and no linter config to satisfy — just match the surrounding style.
  • Rules must stay environment-agnostic. A rule receives (ctx, model) and must never touch a global. Reaching for document or window directly breaks the browser build, the CLI and the tests all at once.
  • Every top-level identifier must be globally unique across src/. The browser build concatenates the sources and will fail loudly on a collision — this is intentional, not a bug to work around.
  • Every rule needs tests in both directions: a fixture that triggers it and a fixture that must not. A rule that only has positive tests will get noisy in the field and nobody will notice.

Adding a rule

  1. Create src/rules/<your-rule-id>.js. Export a uniquely-named rule object with id, title, severity, wcag, description, howToFix, learnMore and run. Name the run function run<YourRuleId>.
  2. Register it in src/rules/index.js — import order is report order.
  3. Add the file to SEGMENTS in scripts/build-browser.mjs, after anything it imports from.
  4. Add tests to tests/rules.test.mjs using the helpers in tests/helpers/stub-dom.mjs. If the stub lacks something you need, extend the stub rather than working around it in the rule.
  5. Add a row to the rules reference table in README.md.
  6. Add a triggering case to demo/bad.html and the correct pattern to demo/good.html.

Run the full check before opening a pull request:

npm test
node scripts/build-browser.mjs
node --check browser/scroll-a11y-audit.js

Reporting false positives

False positives matter more than missed findings here — a noisy auditor gets switched off, and then it catches nothing at all. When you report one, please include the smallest CSS and HTML that reproduces it, the rule id, and what the correct verdict should be. A failing test case in tests/rules.test.mjs is the most useful possible bug report.

Commit messages

Write in the imperative mood and explain the reasoning, not just the change: "Stop flagging reduced-motion blocks in animation-blocks-interaction" beats "fix bug".

Licence

Contributions are accepted under the MIT Licence.